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="); }); });