Files
clean-architecture-frontend…/src/bootstrap/runtime-config-schema.ts
T
DongHyeonka da1e128999 feat(bootstrap): 제품 capability·자격증명·설정 키를 제품 소유 파일로 받는다 (1101/09-02)
문제
제품이 http·telemetry·indexedDb 밖의 capability, 세션 밖 자격증명(BFF
쿠키 XSRF, Studio CSRF), 제품 런타임 설정 키를 넣으려면
runtime-adapters.ts, feature-adapter-contribution.ts, rest-profiles.ts,
release-artifacts.ts, runtime-config-schema.ts를 직접 고쳐야 한다. 이
파일들은 템플릿이 보안·계약 수정을 자주 넣는 곳이라, 동기화 때마다
fail-closed 코드를 손으로 병합한다(memento +61줄, tech-log +118줄).

고른 방법 (리뷰 09 4.2의 (B))
- FeaturePlatformCapabilities를 interface로 바꾼다. 제품은 이 repo의
  FeatureIndexedDbRepositories·ApplicationFeatureInputs와 같은
  declaration merging으로 capability를 더한다.
- 제품 소유 파일 둘을 빈 구현으로 둔다.
  - src/bootstrap/product-composition.ts: 추가 capability와 "인증 프로필
    id → 자격증명 제공자" 표. 계약 타입은 템플릿 소유
    product-composition-contract.ts에 둔다.
  - src/contracts/product-contracts.ts: 제품 인증 프로필과 런타임 설정
    zod 조각. 프로필 레지스트리와 strict 설정 스키마는 contracts 층에
    있고 빌드 스크립트도 읽는다. contracts는 bootstrap을 import할 수
    없어서 파일을 하나로 합치지 못했다.
- 판단 순서는 조립 루트가 쥔다: scope fence → ANONYMOUS 프로필 → 제품
  제공자 → 세션 → 응답 뒤 fence 재확인. 제공자가 throw하면 executor가
  CREDENTIAL_OWNER_FAILED로 닫는다. 나가는 헤더는 여전히 프로필 허용
  목록이 정한다.
- 제공자 계약은 기존 attachCredentials 시그니처를 그대로 쓴다.
- 제품 composition은 http capability가 생긴 뒤에 부른다. tech-log가
  두었던 전방 참조 stub이 필요 없다.
- 제품에 host 전체를 넘기지 않고 readCookie(name)만 넘긴다. host를 객체에
  담으면 browser-data-boundary/no-capability-alias가 막는다.
- http·telemetry는 spread 뒤에 둬서 제품이 바꿀 수 없다(타입에서도 뺀다).
  제품 프로필 id나 설정 키가 템플릿 이름과 겹치면 모듈 로드 때 throw한다.

버린 대안
- (A) 현 상태: 템플릿 비용은 0이지만 제품마다 동기화 비용이 반복된다.
- (C) 기능 계약 기여가 인증 프로필과 제공자를 함께 가져온다: 인증
  정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
- 제공자에 응답 관찰 훅 추가: tech-log의 401/403 토큰 폐기는 제품
  capability가 http를 감싸서 표현된다(픽스처). 제공자 계약을 작게 둔다.

위험·한계
- memento의 x-xsrf-token은 닫힌 자격증명 헤더 목록(VD-23,
  CREDENTIAL_HEADER_NAMES)에 없다. 그 이름을 쓰려면 여전히
  rest-profiles.ts를 고치거나 백엔드가 x-csrf-token을 받아야 한다.
  픽스처는 x-csrf-token으로 표현했다.
- 제품 설정 키의 FE-REG-ENV 행(src/contracts/env.ts)은 이 변경 밖이다.
  그 행을 요구하는 검사는 없다.
- tech-log가 부트 전에 BFF 세션 owner를 설치하는 코드
  (create-runtime-composition.ts)는 이 확장 지점 밖이다.
- 제공자 응답 뒤 fence 재확인은 executor가 같은 fence로 먼저 전송을
  끊어서 조립 루트 경유 테스트로는 따로 보이지 않는다. 세션 경로와 같은
  이중 방어로 둔다.
- V1 설정 문서도 제품 키를 받는다(없으면 기본값). V1은 한 릴리스 동안만
  쓰는 리더다.
