fix(release): 배포된 config.json 사본을 바꾸기 전에 검사한다 (1101/13-05)

문제
.env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고
적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를
검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고,
build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를
스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID
변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세
줄이고 고치는 방법이 없다.

고른 방법
- check-release-admission.ts가 `--config <고친 사본> --original <배포된
  원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고,
  원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도
  바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다.
  `--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지
  않는다).
- 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다.
  그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다.
- FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서
  rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고,
  release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치
  설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드
  없이 바꾼다"로 좁혔다.
- pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다.

버린 대안
- `--build-id <id>`로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼
  빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로
  더 좁다.
- release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더
  늘고, 여전히 BUILD_ID만 본다.
- 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어
  스위치의 목적이 사라진다(리뷰 대안 비교).

위험·한계
- 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도
  "바뀜"으로 거절한다(닫힌 쪽으로 실패).
- 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release
  기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
  새 6건 실패. 모두 "release admission refused: dist/config.json is
  unreadable"(--config를 무시하고 dist를 읽음)
- GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음,
  SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경·
  --original 누락은 exit 1
- runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed
- 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성),
  `-- --config dist/config.json --original public/config.json` ADMITTED
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
  PASS_SCOPED

Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05
This commit is contained in:
DongHyeonka
2026-11-01 22:49:13 +09:00
parent 629c8f045e
commit b3af26fc0e
6 changed files with 198 additions and 25 deletions
+5 -2
View File
@@ -5,8 +5,11 @@
#
# Runtime configuration — API endpoints, auth mode, telemetry, capability
# switches — is NOT here. It lives in `config/runtime/<profile>.json` and is
# materialized into `dist/config.json` at build time, so it can be changed
# without rebuilding. See the "Runtime configuration" section of README.md.
# materialized into `dist/config.json` at build time. Only the emergency
# switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) may be changed in a
# deployed config.json without rebuilding, by the checked procedure in
# docs/runbooks/FE-RB-001.md. See the "Runtime configuration" section of
# README.md.
#
# Copy to `.env.local` (git-ignored) to override locally.
@@ -515,7 +515,8 @@ Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가
스위치는 없다. 끄는 경로는 아래 둘이다.
- 페이지가 부팅하면: runtime config에 `CAPABILITY_OVERRIDES.SERVICE_WORKER:
"DISABLED"`를 넣는다. 재빌드는 필요 없다. 다음 부팅 때 page controller가 scope와
"DISABLED"`를 넣는다. 재빌드는 필요 없다. 사본을 고쳐 검사한 뒤 바꾸는 절차는
`docs/runbooks/FE-RB-001.md`에 있다. 다음 부팅 때 page controller가 scope와
script가 정확히 일치하는 등록만 unregister하고, 새 등록은 하지 않는다
(`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`,
`service-worker-page-controller.ts` `start()`의 `disabledCleanup` 분기). 소유
+3 -1
View File
@@ -173,7 +173,9 @@ same build as the HTML and assets it caches.
next boot unregisters the owned registration and registers nothing; owned
caches stay (`src/contracts/runtime-capabilities.ts`
`resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`).
This needs a page that boots.
This needs a page that boots. Edit a copy and check it with
`check:release-admission --config <copy> --original <deployed>` before it
replaces the served file (`docs/runbooks/FE-RB-001.md`).
3. **A worker stops the page from booting.** Deploy a release whose static
selection is `REMOVE_REGISTRATION`. It ships a self-unregistering
`service-worker.js` (`scripts/build-frontend.ts`,
+23
View File
@@ -7,3 +7,26 @@ the release owner.
Close only after a clean-session boot mounts the product root, config
validation evidence passes, and repeated boot-error telemetry is absent.
## Changing an emergency switch without a rebuild
Only `CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` may change in a deployed
`config.json`. Every browser validates the document on boot, so a typo there
causes this runbook's failure for every user. Change it in four steps:
1. Download the deployed `config.json` twice, as `deployed.json` (keep it as
is) and `edited.json`. Change only the switch in `edited.json`.
2. From a checkout of the deployed commit, run
`RELEASE_TARGET=<environment> corepack pnpm check:release-admission --config /abs/edited.json --original /abs/deployed.json`
(absolute paths: pnpm runs it from the repository root). It must print
`ADMITTED`. It refuses a schema error, a target rule, and any changed field
other than the two switches, `BUILD_ID` and `RELEASE_ID` included.
3. Upload `edited.json` next to the live file and rename it over
`config.json` on the same filesystem. Never edit the live file in place.
To undo, rename `deployed.json` back the same way.
4. Boot in a clean session (new browser profile) and see the product root
mount. The switch takes effect on the next boot only.
The served document then differs from the release record (`checksums.txt`,
the promoted archive). Note the change in the release log, and put it in the
profile (`config/runtime/<environment>.json`) for the next build.
+95 -21
View File
@@ -1,5 +1,6 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import process from "node:process";
import { parseArgs } from "node:util";
import {
DEPLOYMENT_TARGETS,
@@ -29,7 +30,62 @@ import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-
const RUNTIME_CONFIG_PATH = "dist/config.json";
const RECORD_PATH = "artifacts/release/deployment-admission.json";
/**
* 1101/13-05. The only fields an operator may change in a deployed config.json
* without a rebuild (docs/runbooks/FE-RB-001.md). Every other field belongs to
* the build: BUILD_ID and RELEASE_ID must still match the deployed HTML and
* release manifest, or every boot stops with CONFIG_BUILD_MISMATCH.
*/
const EMERGENCY_SWITCHES: ReadonlySet<string> = new Set([
"CAPABILITY_OVERRIDES",
"FEATURE_OVERRIDES",
]);
function refuse(reason: string): void {
process.stderr.write(`release admission refused: ${reason}\n`);
process.exitCode = 1;
}
function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
async function readRuntimeConfig(file: string): Promise<AdmissionInput | null> {
let document: unknown;
try {
document = JSON.parse(await readFile(file, "utf8"));
} catch (error) {
refuse(`${file} is unreadable: ${errorMessage(error)}`);
return null;
}
try {
return parseRuntimeConfigArtifact(document) as AdmissionInput;
} catch (error) {
refuse(`${file} is not a valid runtime config: ${errorMessage(error)}`);
return null;
}
}
function changedBuildFields(original: object, edited: object): string[] {
const before = new Map(Object.entries(original));
const after = new Map(Object.entries(edited));
return [...new Set([...before.keys(), ...after.keys()])]
.filter(
(field) =>
!EMERGENCY_SWITCHES.has(field) &&
JSON.stringify(before.get(field)) !== JSON.stringify(after.get(field)),
)
.sort();
}
async function main(): Promise<void> {
// `pnpm check:release-admission -- --config …` may pass the separator through.
const argv = process.argv.slice(2);
if (argv[0] === "--") argv.shift();
const { values: options } = parseArgs({
args: argv,
options: { config: { type: "string" }, original: { type: "string" } },
});
const declared = process.env["RELEASE_TARGET"];
if (!isDeploymentTarget(declared)) {
process.stderr.write(
@@ -54,30 +110,30 @@ async function main(): Promise<void> {
return;
}
let document: unknown;
try {
document = JSON.parse(await readFile(RUNTIME_CONFIG_PATH, "utf8"));
} catch (error) {
process.stderr.write(
`release admission refused: ${RUNTIME_CONFIG_PATH} is unreadable: ${
error instanceof Error ? error.message : String(error)
}\n`,
// 1101/13-05. An edited copy of the deployed document is checked against
// that document, so a changed build field is refused, not just a bad value.
const editedCopy = options.config;
if (editedCopy !== undefined && options.original === undefined) {
refuse(
"--config needs --original <the deployed config.json before the edit>; " +
"BUILD_ID, RELEASE_ID and every other build field are compared with it.",
);
process.exitCode = 1;
return;
}
let config: AdmissionInput;
try {
config = parseRuntimeConfigArtifact(document) as AdmissionInput;
} catch (error) {
process.stderr.write(
`release admission refused: ${RUNTIME_CONFIG_PATH} is not a valid runtime config: ${
error instanceof Error ? error.message : String(error)
}\n`,
);
process.exitCode = 1;
return;
const configPath = editedCopy ?? RUNTIME_CONFIG_PATH;
const config = await readRuntimeConfig(configPath);
if (config === null) return;
if (options.original !== undefined) {
const original = await readRuntimeConfig(options.original);
if (original === null) return;
const changed = changedBuildFields(original, config);
if (changed.length > 0) {
refuse(
`${configPath} changes ${changed.join(", ")}; without a rebuild only ` +
`${[...EMERGENCY_SWITCHES].join(" and ")} may change.`,
);
return;
}
}
const violations = findAdmissionViolations(declared, config);
@@ -93,6 +149,24 @@ async function main(): Promise<void> {
for (const warning of warnings) {
process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`);
}
if (editedCopy !== undefined) {
// The record is the build's admission evidence (a CI artifact); an
// operator's edited copy is not the build and does not replace it.
if (violations.length > 0) {
refuse(
`${editedCopy} for ${declared}:\n${violations
.map((violation) => ` ${violation.field}: ${violation.reason}`)
.join("\n")}`,
);
return;
}
process.stdout.write(
`release admission: ${editedCopy} ADMITTED for ${declared}; no field other than ` +
`${[...EMERGENCY_SWITCHES].join(" and ")} differs from ${options.original}. ` +
"Not recorded: this checks an edited copy, not the build.\n",
);
return;
}
await mkdir("artifacts/release", { recursive: true });
await writeFile(
RECORD_PATH,
+70
View File
@@ -269,3 +269,73 @@ describe("runtime config profiles", () => {
}
});
});
// 1101/13-05. The emergency switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES)
// are changed in the deployed config.json without a rebuild. A typo there stops
// every boot, so the edited copy is checked against the deployed one first.
describe("checking an edited copy of the deployed runtime config", () => {
async function check(
edit: (deployed: Record<string, unknown>) => Record<string, unknown>,
args: readonly string[] = ["--config", "edited.json", "--original", "deployed.json"],
) {
const root = await mkdtemp(path.join(tmpdir(), "release-admission-copy-"));
try {
const deployed = await generateRuntimeConfig("production", {
VITE_BUILD_ID: "20260815.42",
RELEASE_ID: "r-2026.08.15-1",
});
await writeFile(path.join(root, "deployed.json"), JSON.stringify(deployed));
await writeFile(path.join(root, "edited.json"), JSON.stringify(edit(deployed)));
const result = spawnSync(
process.execPath,
[path.resolve("scripts/check-release-admission.ts"), ...args],
{
cwd: root,
encoding: "utf8",
env: { ...process.env, APP_PROFILE: "production", RELEASE_TARGET: "production" },
},
);
const records = await readdir(path.join(root, "artifacts/release")).catch(() => []);
return { status: result.status, stderr: result.stderr, stdout: result.stdout, records };
} finally {
await rm(root, { recursive: true, force: true });
}
}
const withServiceWorker = (deployed: Record<string, unknown>, value: string) => ({
...deployed,
CAPABILITY_OVERRIDES: {
...(deployed["CAPABILITY_OVERRIDES"] as Record<string, unknown>),
SERVICE_WORKER: value,
},
});
it("admits a copy that only flips an emergency switch, without writing the build's record", async () => {
const result = await check((deployed) => withServiceWorker(deployed, "DISABLED"));
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toContain("edited.json");
expect(result.records).toEqual([]);
});
it("refuses a typo in a switch value", async () => {
const result = await check((deployed) => withServiceWorker(deployed, "DISABLE"));
expect(result.status).toBe(1);
expect(result.stderr).toMatch(/edited\.json is not a valid runtime config/u);
});
// A valid value, so only the comparison with the deployed copy can refuse it.
it.each([
["BUILD_ID", "20260815.43"],
["RELEASE_ID", "r-2026.08.15-2"],
["API_BASE_URL", "https://other.example.org/"],
])("refuses a copy that changes %s, which only a build may change", async (field, value) => {
const result = await check((deployed) => ({ ...deployed, [field]: value }));
expect(result.status).toBe(1);
expect(result.stderr).toContain(`edited.json changes ${field}`);
});
it("refuses --config without the deployed original to compare with", async () => {
const result = await check((deployed) => deployed, ["--config", "edited.json"]);
expect(result.status).toBe(1);
expect(result.stderr).toContain("--original");
});
});