test(contracts): 금지 조각이 든 런타임 설정 키를 test:unit에서 막는다

문제
설정 키 금지 조각 검사(assertSafeConfigNames: TOKEN, COOKIE, SECRET 등)는
부팅 때 한 곳에서만 돈다. ece944d가 연 제품 키 경로로 PRODUCT_COOKIE_NOTICE
같은 키를 zod 필드·FE-REG-ENV 행·config/runtime 값으로 더하면
generateRuntimeConfig, 범위 테스트, check:registries가 모두 통과한다. 그
config.json으로 배포하면 모든 사용자가 부팅 실패 화면을 보고, 오류 코드
CONFIG_SECRET_NAME_REJECTED에는 키 이름이 없다(실험 E-4).

고른 방법
env-registry-coverage에 사례 하나를 더한다. V2 스키마가 읽는 키와
FE-REG-ENV 런타임 행 키 전부로, 값은 스키마 기본값(CAPABILITY_OVERRIDES의
중첩 키 포함)으로 문서를 만들어 assertSafeConfigNames에 넣는다. 실패
메시지가 키 이름을 말한다. 규칙은 매뉴얼 03 C절의 product-contracts.ts
항목에 적었다.

버린 대안
- product-contracts.ts 주석에 규칙 적기: 이 파일은 제품 소유이고 템플릿이
  복사 뒤에 고치지 않는다고 약속한 파일이다. 동기화 때 충돌을 만든다.
- generate-runtime-config에서도 검사: 스키마가 strict라 제품 키는 스키마
  필드여야 들어가고, 그 키는 이 테스트가 먼저 잡는다. 같은 검사를 한 곳
  더 두지 않았다.

위험·한계
- 부팅 오류 CONFIG_SECRET_NAME_REJECTED에 거절한 키 이름을 싣는 것은 하지
  않았다(src/bootstrap/load-runtime-config.ts, 다른 작업 범위).
- 제품 record 필드의 임의 중첩 키(값으로만 생기는 키)는 기본값에 없으면
  이 테스트가 보지 못한다. 부팅 검사가 여전히 막는다.

검증
- E-4 재실행: PRODUCT_COOKIE_NOTICE를 제품 zod 필드와 행으로 더하면 이
  사례가 "Forbidden client configuration key: PRODUCT_COOKIE_NOTICE"로
  실패한다. 되돌리면 4건 통과.
- eslint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-04
This commit is contained in:
DongHyeonka
2026-11-04 20:28:49 +09:00
parent a144b575e5
commit 9800bc89f3
2 changed files with 22 additions and 0 deletions
+2
View File
@@ -106,6 +106,8 @@ release admission refused for staging:
- 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다.
- `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: <키>`로 실패한다.
- FE-REG-ENV 행의 `required`·`defaultValue`는 zod 필드가 키가 없을 때 하는 것과 같게 적는다. 기본값이 없으면 `defaultValue: null`이다. 같은 테스트가 대조한다.
- `config/runtime/<profile>.json`: 환경별로 기능을 끄고 싶을 때(`FEATURE_OVERRIDES`).
- `package.json`, lockfile, `config/security/dependency-change-evidence.json`: 계약 패키지를 더할 때(B절).
+20
View File
@@ -3,6 +3,7 @@ import { isDeepStrictEqual } from "node:util";
import { describe, expect, it } from "vitest";
import {
assertSafeConfigNames,
ENV_REGISTRY,
type EnvironmentDefinition,
} from "../../src/contracts/env.ts";
@@ -61,4 +62,23 @@ describe("FE-REG-ENV coverage", () => {
expect(differences).toEqual([]);
});
// 1103/07-04. The boot refuses a config.json key with a credential-like
// name (`assertSafeConfigNames`). Checking every key the schema reads, with
// the nested keys of its defaults, fails here instead of at the first boot,
// and the error names the key.
it("names no runtime config key the boot would refuse", () => {
const keys = new Set([
...Object.keys(shape),
...Object.keys(rows).filter((key) => rows[key]!.phase === "runtime"),
]);
const document = Object.fromEntries(
[...keys].map((key) => [
key,
Object.hasOwn(shape, key) ? schemaDeclaration(key).defaultValue : null,
]),
);
expect(() => assertSafeConfigNames(document)).not.toThrow();
});
});