diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index ca3ce7c8..d4b56fcf 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -110,7 +110,7 @@ release admission refused for staging: - 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../architecture/realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02). - `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때. - 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다. - - 설정 키 이름에 `TOKEN`·`COOKIE`·`SECRET`·`PASSWORD` 같은 조각(`src/contracts/env.ts`의 `FORBIDDEN_CONFIG_NAME_FRAGMENTS`, 대소문자 무관)을 넣지 않는다. 부팅이 `CONFIG_SECRET_NAME_REJECTED`로 멈춘다. `test:unit`의 `env-registry-coverage`가 먼저 `Forbidden client configuration key: <키>`로 실패한다. + - 설정 키 이름에 `TOKEN`·`COOKIE`·`SECRET`·`PASSWORD` 같은 조각(`src/contracts/env.ts`의 `FORBIDDEN_CONFIG_NAME_FRAGMENTS`, 대소문자 무관)을 넣지 않는다. 부팅이 `CONFIG_SECRET_NAME_REJECTED`로 멈추고, 오류 화면의 "잘못된 설정 키"에 그 키 이름(값은 아님. 중첩 키는 `CAPABILITY_OVERRIDES.AUTH_TOKEN`처럼 경로)이 나온다. `test:unit`의 `env-registry-coverage`가 먼저 `Forbidden client configuration key: <키>`로 실패한다. - FE-REG-ENV 행의 `required`·`defaultValue`는 zod 필드가 키가 없을 때 하는 것과 같게 적는다. 기본값이 없으면 `defaultValue: null`이다. 같은 테스트가 대조한다. - `config/runtime/.json`: 환경별로 기능을 끄고 싶을 때(`FEATURE_OVERRIDES`). - `src/features/product-capabilities.ts`의 선택 런타임(`PRODUCT_RUNTIME_CAPABILITY_SELECTION`): Service Worker를 켤 때. 아래 "SW 켜기"를 본다. diff --git a/src/bootstrap/load-runtime-config.ts b/src/bootstrap/load-runtime-config.ts index 566002fa..b31898ba 100644 --- a/src/bootstrap/load-runtime-config.ts +++ b/src/bootstrap/load-runtime-config.ts @@ -1,4 +1,8 @@ -import { assertSafeConfigNames, getBuildConfig } from "../contracts/env.ts"; +import { + assertSafeConfigNames, + getBuildConfig, + UnsafeConfigNameError, +} from "../contracts/env.ts"; import { checkReleaseCoherence } from "../platform/release/release-coherence.ts"; import { BOOT_JSON_POLICIES, @@ -21,7 +25,10 @@ export type BootConfigSafe = Readonly<{ buildId: string; configSchemaVersion?: string; releaseId?: string; - /** 09-04. Names of rejected keys (never their values), bounded. */ + /** + * 09-04. Names of rejected keys (never their values), bounded: the keys the + * schema rejected, or (1103/07-04) the secret-looking key's dotted path. + */ invalidKeys?: readonly string[]; supportReference: string; }>; @@ -117,9 +124,16 @@ export async function loadRuntimeConfig( try { assertSafeConfigNames(rawConfig); - } catch { + } catch (error) { + // 1103/07-04. The rejected key's name, never its value, tells an operator + // what to remove. It comes from the rejected document, so it is bounded + // like the schema failure's keys below. + const key = error instanceof UnsafeConfigNameError ? error.key : undefined; throw new BootConfigError("CONFIG_SECRET_NAME_REJECTED", { buildId: buildConfig.buildId, + ...(key !== undefined && SAFE_KEY_PATTERN.test(key) + ? { invalidKeys: Object.freeze([key]) } + : {}), }); } diff --git a/src/contracts/env.ts b/src/contracts/env.ts index 0fcf1a9e..363bf00f 100644 --- a/src/contracts/env.ts +++ b/src/contracts/env.ts @@ -116,25 +116,56 @@ function runtime( return Object.freeze({ phase: "runtime", classification, required, defaultValue }); } +/** + * 1103/07-04. What `assertSafeConfigNames` throws. `key` is the rejected + * key's dotted path from where the check started + * (`CAPABILITY_OVERRIDES.AUTH_TOKEN`), so the boot error can name it without + * its value. It is absent when the document nests too deep. + */ +export class UnsafeConfigNameError extends Error { + readonly key: string | undefined; + + constructor(message: string, key?: string) { + super(message); + this.name = "UnsafeConfigNameError"; + this.key = key; + } +} + export function assertSafeConfigNames( config: Readonly>, depth = 0, +): void { + assertSafeConfigNamesAt(config, depth, []); +} + +function assertSafeConfigNamesAt( + config: Readonly>, + depth: number, + path: readonly string[], ): void { if (depth > 4) { - throw new Error("Client configuration nesting exceeds its bound"); + throw new UnsafeConfigNameError( + "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}`); + throw new UnsafeConfigNameError( + `Forbidden client configuration key: ${name}`, + [...path, name].join("."), + ); } 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); + for (const [featureId, entry] of Object.entries(value)) { + if (isPlainNested(entry)) { + assertSafeConfigNamesAt(entry, depth + 2, [...path, name, featureId]); + } } } else { - assertSafeConfigNames(value, depth + 1); + assertSafeConfigNamesAt(value, depth + 1, [...path, name]); } } } diff --git a/tests/runtime-schema/runtime-config.test.ts b/tests/runtime-schema/runtime-config.test.ts index 39ac1f86..451bcc30 100644 --- a/tests/runtime-schema/runtime-config.test.ts +++ b/tests/runtime-schema/runtime-config.test.ts @@ -294,6 +294,44 @@ describe("runtime configuration boundary", () => { expect(JSON.stringify(safe)).not.toContain("value-probe"); }); + // 1103/07-04. A secret-looking key stops boot before the schema runs. The + // boot error names that key, with its path below a nested map, and never + // its value. A key name that is not safe to show is left out. + it.each<[Record, readonly string[] | undefined]>([ + [{ CLIENT_SECRET: "value-probe" }, ["CLIENT_SECRET"]], + [ + { CAPABILITY_OVERRIDES: { AUTH_TOKEN: "value-probe" } }, + ["CAPABILITY_OVERRIDES.AUTH_TOKEN"], + ], + [ + { FEATURE_OVERRIDES: { alpha: { CLIENT_SECRET: "value-probe" } } }, + ["FEATURE_OVERRIDES.alpha.CLIENT_SECRET"], + ], + [{ "CLIENT_SECRET": "value-probe" }, undefined], + ])( + "names the forbidden key of %o as %o, never its value (1103/07-04)", + async (extra, invalidKeys) => { + const failure = await loadRuntimeConfig({ + buildConfig: { + buildId: "build-a", + commitSha: "local", + routerBasePath: "/", + runtimeConfigUrl: "/config.json", + }, + fetcher: async () => + new Response(JSON.stringify({ ...validConfig, ...extra }), { + headers: { "content-type": "application/json" }, + }), + }).catch((error: unknown) => error); + + expect(failure).toBeInstanceOf(BootConfigError); + const safe = (failure as BootConfigError).safe; + expect(safe.code).toBe("CONFIG_SECRET_NAME_REJECTED"); + expect(safe.invalidKeys).toEqual(invalidKeys); + expect(JSON.stringify(safe)).not.toContain("value-probe"); + }, + ); + it("returns only safe boot fields on failure", async () => { await expect( loadRuntimeConfig({