Environment Variable Management with Vercel Push

The SaaS Factory platform includes a built-in environment variable management system that handles the full lifecycle of secrets — from secure storage through live external validation to automatic synchronisation with your Vercel deployments.

Overview

Environment variable management is implemented in src/lib/routers/env-vars.ts and relies on src/lib/encryption.ts for at-rest encryption. The system exposes a set of typed operations that the platform's agent pipeline can call programmatically, removing the need to manage secrets by hand across multiple deployment targets.

Core Operations

Listing Variables

list()

Returns all configured environment variable keys. Sensitive values are masked in the response — the system never returns plaintext secrets through the list endpoint.

Setting a Variable

set(key: string, value: string)

Encrypts value using the platform encryption layer and upserts the key-value pair into the store. If the key already exists its value is overwritten.

Deleting a Variable

delete(key: string)

Permanently removes the key and its encrypted value from the store.

Checking Required Variables

checkRequired()

Validates that every key marked as required for the current product is present in the store. Keys that appear in the PLATFORM_MANAGED_KEYS set are skipped — this prevents false-positive alerts for shared infrastructure credentials that are managed at the platform level rather than the per-product level.

External Service Validation

Before secrets are trusted by the pipeline they can be validated against real external APIs:

GitHub

validateGitHub(token: string)

Makes a live request to github.com/user with the supplied token to confirm it is valid and has the expected scopes.

Vercel

validateVercel(token: string)

Makes a live request to api.vercel.com/v2/user to confirm the token belongs to an active Vercel account.

Twilio

validateTwilio(accountSid: string, authToken: string)

Makes a live request to api.twilio.com to verify the credential pair.

All validators return a structured result object with a valid boolean and an optional error message — they never throw on invalid credentials, making them safe to use inside agent decision loops.

Vercel Integration

List Vercel Projects

listVercelProjects()

Enumerates all Vercel projects connected to the configured Vercel token.

Push Environment Variables to Vercel

pushToVercel(projectId: string, keys?: string[])

Decrypts the requested environment variables from the store and pushes them to the specified Vercel project using pushEnvVarsToVercel. If keys is omitted, all stored variables are pushed.

Note: Decryption happens in-process immediately before the push and the plaintext values are never written to disk or logged.

Deploy Auth Config to Vercel

deployAuthToVercel(projectId: string, authConfig: AuthConfig)

A higher-level helper that:

1. Maps an authConfig object to the corresponding environment variable names expected by the Next.js auth layer.
2. Pushes those variables to the target Vercel project.
3. Triggers a redeployment so the new values take effect immediately.

This is the primary mechanism the platform uses when an AI agent reconfigures authentication providers — no manual Vercel dashboard interaction is required.

Security Model

Concern	Approach
Storage	AES encryption via src/lib/encryption.ts — values are never stored in plaintext
API responses	Values are masked in all list/read responses
Validation	Real API calls — not regex or format checks
Platform keys	PLATFORM_MANAGED_KEYS exempts shared infrastructure keys from per-product checks

Environment Variables

The following platform-level variables must be configured for the full feature set to be available:

Key	Purpose
ENCRYPTION_KEY	Secret used by src/lib/encryption.ts to encrypt/decrypt stored values
VERCEL_TOKEN	Bearer token used by listVercelProjects, pushToVercel, and deployAuthToVercel
PLATFORM_MANAGED_KEYS	Comma-separated list of key names that bypass per-project required-key checks