- 초기 JS gzip 203,818 → 204,178 B(+360, 예산 204,800).

검증
- RED: tests/unit/runtime-adapters-credential-order.test.ts 7행 중 제품
  제공자를 기대하는 4행 실패(세션이 먼저 답해 UNAUTHENTICATED, owner가
  먼저 답해 SUCCESS). fence·ANONYMOUS·세션 3행은 통과.
- GREEN: 같은 파일 7/7. tests/unit/product-composition-fixture.test.ts
  9/9(가짜 제품 파일 두 개로 offsetUpload, runtime, BFF 쿠키 XSRF 읽기·
  쓰기, Studio CSRF 발급·403 폐기, 제품 설정 키, 이름 충돌 거절). 09-01
  tests/unit/runtime-adapters-auth-profile.test.ts 12/12.
- 회귀: tests/unit·contract·runtime-schema 182 files 2590 tests 통과.
  integration·component 47 files 386 tests 통과(pnpm을 띄우는
  security-followup-archive 제외). tsc app·test·node·recipes·web-worker·
  service-worker 통과. 바꾼 파일 eslint 통과. check:registries PASS
  (compatibility=breaking은 기존 route·storage 행). verify:documentation
  PASS_SCOPED. check:adapter-inventory PASS. check:architecture는 pnpm 대신
  exec 전용 shim으로 그래프·fixture PASS. 템플릿 런타임 설정 JSON
  schema는 baseline과 같다.
2026-11-03 00:56:40 +09:00

174 lines
5.8 KiB
TypeScript

