Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/config/src/env-access-inventory.test.ts
T

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