문제
유일한 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
238 lines
7.6 KiB
TypeScript
238 lines
7.6 KiB
TypeScript
import { readdir, readFile } from "node:fs/promises";
|
|
import path from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import { defineRestOperation } from "../../src/contracts/api-operations.ts";
|
|
import {
|
|
composeContractContributions,
|
|
ContractContributionError,
|
|
} from "../../src/contracts/external-contract-runtime.ts";
|
|
import {
|
|
createRestProviderProfile,
|
|
INSTALLED_REST_AUTH_PROFILES,
|
|
installRestAuthProfileRegistry,
|
|
resolveRestSecurityProfiles,
|
|
REST_AUTH_PROFILES,
|
|
validateRestProfileBindings,
|
|
} from "../../src/contracts/rest-profiles.ts";
|
|
import { TEST_CONTRACT_CONTRIBUTION } from "../helpers/external-contract-fixture.ts";
|
|
|
|
/**
|
|
* §24.12: the common REST profile contract must stay independently verifiable
|
|
* after the sample feature is removed, so this suite owns its own operation
|
|
* fixture instead of importing an installed feature contract.
|
|
*/
|
|
const SAMPLE_COMMAND = defineRestOperation({
|
|
method: "POST",
|
|
path: "/api/sample-resources",
|
|
operationId: "CREATE_SAMPLE_RESOURCE",
|
|
auth: "external-session",
|
|
timeoutMs: null,
|
|
idempotency: "keyed",
|
|
retry: "runtime",
|
|
requestSource: "body",
|
|
requestSchema: "SampleCommand",
|
|
responseSchema: "SamplePayload",
|
|
owner: "platform-test-fixture",
|
|
contractVersion: 2,
|
|
protocol: "REST",
|
|
semantics: "COMMAND",
|
|
replayPolicy: "KEYED_COMMAND",
|
|
idempotencyKeyPolicy: "REQUIRED",
|
|
mapperId: "SampleMapper",
|
|
successStatuses: [200, 201],
|
|
responseMediaTypes: ["application/json"],
|
|
maxResponseBytes: 32_768,
|
|
providerId: "PRIMARY_API",
|
|
authProfileId: "EXTERNAL_BEARER",
|
|
csrfProfileId: "NO_CSRF_BEARER",
|
|
pathSchema: "NoRequest",
|
|
pathParameterNames: [],
|
|
maxEncodedSearchBytes: 0,
|
|
});
|
|
|
|
const SAMPLE_OPERATIONS = Object.freeze({
|
|
CREATE_SAMPLE_RESOURCE: SAMPLE_COMMAND,
|
|
});
|
|
|
|
describe("REST provider/auth/CSRF profiles", () => {
|
|
it("preserves the provider prefix and rejects unsafe endpoint forms", () => {
|
|
expect(
|
|
createRestProviderProfile(
|
|
"PRIMARY_API",
|
|
"https://api.test/base/",
|
|
["omit"],
|
|
),
|
|
).toMatchObject({
|
|
providerId: "PRIMARY_API",
|
|
baseUrl: "https://api.test/base/",
|
|
redirect: "error",
|
|
referrerPolicy: "no-referrer",
|
|
});
|
|
expect(() =>
|
|
createRestProviderProfile(
|
|
"PRIMARY_API",
|
|
"https://user:password@api.test/base/",
|
|
),
|
|
).toThrow("Invalid REST provider profile");
|
|
expect(() =>
|
|
createRestProviderProfile("PRIMARY_API", "http://api.test/base/"),
|
|
).toThrow("Invalid REST provider profile");
|
|
});
|
|
|
|
it("resolves bearer auth to omit credentials and no CSRF", () => {
|
|
const resolved = resolveRestSecurityProfiles(
|
|
SAMPLE_COMMAND,
|
|
createRestProviderProfile("PRIMARY_API", "https://api.test", ["omit"]),
|
|
);
|
|
expect(resolved).toMatchObject({
|
|
auth: {
|
|
transport: "BEARER_HEADER",
|
|
credentials: "omit",
|
|
allowedCredentialHeaders: ["authorization"],
|
|
},
|
|
csrf: { mode: "NONE" },
|
|
});
|
|
});
|
|
|
|
it("validates every installed profile binding as a set", () => {
|
|
expect(
|
|
validateRestProfileBindings(SAMPLE_OPERATIONS, {
|
|
PRIMARY_API: ["omit"],
|
|
}),
|
|
).toBe(true);
|
|
expect(() =>
|
|
validateRestProfileBindings(SAMPLE_OPERATIONS, {}),
|
|
).toThrow("Unregistered REST provider binding");
|
|
});
|
|
|
|
// 16-03. A copied feature that renamed the sample's profile id stopped every
|
|
// gate with one sentence that named neither the operation nor the profile.
|
|
it("names the operation, the profile and the broken condition", () => {
|
|
const renamed = Object.freeze({
|
|
CREATE_SAMPLE_RESOURCE: {
|
|
...SAMPLE_COMMAND,
|
|
authProfileId: "ORDER_EXTERNAL_BEARER",
|
|
},
|
|
});
|
|
expect(() =>
|
|
validateRestProfileBindings(renamed, { PRIMARY_API: ["omit"] }),
|
|
).toThrow(
|
|
/incoherent.*CREATE_SAMPLE_RESOURCE.*unknown authProfileId ORDER_EXTERNAL_BEARER/,
|
|
);
|
|
|
|
const publicWithBearer = Object.freeze({
|
|
CREATE_SAMPLE_RESOURCE: { ...SAMPLE_COMMAND, auth: "none" as const },
|
|
});
|
|
expect(() =>
|
|
validateRestProfileBindings(publicWithBearer, { PRIMARY_API: ["omit"] }),
|
|
).toThrow(
|
|
/CREATE_SAMPLE_RESOURCE.*auth "none" needs an ANONYMOUS profile.*EXTERNAL_BEARER is BEARER_HEADER/,
|
|
);
|
|
});
|
|
});
|
|
|
|
/**
|
|
* Q-6.7-9. Composition, the V3 executor and the V2 resolve must all answer
|
|
* from one validated installed registry. A raw record handed to resolve used
|
|
* to skip installation, so a bearer profile with ambient credentials passed.
|
|
*/
|
|
describe("one installed REST auth profile registry", () => {
|
|
const provider = createRestProviderProfile("PRIMARY_API", "https://api.test", [
|
|
"omit",
|
|
"same-origin",
|
|
]);
|
|
|
|
it("rejects a raw profile record that installation would refuse", () => {
|
|
const incoherent = {
|
|
EXTERNAL_BEARER: {
|
|
...REST_AUTH_PROFILES.EXTERNAL_BEARER,
|
|
credentials: "same-origin" as const,
|
|
},
|
|
};
|
|
expect(() =>
|
|
resolveRestSecurityProfiles(SAMPLE_COMMAND, provider, incoherent),
|
|
).toThrow(TypeError);
|
|
});
|
|
|
|
it("resolves through the installed registry", () => {
|
|
expect(
|
|
resolveRestSecurityProfiles(
|
|
SAMPLE_COMMAND,
|
|
provider,
|
|
INSTALLED_REST_AUTH_PROFILES,
|
|
).auth,
|
|
).toBe(INSTALLED_REST_AUTH_PROFILES.get("EXTERNAL_BEARER"));
|
|
});
|
|
|
|
it("does not resolve an inherited profile id", () => {
|
|
expect(() =>
|
|
resolveRestSecurityProfiles(
|
|
{ ...SAMPLE_COMMAND, authProfileId: "toString" },
|
|
provider,
|
|
REST_AUTH_PROFILES,
|
|
),
|
|
).toThrow("incoherent");
|
|
});
|
|
|
|
it("composes contributions against the registry it is given", () => {
|
|
const registry = installRestAuthProfileRegistry({
|
|
...REST_AUTH_PROFILES,
|
|
CUSTOM_BEARER: {
|
|
...REST_AUTH_PROFILES.EXTERNAL_BEARER,
|
|
authProfileId: "CUSTOM_BEARER",
|
|
},
|
|
});
|
|
const row = TEST_CONTRACT_CONTRIBUTION.http[0]!;
|
|
const contribution = {
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
http: [
|
|
{ ...row, frontend: { ...row.frontend, authProfileId: "CUSTOM_BEARER" } },
|
|
],
|
|
};
|
|
expect(() => composeContractContributions([contribution])).toThrow(
|
|
ContractContributionError,
|
|
);
|
|
expect(
|
|
composeContractContributions([contribution], registry).httpByOperationId
|
|
.size,
|
|
).toBe(1);
|
|
});
|
|
});
|
|
|
|
/**
|
|
* 1101/16-03. The only bearer profile is the platform's, not the sample's:
|
|
* `EXTERNAL_BEARER`. The old name stays for one release as a deprecated alias
|
|
* that resolves to the same transport and headers.
|
|
*/
|
|
describe("EXTERNAL_BEARER and its deprecated alias (16-03)", () => {
|
|
it("resolves the alias exactly like EXTERNAL_BEARER but for its id", () => {
|
|
expect(INSTALLED_REST_AUTH_PROFILES.get("EXTERNAL_BEARER")).toMatchObject({
|
|
transport: "BEARER_HEADER",
|
|
requiredCredentialHeaders: ["authorization"],
|
|
});
|
|
expect({
|
|
...INSTALLED_REST_AUTH_PROFILES.get("REFERENCE_EXTERNAL_BEARER"),
|
|
authProfileId: "EXTERNAL_BEARER",
|
|
}).toEqual(INSTALLED_REST_AUTH_PROFILES.get("EXTERNAL_BEARER"));
|
|
});
|
|
|
|
it("keeps the old name in src only on the alias line", async () => {
|
|
const files = (await readdir("src", { recursive: true }))
|
|
.filter((file) => /\.tsx?$/u.test(file))
|
|
.map((file) => path.join("src", file));
|
|
const lines: string[] = [];
|
|
for (const file of files) {
|
|
for (const line of (await readFile(file, "utf8")).split("\n")) {
|
|
if (line.includes("REFERENCE_EXTERNAL_BEARER")) {
|
|
lines.push(`${file}: ${line.trim()}`);
|
|
}
|
|
}
|
|
}
|
|
expect(lines).toEqual([
|
|
'src/contracts/rest-profiles.ts: REFERENCE_EXTERNAL_BEARER: Object.freeze({ ...EXTERNAL_BEARER, authProfileId: "REFERENCE_EXTERNAL_BEARER" }),',
|
|
]);
|
|
});
|
|
});
|