215 lines
11 KiB
TypeScript
215 lines
11 KiB
TypeScript
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: ["web", "api", "worker"], source: "code-and-example" },
|
|
DATABASE_URL: { classification: "required-core", targets: ["shared", "web", "api", "mcp", "worker"], source: "code-and-example" },
|
|
SESSION_SECRET: { classification: "required-core", targets: ["web", "api"], source: "code-and-example" },
|
|
AUDIT_CHAIN_SECRET: { classification: "production-only", targets: ["web", "api", "mcp", "worker"], 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", "mcp", "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", "mcp", "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" },
|
|
HIVEGRID_API_MAINTENANCE_MODE: { classification: "production-only", targets: ["api"], source: "code" },
|
|
HIVEGRID_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",
|
|
"CRYPTO_SECRET",
|
|
"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_*"])
|
|
);
|
|
expect(getRequiredEnvVariableNames({ target: "mcp", nodeEnv: "production" })).not.toContain("APP_NAME");
|
|
expect(getRequiredEnvVariableNames({ target: "mcp", nodeEnv: "production" })).toEqual(
|
|
expect.arrayContaining(["DATABASE_URL", "REDIS_URL"])
|
|
);
|
|
});
|
|
|
|
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: "HiveGrid",
|
|
CRYPTO_SECRET: "crypto-secret",
|
|
ADMIN_CONNECTION_MASTER_KEY:
|
|
"admin-connection-master-key-value",
|
|
DATABASE_URL: "postgresql://user:pass@localhost:5432/app",
|
|
JWT_SECRET: "jwt-secret",
|
|
SESSION_SECRET: "session-secret",
|
|
ANALYTICS_TOKEN: "analytics-token",
|
|
AUDIT_CHAIN_SECRET: "audit-chain-secret-value-with-at-least-32-characters",
|
|
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 the required MCP shared-store URL and queue fallback");
|
|
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("Required by MCP in production and a BullMQ fallback elsewhere");
|
|
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.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=");
|
|
});
|
|
});
|