import { PRODUCT_ENV_REGISTRY } from "./product-contracts.ts"; /** * §6.3. Case-insensitive key fragments that can never appear in a client * configuration document. */ const FORBIDDEN_CONFIG_NAME_FRAGMENTS = Object.freeze([ "PASSWORD", "SECRET", "TOKEN", "PRIVATE_KEY", "CLIENT_SECRET", "ACCESS_KEY", "REFRESH_TOKEN", "COOKIE", "AUTHORIZATION", ]); /** * Exact top-level keys whose fragment match is a semantic enum name, not a * credential. The allowlist is exact-key only; it is never applied to arbitrary * nested keys. */ const SEMANTIC_KEY_ALLOWLIST = Object.freeze( new Set(["AUTH_MODE", "TELEMETRY_ENABLED"]), ); /** * R-7.2. Exact top-level keys whose own keys are feature ids (data), not * configuration names: `cookie-consent` or `token-wallet` is a feature, not a * credential. Only the map keys are exempt; anything nested below them is * still checked. */ const FEATURE_ID_KEYED_MAPS = Object.freeze(new Set(["FEATURE_OVERRIDES"])); export type EnvironmentPhase = "build" | "runtime"; export type EnvironmentDefinition = Readonly<{ phase: EnvironmentPhase; classification: string; required: boolean; defaultValue: unknown; }>; /** * FE-REG-ENV. A runtime row states its key as `runtimeConfigV2ArtifactSchema` * (`release-artifacts.ts`) reads it: `required` when config.json must carry * the key, and `defaultValue` the value the schema gives an absent key, or * `null` when it gives none (1103/13-04, tests/unit/env-registry-coverage). */ export const ENV_REGISTRY = Object.freeze(withProductRows({ // F-6. Required: a staging or production build fails without it // (scripts/generate-runtime-config.ts). Local and development builds fall // back to the placeholder, which admission refuses for public targets. VITE_BUILD_ID: build("public-metadata", true, "local-build"), VITE_COMMIT_SHA: build("public-metadata", false, "local"), VITE_ROUTER_BASE_PATH: build("compile-time", true, "/"), VITE_RUNTIME_CONFIG_URL: build("compile-time", true, "/config.json"), APP_ENV: runtime("public", true, null), API_BASE_URL: runtime("public-sensitive", true, null), REQUEST_TIMEOUT_MS: runtime("public", false, 10_000), MAX_RETRY_ATTEMPTS: runtime("public", false, 2), TELEMETRY_ENABLED: runtime("public", true, null), TELEMETRY_ENDPOINT: runtime("public-sensitive", false, null), AUTH_MODE: runtime("public", true, null), CONFIG_SCHEMA_VERSION: runtime("public", true, null), RELEASE_MANIFEST_URL: runtime("public", false, "/release-manifest.json"), // F-6. The release identity the build writes into config.json. It must match // the deployed HTML and release manifest, or boot stops with // CONFIG_BUILD_MISMATCH (scripts/check-release-admission.ts). RELEASE_ID: runtime("public-metadata", false, null), BUILD_ID: runtime("public-metadata", false, null), // §3.5: overrides may only disable an installed capability, never enable one. CAPABILITY_OVERRIDES: runtime("public", false, Object.freeze({ REALTIME: "DEFAULT", WEB_WORKER: "DEFAULT", SERVICE_WORKER: "DEFAULT", OFFLINE_COMMANDS: "DEFAULT", })), // §3.5: likewise for features — subtractive, keyed by installed feature id. FEATURE_OVERRIDES: runtime("public", false, Object.freeze({})), // §3.5: build-time narrowing of the product manifest, applied by // scripts/generate-product-feature-index.ts (09-02). A feature left out here // is not imported by any registry and never reaches the bundle. VITE_PRODUCT_FEATURES: build("compile-time", false, null), })); /** * 09-02. The product's rows (`product-contracts.ts`) join FE-REG-ENV and are * checked with it. A product row cannot take a template key's name. */ function withProductRows>>( rows: Rows, ) { const product: Readonly> = PRODUCT_ENV_REGISTRY; const reused = Object.keys(product).find((name) => Object.hasOwn(rows, name)); if (reused !== undefined) { throw new TypeError(`Product env key ${reused} is a template key.`); } return { ...rows, ...product }; } function build( classification: string, required: boolean, defaultValue: unknown, ): EnvironmentDefinition { return Object.freeze({ phase: "build", classification, required, defaultValue }); } function runtime( classification: string, required: boolean, defaultValue: unknown, ): EnvironmentDefinition { return Object.freeze({ phase: "runtime", classification, required, defaultValue }); } export function assertSafeConfigNames( config: Readonly>, depth = 0, ): void { if (depth > 4) { throw new Error("Client configuration nesting exceeds its bound"); } for (const [name, value] of Object.entries(config)) { const allowlisted = depth === 0 && SEMANTIC_KEY_ALLOWLIST.has(name); if (!allowlisted && isForbiddenConfigName(name)) { throw new Error(`Forbidden client configuration key: ${name}`); } if (!isPlainNested(value)) continue; if (depth === 0 && FEATURE_ID_KEYED_MAPS.has(name)) { for (const entry of Object.values(value)) { if (isPlainNested(entry)) assertSafeConfigNames(entry, depth + 2); } } else { assertSafeConfigNames(value, depth + 1); } } } function isPlainNested(value: unknown): value is Record { return Boolean(value) && typeof value === "object" && !Array.isArray(value); } function isForbiddenConfigName(name: string): boolean { const upper = name.toUpperCase(); return FORBIDDEN_CONFIG_NAME_FRAGMENTS.some((fragment) => upper.includes(fragment), ); } export type BuildEnvironment = Readonly<{ VITE_BUILD_ID?: string; VITE_COMMIT_SHA?: string; VITE_ROUTER_BASE_PATH?: string; VITE_RUNTIME_CONFIG_URL?: string; }>; /** * 13-06. Each variable is read by key so Vite replaces it on its own. Passing * `import.meta.env` whole made Vite inline every loaded VITE_* value, read or * not, into this module's chunk. */ export function getBuildConfig( environment: BuildEnvironment = { VITE_BUILD_ID: import.meta.env.VITE_BUILD_ID, VITE_COMMIT_SHA: import.meta.env.VITE_COMMIT_SHA, VITE_ROUTER_BASE_PATH: import.meta.env.VITE_ROUTER_BASE_PATH, VITE_RUNTIME_CONFIG_URL: import.meta.env.VITE_RUNTIME_CONFIG_URL, }, ) { const buildId = environment.VITE_BUILD_ID || "local-build"; const commitSha = environment.VITE_COMMIT_SHA || "local"; const routerBasePath = environment.VITE_ROUTER_BASE_PATH || "/"; // 13-07. dist is served under the base path, so the default follows it. const runtimeConfigUrl = environment.VITE_RUNTIME_CONFIG_URL || `${routerBasePath}config.json`; return Object.freeze({ buildId, commitSha, routerBasePath, runtimeConfigUrl }); }