Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

+87
View File
@@ -0,0 +1,87 @@
# @toolctrl/config
Typed environment catalog and lightweight validation helpers for the `apps/web`, `apps/api` and `apps/worker` runtime split.
This package is now partially wired into runtime loaders for web/API/worker configuration and remains the source of truth for env examples and documentation drift checks. Catalog entries should describe whether a key is required for core boot, required by a specific app, optional for an enabled provider, platform-supplied, or deprecated.
## Classification
- `required-core`: needed for the current app to boot safely.
- `required-per-app`: required by at least one target app or API path.
- `optional-provider`: only required when the related integration is enabled.
- `local-development-only`: local convenience variables.
- `production-only`: supplied by production/runtime platforms or only useful in production.
- `deprecated-remove`: present in examples but not currently backed by active code usage.
## Current Inventory
The catalog is verified against `.env.example`, `.env.local.example`, `.env.production.example`, `.env.fly.example`, `.env.test`, Prisma `env(...)` usage, and active web/API/worker/package environment reads.
| Variable | Classification | Targets | Source |
| ----------------------------------- | ---------------------- | ------------------------ | ---------------- |
| `APP_NAME` | required-core | shared, web, api, worker | code-and-example |
| `DATABASE_URL` | required-core | shared, web, api, worker | code-and-example |
| `SESSION_SECRET` | required-core | web, api | code-and-example |
| `CRYPTO_SECRET` | required-per-app | web, api | code-and-example |
| `API_ACCESS_TOKEN` | required-per-app | web, api | code-and-example |
| `JWT_SECRET` | required-per-app | web, api | code-and-example |
| `ANALYTICS_TOKEN` | required-per-app | api | code |
| `NODE_ENV` | production-only | shared, web, api, worker | runtime |
| `APP_REVISION` | production-only | shared, web, api, worker | runtime |
| `DIRECT_URL` | production-only | shared, web, api, worker | code |
| `SERVER_URL` | production-only | web, api | code |
| `VERCEL_URL` | production-only | web | code |
| `WEBHOOKS_URL` | optional-provider | web, api | code-and-example |
| `SUPABASE_API_URL` | optional-provider | web, api | code-and-example |
| `SUPABASE_KEY` | optional-provider | web, api | code-and-example |
| `STRIPE_SK` | optional-provider | web, api | code-and-example |
| `STRIPE_WEBHOOK_SIGNING_SECRET` | optional-provider | web, api | code-and-example |
| `STRIPE_ACCOUNT_COUNTRY` | production-only | web, api | example |
| `MAILJET_API_KEY` | optional-provider | web, api, worker | code-and-example |
| `MAILJET_FROM_EMAIL` | optional-provider | web, api, worker | code-and-example |
| `MAILJET_FROM_NAME` | optional-provider | web, api, worker | example |
| `MAILJET_SECRET_KEY` | production-only | web, api, worker | example |
| `SUPPORT_EMAIL` | optional-provider | web | example |
| `COMPANY_NAME` | optional-provider | web, api | example |
| `COMPANY_ADDRESS` | optional-provider | web, api | example |
| `INTEGRATIONS_CONTACT_FORMSPREE` | optional-provider | web | code-and-example |
| `CONVERTKIT_APIKEY` | optional-provider | web | code-and-example |
| `CONVERTKIT_FORM` | optional-provider | web | code-and-example |
| `CONVERTKIT_API_SECRET` | optional-provider | web | code |
| `CRISP_CHAT_WEBSITE_ID` | optional-provider | web | code-and-example |
| `ANALYTICS_GA_TRACKING_ID` | optional-provider | web | code-and-example |
| `GITHUB_OAUTH_CLIENT_ID` | optional-provider | web, api | code-and-example |
| `GITHUB_OAUTH_CLIENT_SECRET` | optional-provider | web, api | code-and-example |
| `AUTH_MAGIC_LINK_ENABLED` | optional-provider | web, api | code-and-example |
| `AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES` | optional-provider | web, api | code-and-example |
| `AUTH_RECAPTCHA_SITE_KEY` | optional-provider | web | code-and-example |
| `NOTIFICATIONS_NOVU_API_KEY` | optional-provider | web | code-and-example |
| `MISTRAL_API_KEY` | optional-provider | web, api, worker | code-and-example |
| `AI_PROCESSING_REGION` | production-only | web, api, worker | example |
| `MISTRAL_MODEL` | optional-provider | web, api, worker | code-and-example |
| `SCALEWAY_API_KEY` | optional-provider | web, api, worker | code-and-example |
| `SCALEWAY_MODEL` | optional-provider | web, api, worker | code-and-example |
| `SCALEWAY_BASE_URL` | optional-provider | web, api, worker | code-and-example |
| `SCALEWAY_REGION` | production-only | web, api, worker | example |
| `ALEPH_ALPHA_API_KEY` | optional-provider | web, api, worker | code-and-example |
| `ALEPH_ALPHA_MODEL` | optional-provider | web, api, worker | code-and-example |
| `ALEPH_ALPHA_BASE_URL` | optional-provider | web, api, worker | code-and-example |
| `IMPORT_QUEUE_ENABLED` | optional-provider | web, worker | code-and-example |
| `BULLMQ_REDIS_URL` | optional-provider | web, api, worker | code-and-example |
| `BROWSER_RUNTIME_URL` | optional-provider | api, worker | example |
| `BROWSER_RUNTIME_API_KEY` | optional-provider | api, worker | example |
| `BROWSER_SESSION_TIMEOUT_MS` | optional-provider | api, worker | example |
| `IPSTACK_API_KEY` | optional-provider | api, worker | code |
| `IPAPIIS_API_KEY` | optional-provider | api, worker | code |
| `PORTAL_SERVER_URL` | optional-provider | web, api | code-and-example |
| `PORTAL_SERVER_FLY_TOKEN` | optional-provider | web, api, worker | code-and-example |
| `DEMO_USER` | local-development-only | web | code |
| `SEED_ADMIN_EMAIL` | production-only | web | code-and-example |
| `SEED_ADMIN_PASSWORD` | production-only | web | code-and-example |
| `SEED_DEMO_DATA` | local-development-only | web | code-and-example |
| `ALLOW_STAGING_DEMO_SEED` | production-only | web | code |
| `SITE_KEY_*` | optional-provider | api | dynamic |
## Mail Provider Scope
Mailjet is the transactional runtime default. `MAILJET_API_KEY`, `MAILJET_FROM_EMAIL`, and `MAILJET_FROM_NAME` configure standard outbound transactional delivery.
@@ -0,0 +1,13 @@
{
"name": "@toolctrl/config",
"version": "0.0.0",
"private": true,
"type": "module",
"sideEffects": false,
"exports": {
".": "./src/index.ts"
},
"scripts": {
"test": "cd ../.. && vitest run packages/config/src"
}
}
@@ -0,0 +1,320 @@
import { describe, expect, test } from "vitest";
import { ApiConfigError, loadApiConfig, loadRequiredApiConfig } from "./index.js";
const REQUIRED_PRODUCTION_ENV = {
APP_NAME: "Production API",
DATABASE_URL: "postgres://example.invalid/app",
APP_BASE_DOMAIN: "example.com",
WEB_APP_HOST: "app.example.com",
ADMIN_APP_HOST: "admin.example.com",
API_HOST: "api.example.com",
SESSION_SECRET: "session-secret-value",
CRYPTO_SECRET: "crypto-secret-value",
API_ACCESS_TOKEN: "api-access-token-value",
JWT_SECRET: "jwt-secret-value",
ANALYTICS_TOKEN: "analytics-token-value",
};
describe("loadRequiredApiConfig", () => {
test("returns production API config when required values are valid", () => {
const config = loadRequiredApiConfig(
{
...REQUIRED_PRODUCTION_ENV,
API_PORT: "8081",
APP_PROTOCOL: "https",
},
{ nodeEnv: "production" }
);
expect(config).toMatchObject({
appName: "Production API",
nodeEnv: "production",
listen: { port: 8081 },
routing: {
appBaseDomain: "example.com",
apiHost: "api.example.com",
protocol: "https",
},
apiAccessToken: "api-access-token-value",
jwtSecret: "jwt-secret-value",
});
});
test("throws redacted ApiConfigError for missing required API_ACCESS_TOKEN", () => {
const secretValues = ["session-secret-value", "crypto-secret-value", "jwt-secret-value", "analytics-token-value"];
expect(() =>
loadRequiredApiConfig(
{
...REQUIRED_PRODUCTION_ENV,
API_ACCESS_TOKEN: undefined,
},
{ nodeEnv: "production" }
)
).toThrow(ApiConfigError);
try {
loadRequiredApiConfig(
{
...REQUIRED_PRODUCTION_ENV,
API_ACCESS_TOKEN: undefined,
},
{ nodeEnv: "production" }
);
} catch (error) {
expect(error).toBeInstanceOf(ApiConfigError);
const apiConfigError = error as ApiConfigError;
expect(apiConfigError.message).toBe("Invalid API configuration (API_ACCESS_TOKEN:missing-required).");
expect(apiConfigError.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "API_ACCESS_TOKEN",
classification: "required-per-app",
})
);
const errorText = JSON.stringify({ message: apiConfigError.message, details: apiConfigError.details });
for (const secretValue of secretValues) {
expect(errorText).not.toContain(secretValue);
}
}
});
test("throws redacted ApiConfigError for invalid API_PORT", () => {
const invalidPort = "secret-like-invalid-port-value";
const secretValues = ["session-secret-value", "crypto-secret-value", "api-access-token-value", "jwt-secret-value", "analytics-token-value"];
try {
loadRequiredApiConfig(
{
...REQUIRED_PRODUCTION_ENV,
API_PORT: invalidPort,
},
{ nodeEnv: "production" }
);
} catch (error) {
expect(error).toBeInstanceOf(ApiConfigError);
const apiConfigError = error as ApiConfigError;
expect(apiConfigError.message).toBe("Invalid API configuration (API_PORT:invalid-port).");
expect(apiConfigError.details.diagnostics).toEqual([
expect.objectContaining({
code: "invalid-port",
name: "API_PORT",
}),
]);
const errorText = JSON.stringify({ message: apiConfigError.message, details: apiConfigError.details });
expect(errorText).not.toContain(invalidPort);
for (const secretValue of secretValues) {
expect(errorText).not.toContain(secretValue);
}
}
});
test("preserves default development failure behavior by throwing diagnostics", () => {
expect(() => loadRequiredApiConfig({})).toThrow(ApiConfigError);
});
});
describe("loadApiConfig", () => {
test("returns local defaults and API listen defaults", () => {
const result = loadApiConfig({});
expect(result.ok).toBe(false);
expect(result.config).toMatchObject({
appName: "ToolController",
nodeEnv: "development",
listen: {
port: 3001,
},
routing: {
appBaseDomain: "localhost",
webAppHost: "app.localhost",
adminAppHost: "admin.localhost",
apiHost: "api.localhost",
protocol: "http",
},
origins: {},
analytics: {},
mailjet: {},
stripe: {},
storage: {},
});
});
test("reports missing production requirements including analytics token with redacted diagnostics", () => {
const result = loadApiConfig(
{
...REQUIRED_PRODUCTION_ENV,
API_ACCESS_TOKEN: undefined,
ANALYTICS_TOKEN: undefined,
},
{ nodeEnv: "production" }
);
expect(result.ok).toBe(false);
expect(result.diagnostics).toEqual(
expect.arrayContaining([
expect.objectContaining({ code: "missing-required", name: "API_ACCESS_TOKEN", classification: "required-per-app" }),
expect.objectContaining({ code: "missing-required", name: "ANALYTICS_TOKEN", classification: "required-per-app" }),
])
);
expect(JSON.stringify(result.diagnostics)).not.toContain("api-access-token-value");
expect(JSON.stringify(result.diagnostics)).not.toContain("analytics-token-value");
});
test("prefers API_PORT over PORT and falls back to PORT when API_PORT is empty", () => {
expect(loadApiConfig({ API_PORT: "4001", PORT: "4000" }).config.listen.port).toBe(4001);
expect(loadApiConfig({ API_PORT: " ", PORT: "4000" }).config.listen.port).toBe(4000);
expect(loadApiConfig({ PORT: "4000" }).config.listen.port).toBe(4000);
});
test("falls back for invalid API_PORT without leaking configured secrets", () => {
const secretValues = ["api-access-token-value", "jwt-secret-value", "analytics-token-value"];
const result = loadApiConfig({
API_ACCESS_TOKEN: secretValues[0],
JWT_SECRET: secretValues[1],
ANALYTICS_TOKEN: secretValues[2],
API_PORT: "not-a-port",
PORT: "4000",
});
expect(result.ok).toBe(false);
expect(result.config.listen.port).toBe(3001);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-port",
name: "API_PORT",
})
);
const diagnosticText = JSON.stringify(result.diagnostics);
for (const secretValue of secretValues) {
expect(diagnosticText).not.toContain(secretValue);
}
});
test("normalizes provider values and trims empty strings to undefined", () => {
const result = loadApiConfig({
...REQUIRED_PRODUCTION_ENV,
NODE_ENV: "production",
API_PORT: "8081",
APP_PROTOCOL: "https",
WEB_ORIGIN: " ",
ADMIN_ORIGIN: "\t",
API_ACCESS_TOKEN: " api-access-token-value ",
JWT_SECRET: " jwt-secret-value ",
ANALYTICS_TOKEN: " analytics-token-value ",
MAILJET_WEBHOOK_SECRET: " mailjet-webhook-secret-value ",
STRIPE_SK: " stripe-secret-value ",
STRIPE_WEBHOOK_SIGNING_SECRET: " stripe-webhook-secret-value ",
STORAGE_ENDPOINT: " https://storage.example.com ",
STORAGE_REGION: " us-east-1 ",
STORAGE_BUCKET: " uploads ",
STORAGE_ACCESS_KEY_ID: " storage-access-key-id-value ",
STORAGE_SECRET_ACCESS_KEY: " storage-secret-access-key-value ",
STORAGE_SESSION_TOKEN: " storage-session-token-value ",
STORAGE_PUBLIC_BASE_URL: " https://cdn.example.com/files ",
STORAGE_FORCE_PATH_STYLE: " true ",
});
expect(result.ok).toBe(true);
expect(result.diagnostics).toEqual([]);
expect(result.config).toMatchObject({
appName: "Production API",
nodeEnv: "production",
listen: { port: 8081 },
routing: {
appBaseDomain: "example.com",
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
protocol: "https",
},
origins: {},
apiAccessToken: "api-access-token-value",
jwtSecret: "jwt-secret-value",
analytics: {
token: "analytics-token-value",
},
mailjet: {
webhookSecret: "mailjet-webhook-secret-value",
},
stripe: {
secretKey: "stripe-secret-value",
webhookSigningSecret: "stripe-webhook-secret-value",
},
storage: {
endpoint: "https://storage.example.com",
region: "us-east-1",
bucket: "uploads",
accessKeyId: "storage-access-key-id-value",
secretAccessKey: "storage-secret-access-key-value",
sessionToken: "storage-session-token-value",
publicBaseUrl: "https://cdn.example.com/files",
forcePathStyle: "true",
},
apiKeys: {
allowLegacyPlaintextFallback: false,
},
});
});
test("parses API key legacy plaintext fallback cutover flag", () => {
expect(loadApiConfig({}).config.apiKeys.allowLegacyPlaintextFallback).toBe(false);
expect(loadApiConfig({ API_KEY_LEGACY_PLAINTEXT_FALLBACK: "false" }).config.apiKeys.allowLegacyPlaintextFallback).toBe(false);
expect(loadApiConfig({ API_KEY_LEGACY_PLAINTEXT_FALLBACK: "0" }).config.apiKeys.allowLegacyPlaintextFallback).toBe(false);
expect(loadApiConfig({ API_KEY_LEGACY_PLAINTEXT_FALLBACK: "true" }).config.apiKeys.allowLegacyPlaintextFallback).toBe(true);
expect(loadApiConfig({ API_KEY_LEGACY_PLAINTEXT_FALLBACK: "invalid" }).config.apiKeys.allowLegacyPlaintextFallback).toBe(false);
});
test("normalizes empty storage strings to undefined and redacts storage secrets from diagnostics", () => {
const storageSecretValues = ["storage-access-key-id-value", "storage-secret-access-key-value", "storage-session-token-value"];
const result = loadApiConfig({
API_PORT: "not-a-port",
STORAGE_ENDPOINT: " ",
STORAGE_REGION: "\t",
STORAGE_BUCKET: " ",
STORAGE_ACCESS_KEY_ID: ` ${storageSecretValues[0]} `,
STORAGE_SECRET_ACCESS_KEY: ` ${storageSecretValues[1]} `,
STORAGE_SESSION_TOKEN: ` ${storageSecretValues[2]} `,
STORAGE_PUBLIC_BASE_URL: "",
STORAGE_FORCE_PATH_STYLE: " ",
});
expect(result.ok).toBe(false);
expect(result.config.storage).toEqual({
accessKeyId: "storage-access-key-id-value",
secretAccessKey: "storage-secret-access-key-value",
sessionToken: "storage-session-token-value",
});
const diagnosticText = JSON.stringify(result.diagnostics);
for (const secretValue of storageSecretValues) {
expect(diagnosticText).not.toContain(secretValue);
}
});
test("preserves explicit API origins while routing hosts remain host-only", () => {
const result = loadApiConfig({
...REQUIRED_PRODUCTION_ENV,
NODE_ENV: "production",
APP_PROTOCOL: "https",
WEB_ORIGIN: " https://app.example.com ",
ADMIN_ORIGIN: " https://admin.example.com ",
WEB_APP_HOST: "web-routing.example.com",
ADMIN_APP_HOST: "admin-routing.example.com",
});
expect(result.ok).toBe(true);
expect(result.diagnostics).toEqual([]);
expect(result.config).toMatchObject({
routing: {
webAppHost: "web-routing.example.com",
adminAppHost: "admin-routing.example.com",
},
origins: {
web: "https://app.example.com",
admin: "https://admin.example.com",
},
});
});
});
+167
View File
@@ -0,0 +1,167 @@
import { getEnvVariableDefinition, validateEnv } from "./index.js";
import { getDomainRoutingConfig } from "./routing.js";
import type { ApiConfig, ApiConfigDiagnostic, ApiConfigErrorDetails, ApiConfigOptions, ApiConfigResult, EnvRecord, RequiredApiConfigOptions } from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_LISTEN_PORT = 3001;
const MIN_PORT = 1;
const MAX_PORT = 65535;
export class ApiConfigError extends Error {
readonly diagnostics: ApiConfigDiagnostic[];
constructor(diagnostics: readonly ApiConfigDiagnostic[]) {
super(formatApiConfigErrorMessage(diagnostics));
this.name = "ApiConfigError";
this.diagnostics = diagnostics.map(redactDiagnostic);
}
get details(): ApiConfigErrorDetails {
return {
diagnostics: this.diagnostics,
};
}
}
export function loadRequiredApiConfig(env: EnvRecord = process.env, options: RequiredApiConfigOptions = {}): ApiConfig {
const result = loadApiConfig(env, options);
if (result.ok) {
return result.config;
}
throw new ApiConfigError(result.diagnostics);
}
export function loadApiConfig(env: EnvRecord = process.env, options: ApiConfigOptions = {}): ApiConfigResult {
const nodeEnv = options.nodeEnv ?? env.NODE_ENV ?? DEFAULT_NODE_ENV;
const routing = getDomainRoutingConfig({ ...env, NODE_ENV: nodeEnv });
const portResult = normalizeListenPort(env.API_PORT, env.PORT);
const diagnostics: ApiConfigDiagnostic[] = [
...toDiagnostics(
validateEnv(env, {
target: "api",
nodeEnv,
includeOptionalProviders: options.includeOptionalProviders,
extraRequired: options.extraRequired,
}).missing
),
];
if (portResult.diagnostic) {
diagnostics.push(portResult.diagnostic);
}
const config: ApiConfig = {
appName: present(env.APP_NAME) ?? DEFAULT_APP_NAME,
nodeEnv,
revision: present(env.APP_REVISION) ?? "unknown",
listen: {
port: portResult.port,
},
routing,
origins: {
web: present(env.WEB_ORIGIN),
admin: present(env.ADMIN_ORIGIN),
},
apiAccessToken: present(env.API_ACCESS_TOKEN),
jwtSecret: present(env.JWT_SECRET),
analytics: {
token: present(env.ANALYTICS_TOKEN),
},
mailjet: {
webhookSecret: present(env.MAILJET_WEBHOOK_SECRET),
},
stripe: {
secretKey: present(env.STRIPE_SK),
webhookSigningSecret: present(env.STRIPE_WEBHOOK_SIGNING_SECRET),
},
storage: {
endpoint: present(env.STORAGE_ENDPOINT),
region: present(env.STORAGE_REGION),
bucket: present(env.STORAGE_BUCKET),
accessKeyId: present(env.STORAGE_ACCESS_KEY_ID),
secretAccessKey: present(env.STORAGE_SECRET_ACCESS_KEY),
sessionToken: present(env.STORAGE_SESSION_TOKEN),
publicBaseUrl: present(env.STORAGE_PUBLIC_BASE_URL),
forcePathStyle: present(env.STORAGE_FORCE_PATH_STYLE),
},
apiKeys: {
allowLegacyPlaintextFallback: parseBooleanFlag(env.API_KEY_LEGACY_PLAINTEXT_FALLBACK, false),
},
};
return {
ok: diagnostics.length === 0,
config,
diagnostics,
};
}
function parseBooleanFlag(value: string | undefined, defaultValue: boolean): boolean {
const normalized = present(value)?.toLowerCase();
if (normalized === undefined) {
return defaultValue;
}
if (["1", "true", "yes", "on"].includes(normalized)) {
return true;
}
if (["0", "false", "no", "off"].includes(normalized)) {
return false;
}
return defaultValue;
}
function normalizeListenPort(apiPort: string | undefined, port: string | undefined): { port: number; diagnostic?: ApiConfigDiagnostic } {
const selected = present(apiPort) !== undefined ? { name: "API_PORT", value: apiPort } : { name: "PORT", value: port };
const trimmed = selected.value?.trim();
if (!trimmed) {
return { port: DEFAULT_LISTEN_PORT };
}
const parsed = Number(trimmed);
if (!Number.isInteger(parsed) || parsed < MIN_PORT || parsed > MAX_PORT) {
return {
port: DEFAULT_LISTEN_PORT,
diagnostic: {
code: "invalid-port",
name: selected.name,
classification: getEnvVariableDefinition(selected.name)?.classification,
message: `${selected.name} must be an integer between 1 and 65535. Falling back to 3001.`,
},
};
}
return { port: parsed };
}
function toDiagnostics(issues: ReturnType<typeof validateEnv>["missing"]): ApiConfigDiagnostic[] {
return issues.map((issue) => ({
code: "missing-required",
name: issue.name,
classification: issue.classification,
message: issue.message,
}));
}
function formatApiConfigErrorMessage(diagnostics: readonly ApiConfigDiagnostic[]): string {
const summary = diagnostics.map((diagnostic) => `${diagnostic.name}:${diagnostic.code}`).join(", ");
return `Invalid API configuration (${summary}).`;
}
function redactDiagnostic(diagnostic: ApiConfigDiagnostic): ApiConfigDiagnostic {
return {
code: diagnostic.code,
name: diagnostic.name,
classification: diagnostic.classification,
message: diagnostic.message,
};
}
function present(value: string | undefined): string | undefined {
const trimmed = value?.trim();
return trimmed ? trimmed : undefined;
}
@@ -0,0 +1,121 @@
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { describe, expect, test } from "vitest";
import { getEnvVariableDefinition, getRequiredEnvVariableNames, groupEnvVariablesByClassification } from "./index.js";
const envVarsDocument = readFileSync(resolve(process.cwd(), "docs/env-vars.md"), "utf8");
describe("env catalog", () => {
test("looks up dynamic SITE_KEY_* definitions without requiring a concrete catalog entry", () => {
expect(getEnvVariableDefinition("SITE_KEY_BOOKING")?.dynamicPrefix).toBe("SITE_KEY_");
expect(getEnvVariableDefinition("SITE_KEY_COMMUNITY")?.name).toBe("SITE_KEY_*");
});
test("classifies worker Redis keys and opt-in toggle", () => {
expect(getEnvVariableDefinition("WORKER_ENABLED")).toMatchObject({
classification: "optional-provider",
targets: ["worker"],
source: "code-and-example",
defaultValue: "false",
});
expect(getEnvVariableDefinition("BULLMQ_REDIS_URL")).toMatchObject({
classification: "optional-provider",
targets: ["web", "api", "worker"],
source: "code-and-example",
});
expect(getEnvVariableDefinition("REDIS_URL")).toMatchObject({
classification: "optional-provider",
targets: ["web", "api", "worker"],
source: "code",
});
expect(getEnvVariableDefinition("EMAIL_QUEUE_NAME")).toMatchObject({
classification: "optional-provider",
targets: ["worker"],
source: "code",
defaultValue: "toolctrl.email",
});
expect(getEnvVariableDefinition("WORKFLOW_QUEUE_NAME")).toMatchObject({
classification: "optional-provider",
targets: ["worker"],
source: "code",
defaultValue: "toolctrl.workflows",
});
expect(getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.description).toContain("plugin");
expect(getEnvVariableDefinition("WORKER_CONCURRENCY_PLUGIN")).toMatchObject({
classification: "optional-provider",
targets: ["worker"],
source: "code-and-example",
defaultValue: "5",
});
expect(getEnvVariableDefinition("WORKER_REDIS_POOL_SIZE")?.notes).toContain("plugin=4");
});
test("keeps active Crisp usage out of deprecated-only classification", () => {
expect(getEnvVariableDefinition("CRISP_CHAT_WEBSITE_ID")).toMatchObject({
classification: "optional-provider",
targets: ["web"],
source: "code-and-example",
});
});
test("catalogs active operational runtime toggles", () => {
expect(getEnvVariableDefinition("TOOLCTRL_API_MAINTENANCE_MODE")).toMatchObject({
classification: "production-only",
targets: ["api"],
source: "code",
});
expect(getEnvVariableDefinition("WEB_BUILD_DIRECTORY")).toMatchObject({
classification: "production-only",
targets: ["web"],
source: "code",
});
});
test("groups required production keys without optional worker fallback keys", () => {
expect(getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" })).toEqual(
expect.arrayContaining(["APP_NAME", "DATABASE_URL"])
);
expect(getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" })).not.toEqual(
expect.arrayContaining(["WORKER_ENABLED", "BULLMQ_REDIS_URL", "REDIS_URL", "SITE_KEY_*"])
);
expect(groupEnvVariablesByClassification()["optional-provider"].map((definition) => definition.name)).toEqual(
expect.arrayContaining(["WORKER_ENABLED", "BULLMQ_REDIS_URL", "REDIS_URL", "CRISP_CHAT_WEBSITE_ID", "SITE_KEY_*"])
);
});
test("documents production-required and active provider keys in env-vars", () => {
const requiredKeys = new Set([
...getRequiredEnvVariableNames({ target: "web", nodeEnv: "production" }),
...getRequiredEnvVariableNames({ target: "api", nodeEnv: "production" }),
...getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" }),
]);
for (const key of requiredKeys) {
expect(envVarsDocument, `docs/env-vars.md missing required key ${key}`).toContain(`\`${key}\``);
}
for (const key of [
"STRIPE_SK",
"STRIPE_WEBHOOK_SIGNING_SECRET",
"PORTAL_SERVER_URL",
"PORTAL_SERVER_FLY_TOKEN",
"IMPORT_QUEUE_ENABLED",
"IMPORT_QUEUE_RUNTIME_READY",
]) {
expect(envVarsDocument, `docs/env-vars.md missing active optional key ${key}`).toContain(`\`${key}\``);
}
});
test("targets provider keys consumed by web config to the web runtime", () => {
for (const key of ["STRIPE_WEBHOOK_SIGNING_SECRET", "MAILJET_API_KEY", "MAILJET_SECRET_KEY", "MAILJET_FROM_EMAIL", "MAILJET_FROM_NAME"]) {
expect(getEnvVariableDefinition(key)?.targets, `${key} must include web because loadWebConfig consumes it`).toContain("web");
}
});
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,158 @@
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, resolve } from "node:path";
import { describe, expect, test } from "vitest";
import { getEnvVariableDefinition } from "./index.js";
const rootPath = (...segments: string[]) => resolve(process.cwd(), ...segments);
const readProjectFile = (path: string) => readFileSync(rootPath(path), "utf8");
const scannedProductionFiles = [
"apps/api/src/config.ts",
"apps/api/src/app.ts",
"apps/worker/src/runtime.ts",
"apps/worker/src/health.ts",
"packages/queue/src/connection.ts",
"packages/mail/src/mailjet.ts",
"packages/config/src/api.ts",
"packages/config/src/web.ts",
"packages/config/src/worker.ts",
"packages/config/src/routing.ts",
] as const;
const providerBoundaryFiles = new Set<string>([
"apps/api/src/app.ts",
"apps/worker/src/runtime.ts",
"apps/worker/src/health.ts",
"packages/queue/src/connection.ts",
"packages/config/src/api.ts",
"packages/config/src/web.ts",
"packages/config/src/worker.ts",
"packages/config/src/routing.ts",
]);
const packageEnvReadBaseline = new Set<string>([
"packages/cli/src/commands/dsgvo/delete.ts",
"packages/cli/src/commands/feature-flags/invalidate.ts",
"packages/cli/src/commands/tenant/list-snapshots.ts",
"packages/cli/src/commands/tenant/restore.ts",
"packages/config/src/api.ts",
"packages/config/src/routing.ts",
"packages/config/src/web.ts",
"packages/config/src/worker.ts",
"packages/db/src/client.server.ts",
"packages/db/src/seed.server.ts",
"packages/logger/src/index.ts",
"packages/mail/scripts/preview-server.ts",
"packages/feature-flags/src/publisher.ts",
"packages/queue/src/connection.ts",
"packages/queue/src/priority.ts",
"packages/shared-store/src/factory.ts",
]);
const catalogGuardKeys = ["API_PORT", "WEB_ORIGIN", "ADMIN_ORIGIN", "PORT", "HOST", "SITE_KEY_EXAMPLE_SITE"] as const;
type DirectEnvRead = {
file: string;
key: string;
};
function stripComments(source: string) {
return source
.replace(/\/\*[\s\S]*?\*\//g, "")
.split(/\r?\n/)
.map((line) => line.replace(/\/\/.*$/, ""))
.join("\n");
}
function findDirectEnvReads(file: string, source: string): DirectEnvRead[] {
const executableSource = stripComments(source);
const directReads = [
...executableSource.matchAll(/\bprocess\.env\.([A-Z][A-Z0-9_]*)\b/g),
...executableSource.matchAll(/\bprocess\.env\[(["'])([A-Z][A-Z0-9_]*)\1\]/g),
];
return directReads.map((match) => ({ file, key: match[2] ?? match[1] }));
}
function formatDirectEnvReads(directReads: readonly DirectEnvRead[]) {
return directReads.map(({ file, key }) => `${file}:${key}`).join(", ");
}
function listSourceFiles(root: string): string[] {
const absoluteRoot = rootPath(root);
const ignoredSegments = new Set(["generated", "dist", "build", "node_modules"]);
const files: string[] = [];
function walk(directory: string) {
for (const entry of readdirSync(directory)) {
if (ignoredSegments.has(entry)) {
continue;
}
const absolutePath = join(directory, entry);
const stats = statSync(absolutePath);
if (stats.isDirectory()) {
walk(absolutePath);
continue;
}
if (!/\.(ts|tsx|mts|cts)$/.test(entry) || /\.test\./.test(entry) || /\.spec\./.test(entry)) {
continue;
}
files.push(absolutePath.replace(`${process.cwd()}/`, ""));
}
}
walk(absoluteRoot);
return files.sort();
}
describe("approved env boundary enforcement", () => {
test("detects dot and bracket process.env reads after stripping comments", () => {
const directReads = findDirectEnvReads(
"inline-sample.ts",
`
// process.env.JWT_SECRET is documentation only.
const token = process.env.API_ACCESS_TOKEN;
const port = process.env["API_PORT"];
`
);
expect(directReads).toEqual([
{ file: "inline-sample.ts", key: "API_ACCESS_TOKEN" },
{ file: "inline-sample.ts", key: "API_PORT" },
]);
});
test("keeps direct production env reads inside approved provider boundaries", () => {
const directReads = scannedProductionFiles.flatMap((file) => findDirectEnvReads(file, readProjectFile(file)));
const forbiddenReads = directReads.filter(({ file }) => !providerBoundaryFiles.has(file));
expect(forbiddenReads, `Forbidden direct env reads: ${formatDirectEnvReads(forbiddenReads)}`).toEqual([]);
});
test("blocks new package-level direct env reads outside the reviewed baseline", () => {
const filesWithDirectReads = listSourceFiles("packages").filter((file) => findDirectEnvReads(file, readProjectFile(file)).length > 0);
const unexpectedFiles = filesWithDirectReads.filter((file) => !packageEnvReadBaseline.has(file));
expect(unexpectedFiles, `Unexpected package env reads: ${unexpectedFiles.join(", ")}`).toEqual([]);
});
test("catalogs protected API, platform and dynamic env keys", () => {
for (const key of catalogGuardKeys) {
expect(getEnvVariableDefinition(key), `${key} must resolve to an env catalog entry or dynamic prefix entry`).toBeDefined();
}
expect(getEnvVariableDefinition("SITE_KEY_EXAMPLE_SITE")).toMatchObject({
name: "SITE_KEY_*",
dynamicPrefix: "SITE_KEY_",
});
});
test("keeps S06 enforcement ownership visible in the inventory without reading env value files", () => {
const inventory = readProjectFile("docs/env-access-inventory.md");
expect(inventory).toContain("S06 enforcement");
});
});
@@ -0,0 +1,205 @@
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { describe, expect, test } from "vitest";
import { getEnvVariableDefinition, getRequiredEnvVariableNames, listEnvVariables, validateEnv } from "./index.js";
const representativeDefinitions = {
APP_NAME: { classification: "required-core", targets: ["shared", "web", "api", "worker"], source: "code-and-example" },
DATABASE_URL: { classification: "required-core", targets: ["shared", "web", "api", "worker"], source: "code-and-example" },
SESSION_SECRET: { classification: "required-core", targets: ["web", "api"], source: "code-and-example" },
API_ACCESS_TOKEN: { classification: "required-per-app", targets: ["web", "api"], source: "code-and-example" },
JWT_SECRET: { classification: "required-per-app", targets: ["web", "api"], source: "code-and-example" },
ANALYTICS_TOKEN: { classification: "required-per-app", targets: ["api"], source: "code" },
APP_REVISION: { classification: "production-only", targets: ["shared", "web", "api", "worker"], source: "runtime" },
WORKER_ENABLED: { classification: "optional-provider", targets: ["worker"], source: "code-and-example" },
EMAIL_QUEUE_NAME: { classification: "optional-provider", targets: ["worker"], source: "code" },
WORKFLOW_QUEUE_NAME: { classification: "optional-provider", targets: ["worker"], source: "code" },
BULLMQ_REDIS_URL: { classification: "optional-provider", targets: ["web", "api", "worker"], source: "code-and-example" },
REDIS_URL: { classification: "optional-provider", targets: ["web", "api", "worker"], source: "code" },
BROWSER_RUNTIME_URL: { classification: "optional-provider", targets: ["api", "worker"], source: "code-and-example" },
BROWSER_RUNTIME_API_KEY: { classification: "optional-provider", targets: ["api", "worker"], source: "code-and-example" },
BROWSER_SESSION_TIMEOUT_MS: { classification: "optional-provider", targets: ["api", "worker"], source: "code-and-example" },
TOOLCTRL_API_MAINTENANCE_MODE: { classification: "production-only", targets: ["api"], source: "code" },
TOOLCTRL_API_MAINTENANCE_RETRY_AFTER_SECONDS: { classification: "production-only", targets: ["api"], source: "code" },
WEB_BUILD_DIRECTORY: { classification: "production-only", targets: ["web"], source: "code" },
CRISP_CHAT_WEBSITE_ID: { classification: "optional-provider", targets: ["web"], source: "code-and-example" },
WEB_ORIGIN: { classification: "optional-provider", targets: ["api", "worker"], source: "code" },
ADMIN_ORIGIN: { classification: "optional-provider", targets: ["api"], source: "code" },
} as const;
const inventoryDocument = readFileSync(resolve(process.cwd(), "docs/env-access-inventory.md"), "utf8");
const sourceAccessTable = inventoryDocument.slice(inventoryDocument.indexOf("## Source-access table"), inventoryDocument.indexOf("## Example-file-only keys"));
const followUpMapping = inventoryDocument.slice(inventoryDocument.indexOf("## Follow-up mapping"));
describe("env access inventory contract", () => {
test("looks up representative catalog definitions used by web, api, and worker migration owners", () => {
for (const [name, expected] of Object.entries(representativeDefinitions)) {
expect(getEnvVariableDefinition(name), name).toMatchObject(expected);
}
expect(getEnvVariableDefinition("SITE_KEY_EXAMPLE_SITE")).toMatchObject({
name: "SITE_KEY_*",
classification: "optional-provider",
targets: ["api"],
source: "dynamic",
dynamicPrefix: "SITE_KEY_",
});
});
test("keeps unknown dynamic site keys matched by prefix while unrelated keys stay uncataloged", () => {
expect(getEnvVariableDefinition("SITE_KEY_UNKNOWN_SITE")).toMatchObject({
name: "SITE_KEY_*",
dynamicPrefix: "SITE_KEY_",
});
expect(getEnvVariableDefinition("SITEKEY_UNKNOWN_SITE")).toBeUndefined();
});
test("lists target-specific env variables for later web, api, and worker loaders", () => {
expect(listEnvVariables({ target: "web" }).map((definition) => definition.name)).toEqual(
expect.arrayContaining([
"APP_NAME",
"DATABASE_URL",
"SESSION_SECRET",
"API_ACCESS_TOKEN",
"JWT_SECRET",
"CRISP_CHAT_WEBSITE_ID",
"BULLMQ_REDIS_URL",
])
);
expect(listEnvVariables({ target: "api" }).map((definition) => definition.name)).toEqual(
expect.arrayContaining([
"APP_NAME",
"DATABASE_URL",
"SESSION_SECRET",
"API_ACCESS_TOKEN",
"JWT_SECRET",
"ANALYTICS_TOKEN",
"BULLMQ_REDIS_URL",
"REDIS_URL",
"WEB_ORIGIN",
"ADMIN_ORIGIN",
"SITE_KEY_*",
])
);
expect(listEnvVariables({ target: "worker" }).map((definition) => definition.name)).toEqual(
expect.arrayContaining([
"APP_NAME",
"DATABASE_URL",
"WORKER_ENABLED",
"APP_URL",
"WEB_ORIGIN",
"EMAIL_QUEUE_NAME",
"WORKFLOW_QUEUE_NAME",
"WORKFLOW_TRIGGER_EXECUTOR_MODE",
"WORKFLOW_TRIGGER_EXECUTOR_URL",
"OUTBOX_DISPATCHER_REQUIRED",
"WORKFLOW_TRIGGER_OUTBOX_REQUIRED",
"BULLMQ_REDIS_URL",
"REDIS_URL",
"BROWSER_RUNTIME_URL",
"BROWSER_RUNTIME_API_KEY",
"BROWSER_SESSION_TIMEOUT_MS",
])
);
expect(listEnvVariables({ classification: "deprecated-remove" }).map((definition) => definition.name)).toEqual([]);
});
test("groups required keys per runtime without promoting optional worker/provider keys", () => {
expect(getRequiredEnvVariableNames({ target: "web", nodeEnv: "production" })).toEqual(
expect.arrayContaining(["APP_NAME", "DATABASE_URL", "SESSION_SECRET", "API_ACCESS_TOKEN", "JWT_SECRET"])
);
expect(getRequiredEnvVariableNames({ target: "api", nodeEnv: "production" })).toEqual(
expect.arrayContaining(["APP_NAME", "DATABASE_URL", "SESSION_SECRET", "API_ACCESS_TOKEN", "JWT_SECRET", "ANALYTICS_TOKEN"])
);
expect(getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" })).toEqual(expect.arrayContaining(["APP_NAME", "DATABASE_URL"]));
expect(getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" })).not.toEqual(
expect.arrayContaining(["WORKER_ENABLED", "BULLMQ_REDIS_URL", "REDIS_URL", "SITE_KEY_*"])
);
});
test("validates missing required env values deterministically without reading process.env", () => {
const apiResult = validateEnv({}, { target: "api", nodeEnv: "production" });
expect(apiResult.ok).toBe(false);
expect(apiResult.missing).toEqual(
expect.arrayContaining([
expect.objectContaining({ name: "APP_NAME", classification: "required-core" }),
expect.objectContaining({ name: "DATABASE_URL", classification: "required-core" }),
expect.objectContaining({ name: "ANALYTICS_TOKEN", classification: "required-per-app" }),
])
);
expect(apiResult.missing.map((issue) => issue.name)).not.toContain("SITE_KEY_*");
expect(
validateEnv(
{
ADMIN_APP_HOST: "admin.example.com",
API_ACCESS_TOKEN: "api-token",
API_HOST: "api.example.com",
APP_BASE_DOMAIN: "example.com",
APP_NAME: "Boilerplate",
CRYPTO_SECRET: "crypto-secret",
DATABASE_URL: "postgresql://user:pass@localhost:5432/app",
JWT_SECRET: "jwt-secret",
SESSION_SECRET: "session-secret",
ANALYTICS_TOKEN: "analytics-token",
WEB_APP_HOST: "app.example.com",
},
{ target: "api", nodeEnv: "production" }
)
).toEqual({ ok: true, missing: [] });
});
test("documents inventory scan evidence and follow-up owners without relying on prose wording", () => {
expect(inventoryDocument).toContain("## Scan command");
expect(inventoryDocument).toContain("grep -R \"process\\.env\\|env(\"");
for (const owner of ["S02 web", "S03 api", "S04 worker", "S05 docs", "S06 enforcement"]) {
expect(inventoryDocument).toContain(`| ${owner} |`);
}
for (const key of ["APP_NAME", "DATABASE_URL", "SESSION_SECRET", "ANALYTICS_TOKEN", "WORKER_ENABLED", "EMAIL_QUEUE_NAME", "WORKFLOW_QUEUE_NAME", "SITE_KEY_EXAMPLE_SITE"]) {
expect(inventoryDocument).toContain(`\`${key}\``);
}
});
test("locks stable inventory wording for S05/S06 owners and dynamic/fallback key semantics", () => {
expect(followUpMapping).toContain("| S05 docs | Example and documentation alignment, fallback wording, deprecated/example-only cleanup |");
expect(followUpMapping).toContain("`BULLMQ_REDIS_URL` as primary");
expect(followUpMapping).toContain("`REDIS_URL` as fallback only when `BULLMQ_REDIS_URL` is absent");
expect(followUpMapping).toContain("| S06 enforcement | Future direct-read guardrails and drift tests |");
expect(followUpMapping).toContain("Prefix support for `SITE_KEY_*`");
expect(followUpMapping).toContain("CORS-origin catalog drift checks for `WEB_ORIGIN` and `ADMIN_ORIGIN`");
expect(sourceAccessTable).toContain("| `BULLMQ_REDIS_URL` |");
expect(sourceAccessTable).toContain("Primary BullMQ Redis URL for web/API enqueue and worker queues");
expect(sourceAccessTable).toContain("| `REDIS_URL` |");
expect(sourceAccessTable).toContain("BullMQ fallback only when `BULLMQ_REDIS_URL` is absent");
expect(sourceAccessTable).toContain("| `SITE_KEY_*` |");
expect(sourceAccessTable).toContain("Must be matched by prefix, not enumerated as one literal key");
expect(sourceAccessTable).toContain("| `WEB_ORIGIN` |");
expect(sourceAccessTable).toContain("| `ADMIN_ORIGIN` |");
});
test("documents the env drift gate contract and redaction boundary", () => {
expect(inventoryDocument).toContain("## env drift gate contract");
expect(inventoryDocument).toContain("`pnpm run verify:env-drift`");
expect(inventoryDocument).toContain("`scripts/check-env-drift.mjs`");
expect(inventoryDocument).toContain("`.env.test`");
for (const fixturePath of [".env.example", ".env.local.example", ".env.production.example", ".env.fly.example", ".env.test"]) {
expect(inventoryDocument).toContain(`\`${fixturePath}\``);
}
expect(inventoryDocument).toContain("immediately after `pnpm run verify:ci-baseline` and before `pnpm typecheck`");
expect(inventoryDocument).toContain("No secret values, placeholder values, or raw `.env` assignments may be emitted");
});
test("documents scan evidence without using raw env value files as fixtures", () => {
expect(inventoryDocument).toContain("No secret values were copied from `.env*` files");
expect(inventoryDocument).toContain("key names and paths only");
expect(inventoryDocument).not.toMatch(/expected secret value/i);
expect(inventoryDocument).not.toMatch(/fixture value/i);
expect(inventoryDocument).not.toContain("DATABASE_URL=postgres");
expect(inventoryDocument).not.toContain("JWT_SECRET=");
expect(inventoryDocument).not.toContain("SESSION_SECRET=");
});
});
@@ -0,0 +1,165 @@
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { describe, expect, test } from "vitest";
import { envVariableDefinitions, getEnvVariableDefinition } from "./index.js";
import type { EnvVariableDefinition } from "./types.js";
const examplePaths = [".env.example", ".env.local.example", ".env.production.example", ".env.fly.example", ".env.test"] as const;
const safeEnvFixturePaths = [".env.example", ".env.local.example", ".env.production.example", ".env.fly.example", ".env.test"] as const;
const rootPath = (...segments: string[]) => resolve(process.cwd(), ...segments);
const readProjectFile = (path: string) => readFileSync(rootPath(path), "utf8");
function parseEnvExampleKeys(contents: string) {
return contents
.split(/\r?\n/)
.map((line) => line.trim())
.map((line) => line.replace(/^#\s*/, ""))
.map((line) => line.replace(/\\$/, "").trim())
.map((line) => {
const match = /^(?:[A-Za-z_][A-Za-z0-9_]*\s+)*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
return match?.[1];
})
.filter((key): key is string => Boolean(key));
}
function parseUncommentedEnvExampleKeys(contents: string) {
return contents
.split(/\r?\n/)
.filter((line) => !line.trimStart().startsWith("#"))
.map((line) => line.trim().replace(/\\$/, "").trim())
.map((line) => /^(?:[A-Za-z_][A-Za-z0-9_]*\s+)*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1])
.filter((key): key is string => Boolean(key));
}
function parseEnvAssignments(contents: string) {
return contents
.split(/\r?\n/)
.filter((line) => !line.trimStart().startsWith("#"))
.map((line) => line.trim().replace(/\\$/, "").trim())
.map((line) => {
const match = /^(?:[A-Za-z_][A-Za-z0-9_]*\s+)*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
if (!match) {
return undefined;
}
return [match[1], match[2].trim().replace(/^(["'])(.*)\1$/, "$2")] as const;
})
.filter((assignment): assignment is readonly [string, string] => Boolean(assignment));
}
const catalogNames = new Set<string>(envVariableDefinitions.map((definition) => definition.name));
// Pre-existing example keys that are documented in .env.example but not yet promoted into the
// typed env catalog. Kept as an explicit baseline so future drift still trips the contract.
const exampleOnlyBaseline = new Set<string>([
"FORM_WIDGET_CDN_URL",
"AI_OVERAGE_SUBMISSION_ENABLED",
]);
const catalogedOrDynamicSiteKey = (key: string) =>
Boolean(getEnvVariableDefinition(key as EnvVariableDefinition["name"])) || key.startsWith("SITE_KEY_") || exampleOnlyBaseline.has(key);
const secretLikeKeyPattern = /(?:SECRET|TOKEN|KEY|PASSWORD|WEBHOOK_SIGNING_SECRET|ACCESS_TOKEN|JWT)/i;
const safePlaceholderValuePattern = /^(?:|test[-\w.:@/?=&]+|replace-with[-\w.]+|<[-\w]+>|\{[A-Z_]+\}|YOUR_[A-Z_]+|https:\/\/\.\.\.ngrok-free\.app|https:\/\/your-project\.supabase\.co|https:\/\/formspree\.io\/f\/example|G-XXXXXXXXXX|FlyV1 <portal-token>)$/;
describe("env example drift contract", () => {
test.each(examplePaths)("catalogs every example key in %s", (path) => {
const keys = parseEnvExampleKeys(readProjectFile(path));
const unknownKeys = keys.filter((key) => !catalogedOrDynamicSiteKey(key));
expect(unknownKeys, `${path} contains uncataloged env keys: ${unknownKeys.join(", ")}`).toEqual([]);
});
test("keeps only explicit safe env fixtures versionable", () => {
const gitignore = readProjectFile(".gitignore");
expect(gitignore).toMatch(/^\.env$/m);
expect(gitignore).toMatch(/^\.env\.\*$/m);
expect(gitignore).toMatch(/^!\.env\.test$/m);
expect(gitignore).not.toMatch(/^!\.env$/m);
expect(gitignore).not.toMatch(/^!\.env\.\*$/m);
for (const path of safeEnvFixturePaths) {
expect(gitignore, `${path} must be explicitly allowlisted`).toMatch(new RegExp(`^!${path.replace(/\./g, "\\.")}$`, "m"));
}
});
test("keeps .env.test non-secret and cataloged without exposing values", () => {
const path = ".env.test";
const contents = readProjectFile(path);
const assignments = parseEnvAssignments(contents);
const keys = assignments.map(([key]) => key);
const unknownKeys = keys.filter((key) => !catalogedOrDynamicSiteKey(key));
const suspiciousKeys = assignments
.filter(([key, value]) => secretLikeKeyPattern.test(key) && !safePlaceholderValuePattern.test(value))
.map(([key]) => key);
expect(unknownKeys, `${path} contains uncataloged env keys: ${unknownKeys.join(", ")}`).toEqual([]);
expect(suspiciousKeys, `${path} contains secret-looking fixture values for keys: ${suspiciousKeys.join(", ")}`).toEqual([]);
expect(keys).toEqual(expect.arrayContaining(["APP_NAME", "DATABASE_URL", "SESSION_SECRET", "CRYPTO_SECRET", "API_ACCESS_TOKEN", "JWT_SECRET", "WORKER_ENABLED", "BULLMQ_REDIS_URL"]));
});
test("keeps platform and runtime keys explicitly cataloged", () => {
for (const key of ["NODE_ENV", "PORT", "HOST", "WORKER_ENABLED", "BULLMQ_REDIS_URL", "REDIS_URL", "BROWSER_RUNTIME_URL", "BROWSER_RUNTIME_API_KEY", "BROWSER_SESSION_TIMEOUT_MS"]) {
expect(catalogNames.has(key), `${key} must be an explicit catalog entry, not an example-only exemption`).toBe(true);
}
});
test("keeps the shared example aligned with core, worker, and browser runtime keys", () => {
const contents = readProjectFile(".env.example");
const keys = parseEnvExampleKeys(contents);
expect(keys).toEqual(
expect.arrayContaining([
"APP_NAME",
"DATABASE_URL",
"SESSION_SECRET",
"CRYPTO_SECRET",
"APP_BASE_DOMAIN",
"WEB_APP_HOST",
"ADMIN_APP_HOST",
"API_HOST",
"API_ACCESS_TOKEN",
"JWT_SECRET",
"MAILJET_API_KEY",
"MAILJET_SECRET_KEY",
"MAILJET_FROM_EMAIL",
"STRIPE_ACCOUNT_COUNTRY",
"WORKER_ENABLED",
"WORKER_QUEUE_GROUP",
"WORKER_CONCURRENCY_PLUGIN",
"BULLMQ_REDIS_URL",
"BROWSER_RUNTIME_URL",
"BROWSER_RUNTIME_API_KEY",
"BROWSER_SESSION_TIMEOUT_MS",
])
);
expect(keys).not.toEqual(expect.arrayContaining(["CRISP_CHAT_WEBSITE_ID"]));
expect(contents).not.toContain("CRISP_CHAT_WEBSITE_ID");
});
test.each([".env.production.example", ".env.fly.example"] as const)("documents worker runtime keys in %s without required REDIS_URL", (path) => {
const contents = readProjectFile(path);
const keys = parseEnvExampleKeys(contents);
const requiredKeys = parseUncommentedEnvExampleKeys(contents);
expect(keys).toEqual(
expect.arrayContaining([
"BULLMQ_REDIS_URL",
])
);
expect(requiredKeys, `${path} must not make REDIS_URL an uncommented required key`).not.toContain("REDIS_URL");
if (path === ".env.fly.example") {
expect(requiredKeys, `${path} must not pin worker enablement in shared Fly secrets`).not.toContain("WORKER_ENABLED");
} else {
expect(keys).toContain("WORKER_ENABLED");
}
});
test("documents REDIS_URL as a fallback and keeps S05/S06 inventory owners visible", () => {
const inventory = readProjectFile("docs/env-access-inventory.md");
expect(inventory).toMatch(/`REDIS_URL`[^\n]*fallback only when `BULLMQ_REDIS_URL` is absent/i);
expect(inventory).toMatch(/\|[^\n]*\|[^\n]*\|[^\n]*\|[^\n]*\|[^\n]*S05 docs[^\n]*\|/);
expect(inventory).toMatch(/\|[^\n]*\|[^\n]*\|[^\n]*\|[^\n]*\|[^\n]*S06 enforcement[^\n]*\|/);
});
});
+148
View File
@@ -0,0 +1,148 @@
import { envVariableDefinitions } from "./catalog.js";
export { getDomainRoutingConfig, hostMatches, normalizeHost } from "./routing.js";
export { ApiConfigError, loadApiConfig, loadRequiredApiConfig } from "./api.js";
export { WebConfigError, loadRequiredWebConfig, loadWebConfig } from "./web.js";
export { resolveApiSessionCookiePolicy, resolveSessionCookiePolicy } from "./session-cookie.js";
export { WorkerConfigError, loadRequiredWorkerConfig, loadWorkerConfig } from "./worker.js";
export { resolvePluginLifecycleRuntimeEnv } from "./plugin-lifecycle.js";
export { validateBooleanFlag, validateOptionalSecretString, validateOptionalSecretUrl, validateRequiredSecretString } from "./secret-validator.js";
import type { EnvClassification, EnvRecord, EnvValidationOptions, EnvValidationResult, EnvVariableDefinition, RuntimeTarget } from "./types.js";
export type { DomainRoutingConfig, DomainRoutingEnv } from "./routing.js";
export type { PluginLifecycleRuntimeEnv } from "./plugin-lifecycle.js";
export type { ResolveApiSessionCookiePolicyOptions, ResolveSessionCookiePolicyOptions, SessionCookiePolicy, SessionCookieSameSite } from "./session-cookie.js";
const definitions: readonly EnvVariableDefinition[] = envVariableDefinitions;
export { envVariableDefinitions } from "./catalog.js";
export type {
ApiConfig,
ApiConfigAnalytics,
ApiConfigDiagnostic,
ApiConfigDiagnosticCode,
ApiConfigErrorDetails,
ApiConfigListen,
ApiConfigMailjet,
ApiConfigOptions,
ApiConfigOrigins,
ApiConfigResult,
ApiConfigStorage,
RequiredApiConfigOptions,
WorkerConfig,
WorkerConfigDiagnostic,
WorkerConfigDiagnosticCode,
WorkerConfigOptions,
WorkerConfigQueues,
WorkerConfigRedis,
WorkerConfigRedisParseStatus,
WorkerConfigRedisSource,
WorkerConfigResult,
RequiredWorkerConfigOptions,
RequiredWebConfigOptions,
WebConfig,
WebConfigDiagnostic,
WebConfigDiagnosticCode,
WebConfigErrorDetails,
WebConfigListen,
WebConfigOptions,
WebConfigResult,
WebConfigRouting,
WebConfigStorage,
EnvAuditSource,
EnvClassification,
EnvRecord,
EnvValidationIssue,
EnvValidationOptions,
EnvValidationResult,
EnvValueKind,
SecretUrlValidationOptions,
SecretValidationDiagnostic,
SecretValidationDiagnosticCode,
SecretValidationResult,
EnvVariableDefinition,
RuntimeTarget,
} from "./types.js";
export function listEnvVariables(options: { classification?: EnvClassification; target?: RuntimeTarget } = {}) {
return definitions.filter((definition) => {
if (options.classification && definition.classification !== options.classification) {
return false;
}
if (options.target && !definition.targets.includes(options.target)) {
return false;
}
return true;
});
}
export function getEnvVariableDefinition(name: string): EnvVariableDefinition | undefined {
return definitions.find((definition) => {
if (definition.name === name) {
return true;
}
return definition.dynamicPrefix ? name.startsWith(definition.dynamicPrefix) : false;
});
}
export function groupEnvVariablesByClassification() {
return definitions.reduce<Record<EnvClassification, EnvVariableDefinition[]>>(
(groups, definition) => {
groups[definition.classification].push(definition);
return groups;
},
{
"required-core": [],
"required-per-app": [],
"optional-provider": [],
"local-development-only": [],
"production-only": [],
"deprecated-remove": [],
}
);
}
export function getRequiredEnvVariableNames(options: EnvValidationOptions = {}) {
const target = options.target ?? "web";
const nodeEnv = options.nodeEnv ?? "development";
const required = new Set(options.extraRequired ?? []);
for (const definition of definitions) {
if (!definition.targets.includes(target) && !definition.targets.includes("shared")) {
continue;
}
if ((definition.classification === "required-core" || definition.classification === "required-per-app") && !(nodeEnv !== "production" && definition.defaultValue)) {
required.add(definition.name);
continue;
}
if (nodeEnv === "production" && definition.requiredInProduction) {
required.add(definition.name);
continue;
}
if (options.includeOptionalProviders && definition.classification === "optional-provider") {
required.add(definition.name);
}
}
return [...required].sort();
}
export function validateEnv(input: EnvRecord, options: EnvValidationOptions = {}): EnvValidationResult {
const missing = getRequiredEnvVariableNames(options)
.filter((name) => !name.includes("*"))
.filter((name) => !input[name])
.map((name) => {
const definition = getEnvVariableDefinition(name);
return {
name,
classification: definition?.classification,
message: `${name} is required${options.target ? ` for ${options.target}` : ""}.`,
};
});
return {
ok: missing.length === 0,
missing,
};
}
@@ -0,0 +1,13 @@
import type { EnvRecord } from "./types.js";
export type PluginLifecycleRuntimeEnv = {
readonly nodeEnv: string;
readonly requireCapabilityConsent: boolean;
};
export function resolvePluginLifecycleRuntimeEnv(env: EnvRecord = {}): PluginLifecycleRuntimeEnv {
return {
nodeEnv: env.NODE_ENV ?? "development",
requireCapabilityConsent: env.PLUGIN_REQUIRE_CAPABILITY_CONSENT !== "false",
};
}
@@ -0,0 +1,55 @@
import { describe, expect, test } from "vitest";
import { getDomainRoutingConfig, hostMatches, normalizeHost } from "./routing.js";
describe("routing config", () => {
test("uses local subdomain defaults", () => {
expect(getDomainRoutingConfig({})).toEqual({
appBaseDomain: "localhost",
webAppHost: "app.localhost",
adminAppHost: "admin.localhost",
apiHost: "api.localhost",
protocol: "http",
});
});
test("preserves local dev ports on derived hosts", () => {
expect(getDomainRoutingConfig({ APP_BASE_DOMAIN: "localhost:3000" })).toMatchObject({
webAppHost: "app.localhost:3000",
adminAppHost: "admin.localhost:3000",
apiHost: "api.localhost:3000",
});
});
test("normalizes explicit hosts", () => {
expect(normalizeHost("https://APP.example.com/path")).toBe("app.example.com");
expect(hostMatches("https://app.example.com", "app.example.com")).toBe(true);
});
test("uses explicit app, admin, api, base domain, and protocol hosts", () => {
expect(
getDomainRoutingConfig({
APP_BASE_DOMAIN: "Example.com",
WEB_APP_HOST: "https://APP.example.com/ignored/path",
ADMIN_APP_HOST: "ADMIN.example.com:8443",
API_HOST: "https://API.example.com/v1",
APP_PROTOCOL: "http",
})
).toEqual({
appBaseDomain: "example.com",
webAppHost: "app.example.com",
adminAppHost: "admin.example.com:8443",
apiHost: "api.example.com",
protocol: "http",
});
});
test("derives canonical subdomains and https for non-local base domains", () => {
expect(getDomainRoutingConfig({ APP_BASE_DOMAIN: "example.com" })).toMatchObject({
appBaseDomain: "example.com",
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
protocol: "https",
});
});
});
@@ -0,0 +1,104 @@
export type DomainRoutingEnv = Record<string, string | undefined> & {
APP_BASE_DOMAIN?: string;
WEB_APP_HOST?: string;
ADMIN_APP_HOST?: string;
API_HOST?: string;
APP_PROTOCOL?: string;
NODE_ENV?: string;
};
export type DomainRoutingConfig = {
appBaseDomain: string;
webAppHost: string;
adminAppHost: string;
apiHost: string;
protocol: "http" | "https";
};
const LOCAL_BASE_DOMAIN = "localhost";
const LOCAL_WEB_APP_HOST = "app.localhost";
const LOCAL_ADMIN_APP_HOST = "admin.localhost";
const LOCAL_API_HOST = "api.localhost";
export function getDomainRoutingConfig(env: DomainRoutingEnv = process.env): DomainRoutingConfig {
const appBaseDomain = normalizeHost(env.APP_BASE_DOMAIN) ?? LOCAL_BASE_DOMAIN;
const derivedHosts = getDerivedHosts(appBaseDomain);
return {
appBaseDomain,
webAppHost: normalizeHost(env.WEB_APP_HOST) ?? derivedHosts.webAppHost,
adminAppHost: normalizeHost(env.ADMIN_APP_HOST) ?? derivedHosts.adminAppHost,
apiHost: normalizeHost(env.API_HOST) ?? derivedHosts.apiHost,
protocol: normalizeProtocol(env.APP_PROTOCOL) ?? (isLocalHost(appBaseDomain) || env.NODE_ENV === "development" ? "http" : "https"),
};
}
export function normalizeHost(value: string | undefined): string | undefined {
const trimmed = value?.trim();
if (!trimmed) {
return undefined;
}
const withProtocol = /^[a-z][a-z\d+\-.]*:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
const url = new URL(withProtocol);
return url.host.toLowerCase();
}
export function hostMatches(actualHost: string | undefined, expectedHost: string | undefined): boolean {
const actual = normalizeHost(actualHost);
const expected = normalizeHost(expectedHost);
if (!actual || !expected) {
return false;
}
if (actual === expected) {
return true;
}
const actualUrl = new URL(`http://${actual}`);
const expectedUrl = new URL(`http://${expected}`);
const bothLocal = isLocalHost(actualUrl.hostname) && isLocalHost(expectedUrl.hostname);
if (!bothLocal || actualUrl.hostname !== expectedUrl.hostname) {
return false;
}
return !actualUrl.port || !expectedUrl.port;
}
function normalizeProtocol(value: string | undefined): DomainRoutingConfig["protocol"] | undefined {
if (value === "http" || value === "https") {
return value;
}
return undefined;
}
function isLocalHost(host: string) {
const hostname = host.split(":")[0];
return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "::1";
}
function getDerivedHosts(baseDomain: string) {
if (isLocalHost(baseDomain)) {
return {
webAppHost: withLocalPort(LOCAL_WEB_APP_HOST, baseDomain),
adminAppHost: withLocalPort(LOCAL_ADMIN_APP_HOST, baseDomain),
apiHost: withLocalPort(LOCAL_API_HOST, baseDomain),
};
}
return {
webAppHost: withSubdomain("app", baseDomain),
adminAppHost: withSubdomain("admin", baseDomain),
apiHost: withSubdomain("api", baseDomain),
};
}
function withLocalPort(defaultHost: string, baseDomain: string) {
const port = normalizeHost(baseDomain)?.split(":")[1];
return port ? `${defaultHost}:${port}` : defaultHost;
}
function withSubdomain(subdomain: string, baseDomain: string) {
const normalizedBaseDomain = normalizeHost(baseDomain) ?? baseDomain;
const [hostname, port] = normalizedBaseDomain.split(":");
return port ? `${subdomain}.${hostname}:${port}` : `${subdomain}.${hostname}`;
}
@@ -0,0 +1,125 @@
import { describe, expect, test } from "vitest";
import { validateBooleanFlag, validateOptionalSecretString, validateOptionalSecretUrl, validateRequiredSecretString } from "./secret-validator.js";
const SECRET_VALUE = "redis://:super-secret-password@redis.example.com:6379/0";
const SENTINEL_INVALID_URL = "redis://:sentinel-invalid-url-secret@";
const SENTINEL_INVALID_PROTOCOL_URL = SECRET_VALUE.replace("redis://", "https://");
const SENTINEL_INVALID_BOOLEAN = "sentinel-invalid-boolean-secret";
const SENTINEL_MISSING_REQUIRED = "sentinel-missing-required-secret";
function expectRedacted(payload: unknown, sentinels: readonly string[] = [SECRET_VALUE, "super-secret-password"]) {
const serialized = JSON.stringify(payload);
for (const sentinel of sentinels) {
expect(serialized).not.toContain(sentinel);
}
}
describe("secret validator", () => {
test("reports missing required values with catalog classification", () => {
const result = validateRequiredSecretString("MAILJET_API_KEY", undefined);
expect(result).toEqual({
ok: false,
configured: false,
diagnostics: [
{
code: "missing-required",
name: "MAILJET_API_KEY",
classification: "optional-provider",
message: "MAILJET_API_KEY is required.",
},
],
});
expectRedacted(result, [SENTINEL_MISSING_REQUIRED]);
});
test("classifies dynamic site keys while leaving unknown names unclassified", () => {
expect(validateRequiredSecretString("SITE_KEY_EXAMPLE_SITE", undefined)).toEqual({
ok: false,
configured: false,
diagnostics: [
{
code: "missing-required",
name: "SITE_KEY_EXAMPLE_SITE",
classification: "optional-provider",
message: "SITE_KEY_EXAMPLE_SITE is required.",
},
],
});
expect(validateRequiredSecretString("UNKNOWN_SECRET_NAME", undefined)).toEqual({
ok: false,
configured: false,
diagnostics: [
{
code: "missing-required",
name: "UNKNOWN_SECRET_NAME",
message: "UNKNOWN_SECRET_NAME is required.",
},
],
});
});
test("treats whitespace-only required secrets as missing and trims valid strings", () => {
expect(validateRequiredSecretString("MAILJET_API_KEY", " ")).toMatchObject({
ok: false,
configured: false,
diagnostics: [expect.objectContaining({ code: "missing-required" })],
});
expect(validateRequiredSecretString("MAILJET_API_KEY", " mailer-key ")).toMatchObject({
ok: true,
configured: true,
value: "mailer-key",
diagnostics: [],
});
});
test("normalizes optional strings without treating empty input as configured", () => {
expect(validateOptionalSecretString("MAILJET_FROM_NAME", " ")).toEqual({
ok: true,
configured: false,
value: undefined,
diagnostics: [],
});
expect(validateOptionalSecretString("MAILJET_FROM_NAME", " Support ")).toMatchObject({
ok: true,
configured: true,
value: "Support",
});
});
test("validates optional URLs and rejects invalid protocol without leaking values", () => {
const invalidUrl = validateOptionalSecretUrl("BULLMQ_REDIS_URL", SENTINEL_INVALID_URL, { allowedProtocols: ["redis", "rediss"] });
const invalidProtocol = validateOptionalSecretUrl("BULLMQ_REDIS_URL", SENTINEL_INVALID_PROTOCOL_URL, { allowedProtocols: ["redis", "rediss"] });
expect(invalidUrl).toMatchObject({
ok: false,
configured: true,
diagnostics: [expect.objectContaining({ code: "invalid-url", name: "BULLMQ_REDIS_URL", classification: "optional-provider" })],
});
expect(invalidProtocol).toMatchObject({
ok: false,
configured: true,
diagnostics: [expect.objectContaining({ code: "invalid-url-protocol", name: "BULLMQ_REDIS_URL" })],
});
expectRedacted([invalidUrl, invalidProtocol], [SENTINEL_INVALID_URL, SENTINEL_INVALID_PROTOCOL_URL, "super-secret-password"]);
});
test("parses boolean flags and rejects unrelated boolean strings", () => {
expect(validateBooleanFlag("WORKER_ENABLED", " true ")).toMatchObject({ ok: true, configured: true, value: true });
expect(validateBooleanFlag("WORKER_ENABLED", "0")).toMatchObject({ ok: true, configured: true, value: false });
expect(validateBooleanFlag("WORKER_ENABLED", undefined, true)).toMatchObject({ ok: true, configured: false, value: true });
const invalid = validateBooleanFlag("WORKER_ENABLED", SENTINEL_INVALID_BOOLEAN);
expect(invalid).toMatchObject({
ok: false,
configured: true,
diagnostics: [expect.objectContaining({ code: "invalid-boolean", name: "WORKER_ENABLED", classification: "optional-provider" })],
});
expectRedacted(invalid, [SENTINEL_INVALID_BOOLEAN]);
});
});
@@ -0,0 +1,118 @@
import { envVariableDefinitions } from "./catalog.js";
import type { EnvClassification, SecretValidationDiagnostic, SecretValidationResult, SecretUrlValidationOptions } from "./types.js";
function getSecretClassification(name: string): EnvClassification | undefined {
const definition = envVariableDefinitions.find((candidate) => {
if (candidate.name === name) {
return true;
}
return "dynamicPrefix" in candidate && candidate.dynamicPrefix ? name.startsWith(candidate.dynamicPrefix) : false;
});
return definition?.classification;
}
function createDiagnostic(code: SecretValidationDiagnostic["code"], name: string, message: string): SecretValidationDiagnostic {
const classification = getSecretClassification(name);
return {
code,
name,
...(classification ? { classification } : {}),
message,
};
}
function ok<T>(value: T, configured: boolean): SecretValidationResult<T> {
return {
ok: true,
configured,
value,
diagnostics: [],
};
}
function failed<T>(diagnostic: SecretValidationDiagnostic, configured: boolean): SecretValidationResult<T> {
return {
ok: false,
configured,
diagnostics: [diagnostic],
};
}
type NormalizedOptionalStringValue =
| { configured: false; value?: undefined }
| { configured: true; value: string };
function normalizeOptionalStringValue(value: string | undefined): NormalizedOptionalStringValue {
const normalized = value?.trim();
if (!normalized) {
return { configured: false };
}
return { configured: true, value: normalized };
}
export function validateRequiredSecretString(name: string, value: string | undefined): SecretValidationResult<string> {
const normalized = normalizeOptionalStringValue(value);
if (!normalized.configured) {
return failed(createDiagnostic("missing-required", name, `${name} is required.`), false);
}
return ok(normalized.value, true);
}
export function validateOptionalSecretString(name: string, value: string | undefined): SecretValidationResult<string | undefined> {
const normalized = normalizeOptionalStringValue(value);
return ok(normalized.value, normalized.configured);
}
export function validateOptionalSecretUrl(name: string, value: string | undefined, options: SecretUrlValidationOptions = {}): SecretValidationResult<string | undefined> {
const normalized = normalizeOptionalStringValue(value);
if (!normalized.configured) {
return ok(undefined, false);
}
let parsed: URL;
try {
parsed = new URL(normalized.value);
} catch {
return failed(createDiagnostic("invalid-url", name, `${name} must be a valid URL.`), true);
}
if (options.allowedProtocols?.length) {
const allowedProtocols = options.allowedProtocols.map((protocol) => (protocol.endsWith(":") ? protocol : `${protocol}:`));
if (!allowedProtocols.includes(parsed.protocol)) {
return failed(createDiagnostic("invalid-url-protocol", name, `${name} must use an allowed URL protocol.`), true);
}
}
return ok(normalized.value, true);
}
export function validateBooleanFlag(name: string, value: string | undefined, defaultValue = false): SecretValidationResult<boolean> {
const normalized = normalizeOptionalStringValue(value);
if (!normalized.configured) {
return ok(defaultValue, false);
}
switch (normalized.value.toLowerCase()) {
case "true":
case "1":
case "yes":
case "on":
return ok(true, true);
case "false":
case "0":
case "no":
case "off":
return ok(false, true);
default:
return failed(createDiagnostic("invalid-boolean", name, `${name} must be a boolean flag.`), true);
}
}
@@ -0,0 +1,112 @@
import { describe, expect, test } from "vitest";
import { resolveApiSessionCookiePolicy, resolveSessionCookiePolicy } from "./session-cookie.js";
const productionRouting = {
appBaseDomain: "example.com",
protocol: "https" as const,
};
describe("session cookie policy", () => {
test("sets a shared hardened cookie policy for production app base domains", () => {
const policy = resolveSessionCookiePolicy({
nodeEnv: "production",
routing: productionRouting,
name: "session",
maxAge: 60 * 60,
});
expect(policy).toEqual({
name: "session",
maxAge: 3600,
domain: "example.com",
sameSite: "lax",
secure: true,
httpOnly: true,
path: "/",
});
expect(JSON.stringify(policy)).not.toContain("secret");
});
test("keeps localhost cookies domainless for local development", () => {
expect(
resolveSessionCookiePolicy({
nodeEnv: "development",
routing: {
appBaseDomain: "localhost:3000",
protocol: "http",
},
})
).toEqual({
sameSite: "lax",
secure: false,
httpOnly: true,
path: "/",
});
expect(
resolveSessionCookiePolicy({
nodeEnv: "development",
routing: {
appBaseDomain: "app.localhost",
protocol: "http",
},
})
).not.toHaveProperty("domain");
});
test("enables secure cookies for HTTPS routing outside production", () => {
expect(
resolveSessionCookiePolicy({
nodeEnv: "test",
routing: {
appBaseDomain: "example.test",
protocol: "https",
},
})
).toMatchObject({
domain: "example.test",
sameSite: "lax",
secure: true,
httpOnly: true,
path: "/",
});
});
test("resolves API session cookies with the API name and shared production hardening", () => {
const policy = resolveApiSessionCookiePolicy({
nodeEnv: "production",
routing: productionRouting,
maxAge: 60 * 15,
});
expect(policy).toEqual({
name: "RJ_api_session",
maxAge: 900,
domain: "example.com",
sameSite: "lax",
secure: true,
httpOnly: true,
path: "/",
});
expect(policy.name).not.toBe("RJ_session");
expect(JSON.stringify(policy)).not.toContain("secret");
});
test("keeps API session cookies domainless and insecure on localhost HTTP", () => {
const policy = resolveApiSessionCookiePolicy({
nodeEnv: "development",
routing: {
appBaseDomain: "localhost:3000",
protocol: "http",
},
});
expect(policy).toEqual({
name: "RJ_api_session",
sameSite: "lax",
secure: false,
httpOnly: true,
path: "/",
});
});
});
@@ -0,0 +1,70 @@
import type { DomainRoutingConfig } from "./routing.js";
export type SessionCookieSameSite = "lax";
export type SessionCookiePolicy = {
name?: string;
domain?: string;
sameSite: SessionCookieSameSite;
secure: boolean;
httpOnly: boolean;
path: "/";
maxAge?: number;
};
export type ResolveSessionCookiePolicyOptions = {
nodeEnv?: string;
routing: Pick<DomainRoutingConfig, "appBaseDomain" | "protocol">;
name?: string;
maxAge?: number;
};
export type ResolveApiSessionCookiePolicyOptions = Omit<ResolveSessionCookiePolicyOptions, "name">;
const API_SESSION_COOKIE_NAME = "RJ_api_session";
export function resolveSessionCookiePolicy({ nodeEnv, routing, name, maxAge }: ResolveSessionCookiePolicyOptions): SessionCookiePolicy {
return {
...(name ? { name } : {}),
...(maxAge === undefined ? {} : { maxAge }),
...resolveCookieDomain(routing.appBaseDomain),
sameSite: "lax",
secure: nodeEnv === "production" || routing.protocol === "https",
httpOnly: true,
path: "/",
};
}
export function resolveApiSessionCookiePolicy(options: ResolveApiSessionCookiePolicyOptions): SessionCookiePolicy {
return resolveSessionCookiePolicy({
...options,
name: API_SESSION_COOKIE_NAME,
});
}
function resolveCookieDomain(appBaseDomain: string): Pick<SessionCookiePolicy, "domain"> {
const hostname = stripPort(appBaseDomain.trim().toLowerCase());
if (!hostname || isLocalCookieHost(hostname)) {
return {};
}
return { domain: hostname };
}
function stripPort(host: string) {
if (host.startsWith("[")) {
return host.slice(1, host.indexOf("]"));
}
const firstColon = host.indexOf(":");
return firstColon === -1 ? host : host.slice(0, firstColon);
}
function isLocalCookieHost(hostname: string) {
return hostname === "localhost" || hostname.endsWith(".localhost") || isIpv4Address(hostname) || hostname === "::1";
}
function isIpv4Address(hostname: string) {
return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname);
}
@@ -0,0 +1,22 @@
import { describe, expectTypeOf, test } from "vitest";
import type { EnvValidationIssue, RequiredWebConfigOptions, WebConfig, WebConfigDiagnostic, WebConfigErrorDetails, WebConfigOptions, WebConfigResult } from "./types.js";
describe("web config types", () => {
test("extends env validation diagnostics without exposing values", () => {
expectTypeOf<WebConfigDiagnostic>().toMatchTypeOf<Pick<EnvValidationIssue, "name" | "message" | "classification">>();
expectTypeOf<WebConfigDiagnostic>()
.toHaveProperty("code")
.toEqualTypeOf<"missing-required" | "invalid-port" | "invalid-boolean" | "invalid-duration" | "invalid-number">();
});
test("keeps the loader result typed around config and diagnostics", () => {
expectTypeOf<WebConfigResult>().toHaveProperty("ok").toEqualTypeOf<boolean>();
expectTypeOf<WebConfigResult>().toHaveProperty("config").toEqualTypeOf<WebConfig>();
expectTypeOf<WebConfigResult>().toHaveProperty("diagnostics").toEqualTypeOf<WebConfigDiagnostic[]>();
});
test("keeps required loader options and error details typed without values", () => {
expectTypeOf<RequiredWebConfigOptions>().toEqualTypeOf<WebConfigOptions>();
expectTypeOf<WebConfigErrorDetails>().toHaveProperty("diagnostics").toEqualTypeOf<WebConfigDiagnostic[]>();
});
});
+325
View File
@@ -0,0 +1,325 @@
export type RuntimeTarget = "shared" | "web" | "api" | "worker";
export type EnvClassification = "required-core" | "required-per-app" | "optional-provider" | "local-development-only" | "production-only" | "deprecated-remove";
export type EnvValueKind = "string" | "url" | "database-url" | "secret" | "token" | "email" | "node-env";
export type EnvAuditSource = "code" | "example" | "code-and-example" | "runtime" | "dynamic";
export type EnvVariableDefinition = {
name: string;
description: string;
classification: EnvClassification;
targets: readonly RuntimeTarget[];
kind: EnvValueKind;
source: EnvAuditSource;
requiredInProduction?: boolean;
dynamicPrefix?: string;
defaultValue?: string;
notes?: string;
};
export type EnvRecord = Record<string, string | undefined>;
export type EnvValidationOptions = {
target?: RuntimeTarget;
nodeEnv?: string;
includeOptionalProviders?: boolean;
extraRequired?: readonly string[];
};
export type EnvValidationIssue = {
name: string;
message: string;
classification?: EnvClassification;
};
export type EnvValidationResult = {
ok: boolean;
missing: EnvValidationIssue[];
};
export type SecretValidationDiagnosticCode = "missing-required" | "invalid-url" | "invalid-url-protocol" | "invalid-boolean";
export type SecretValidationDiagnostic = {
code: SecretValidationDiagnosticCode;
name: string;
message: string;
classification?: EnvClassification;
};
export type SecretValidationResult<T> = {
ok: boolean;
configured: boolean;
value?: T;
diagnostics: SecretValidationDiagnostic[];
};
export type SecretUrlValidationOptions = {
allowedProtocols?: readonly string[];
};
export type WebConfigDiagnosticCode = "missing-required" | "invalid-port" | "invalid-boolean" | "invalid-duration" | "invalid-number" | "weak-secret";
export type WebConfigDiagnostic = {
code: WebConfigDiagnosticCode;
name: string;
message: string;
classification?: EnvClassification;
};
export type WebConfigListen = {
host: string;
port: number;
};
export type WebConfigRouting = {
appBaseDomain: string;
webAppHost: string;
adminAppHost: string;
apiHost: string;
protocol: "http" | "https";
};
export type WebConfig = {
appName: string;
nodeEnv: string;
sessionSecret?: string;
listen: WebConfigListen;
routing: WebConfigRouting;
webhooksUrl?: string;
stripe: {
secretKey?: string;
webhookSigningSecret?: string;
};
crisp: {
chatWebsiteId?: string;
};
captcha: {
instanceUrl?: string;
loginSiteKey?: string;
};
analytics: {
// EU-Sterilisation (R-P1a): kein Google-Analytics mehr; nur First-Party-Analytics-Token.
token?: string;
};
novu: {
apiKey?: string;
};
mailjet: {
apiKey?: string;
secretKey?: string;
fromEmail?: string;
fromName?: string;
};
ipProviders: {
ipstackApiKey?: string;
ipapiIsApiKey?: string;
};
ipGeo: {
hashPepper?: string;
dbPath?: string;
};
portalServer: {
url?: string;
flyToken?: string;
};
magicLink: {
enabled: boolean;
tokenTtlMinutes?: number;
};
storage: WebConfigStorage;
cryptoSecret?: string;
apiAccessToken?: string;
jwtSecret?: string;
demoUser?: string;
supportEmail?: string;
companyName?: string;
companyAddress?: string;
contactFormspreeEndpoint?: string;
};
export type WebConfigStorage = ApiConfigStorage & {
provider?: "s3" | "local";
fallbackProvider?: "s3" | "local";
localRoot?: string;
localPublicBaseUrl?: string;
};
export type WebConfigOptions = {
nodeEnv?: string;
includeOptionalProviders?: boolean;
extraRequired?: readonly string[];
};
export type WebConfigResult = {
ok: boolean;
config: WebConfig;
diagnostics: WebConfigDiagnostic[];
};
export type RequiredWebConfigOptions = WebConfigOptions;
export type WebConfigErrorDetails = {
diagnostics: WebConfigDiagnostic[];
};
export type ApiConfigListen = {
port: number;
};
export type ApiConfigOrigins = {
web?: string;
admin?: string;
};
export type ApiConfigStorage = {
endpoint?: string;
region?: string;
bucket?: string;
accessKeyId?: string;
secretAccessKey?: string;
sessionToken?: string;
publicBaseUrl?: string;
forcePathStyle?: string;
};
export type ApiConfigApiKeys = {
allowLegacyPlaintextFallback: boolean;
};
export type ApiConfigAnalytics = {
token?: string;
};
export type ApiConfigMailjet = {
webhookSecret?: string;
};
export type ApiConfigStripe = {
secretKey?: string;
webhookSigningSecret?: string;
};
export type ApiConfig = {
appName: string;
nodeEnv: string;
revision: string;
listen: ApiConfigListen;
routing: WebConfigRouting;
origins: ApiConfigOrigins;
apiAccessToken?: string;
jwtSecret?: string;
analytics: ApiConfigAnalytics;
mailjet: ApiConfigMailjet;
stripe: ApiConfigStripe;
storage: ApiConfigStorage;
apiKeys: ApiConfigApiKeys;
};
export type ApiConfigOptions = {
nodeEnv?: string;
includeOptionalProviders?: boolean;
extraRequired?: readonly string[];
};
export type RequiredApiConfigOptions = ApiConfigOptions;
export type ApiConfigDiagnosticCode = "missing-required" | "invalid-port";
export type ApiConfigDiagnostic = {
code: ApiConfigDiagnosticCode;
name: string;
message: string;
classification?: EnvClassification;
};
export type ApiConfigErrorDetails = {
diagnostics: ApiConfigDiagnostic[];
};
export type ApiConfigResult = {
ok: boolean;
config: ApiConfig;
diagnostics: ApiConfigDiagnostic[];
};
export type WorkerConfigDiagnosticCode =
| "missing-required"
| "invalid-redis-url"
| "invalid-redis-protocol"
| "invalid-redis-database"
| "invalid-url"
| "invalid-url-protocol"
| "invalid-boolean"
| "invalid-timeout"
| "invalid-concurrency"
| "invalid-worker-queue-group";
export type WorkerConfigDiagnostic = {
code: WorkerConfigDiagnosticCode;
name: string;
message: string;
classification?: EnvClassification;
};
export type WorkerConfigRedisSource = "BULLMQ_REDIS_URL" | "REDIS_URL" | "none";
export type WorkerConfigRedisParseStatus = "not-provided" | "valid" | "invalid-url" | "invalid-protocol" | "invalid-database";
export type WorkerConfigRedis = {
source: WorkerConfigRedisSource;
url?: string;
configured: boolean;
parseStatus: WorkerConfigRedisParseStatus;
database?: number;
};
export type WorkerConfigQueues = {
email: string;
workflow: string;
};
export type WorkerConfigMailjet = {
configured: boolean;
apiKey?: string;
secretKey?: string;
fromEmail?: string;
fromName?: string;
};
export type WorkerConfigBrowserRuntime = {
configured: boolean;
url?: string;
apiKey?: string;
sessionTimeoutMs?: number;
};
export type WorkerConfig = {
appName: string;
nodeEnv: string;
enabled: boolean;
concurrency: number;
redis: WorkerConfigRedis;
queues: WorkerConfigQueues;
mailjet: WorkerConfigMailjet;
browserRuntime: WorkerConfigBrowserRuntime;
};
export type WorkerConfigOptions = {
nodeEnv?: string;
includeOptionalProviders?: boolean;
extraRequired?: readonly string[];
};
export type RequiredWorkerConfigOptions = WorkerConfigOptions;
export type WorkerConfigErrorDetails = {
diagnostics: WorkerConfigDiagnostic[];
};
export type WorkerConfigResult = {
ok: boolean;
config: WorkerConfig;
diagnostics: WorkerConfigDiagnostic[];
};
@@ -0,0 +1,390 @@
import { describe, expect, test } from "vitest";
import { getEnvVariableDefinition, loadRequiredWebConfig, loadWebConfig, WebConfigError } from "./index.js";
const REQUIRED_PRODUCTION_ENV = {
APP_NAME: "Production App",
DATABASE_URL: "postgres://example.invalid/app",
APP_BASE_DOMAIN: "example.com",
WEB_APP_HOST: "app.example.com",
ADMIN_APP_HOST: "admin.example.com",
API_HOST: "api.example.com",
SESSION_SECRET: "session-secret-value-prod-0123456789",
CRYPTO_SECRET: "crypto-secret-value-prod-0123456789",
API_ACCESS_TOKEN: "api-access-token-value-prod-0123456789",
JWT_SECRET: "jwt-secret-value-prod-0123456789abcd",
};
describe("loadRequiredWebConfig", () => {
test("returns production config when required values are valid", () => {
const config = loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
PORT: "8080",
},
{ nodeEnv: "production" }
);
expect(config).toMatchObject({
appName: "Production App",
nodeEnv: "production",
sessionSecret: "session-secret-value-prod-0123456789",
listen: {
port: 8080,
},
routing: {
appBaseDomain: "example.com",
protocol: "https",
},
});
});
test("throws redacted WebConfigError for missing production SESSION_SECRET", () => {
const secretValues = ["crypto-secret-value", "api-access-token-value", "jwt-secret-value"];
expect(() =>
loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
SESSION_SECRET: undefined,
},
{ nodeEnv: "production" }
)
).toThrow(WebConfigError);
try {
loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
SESSION_SECRET: undefined,
},
{ nodeEnv: "production" }
);
} catch (error) {
expect(error).toBeInstanceOf(WebConfigError);
const webConfigError = error as WebConfigError;
expect(webConfigError.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "SESSION_SECRET",
})
);
const errorText = JSON.stringify({ message: webConfigError.message, details: webConfigError.details });
for (const secretValue of secretValues) {
expect(errorText).not.toContain(secretValue);
}
}
});
test("throws redacted WebConfigError for invalid PORT", () => {
const secretValues = ["session-secret-value", "crypto-secret-value", "api-access-token-value", "jwt-secret-value"];
try {
loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
PORT: "secret-like-invalid-port-value",
},
{ nodeEnv: "production" }
);
} catch (error) {
expect(error).toBeInstanceOf(WebConfigError);
const webConfigError = error as WebConfigError;
expect(webConfigError.diagnostics).toEqual([
expect.objectContaining({
code: "invalid-port",
name: "PORT",
}),
]);
const errorText = JSON.stringify({ message: webConfigError.message, details: webConfigError.details });
expect(errorText).not.toContain("secret-like-invalid-port-value");
for (const secretValue of secretValues) {
expect(errorText).not.toContain(secretValue);
}
}
});
test("preserves default development behavior by throwing diagnostics instead of silently succeeding", () => {
expect(() => loadRequiredWebConfig({})).toThrow(WebConfigError);
});
});
describe("secret strength (production)", () => {
test("rejects a present-but-too-short SESSION_SECRET in production", () => {
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, SESSION_SECRET: "too-short" }, { nodeEnv: "production" });
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(expect.objectContaining({ code: "weak-secret", name: "SESSION_SECRET" }));
});
test("rejects reusing one value for SESSION_SECRET and CRYPTO_SECRET in production", () => {
const shared = "shared-secret-value-prod-0123456789";
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, SESSION_SECRET: shared, CRYPTO_SECRET: shared }, { nodeEnv: "production" });
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(expect.objectContaining({ code: "weak-secret", name: "CRYPTO_SECRET" }));
});
test("does not leak the weak secret value in diagnostics", () => {
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, JWT_SECRET: "short-jwt-secret" }, { nodeEnv: "production" });
expect(JSON.stringify(result.diagnostics)).not.toContain("short-jwt-secret");
});
test("does not enforce secret length outside production (placeholders allowed)", () => {
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, NODE_ENV: "test", SESSION_SECRET: "short" }, { nodeEnv: "test" });
expect(result.diagnostics).not.toContainEqual(expect.objectContaining({ code: "weak-secret" }));
});
});
describe("loadWebConfig", () => {
test("returns local defaults and domain routing defaults", () => {
const result = loadWebConfig({});
expect(result.ok).toBe(false);
expect(result.config).toMatchObject({
appName: "ToolController",
nodeEnv: "development",
listen: {
host: "0.0.0.0",
port: 3000,
},
routing: {
appBaseDomain: "localhost",
webAppHost: "app.localhost",
adminAppHost: "admin.localhost",
apiHost: "api.localhost",
protocol: "http",
},
});
});
test("normalizes explicit listen and server-side provider values", () => {
const result = loadWebConfig({
...REQUIRED_PRODUCTION_ENV,
NODE_ENV: "production",
HOST: "127.0.0.1",
PORT: "8080",
WEBHOOKS_URL: "https://hooks.example.com",
STRIPE_SK: "stripe-secret-value",
STRIPE_WEBHOOK_SIGNING_SECRET: "stripe-webhook-secret-value",
CRISP_CHAT_WEBSITE_ID: "crisp-id",
MCAPTCHA_INSTANCE_URL: "https://captcha.example.test",
MCAPTCHA_SITEKEY_LOGIN: "login-key",
ANALYTICS_TOKEN: "analytics-token-value",
NOTIFICATIONS_NOVU_API_KEY: "novu-secret-value",
MAILJET_API_KEY: "mailjet-public-value",
MAILJET_SECRET_KEY: "mailjet-secret-value",
MAILJET_FROM_EMAIL: "sender@example.com",
MAILJET_FROM_NAME: "Example Support",
IPSTACK_API_KEY: "ipstack-api-key",
IPAPIIS_API_KEY: "ipapiis-api-key",
PORTAL_SERVER_URL: "https://portals.example.com",
PORTAL_SERVER_FLY_TOKEN: "portal-fly-token-value",
AUTH_MAGIC_LINK_ENABLED: "true",
AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "15",
STORAGE_PROVIDER: "s3",
STORAGE_FALLBACK_PROVIDER: "local",
STORAGE_ENDPOINT: "https://storage.example.com",
STORAGE_REGION: "eu-central-1",
STORAGE_BUCKET: "uploads",
STORAGE_ACCESS_KEY_ID: "storage-access-key",
STORAGE_SECRET_ACCESS_KEY: "storage-secret-key",
STORAGE_SESSION_TOKEN: "storage-session-token",
STORAGE_PUBLIC_BASE_URL: "https://cdn.example.com",
STORAGE_FORCE_PATH_STYLE: "true",
STORAGE_LOCAL_ROOT: "/tmp/toolctrl-storage",
STORAGE_LOCAL_PUBLIC_BASE_URL: "http://localhost:3000/storage",
DEMO_USER: "demo@example.com:password",
});
expect(result.ok).toBe(true);
expect(result.diagnostics).toEqual([]);
expect(result.config).toMatchObject({
appName: "Production App",
nodeEnv: "production",
sessionSecret: "session-secret-value-prod-0123456789",
listen: {
host: "127.0.0.1",
port: 8080,
},
routing: {
appBaseDomain: "example.com",
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
protocol: "https",
},
webhooksUrl: "https://hooks.example.com",
stripe: {
secretKey: "stripe-secret-value",
webhookSigningSecret: "stripe-webhook-secret-value",
},
crisp: {
chatWebsiteId: "crisp-id",
},
captcha: {
instanceUrl: "https://captcha.example.test",
loginSiteKey: "login-key",
},
analytics: {
token: "analytics-token-value",
},
novu: {
apiKey: "novu-secret-value",
},
mailjet: {
apiKey: "mailjet-public-value",
secretKey: "mailjet-secret-value",
fromEmail: "sender@example.com",
fromName: "Example Support",
},
ipProviders: {
ipstackApiKey: "ipstack-api-key",
ipapiIsApiKey: "ipapiis-api-key",
},
portalServer: {
url: "https://portals.example.com",
flyToken: "portal-fly-token-value",
},
magicLink: {
enabled: true,
tokenTtlMinutes: 15,
},
storage: {
provider: "s3",
fallbackProvider: "local",
endpoint: "https://storage.example.com",
region: "eu-central-1",
bucket: "uploads",
accessKeyId: "storage-access-key",
secretAccessKey: "storage-secret-key",
sessionToken: "storage-session-token",
publicBaseUrl: "https://cdn.example.com",
forcePathStyle: "true",
localRoot: "/tmp/toolctrl-storage",
localPublicBaseUrl: "http://localhost:3000/storage",
},
cryptoSecret: "crypto-secret-value-prod-0123456789",
apiAccessToken: "api-access-token-value-prod-0123456789",
jwtSecret: "jwt-secret-value-prod-0123456789abcd",
demoUser: undefined,
});
});
test("exposes demo login hints only for development config", () => {
expect(loadWebConfig({ NODE_ENV: "development", DEMO_USER: "demo@example.com:password" }).config.demoUser).toBe("demo@example.com:password");
expect(loadWebConfig({ NODE_ENV: "test", DEMO_USER: "demo@example.com:password" }).config.demoUser).toBeUndefined();
expect(loadWebConfig({ NODE_ENV: "production", DEMO_USER: "demo@example.com:password" }).config.demoUser).toBeUndefined();
});
test("keeps Magic-Link provider capability safely disabled by default", () => {
const result = loadWebConfig({});
expect(result.config.magicLink).toEqual({
enabled: false,
tokenTtlMinutes: undefined,
});
expect(result.diagnostics).not.toContainEqual(
expect.objectContaining({
name: expect.stringMatching(/^AUTH_MAGIC_LINK_/),
})
);
});
test("does not enable Magic-Link auth for malformed env values", () => {
const invalidEnabled = loadWebConfig({ AUTH_MAGIC_LINK_ENABLED: "sometimes", AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "15" });
const invalidTtl = loadWebConfig({ AUTH_MAGIC_LINK_ENABLED: "true", AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "0" });
expect(invalidEnabled.config.magicLink).toEqual({ enabled: false, tokenTtlMinutes: undefined });
expect(invalidEnabled.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-boolean",
name: "AUTH_MAGIC_LINK_ENABLED",
})
);
expect(JSON.stringify(invalidEnabled.diagnostics)).not.toContain("sometimes");
expect(invalidTtl.config.magicLink).toEqual({ enabled: false, tokenTtlMinutes: undefined });
expect(invalidTtl.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-duration",
name: "AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES",
})
);
expect(JSON.stringify(invalidTtl.diagnostics)).not.toContain("0");
});
test("catalogs Magic-Link provider env inputs", () => {
expect(getEnvVariableDefinition("AUTH_MAGIC_LINK_ENABLED")).toMatchObject({
classification: "optional-provider",
defaultValue: "false",
targets: ["web", "api"],
});
});
test("reports missing production session secret with redacted diagnostics", () => {
const result = loadWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
SESSION_SECRET: undefined,
},
{ nodeEnv: "production" }
);
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "SESSION_SECRET",
})
);
expect(JSON.stringify(result.diagnostics)).not.toContain("session-secret-value");
});
test("falls back for invalid PORT and keeps supplied secret values out of diagnostics", () => {
const secretValues = ["session-secret-value", "stripe-secret-value", "crypto-secret-value", "api-token-value", "jwt-secret-value"];
const result = loadWebConfig({
SESSION_SECRET: secretValues[0],
STRIPE_SK: secretValues[1],
CRYPTO_SECRET: secretValues[2],
API_ACCESS_TOKEN: secretValues[3],
JWT_SECRET: secretValues[4],
PORT: "not-a-port",
});
expect(result.ok).toBe(false);
expect(result.config.listen.port).toBe(3000);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-port",
name: "PORT",
})
);
const diagnosticText = JSON.stringify(result.diagnostics);
for (const secretValue of secretValues) {
expect(diagnosticText).not.toContain(secretValue);
}
});
test("keeps web-owned PORT and HOST in the catalog", () => {
expect(getEnvVariableDefinition("PORT")).toMatchObject({
targets: ["web"],
defaultValue: "3000",
});
expect(getEnvVariableDefinition("HOST")).toMatchObject({
targets: ["web"],
defaultValue: "0.0.0.0",
});
});
test("allows S3 as an explicit storage fallback provider", () => {
const result = loadWebConfig({
STORAGE_PROVIDER: "local",
STORAGE_FALLBACK_PROVIDER: "s3",
});
expect(result.config.storage).toMatchObject({
provider: "local",
fallbackProvider: "s3",
});
});
});
+299
View File
@@ -0,0 +1,299 @@
import { getEnvVariableDefinition, validateEnv } from "./index.js";
import { getDomainRoutingConfig } from "./routing.js";
import type { EnvRecord, RequiredWebConfigOptions, WebConfig, WebConfigDiagnostic, WebConfigErrorDetails, WebConfigOptions, WebConfigResult } from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_LISTEN_HOST = "0.0.0.0";
const DEFAULT_LISTEN_PORT = 3000;
const MIN_PORT = 1;
const MAX_PORT = 65535;
const MIN_MAGIC_LINK_TOKEN_TTL_MINUTES = 1;
export class WebConfigError extends Error {
readonly diagnostics: WebConfigDiagnostic[];
constructor(diagnostics: readonly WebConfigDiagnostic[]) {
super(formatWebConfigErrorMessage(diagnostics));
this.name = "WebConfigError";
this.diagnostics = diagnostics.map(redactDiagnostic);
}
get details(): WebConfigErrorDetails {
return {
diagnostics: this.diagnostics,
};
}
}
export function loadRequiredWebConfig(env: EnvRecord = process.env, options: RequiredWebConfigOptions = {}): WebConfig {
const result = loadWebConfig(env, options);
if (result.ok) {
return result.config;
}
throw new WebConfigError(result.diagnostics);
}
export function loadWebConfig(env: EnvRecord = process.env, options: WebConfigOptions = {}): WebConfigResult {
const nodeEnv = options.nodeEnv ?? env.NODE_ENV ?? DEFAULT_NODE_ENV;
const routing = getDomainRoutingConfig({ ...env, NODE_ENV: nodeEnv });
const portResult = normalizeListenPort(env.PORT);
const magicLinkResult = normalizeMagicLinkConfig(env);
const diagnostics: WebConfigDiagnostic[] = [
...toDiagnostics(
validateEnv(env, {
target: "web",
nodeEnv,
includeOptionalProviders: options.includeOptionalProviders,
extraRequired: options.extraRequired,
}).missing
),
];
if (portResult.diagnostic) {
diagnostics.push(portResult.diagnostic);
}
if (magicLinkResult.diagnostic) {
diagnostics.push(magicLinkResult.diagnostic);
}
diagnostics.push(...validateSecretStrength(env, nodeEnv));
const config: WebConfig = {
appName: env.APP_NAME?.trim() || DEFAULT_APP_NAME,
nodeEnv,
sessionSecret: present(env.SESSION_SECRET),
listen: {
host: env.HOST?.trim() || DEFAULT_LISTEN_HOST,
port: portResult.port,
},
routing,
webhooksUrl: present(env.WEBHOOKS_URL),
stripe: {
secretKey: present(env.STRIPE_SK),
webhookSigningSecret: present(env.STRIPE_WEBHOOK_SIGNING_SECRET),
},
crisp: {
chatWebsiteId: present(env.CRISP_CHAT_WEBSITE_ID),
},
captcha: {
instanceUrl: present(env.MCAPTCHA_INSTANCE_URL),
loginSiteKey: present(env.MCAPTCHA_SITEKEY_LOGIN),
},
analytics: {
// EU-Sterilisation (R-P1a): Google-Analytics-Einbindung entfernt; nur First-Party-Analytics-Token bleibt.
token: present(env.ANALYTICS_TOKEN),
},
novu: {
apiKey: present(env.NOTIFICATIONS_NOVU_API_KEY),
},
mailjet: {
apiKey: present(env.MAILJET_API_KEY),
secretKey: present(env.MAILJET_SECRET_KEY),
fromEmail: present(env.MAILJET_FROM_EMAIL),
fromName: present(env.MAILJET_FROM_NAME),
},
ipProviders: {
ipstackApiKey: present(env.IPSTACK_API_KEY),
ipapiIsApiKey: present(env.IPAPIIS_API_KEY),
},
ipGeo: {
hashPepper: present(env.IP_HASH_PEPPER),
dbPath: present(env.GEOIP_DB_PATH),
},
portalServer: {
url: present(env.PORTAL_SERVER_URL),
flyToken: present(env.PORTAL_SERVER_FLY_TOKEN),
},
magicLink: magicLinkResult.config,
storage: {
provider: normalizeStorageProvider(env.STORAGE_PROVIDER),
fallbackProvider: normalizeStorageFallbackProvider(env.STORAGE_FALLBACK_PROVIDER),
endpoint: present(env.STORAGE_ENDPOINT),
region: present(env.STORAGE_REGION),
bucket: present(env.STORAGE_BUCKET),
accessKeyId: present(env.STORAGE_ACCESS_KEY_ID),
secretAccessKey: present(env.STORAGE_SECRET_ACCESS_KEY),
sessionToken: present(env.STORAGE_SESSION_TOKEN),
publicBaseUrl: present(env.STORAGE_PUBLIC_BASE_URL),
forcePathStyle: present(env.STORAGE_FORCE_PATH_STYLE),
localRoot: present(env.STORAGE_LOCAL_ROOT),
localPublicBaseUrl: present(env.STORAGE_LOCAL_PUBLIC_BASE_URL),
},
cryptoSecret: present(env.CRYPTO_SECRET),
apiAccessToken: present(env.API_ACCESS_TOKEN),
jwtSecret: present(env.JWT_SECRET),
demoUser: nodeEnv === "development" ? present(env.DEMO_USER) : undefined,
supportEmail: present(env.SUPPORT_EMAIL),
companyName: present(env.COMPANY_NAME),
companyAddress: present(env.COMPANY_ADDRESS),
contactFormspreeEndpoint: present(env.INTEGRATIONS_CONTACT_FORMSPREE),
};
return {
ok: diagnostics.length === 0,
config,
diagnostics,
};
}
function normalizeStorageProvider(value: string | undefined): "s3" | "local" | undefined {
const normalized = value?.trim().toLowerCase();
if (normalized === "s3" || normalized === "local") {
return normalized;
}
return undefined;
}
function normalizeStorageFallbackProvider(value: string | undefined): "s3" | "local" | undefined {
const normalized = value?.trim().toLowerCase();
if (normalized === "s3" || normalized === "local") {
return normalized;
}
return undefined;
}
function normalizeListenPort(value: string | undefined): { port: number; diagnostic?: WebConfigDiagnostic } {
const trimmed = value?.trim();
if (!trimmed) {
return { port: DEFAULT_LISTEN_PORT };
}
const parsed = Number(trimmed);
if (!Number.isInteger(parsed) || parsed < MIN_PORT || parsed > MAX_PORT) {
return {
port: DEFAULT_LISTEN_PORT,
diagnostic: {
code: "invalid-port",
name: "PORT",
classification: getEnvVariableDefinition("PORT")?.classification,
message: "PORT must be an integer between 1 and 65535. Falling back to 3000.",
},
};
}
return { port: parsed };
}
function normalizeMagicLinkConfig(env: EnvRecord): { config: WebConfig["magicLink"]; diagnostic?: WebConfigDiagnostic } {
const enabledResult = normalizeMagicLinkEnabled(env.AUTH_MAGIC_LINK_ENABLED);
const ttlResult = normalizeMagicLinkTokenTtlMinutes(env.AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES);
const enabled = enabledResult.enabled && !ttlResult.diagnostic;
return {
config: {
enabled,
tokenTtlMinutes: enabled ? ttlResult.tokenTtlMinutes : undefined,
},
diagnostic: enabledResult.diagnostic ?? ttlResult.diagnostic,
};
}
function normalizeMagicLinkEnabled(value: string | undefined): { enabled: boolean; diagnostic?: WebConfigDiagnostic } {
const trimmed = value?.trim().toLowerCase();
if (!trimmed) {
return { enabled: false };
}
if (["1", "true", "yes", "on"].includes(trimmed)) {
return { enabled: true };
}
if (["0", "false", "no", "off"].includes(trimmed)) {
return { enabled: false };
}
return {
enabled: false,
diagnostic: {
code: "invalid-boolean",
name: "AUTH_MAGIC_LINK_ENABLED",
classification: getEnvVariableDefinition("AUTH_MAGIC_LINK_ENABLED")?.classification,
message: "AUTH_MAGIC_LINK_ENABLED must be a boolean-like value. Magic-Link auth remains disabled.",
},
};
}
function normalizeMagicLinkTokenTtlMinutes(value: string | undefined): { tokenTtlMinutes?: number; diagnostic?: WebConfigDiagnostic } {
const trimmed = value?.trim();
if (!trimmed) {
return {};
}
const parsed = Number(trimmed);
if (!Number.isInteger(parsed) || parsed < MIN_MAGIC_LINK_TOKEN_TTL_MINUTES) {
return {
diagnostic: {
code: "invalid-duration",
name: "AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES",
classification: getEnvVariableDefinition("AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES")?.classification,
message: "AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES must be a positive integer. Magic-Link auth remains disabled.",
},
};
}
return { tokenTtlMinutes: parsed };
}
const MIN_SECRET_LENGTH = 32;
const STRENGTH_CHECKED_SECRETS = ["SESSION_SECRET", "CRYPTO_SECRET", "JWT_SECRET", "API_ACCESS_TOKEN"] as const;
// Production-only secret hardening. Missing required secrets are already
// reported by validateEnv; here we additionally fail closed when a secret is
// PRESENT but too weak (< 32 chars) or when SESSION_SECRET and CRYPTO_SECRET are
// reused for both purposes. Non-production envs (placeholders in .env.test etc.)
// are intentionally exempt.
function validateSecretStrength(env: EnvRecord, nodeEnv: string): WebConfigDiagnostic[] {
if (nodeEnv !== "production") {
return [];
}
const diagnostics: WebConfigDiagnostic[] = [];
for (const name of STRENGTH_CHECKED_SECRETS) {
const value = present(env[name]);
if (value && value.length < MIN_SECRET_LENGTH) {
diagnostics.push({
code: "weak-secret",
name,
classification: getEnvVariableDefinition(name)?.classification,
message: `${name} must be at least ${MIN_SECRET_LENGTH} characters in production (generate with \`openssl rand -hex 32\`).`,
});
}
}
const sessionSecret = present(env.SESSION_SECRET);
const cryptoSecret = present(env.CRYPTO_SECRET);
if (sessionSecret && cryptoSecret && sessionSecret === cryptoSecret) {
diagnostics.push({
code: "weak-secret",
name: "CRYPTO_SECRET",
classification: getEnvVariableDefinition("CRYPTO_SECRET")?.classification,
message: "CRYPTO_SECRET must not be identical to SESSION_SECRET; use independent random values.",
});
}
return diagnostics;
}
function toDiagnostics(issues: ReturnType<typeof validateEnv>["missing"]): WebConfigDiagnostic[] {
return issues.map((issue) => ({
code: "missing-required",
name: issue.name,
classification: issue.classification,
message: issue.message,
}));
}
function formatWebConfigErrorMessage(diagnostics: readonly WebConfigDiagnostic[]): string {
const summary = diagnostics.map((diagnostic) => `${diagnostic.name}:${diagnostic.code}`).join(", ");
return `Invalid web configuration (${summary}).`;
}
function redactDiagnostic(diagnostic: WebConfigDiagnostic): WebConfigDiagnostic {
return {
code: diagnostic.code,
name: diagnostic.name,
classification: diagnostic.classification,
message: diagnostic.message,
};
}
function present(value: string | undefined): string | undefined {
const trimmed = value?.trim();
return trimmed ? trimmed : undefined;
}
@@ -0,0 +1,458 @@
import { describe, expect, test } from "vitest";
import { loadRequiredWorkerConfig, loadWorkerConfig, WorkerConfigError } from "./index.js";
const REDIS_WITH_PASSWORD = "rediss://:super-secret-password@redis.example.com:6380/2";
const DATABASE_URL = "postgresql://user:db-secret@localhost:5432/app";
describe("loadRequiredWorkerConfig", () => {
test("returns disabled local worker config without Redis", () => {
const config = loadRequiredWorkerConfig({});
expect(config).toMatchObject({
appName: "ToolController",
nodeEnv: "development",
enabled: false,
redis: {
source: "none",
configured: false,
parseStatus: "not-provided",
},
queues: {
email: "email",
workflow: "workflow",
},
mailjet: {
configured: false,
},
browserRuntime: {
configured: false,
},
});
});
test("returns enabled worker config with valid BULLMQ Redis", () => {
const config = loadRequiredWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
expect(config.enabled).toBe(true);
expect(config.redis).toMatchObject({
source: "BULLMQ_REDIS_URL",
url: REDIS_WITH_PASSWORD,
configured: true,
parseStatus: "valid",
database: 2,
});
});
test("throws redacted WorkerConfigError when enabled worker is missing Redis", () => {
expect(() => loadRequiredWorkerConfig({ WORKER_ENABLED: "true", DATABASE_URL, WORKER_QUEUE_GROUP: "general" })).toThrow(WorkerConfigError);
try {
loadRequiredWorkerConfig({ WORKER_ENABLED: "true", DATABASE_URL, WORKER_QUEUE_GROUP: "general" });
} catch (error) {
expect(error).toBeInstanceOf(WorkerConfigError);
const workerConfigError = error as WorkerConfigError;
expect(workerConfigError.message).toBe("Invalid worker configuration (BULLMQ_REDIS_URL:missing-required).");
expect(workerConfigError.details.diagnostics).toEqual([
expect.objectContaining({
code: "missing-required",
name: "BULLMQ_REDIS_URL",
message: "BULLMQ_REDIS_URL or REDIS_URL is required when WORKER_ENABLED is true.",
}),
]);
expect(JSON.stringify({ message: workerConfigError.message, details: workerConfigError.details })).not.toContain(REDIS_WITH_PASSWORD);
}
});
test("throws redacted WorkerConfigError for invalid Redis URL values", () => {
const cases = [
{
rawUrl: "redis://:super-secret-password@",
message: "Invalid worker configuration (BULLMQ_REDIS_URL:invalid-redis-url).",
code: "invalid-redis-url",
},
{
rawUrl: "https://:super-secret-password@redis.example.com/0",
message: "Invalid worker configuration (BULLMQ_REDIS_URL:invalid-redis-protocol).",
code: "invalid-redis-protocol",
},
{
rawUrl: "redis://:super-secret-password@redis.example.com/not-a-db",
message: "Invalid worker configuration (BULLMQ_REDIS_URL:invalid-redis-database).",
code: "invalid-redis-database",
},
] as const;
for (const invalidCase of cases) {
try {
loadRequiredWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: invalidCase.rawUrl,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
throw new Error("Expected loadRequiredWorkerConfig to throw.");
} catch (error) {
expect(error).toBeInstanceOf(WorkerConfigError);
const workerConfigError = error as WorkerConfigError;
expect(workerConfigError.message).toBe(invalidCase.message);
expect(workerConfigError.details.diagnostics).toContainEqual(expect.objectContaining({ code: invalidCase.code }));
const errorText = JSON.stringify({ message: workerConfigError.message, details: workerConfigError.details });
expect(errorText).not.toContain(invalidCase.rawUrl);
expect(errorText).not.toContain("super-secret-password");
}
}
});
});
describe("loadWorkerConfig", () => {
test("keeps local default disabled without Redis", () => {
const result = loadWorkerConfig({});
expect(result.ok).toBe(true);
expect(result.config).toMatchObject({
appName: "ToolController",
nodeEnv: "development",
enabled: false,
concurrency: 1,
redis: {
source: "none",
configured: false,
parseStatus: "not-provided",
},
queues: {
email: "email",
workflow: "workflow",
},
mailjet: {
configured: false,
},
browserRuntime: {
configured: false,
},
});
expect(result.diagnostics).toEqual([]);
});
test("is ready with BULLMQ Redis, Mailjet, browser runtime and queue defaults", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
REDIS_URL: "redis://fallback.example.com/0",
MAILJET_API_KEY: " mailer-public-key ",
MAILJET_SECRET_KEY: " mailer-secret-key ",
MAILJET_FROM_EMAIL: " support@example.com ",
MAILJET_FROM_NAME: " Example Support ",
BROWSER_RUNTIME_URL: " https://browser-runtime.example.com ",
BROWSER_RUNTIME_API_KEY: " browser-secret-key ",
BROWSER_SESSION_TIMEOUT_MS: " 45000 ",
WORKER_CONCURRENCY: " 4 ",
});
expect(result.ok).toBe(true);
expect(result.config.enabled).toBe(true);
expect(result.config.concurrency).toBe(4);
expect(result.config.redis).toMatchObject({
source: "BULLMQ_REDIS_URL",
url: REDIS_WITH_PASSWORD,
configured: true,
parseStatus: "valid",
database: 2,
});
expect(result.config.mailjet).toEqual({
configured: true,
apiKey: "mailer-public-key",
secretKey: "mailer-secret-key",
fromEmail: "support@example.com",
fromName: "Example Support",
});
expect(result.config.browserRuntime).toEqual({
configured: true,
url: "https://browser-runtime.example.com",
apiKey: "browser-secret-key",
sessionTimeoutMs: 45000,
});
expect(result.diagnostics).toEqual([]);
});
test("falls back to REDIS_URL when BULLMQ_REDIS_URL is absent", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
REDIS_URL: "redis://localhost:6379/0",
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
EMAIL_QUEUE_NAME: "mailers",
WORKFLOW_QUEUE_NAME: "workflow-jobs",
});
expect(result.ok).toBe(true);
expect(result.config.redis).toMatchObject({
source: "REDIS_URL",
configured: true,
parseStatus: "valid",
database: 0,
});
expect(result.config.queues).toEqual({
email: "mailers",
workflow: "workflow-jobs",
});
});
test("reports enabled workers without Redis as missing required", () => {
const result = loadWorkerConfig({ WORKER_ENABLED: "true", DATABASE_URL, WORKER_QUEUE_GROUP: "general" });
expect(result.ok).toBe(false);
expect(result.config.enabled).toBe(true);
expect(result.config.redis).toMatchObject({
source: "none",
configured: false,
parseStatus: "not-provided",
});
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "BULLMQ_REDIS_URL",
message: "BULLMQ_REDIS_URL or REDIS_URL is required when WORKER_ENABLED is true.",
})
);
});
test("reports enabled workers without DATABASE_URL as missing required", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
WORKER_QUEUE_GROUP: "general",
});
expect(result.ok).toBe(false);
expect(result.config.enabled).toBe(true);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "DATABASE_URL",
message: "DATABASE_URL is required when WORKER_ENABLED is true.",
})
);
expect(JSON.stringify(result.diagnostics)).not.toContain("db-secret");
});
test("reports enabled workers without WORKER_QUEUE_GROUP as missing required", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
});
expect(result.ok).toBe(false);
expect(result.config.enabled).toBe(true);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "WORKER_QUEUE_GROUP",
message: "WORKER_QUEUE_GROUP is required when WORKER_ENABLED is true.",
})
);
});
test("reports invalid WORKER_QUEUE_GROUP values", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
WORKER_QUEUE_GROUP: "all",
});
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-worker-queue-group",
name: "WORKER_QUEUE_GROUP",
message: "WORKER_QUEUE_GROUP must be one of: general, mail, import, webhook, plugin.",
})
);
});
test("reports invalid Redis protocol without leaking URL values", () => {
const rawUrl = "https://:super-secret-password@redis.example.com/0";
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: rawUrl,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
expect(result.ok).toBe(false);
expect(result.config.redis).toMatchObject({
source: "BULLMQ_REDIS_URL",
configured: false,
parseStatus: "invalid-protocol",
});
expect(result.diagnostics).toContainEqual(expect.objectContaining({ code: "invalid-redis-protocol" }));
expect(JSON.stringify(result.diagnostics)).not.toContain(rawUrl);
expect(JSON.stringify(result.diagnostics)).not.toContain("super-secret-password");
});
test("reports invalid REDIS_URL fallback diagnostics with the selected key name", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
REDIS_URL: "https://:super-secret-password@redis.example.com/0",
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
expect(result.ok).toBe(false);
expect(result.config.redis).toMatchObject({
source: "REDIS_URL",
configured: false,
parseStatus: "invalid-protocol",
});
expect(result.diagnostics).toContainEqual(expect.objectContaining({ code: "invalid-redis-protocol", name: "REDIS_URL" }));
expect(JSON.stringify(result.diagnostics)).not.toContain("super-secret-password");
});
test("reports invalid browser URL and timeout without leaking provider values", () => {
const rawBrowserUrl = "ftp://browser-secret-token@browser.example.com/session";
const result = loadWorkerConfig({
BROWSER_RUNTIME_URL: rawBrowserUrl,
BROWSER_RUNTIME_API_KEY: "browser-api-secret",
BROWSER_SESSION_TIMEOUT_MS: "not-a-timeout",
});
expect(result.ok).toBe(false);
expect(result.config.browserRuntime).toMatchObject({
configured: false,
apiKey: "browser-api-secret",
});
expect(result.diagnostics).toEqual(
expect.arrayContaining([
expect.objectContaining({ code: "invalid-url-protocol", name: "BROWSER_RUNTIME_URL" }),
expect.objectContaining({ code: "invalid-timeout", name: "BROWSER_SESSION_TIMEOUT_MS" }),
])
);
expect(JSON.stringify(result.diagnostics)).not.toContain(rawBrowserUrl);
expect(JSON.stringify(result.diagnostics)).not.toContain("browser-secret-token");
expect(JSON.stringify(result.diagnostics)).not.toContain("browser-api-secret");
});
test("reports invalid worker concurrency values without leaking unrelated env values", () => {
const cases = ["0", "-1", "1.5", "not-a-number", String(Number.MAX_SAFE_INTEGER + 1)] as const;
for (const rawConcurrency of cases) {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
WORKER_CONCURRENCY: rawConcurrency,
BROWSER_RUNTIME_API_KEY: "browser-api-secret",
});
expect(result.ok).toBe(false);
expect(result.config.enabled).toBe(true);
expect(result.config.concurrency).toBe(1);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-concurrency",
name: "WORKER_CONCURRENCY",
message: "WORKER_CONCURRENCY must be a positive safe integer.",
})
);
expect(JSON.stringify(result.diagnostics)).not.toContain("browser-api-secret");
}
});
test("loadRequiredWorkerConfig blocks enabled startup with invalid worker concurrency", () => {
expect(() =>
loadRequiredWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
WORKER_CONCURRENCY: "0",
})
).toThrow(WorkerConfigError);
try {
loadRequiredWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_WITH_PASSWORD,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
WORKER_CONCURRENCY: "0",
});
} catch (error) {
expect(error).toBeInstanceOf(WorkerConfigError);
const workerConfigError = error as WorkerConfigError;
expect(workerConfigError.message).toBe("Invalid worker configuration (WORKER_CONCURRENCY:invalid-concurrency).");
expect(workerConfigError.details.diagnostics).toEqual([
expect.objectContaining({
code: "invalid-concurrency",
name: "WORKER_CONCURRENCY",
message: "WORKER_CONCURRENCY must be a positive safe integer.",
}),
]);
expect(JSON.stringify({ message: workerConfigError.message, details: workerConfigError.details })).not.toContain(REDIS_WITH_PASSWORD);
}
});
test("reports partial Mailjet config as redacted missing provider fields", () => {
const result = loadWorkerConfig({
MAILJET_API_KEY: "mailer-public-key",
});
expect(result.ok).toBe(false);
expect(result.config.mailjet).toMatchObject({
configured: false,
apiKey: "mailer-public-key",
});
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "MAILJET_FROM_EMAIL",
message: "MAILJET_FROM_EMAIL is required.",
})
);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "MAILJET_SECRET_KEY",
message: "MAILJET_SECRET_KEY is required.",
})
);
expect(JSON.stringify(result.diagnostics)).not.toContain("mailer-public-key");
});
test("reports invalid Redis database index and invalid URL construction without throwing", () => {
const invalidDatabase = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: "redis://:super-secret-password@redis.example.com/not-a-db",
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
expect(invalidDatabase.ok).toBe(false);
expect(invalidDatabase.config.redis.parseStatus).toBe("invalid-database");
expect(invalidDatabase.diagnostics).toContainEqual(expect.objectContaining({ code: "invalid-redis-database" }));
const invalidUrl = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: "redis://:super-secret-password@",
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
expect(invalidUrl.ok).toBe(false);
expect(invalidUrl.config.redis.parseStatus).toBe("invalid-url");
expect(invalidUrl.diagnostics).toContainEqual(expect.objectContaining({ code: "invalid-redis-url" }));
const diagnosticText = JSON.stringify([...invalidDatabase.diagnostics, ...invalidUrl.diagnostics]);
expect(diagnosticText).not.toContain("redis://:super-secret-password@");
expect(diagnosticText).not.toContain("super-secret-password");
});
});
@@ -0,0 +1,394 @@
import { getEnvVariableDefinition, validateEnv } from "./index.js";
import { validateBooleanFlag, validateOptionalSecretString, validateOptionalSecretUrl, validateRequiredSecretString } from "./secret-validator.js";
import type {
EnvRecord,
RequiredWorkerConfigOptions,
WorkerConfig,
WorkerConfigDiagnostic,
WorkerConfigErrorDetails,
WorkerConfigOptions,
WorkerConfigRedisParseStatus,
WorkerConfigRedisSource,
WorkerConfigResult,
} from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_QUEUE_NAMES = {
email: "email",
workflow: "workflow",
} as const;
const WORKER_QUEUE_GROUP_NAMES = ["general", "mail", "import", "webhook", "plugin"] as const;
export class WorkerConfigError extends Error {
readonly diagnostics: WorkerConfigDiagnostic[];
constructor(diagnostics: readonly WorkerConfigDiagnostic[]) {
super(formatWorkerConfigErrorMessage(diagnostics));
this.name = "WorkerConfigError";
this.diagnostics = diagnostics.map(redactDiagnostic);
}
get details(): WorkerConfigErrorDetails {
return {
diagnostics: this.diagnostics,
};
}
}
export function loadRequiredWorkerConfig(env: EnvRecord = process.env, options: RequiredWorkerConfigOptions = {}): WorkerConfig {
const result = loadWorkerConfig(env, options);
if (result.ok) {
return result.config;
}
throw new WorkerConfigError(result.diagnostics);
}
export function loadWorkerConfig(env: EnvRecord = process.env, options: WorkerConfigOptions = {}): WorkerConfigResult {
const nodeEnv = options.nodeEnv ?? env.NODE_ENV ?? DEFAULT_NODE_ENV;
const enabledValidation = validateBooleanFlag("WORKER_ENABLED", env.WORKER_ENABLED, false);
const enabled = enabledValidation.value ?? false;
const redisSelection = selectRedisUrl(env);
const redisParse = parseRedisUrl(redisSelection.value, redisSelection.source === "none" ? undefined : redisSelection.source);
const concurrency = parseWorkerConcurrency(env.WORKER_CONCURRENCY);
const mailjet = parseMailjetConfig(env);
const browserRuntime = parseBrowserRuntimeConfig(env);
const diagnostics: WorkerConfigDiagnostic[] = [
...toDiagnostics(
validateEnv(env, {
target: "worker",
nodeEnv,
includeOptionalProviders: options.includeOptionalProviders,
extraRequired: options.extraRequired,
}).missing.filter((issue) => issue.name !== "APP_NAME" && issue.name !== "DATABASE_URL")
),
];
diagnostics.push(...toWorkerDiagnostics(enabledValidation.diagnostics));
diagnostics.push(...concurrency.diagnostics, ...mailjet.diagnostics, ...browserRuntime.diagnostics);
if (enabled && redisSelection.source === "none") {
diagnostics.push({
code: "missing-required",
name: "BULLMQ_REDIS_URL",
classification: getEnvVariableDefinition("BULLMQ_REDIS_URL")?.classification,
message: "BULLMQ_REDIS_URL or REDIS_URL is required when WORKER_ENABLED is true.",
});
}
if (enabled && !present(env.DATABASE_URL)) {
diagnostics.push({
code: "missing-required",
name: "DATABASE_URL",
classification: getEnvVariableDefinition("DATABASE_URL")?.classification,
message: "DATABASE_URL is required when WORKER_ENABLED is true.",
});
}
if (enabled) {
const workerQueueGroup = present(env.WORKER_QUEUE_GROUP);
if (!workerQueueGroup) {
diagnostics.push({
code: "missing-required",
name: "WORKER_QUEUE_GROUP",
classification: getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.classification,
message: "WORKER_QUEUE_GROUP is required when WORKER_ENABLED is true.",
});
} else if (!isWorkerQueueGroupName(workerQueueGroup)) {
diagnostics.push({
code: "invalid-worker-queue-group",
name: "WORKER_QUEUE_GROUP",
classification: getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.classification,
message: `WORKER_QUEUE_GROUP must be one of: ${WORKER_QUEUE_GROUP_NAMES.join(", ")}.`,
});
}
}
if (redisParse.status !== "not-provided") {
for (const issue of redisParse.diagnostics) {
diagnostics.push(issue);
}
}
const config: WorkerConfig = {
appName: present(env.APP_NAME) ?? DEFAULT_APP_NAME,
nodeEnv,
enabled,
concurrency: concurrency.value,
redis: {
source: redisSelection.source,
url: redisSelection.value,
configured: redisSelection.source !== "none" && redisParse.status === "valid",
parseStatus: redisParse.status,
database: redisParse.database,
},
queues: {
email: present(env.EMAIL_QUEUE_NAME) ?? DEFAULT_QUEUE_NAMES.email,
workflow: present(env.WORKFLOW_QUEUE_NAME) ?? DEFAULT_QUEUE_NAMES.workflow,
},
mailjet: mailjet.config,
browserRuntime: browserRuntime.config,
};
return {
ok: diagnostics.length === 0,
config,
diagnostics,
};
}
function selectRedisUrl(env: EnvRecord): { source: WorkerConfigRedisSource; value?: string } {
const bullmqUrl = validateOptionalSecretString("BULLMQ_REDIS_URL", env.BULLMQ_REDIS_URL);
if (bullmqUrl.configured) {
return { source: "BULLMQ_REDIS_URL", value: bullmqUrl.value };
}
const redisUrl = validateOptionalSecretString("REDIS_URL", env.REDIS_URL);
if (redisUrl.configured) {
return { source: "REDIS_URL", value: redisUrl.value };
}
return { source: "none" };
}
function parseRedisUrl(
value: string | undefined,
source: Exclude<WorkerConfigRedisSource, "none"> = "BULLMQ_REDIS_URL"
): { status: WorkerConfigRedisParseStatus; database?: number; diagnostics: WorkerConfigDiagnostic[] } {
if (!value) {
return { status: "not-provided", diagnostics: [] };
}
const definition = getEnvVariableDefinition(source);
let url: URL;
try {
url = new URL(value);
} catch {
return {
status: "invalid-url",
diagnostics: [
{
code: "invalid-redis-url",
name: source,
classification: definition?.classification,
message: "Configured Redis URL must be a valid URL with redis: or rediss: protocol.",
},
],
};
}
if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
return {
status: "invalid-protocol",
diagnostics: [
{
code: "invalid-redis-protocol",
name: source,
classification: definition?.classification,
message: "Configured Redis URL protocol must be redis: or rediss:.",
},
],
};
}
const database = parseDatabaseIndex(url.pathname);
if (!database.valid) {
return {
status: "invalid-database",
diagnostics: [
{
code: "invalid-redis-database",
name: source,
classification: definition?.classification,
message: "Configured Redis URL database index must be a non-negative integer.",
},
],
};
}
return { status: "valid", database: database.value, diagnostics: [] };
}
function parseDatabaseIndex(pathname: string): { valid: true; value?: number } | { valid: false } {
const value = pathname.replace(/^\//, "");
if (!value) {
return { valid: true };
}
if (!/^\d+$/.test(value)) {
return { valid: false };
}
return { valid: true, value: Number(value) };
}
function isWorkerQueueGroupName(value: string): boolean {
return (WORKER_QUEUE_GROUP_NAMES as readonly string[]).includes(value);
}
function parseWorkerConcurrency(value: string | undefined): { value: number; diagnostics: WorkerConfigDiagnostic[] } {
const normalized = present(value);
if (!normalized) {
return { value: 1, diagnostics: [] };
}
if (!/^\d+$/.test(normalized)) {
return {
value: 1,
diagnostics: [
{
code: "invalid-concurrency",
name: "WORKER_CONCURRENCY",
classification: getEnvVariableDefinition("WORKER_CONCURRENCY")?.classification,
message: "WORKER_CONCURRENCY must be a positive safe integer.",
},
],
};
}
const parsed = Number(normalized);
if (!Number.isSafeInteger(parsed) || parsed <= 0) {
return {
value: 1,
diagnostics: [
{
code: "invalid-concurrency",
name: "WORKER_CONCURRENCY",
classification: getEnvVariableDefinition("WORKER_CONCURRENCY")?.classification,
message: "WORKER_CONCURRENCY must be a positive safe integer.",
},
],
};
}
return { value: parsed, diagnostics: [] };
}
function parseMailjetConfig(env: EnvRecord): {
config: WorkerConfig["mailjet"];
diagnostics: WorkerConfigDiagnostic[];
} {
const apiKey = validateOptionalSecretString("MAILJET_API_KEY", env.MAILJET_API_KEY);
const secretKey = validateOptionalSecretString("MAILJET_SECRET_KEY", env.MAILJET_SECRET_KEY);
const fromEmail = validateOptionalSecretString("MAILJET_FROM_EMAIL", env.MAILJET_FROM_EMAIL);
const fromName = validateOptionalSecretString("MAILJET_FROM_NAME", env.MAILJET_FROM_NAME);
const shouldRequireSet = apiKey.configured || secretKey.configured || fromEmail.configured;
const diagnostics: WorkerConfigDiagnostic[] = [];
if (shouldRequireSet) {
if (!apiKey.configured) {
diagnostics.push(...toWorkerDiagnostics(validateRequiredSecretString("MAILJET_API_KEY", env.MAILJET_API_KEY).diagnostics));
}
if (!secretKey.configured) {
diagnostics.push(...toWorkerDiagnostics(validateRequiredSecretString("MAILJET_SECRET_KEY", env.MAILJET_SECRET_KEY).diagnostics));
}
if (!fromEmail.configured) {
diagnostics.push(...toWorkerDiagnostics(validateRequiredSecretString("MAILJET_FROM_EMAIL", env.MAILJET_FROM_EMAIL).diagnostics));
}
}
return {
config: {
configured: apiKey.configured && secretKey.configured && fromEmail.configured,
apiKey: apiKey.value,
secretKey: secretKey.value,
fromEmail: fromEmail.value,
fromName: fromName.value,
},
diagnostics,
};
}
function parseBrowserRuntimeConfig(env: EnvRecord): {
config: WorkerConfig["browserRuntime"];
diagnostics: WorkerConfigDiagnostic[];
} {
const url = validateOptionalSecretUrl("BROWSER_RUNTIME_URL", env.BROWSER_RUNTIME_URL, { allowedProtocols: ["http", "https"] });
const apiKey = validateOptionalSecretString("BROWSER_RUNTIME_API_KEY", env.BROWSER_RUNTIME_API_KEY);
const timeout = parseOptionalPositiveInteger("BROWSER_SESSION_TIMEOUT_MS", env.BROWSER_SESSION_TIMEOUT_MS);
return {
config: {
configured: url.ok && url.configured,
url: url.value,
apiKey: apiKey.value,
sessionTimeoutMs: timeout.value,
},
diagnostics: [...toWorkerDiagnostics(url.diagnostics), ...timeout.diagnostics],
};
}
function parseOptionalPositiveInteger(
name: string,
value: string | undefined
): { value?: number; diagnostics: WorkerConfigDiagnostic[] } {
const normalized = present(value);
if (!normalized) {
return { diagnostics: [] };
}
if (!/^\d+$/.test(normalized)) {
return {
diagnostics: [
{
code: "invalid-timeout",
name,
classification: getEnvVariableDefinition(name)?.classification,
message: `${name} must be a positive integer in milliseconds.`,
},
],
};
}
const parsed = Number(normalized);
if (!Number.isSafeInteger(parsed) || parsed <= 0) {
return {
diagnostics: [
{
code: "invalid-timeout",
name,
classification: getEnvVariableDefinition(name)?.classification,
message: `${name} must be a positive integer in milliseconds.`,
},
],
};
}
return { value: parsed, diagnostics: [] };
}
function toWorkerDiagnostics(diagnostics: readonly { code: string; name: string; message: string; classification?: WorkerConfigDiagnostic["classification"] }[]): WorkerConfigDiagnostic[] {
return diagnostics.map((diagnostic) => ({
code: diagnostic.code === "invalid-url-protocol" ? "invalid-url-protocol" : (diagnostic.code as WorkerConfigDiagnostic["code"]),
name: diagnostic.name,
classification: diagnostic.classification,
message: diagnostic.message,
}));
}
function toDiagnostics(issues: ReturnType<typeof validateEnv>["missing"]): WorkerConfigDiagnostic[] {
return issues.map((issue) => ({
code: "missing-required",
name: issue.name,
classification: issue.classification,
message: issue.message,
}));
}
function formatWorkerConfigErrorMessage(diagnostics: readonly WorkerConfigDiagnostic[]): string {
const summary = diagnostics.map((diagnostic) => `${diagnostic.name}:${diagnostic.code}`).join(", ");
return `Invalid worker configuration (${summary}).`;
}
function redactDiagnostic(diagnostic: WorkerConfigDiagnostic): WorkerConfigDiagnostic {
return {
code: diagnostic.code,
name: diagnostic.name,
classification: diagnostic.classification,
message: diagnostic.message,
};
}
function present(value: string | undefined): string | undefined {
const trimmed = value?.trim();
return trimmed ? trimmed : undefined;
}