Files
clean-architecture-frontend…/src/contracts/env.ts
T
DongHyeonkaandClaude Opus 5.5 063375ed04 fix(contracts): fail public builds without VITE_BUILD_ID and record the local default (F-6, 13-15)
ENV_REGISTRY called VITE_BUILD_ID required with no default while every reader
fell back to local-build. Staging and production builds now fail without it;
local builds keep the placeholder, and the registry records that default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:32:54 +09:00

148 lines
5.2 KiB
TypeScript

/**
* §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;
}>;
export const ENV_REGISTRY = Object.freeze({
// 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, false),
TELEMETRY_ENDPOINT: runtime("public-sensitive", false, null),
AUTH_MODE: runtime("public", true, "external"),
CONFIG_SCHEMA_VERSION: runtime("public", true, null),
RELEASE_MANIFEST_URL: runtime("public", true, "/release-manifest.json"),
// §3.5: overrides may only disable an installed capability, never enable one.
CAPABILITY_OVERRIDES: runtime("public", false, null),
// §3.5: likewise for features — subtractive, keyed by installed feature id.
FEATURE_OVERRIDES: runtime("public", false, null),
// §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),
});
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<Record<string, unknown>>,
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<string, unknown> {
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 });
}