Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -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",
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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
+158
@@ -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");
|
||||
});
|
||||
});
|
||||
+205
@@ -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]*\|/);
|
||||
});
|
||||
});
|
||||
@@ -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}`;
|
||||
}
|
||||
+125
@@ -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[]>();
|
||||
});
|
||||
});
|
||||
@@ -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",
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
Reference in new issue
Block a user