feat(bootstrap): 제품 세션 owner와 FE-REG-ENV 행을 제품 파일로 받는다 (1101/09-02)

문제
09-02(da1e128) 뒤에도 tech-log가 하는 일 두 가지는 템플릿 파일을 고쳐야
한다(리뷰 1101 README 14.4 "09-02 이식").
- 제품 설정 키의 FE-REG-ENV 행: tech-log는 템플릿 src/contracts/env.ts의
  ENV_REGISTRY에 TECH_LOG_STUDIO_SOURCE·TECH_LOG_PUBLIC_SOURCE 행을 직접
  넣었다(tech-log env.ts:63-70).
- 부트 전 BFF 세션 owner: 세션이 httpOnly 쿠키라 owner가 백엔드에 묻는다.
  tech-log는 템플릿 create-runtime-composition.ts에서 AUTH_MODE external이고
  Studio가 HTTP일 때 createRuntimeAdapters 전에 host 전역
  __CA_FRONTEND_AUTH_OWNER__에 owner를 넣는다(:2, :36-52,
  bff-session-owner.ts:188-194). composeProduct는 http가 생긴 뒤에 불리고
  http는 세션이 필요해서 이 일을 받을 수 없다.

고른 방법
- product-contracts.ts에 PRODUCT_ENV_REGISTRY를 빈 값으로 둔다. env.ts는
  PRODUCT_REST_AUTH_PROFILES·PRODUCT_RUNTIME_CONFIG_FIELDS와 같은 모양으로
  그 행을 ENV_REGISTRY에 합친다. 템플릿 키와 이름이 겹치면 모듈 로드 때
  throw한다. check:registries와 vite.config.ts가 같은 객체를 읽으므로 제품
  행도 같은 필드 검사를 받는다. 행을 더하기만 하면 additive라 기준선을
  고치지 않는다(실험: 제품 행 2개 → compatibility=additive PASS, 허용 밖
  classification → 실패).
- product-composition.ts에 composeProductSessionOwner(context)를 둔다.
  템플릿은 null을 돌려준다. 조립 루트가 세션을 고르기 전에, AUTH_MODE가
  external일 때만 부른다. 제품 owner가 host 전역보다 먼저다. null이면
  지금처럼 host 전역, 없으면 unavailable이다. demo 모드는 묻지 않는다.
  context는 config와 fetcher뿐이다(http 전이라 capability가 없다).

버린 대안
- owner를 composeProduct 반환값에 넣기: http가 세션을 쓰므로 순서가 꼬인다.
- 제품이 host 전역에 계속 넣게 두고 문서화: 부트 전 훅이 템플릿 파일
  (create-runtime-composition.ts)에 남는다.
- FE-REG-ENV 행을 PRODUCT_RUNTIME_CONFIG_FIELDS에서 자동으로 만들기: zod
  필드로는 classification·required를 알 수 없다.
- 행 타입·도우미를 product-contracts.ts가 env.ts에서 import: 순환 의존
  (no-circular-dependencies)이다. 타입 검사는 env.ts의 대입에서 한다.

위험·한계
- product-composition.ts에 export가 하나 늘었다. 이 파일을 이미 복사한
  제품은 composeProductSessionOwner를 더해야 한다. da1e128은 아직 main에
  없고 두 다운스트림 모두 받지 않았다.
- 제품 행을 as const 없이 쓰면 phase가 string으로 넓어져 tsc 오류가
  env.ts:78(템플릿 파일)에서 난다. 메시지에 키 이름은 나온다. product-
  contracts.ts 주석에 as const를 적었다.
- 제품 설정 키에 FE-REG-ENV 행이 있는지 요구하는 검사는 여전히 없다.
  템플릿 키도 RELEASE_ID·BUILD_ID는 행이 없어서 이 변경에서 넣지 않았다.
- 제품 owner가 throw하면 createRuntimeAdapters가 실패해 부트 실패
  화면이 된다. composeProduct와 같다.
- tech-log의 owner는 subject를 null로 돌려준다(템플릿 동작대로 매 변경
  fence). 이 변경과 무관하다.

검증
- RED: tests/unit/product-composition-fixture.test.ts 13건 중 3건 실패.
  FE-REG-ENV 행 없음, external 모드 세션이 authenticated가 아니라
  integration-failed, env 이름 충돌을 거절하지 않음.