import type { ProductFeatureOverrideMap } from "../contracts/product-features.ts";
import { PRODUCT_RUNTIME_CONFIG_FIELDS } from "../contracts/product-contracts.ts";
import {
runtimeConfigV1ArtifactSchema,
runtimeConfigV2ArtifactSchema,
type CapabilityOverrideArtifact,
type RuntimeConfigV1Artifact,
type RuntimeConfigV2Artifact,
} from "../contracts/release-artifacts.ts";
export { isValidReleaseManifestUrl } from "../contracts/release-artifacts.ts";
export type CapabilityOverrides = CapabilityOverrideArtifact;
/**
* §6.1. Runtime Config V2 is deployment and browser operational setting only.
* `API_CONTRACT_VERSION` is gone: a scalar cannot describe a multi-package
* contract set, and Release Manifest V2 `contractSet` owns that meaning.
*/
export const runtimeConfigV2Schema = runtimeConfigV2ArtifactSchema;
/**
* §5.8 / §24.6 RC-2. The V1 reader is retained for one compatibility window so
* a release never swaps source shape, manifest shape and runtime behaviour at
* the same time. Only a V1 document may carry the scalar contract version.
*/
export const runtimeConfigV1Schema = runtimeConfigV1ArtifactSchema;
export type RuntimeConfigV2 = RuntimeConfigV2Artifact;
export type RuntimeConfigV1 = RuntimeConfigV1Artifact;
/** 09-02. The product's keys from `product-contracts.ts`, as validated. */
type ProductRuntimeConfig = Pick<
RuntimeConfigV2,
keyof typeof PRODUCT_RUNTIME_CONFIG_FIELDS
>;
/**
* The composition-facing shape. V1 documents are normalized onto it so the rest
* of the runtime never branches on config schema version.
*/
export type RuntimeConfig = Readonly<{
APP_ENV: RuntimeConfigV2["APP_ENV"];
API_BASE_URL: string;
REQUEST_TIMEOUT_MS: number;
MAX_RETRY_ATTEMPTS: number;
TELEMETRY_ENABLED: boolean;
TELEMETRY_ENDPOINT?: string;
AUTH_MODE: RuntimeConfigV2["AUTH_MODE"];
CONFIG_SCHEMA_VERSION: string;
RELEASE_MANIFEST_URL: string;
RELEASE_ID?: string;
BUILD_ID?: string;
CAPABILITY_OVERRIDES: CapabilityOverrides;
/**
* §3.5. Runtime kill switch per installed feature. Subtractive only: a
* feature the build did not install cannot be named into existence here.
*/
FEATURE_OVERRIDES: ProductFeatureOverrideMap;
/** Present only while a V1 document is still accepted. */
LEGACY_API_CONTRACT_VERSION?: string;
}> &
Readonly<ProductRuntimeConfig>;
export type RuntimeConfigValidation =
| Readonly<{ success: true; data: RuntimeConfig; schema: "V1" | "V2" }>
| Readonly<{
success: false;
issues: readonly Readonly<{ path: string; code: string }>[];
}>;
const DEFAULT_OVERRIDES: CapabilityOverrides = Object.freeze({
REALTIME: "DEFAULT" as const,
WEB_WORKER: "DEFAULT" as const,
SERVICE_WORKER: "DEFAULT" as const,
OFFLINE_COMMANDS: "DEFAULT" as const,
});
function productRuntimeConfig(parsed: object): ProductRuntimeConfig {
return Object.fromEntries(
Object.keys(PRODUCT_RUNTIME_CONFIG_FIELDS).flatMap((key) => {
const value: unknown = Reflect.get(parsed, key);
return value === undefined ? [] : [[key, value]];
}),
) as ProductRuntimeConfig;
}
function canonicalUrl(value: string): string {
return new URL(value).href;
}
export function validateRuntimeConfig(value: unknown): RuntimeConfigValidation {
const declared =
value && typeof value === "object"
? (value as Record<string, unknown>).CONFIG_SCHEMA_VERSION
: undefined;
// §5.8: no precedence between V1 and V2. The declared version selects exactly
// one parser, and a V2 document carrying the removed scalar is rejected.
if (declared !== "1" && declared !== "2.0") {
return Object.freeze({
success: false as const,
issues: Object.freeze([
Object.freeze({
path: "CONFIG_SCHEMA_VERSION",
code: "unsupported_value",
}),
]),
});
}
const isV2 = declared === "2.0";
const result = isV2
? runtimeConfigV2Schema.safeParse(value)
: runtimeConfigV1Schema.safeParse(value);
if (!result.success) {
return Object.freeze({
success: false as const,
issues: Object.freeze(
result.error.issues.flatMap((issue) =>
// 09-04. A misspelt top-level key is one `unrecognized_keys` issue
// at the root; name each key so the boot error can say which.
(issue.code === "unrecognized_keys"
? issue.keys.map((key) => [...issue.path, key])
: [issue.path]
).map((path) =>
Object.freeze({ path: path.join("."), code: issue.code }),
),
),
),
});
}
const parsed = result.data;
const normalized: RuntimeConfig = Object.freeze({
APP_ENV: parsed.APP_ENV,
API_BASE_URL: canonicalUrl(parsed.API_BASE_URL),
REQUEST_TIMEOUT_MS: parsed.REQUEST_TIMEOUT_MS,
MAX_RETRY_ATTEMPTS: parsed.MAX_RETRY_ATTEMPTS,
TELEMETRY_ENABLED: parsed.TELEMETRY_ENABLED,
...(parsed.TELEMETRY_ENDPOINT
? { TELEMETRY_ENDPOINT: canonicalUrl(parsed.TELEMETRY_ENDPOINT) }
: {}),
AUTH_MODE: parsed.AUTH_MODE,
CONFIG_SCHEMA_VERSION: parsed.CONFIG_SCHEMA_VERSION,
RELEASE_MANIFEST_URL: parsed.RELEASE_MANIFEST_URL,
...(parsed.RELEASE_ID ? { RELEASE_ID: parsed.RELEASE_ID } : {}),
...(parsed.BUILD_ID ? { BUILD_ID: parsed.BUILD_ID } : {}),
...productRuntimeConfig(parsed),
CAPABILITY_OVERRIDES: Object.freeze({
...(isV2
? (parsed as RuntimeConfigV2).CAPABILITY_OVERRIDES
: DEFAULT_OVERRIDES),
}),
// A V1 document predates feature overrides, so it disables nothing.
FEATURE_OVERRIDES: Object.freeze({
...(isV2 ? (parsed as RuntimeConfigV2).FEATURE_OVERRIDES : {}),
}),
...(isV2
? {}
: {
LEGACY_API_CONTRACT_VERSION: (parsed as RuntimeConfigV1)
.API_CONTRACT_VERSION,
}),
});
return Object.freeze({
success: true as const,
data: normalized,
schema: isV2 ? ("V2" as const) : ("V1" as const),
});
}