문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.
고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
"REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).
버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
매핑을 알아야 한다. 프로필 항목 하나가 더 작다.
위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
청크라 초기 크기에 영향이 없다.
검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
undefined to match object { transport: 'BEARER_HEADER', …(1) }",
"expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
(FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
http-scenario-evidence, ci-workflow-generation, lab-performance,
fixture-node-modules, deployment-admission, security-followup-archive).
tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
418 lines
13 KiB
TypeScript
418 lines
13 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
|
|
import {
|
|
composeContractContributions,
|
|
ContractContributionError,
|
|
type ComposedContractContributions,
|
|
} from "../../src/contracts/external-contract-runtime.ts";
|
|
import {
|
|
installRestAuthProfileRegistry,
|
|
INSTALLED_REST_AUTH_PROFILES,
|
|
REST_AUTH_PROFILES,
|
|
} from "../../src/contracts/rest-profiles.ts";
|
|
import {
|
|
TEST_CONTRACT_CONTRIBUTION,
|
|
TEST_EVENT_CONTRACT,
|
|
} from "../helpers/external-contract-fixture.ts";
|
|
|
|
/**
|
|
* LIVE-02 / LIVE-03. `Object.freeze(new Map(...))` freezes the wrapper object,
|
|
* not the backing store: `set`, `delete` and `clear` keep working. Every
|
|
* registry the executor consults after composition must therefore be a read
|
|
* facade over a private store, and the rows it hands back must be exact
|
|
* own-data snapshots that a later mutation of the source cannot reach.
|
|
*/
|
|
|
|
const MUTATORS = ["set", "delete", "clear"] as const;
|
|
|
|
function borrowedMapMutation(
|
|
facade: unknown,
|
|
mutator: (typeof MUTATORS)[number],
|
|
): "THREW" | "MUTATED" {
|
|
try {
|
|
switch (mutator) {
|
|
case "set":
|
|
Map.prototype.set.call(facade as never, "INJECTED", {} as never);
|
|
break;
|
|
case "delete":
|
|
Map.prototype.delete.call(facade as never, "ANONYMOUS");
|
|
break;
|
|
case "clear":
|
|
Map.prototype.clear.call(facade as never);
|
|
break;
|
|
}
|
|
return "MUTATED";
|
|
} catch {
|
|
return "THREW";
|
|
}
|
|
}
|
|
|
|
describe("LIVE-02 installed REST auth profile registry", () => {
|
|
it("exposes no mutation API", () => {
|
|
const registry = INSTALLED_REST_AUTH_PROFILES as unknown as Record<
|
|
string,
|
|
unknown
|
|
>;
|
|
for (const mutator of MUTATORS) {
|
|
expect(registry[mutator]).toBeUndefined();
|
|
}
|
|
});
|
|
|
|
it("survives a cast mutation and a borrowed Map.prototype mutator", () => {
|
|
const registry = installRestAuthProfileRegistry(REST_AUTH_PROFILES);
|
|
const before = registry.size;
|
|
const identity = registry.get("ANONYMOUS");
|
|
expect(identity).toBeDefined();
|
|
|
|
for (const mutator of MUTATORS) {
|
|
expect(borrowedMapMutation(registry, mutator)).toBe("THREW");
|
|
}
|
|
|
|
expect(registry.size).toBe(before);
|
|
expect(registry.get("ANONYMOUS")).toBe(identity);
|
|
expect(registry.get("EXTERNAL_BEARER")?.credentials).toBe("omit");
|
|
});
|
|
|
|
it("does not observe a post-installation mutation of the source record", () => {
|
|
const source: Record<string, (typeof REST_AUTH_PROFILES)["ANONYMOUS"]> = {
|
|
ANONYMOUS: {
|
|
authProfileId: "ANONYMOUS",
|
|
transport: "ANONYMOUS",
|
|
credentials: "omit",
|
|
allowedCredentialHeaders: [],
|
|
requiredCredentialHeaders: [],
|
|
},
|
|
};
|
|
const registry = installRestAuthProfileRegistry(source);
|
|
delete source.ANONYMOUS;
|
|
expect(registry.get("ANONYMOUS")?.transport).toBe("ANONYMOUS");
|
|
});
|
|
|
|
it("keeps read APIs the executor depends on", () => {
|
|
const registry = INSTALLED_REST_AUTH_PROFILES;
|
|
expect(registry.has("ANONYMOUS")).toBe(true);
|
|
expect(registry.has("NO_SUCH_PROFILE")).toBe(false);
|
|
expect([...registry.keys()].sort()).toEqual([
|
|
"ANONYMOUS",
|
|
"EXTERNAL_BEARER",
|
|
"REFERENCE_EXTERNAL_BEARER",
|
|
]);
|
|
expect([...registry.entries()].length).toBe(registry.size);
|
|
expect([...registry.values()].length).toBe(registry.size);
|
|
});
|
|
});
|
|
|
|
describe("LIVE-03 composed contract registry", () => {
|
|
function compose(): ComposedContractContributions {
|
|
return composeContractContributions([TEST_CONTRACT_CONTRIBUTION] as never);
|
|
}
|
|
|
|
it("exposes no mutation API on either lookup", () => {
|
|
const composed = compose();
|
|
for (const facade of [composed.httpByOperationId, composed.eventByType]) {
|
|
const record = facade as unknown as Record<string, unknown>;
|
|
for (const mutator of MUTATORS) {
|
|
expect(record[mutator]).toBeUndefined();
|
|
}
|
|
for (const mutator of MUTATORS) {
|
|
expect(borrowedMapMutation(facade, mutator)).toBe("THREW");
|
|
}
|
|
}
|
|
expect(composed.httpByOperationId.size).toBeGreaterThan(0);
|
|
});
|
|
|
|
it("snapshots the frontend policy so a later source mutation cannot reach it", () => {
|
|
const mutablePolicy = {
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!.frontend,
|
|
};
|
|
const contribution = {
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
http: [
|
|
{
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!,
|
|
frontend: mutablePolicy,
|
|
},
|
|
],
|
|
};
|
|
const composed = composeContractContributions([contribution] as never);
|
|
const operationId = [...composed.httpByOperationId.keys()][0]!;
|
|
const installedBefore =
|
|
composed.httpByOperationId.get(operationId)!.frontend.totalDeadlineMs;
|
|
|
|
mutablePolicy.totalDeadlineMs = 999_999;
|
|
|
|
expect(
|
|
composed.httpByOperationId.get(operationId)!.frontend.totalDeadlineMs,
|
|
).toBe(installedBefore);
|
|
expect(installedBefore).not.toBe(999_999);
|
|
});
|
|
|
|
it("rejects an accessor or inherited policy field", () => {
|
|
const inherited = Object.create({ diagnosticsOperation: "INHERITED" }) as
|
|
Record<string, unknown>;
|
|
for (const [key, value] of Object.entries(
|
|
TEST_CONTRACT_CONTRIBUTION.http[0]!.frontend,
|
|
)) {
|
|
if (key === "diagnosticsOperation") continue;
|
|
inherited[key] = value;
|
|
}
|
|
const accessor = { ...TEST_CONTRACT_CONTRIBUTION.http[0]!.frontend };
|
|
Object.defineProperty(accessor, "totalDeadlineMs", {
|
|
configurable: true,
|
|
enumerable: true,
|
|
get: () => 10_000,
|
|
});
|
|
|
|
for (const frontend of [inherited, accessor]) {
|
|
expect(() =>
|
|
composeContractContributions([
|
|
{
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
http: [{ ...TEST_CONTRACT_CONTRIBUTION.http[0]!, frontend }],
|
|
},
|
|
] as never),
|
|
).toThrow();
|
|
}
|
|
});
|
|
|
|
/**
|
|
* NS-02. Composition validated the caller's object and then read it again to
|
|
* copy it. Between those two reads a stateful answer could swap a deadline or
|
|
* a retry budget, so the value that passed the ceiling check and the value the
|
|
* executor ran with were two different things.
|
|
*/
|
|
describe("validate the snapshot, never the source", () => {
|
|
/** Answers a safe value to a plain read and a hostile one to a copy. */
|
|
const statefulFrontend = () =>
|
|
new Proxy(
|
|
{ ...TEST_CONTRACT_CONTRIBUTION.http[0]!.frontend },
|
|
{
|
|
get(target, key, receiver) {
|
|
if (key === "totalDeadlineMs") return 10_000;
|
|
return Reflect.get(target, key, receiver);
|
|
},
|
|
getOwnPropertyDescriptor(target, key) {
|
|
if (key === "totalDeadlineMs") {
|
|
return {
|
|
configurable: true,
|
|
enumerable: true,
|
|
value: 999_999,
|
|
};
|
|
}
|
|
return Reflect.getOwnPropertyDescriptor(target, key);
|
|
},
|
|
},
|
|
);
|
|
|
|
const contributionWith = (row: unknown) => [
|
|
{ ...TEST_CONTRACT_CONTRIBUTION, http: [row] },
|
|
];
|
|
|
|
it("validates the deadline it will install, not the one it was shown", () => {
|
|
// The copied value exceeds the hard ceiling, so composition must stop
|
|
// rather than install a deadline no check ever saw.
|
|
expect(() =>
|
|
composeContractContributions(
|
|
contributionWith({
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!,
|
|
frontend: statefulFrontend(),
|
|
}) as never,
|
|
),
|
|
).toThrow();
|
|
});
|
|
|
|
it("keys the registry by the operation id it copied, not the one it was shown", () => {
|
|
const base = { ...TEST_CONTRACT_CONTRIBUTION.http[0]!.contract };
|
|
const contract = new Proxy(base, {
|
|
get(target, key, receiver) {
|
|
if (key === "operationId") return base.operationId;
|
|
return Reflect.get(target, key, receiver);
|
|
},
|
|
getOwnPropertyDescriptor(target, key) {
|
|
if (key === "operationId") {
|
|
return {
|
|
configurable: true,
|
|
enumerable: true,
|
|
value: "SwappedOperation",
|
|
};
|
|
}
|
|
return Reflect.getOwnPropertyDescriptor(target, key);
|
|
},
|
|
});
|
|
const composed = composeContractContributions(
|
|
contributionWith({
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!,
|
|
contract,
|
|
}) as never,
|
|
);
|
|
expect([...composed.httpByOperationId.keys()]).toEqual([
|
|
"SwappedOperation",
|
|
]);
|
|
expect(
|
|
composed.httpByOperationId.get("SwappedOperation")!.contract
|
|
.operationId,
|
|
).toBe("SwappedOperation");
|
|
});
|
|
|
|
const hostileRows = [
|
|
{
|
|
label: "an installed row with an extra own field",
|
|
row: () => ({
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!,
|
|
injected: true,
|
|
}),
|
|
},
|
|
{
|
|
label: "an installed row with a symbol field",
|
|
row: () => ({
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!,
|
|
[Symbol.for("injected")]: true,
|
|
}),
|
|
},
|
|
{
|
|
label: "an installed row with a custom prototype",
|
|
row: () =>
|
|
Object.assign(Object.create({ injected: true }), {
|
|
...TEST_CONTRACT_CONTRIBUTION.http[0]!,
|
|
}),
|
|
},
|
|
{
|
|
label: "an installed row hiding a non-enumerable own field",
|
|
row: () =>
|
|
Object.defineProperty(
|
|
{ ...TEST_CONTRACT_CONTRIBUTION.http[0]! },
|
|
"injected",
|
|
{ enumerable: false, value: true },
|
|
),
|
|
},
|
|
{
|
|
label: "an installed row behind a throwing ownKeys trap",
|
|
row: () =>
|
|
new Proxy(
|
|
{ ...TEST_CONTRACT_CONTRIBUTION.http[0]! },
|
|
{
|
|
ownKeys() {
|
|
throw new TypeError("hostile ownKeys trap");
|
|
},
|
|
},
|
|
),
|
|
},
|
|
];
|
|
|
|
for (const { label, row } of hostileRows) {
|
|
it(`refuses to compose ${label}`, () => {
|
|
expect(() =>
|
|
composeContractContributions(contributionWith(row()) as never),
|
|
).toThrow();
|
|
});
|
|
}
|
|
|
|
it("refuses a contribution whose own shape is not exact", () => {
|
|
for (const contribution of [
|
|
{ ...TEST_CONTRACT_CONTRIBUTION, injected: true },
|
|
Object.assign(Object.create({ injected: true }), {
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
}),
|
|
{
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
[Symbol.for("injected")]: true,
|
|
},
|
|
]) {
|
|
expect(() =>
|
|
composeContractContributions([contribution] as never),
|
|
).toThrow();
|
|
}
|
|
});
|
|
});
|
|
|
|
describe("event contracts", () => {
|
|
// 10-01. The shared contribution has no events, so every case here puts
|
|
// TEST_EVENT_CONTRACT (or a broken copy of it) into a copy of it.
|
|
const withEvents = (...events: unknown[]) =>
|
|
[{ ...TEST_CONTRACT_CONTRIBUTION, events }] as never;
|
|
|
|
it("installs a well-formed event contract as its own snapshot", () => {
|
|
const composed = composeContractContributions(
|
|
withEvents(TEST_EVENT_CONTRACT),
|
|
);
|
|
const installed = composed.eventByType.get(TEST_EVENT_CONTRACT.eventType);
|
|
expect(installed).toEqual(TEST_EVENT_CONTRACT);
|
|
expect(installed).not.toBe(TEST_EVENT_CONTRACT);
|
|
expect(Object.isFrozen(installed)).toBe(true);
|
|
expect(composed.contributions[0]!.events).toEqual([installed]);
|
|
});
|
|
|
|
const hostileEvents = [
|
|
{
|
|
label: "an extra own field",
|
|
event: () => ({ ...TEST_EVENT_CONTRACT, injected: true }),
|
|
},
|
|
{
|
|
label: "a custom prototype",
|
|
event: () =>
|
|
Object.assign(Object.create({ injected: true }), {
|
|
...TEST_EVENT_CONTRACT,
|
|
}),
|
|
},
|
|
{
|
|
label: "an accessor eventType",
|
|
event: () =>
|
|
Object.defineProperty({ ...TEST_EVENT_CONTRACT }, "eventType", {
|
|
enumerable: true,
|
|
get: () => TEST_EVENT_CONTRACT.eventType,
|
|
}),
|
|
},
|
|
{
|
|
label: "an empty eventType",
|
|
event: () => ({ ...TEST_EVENT_CONTRACT, eventType: "" }),
|
|
},
|
|
{
|
|
label: "an eventType with a space",
|
|
event: () => ({ ...TEST_EVENT_CONTRACT, eventType: "test entity" }),
|
|
},
|
|
{
|
|
label: "an eventType with a control character",
|
|
event: () => ({
|
|
...TEST_EVENT_CONTRACT,
|
|
eventType: "test\u0085entity",
|
|
}),
|
|
},
|
|
{
|
|
label: "an eventType over 160 UTF-8 bytes",
|
|
// 54 three-byte characters = 162 bytes in 54 UTF-16 units.
|
|
event: () => ({ ...TEST_EVENT_CONTRACT, eventType: "가".repeat(54) }),
|
|
},
|
|
{
|
|
label: "a missing envelope validator",
|
|
event: () => ({ ...TEST_EVENT_CONTRACT, envelopeValidator: null }),
|
|
},
|
|
{
|
|
label: "a payload validator without a schemaId",
|
|
event: () => ({
|
|
...TEST_EVENT_CONTRACT,
|
|
payloadValidator: {
|
|
...TEST_EVENT_CONTRACT.payloadValidator,
|
|
schemaId: "",
|
|
},
|
|
}),
|
|
},
|
|
];
|
|
|
|
for (const { label, event } of hostileEvents) {
|
|
it(`refuses an event contract with ${label}`, () => {
|
|
expect(() => composeContractContributions(withEvents(event()))).toThrow(
|
|
ContractContributionError,
|
|
);
|
|
});
|
|
}
|
|
|
|
it("refuses two event contracts with the same eventType", () => {
|
|
expect(() =>
|
|
composeContractContributions(
|
|
withEvents(TEST_EVENT_CONTRACT, { ...TEST_EVENT_CONTRACT }),
|
|
),
|
|
).toThrow(ContractContributionError);
|
|
});
|
|
});
|
|
});
|