- GREEN: 같은 파일 13/13, runtime-adapters-credential-order 7/7(mock에
  composeProductSessionOwner: () => null 추가).
- fixture는 vi.mock 대상이 제품 소유 두 파일(머리 주석 "Product-owned.")과
  설치 기능 seam 두 개뿐이고, tech-log가 고친 템플릿 파일 4개(env.ts,
  create-runtime-composition.ts, runtime-config-schema.ts,
  runtime-adapters.ts)는 대상이 아님을 이 파일의 소스를 읽어 확인한다.
- 회귀: tests/unit·contract·runtime-schema·integration 198 files 2861
  tests 통과(heavy lock 아래).
- tsc app·node·test 통과, 바꾼 파일 eslint 통과, check:registries PASS
  (compatibility=none, 재승인 불필요), verify:documentation PASS_SCOPED,
  check:adapter-inventory PASS.
- 초기 JS gzip 202,770 → 202,931 B(+161, 예산 204,800). 같은 방법(dist
  manifest의 초기 파일 26개, gzipSync 기본 레벨)으로 전·후를 쟀다.
- 미실행: check:architecture(pnpm 필요), test:component, e2e.
This commit is contained in:
DongHyeonka
2026-11-03 20:23:14 +09:00
parent 17fa8d1f65
commit ece944d08b
9 changed files with 293 additions and 20 deletions
@@ -1,3 +1,4 @@
import type { ExternalSessionOwner } from "../adapters/auth/index.ts";
import type {
ContractHttpExecutorDependencies,
InstalledHttpOperationExecutor,
@@ -11,6 +12,24 @@ import type { RuntimeConfig } from "./runtime-config-schema.ts";
* profiles and runtime-config keys) and never edits `runtime-adapters.ts`.
*/
/**
* What a product session owner is built from. It is asked first, before
* `http` exists (`http` needs the session), so it gets no capability.
*/
export type ProductSessionOwnerContext = Readonly<{
/** Validated runtime config, product keys included. */
config: RuntimeConfig;
fetcher?: typeof fetch;
}>;
/**
* The session owner when the product owns the session itself, such as a BFF
* whose session is an httpOnly cookie only the backend can read. Asked only
* when `AUTH_MODE` is `external`; it comes before the host's
* `__CA_FRONTEND_AUTH_OWNER__`, and `null` leaves the session to that global.
*/
export type ProductSessionOwner = ExternalSessionOwner | null;
/** Built by the template; a product cannot return or replace them. */
export type TemplatePlatformCapabilityId = "http" | "telemetry";
+8
View File
@@ -1,12 +1,20 @@
import type {
ProductComposition,
ProductCompositionContext,
ProductSessionOwner,
ProductSessionOwnerContext,
} from "./product-composition-contract.ts";
/**
* Product-owned. The template ships it empty and does not change it after a
* copy; the contract is in `product-composition-contract.ts`.
*/
export function composeProductSessionOwner(
context: ProductSessionOwnerContext,
): ProductSessionOwner {
return null;
}
export function composeProduct(context: ProductCompositionContext) {
return {
capabilities: {},
+14 -2
View File
@@ -64,7 +64,10 @@ import {
} from "./load-release-manifest.ts";
import type { RuntimeConfigLoadResult } from "./load-runtime-config.ts";
import { createServerStateGenerationStore } from "./server-state-generation-store.ts";
import { composeProduct } from "./product-composition.ts";
import {
composeProduct,
composeProductSessionOwner,
} from "./product-composition.ts";
import type { ProductComposition } from "./product-composition-contract.ts";
import { createInstalledContractRegistry } from "../features/installed-contract-contributions.ts";
import {
@@ -343,7 +346,16 @@ export async function createRuntimeAdapters(
context.host ?? (globalThis as unknown as Record<string, unknown>);
const config = context.runtime.config;
const mutationIntentFactory = createBrowserMutationIntentFactory();
const externalOwner = externalOwnerFrom(host);
// 09-02. A product that owns the session (a BFF's httpOnly cookie) returns
// its owner before anything resolves the session; the host global is the
// fallback. Demo mode keeps its own session and never asks.
const externalOwner =
config.AUTH_MODE === "demo"
? null
: (composeProductSessionOwner({
config,
...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }),
}) ?? externalOwnerFrom(host));
const authSession =
config.AUTH_MODE === "demo"
? createDemoSessionAdapter()