refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 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
This commit is contained in:
@@ -303,7 +303,7 @@ allowed/required credential header 집합을 독립적으로 재검증한다.
|
||||
|
||||
`AUTH_MODE=demo`는 profile을 약화시키지 않는다. `createDemoSessionAdapter`가
|
||||
고정된 비밀 아닌 `DEMO_AUTHORIZATION_MARKER` proof header를 제공하여 strict
|
||||
`REFERENCE_EXTERNAL_BEARER`를 그대로 만족시킨다. 진짜 anonymous backend는 별도
|
||||
`EXTERNAL_BEARER`(16-03 전 이름 `REFERENCE_EXTERNAL_BEARER`)를 그대로 만족시킨다. 진짜 anonymous backend는 별도
|
||||
anonymous contract/profile을 composition에서 선택해야 한다.
|
||||
|
||||
credential collaborator는 `AuthOperationContext { signal, deadlineAtMonotonicMs }`를
|
||||
|
||||
@@ -46,7 +46,6 @@ const BUILD_INPUTS = [
|
||||
] as const;
|
||||
// Platform-owned names that only happen to contain "reference".
|
||||
const PLATFORM_TOKENS = [
|
||||
"REFERENCE_EXTERNAL_BEARER",
|
||||
"REFERENCE_FEATURE_V1",
|
||||
"supportReference",
|
||||
] as const;
|
||||
|
||||
@@ -101,7 +101,7 @@ export type DemoSessionAdapter = AuthSessionPort &
|
||||
|
||||
/**
|
||||
* §7.7. `AUTH_MODE=demo` still runs against the strict
|
||||
* `REFERENCE_EXTERNAL_BEARER` profile, so the demo owner must supply a real
|
||||
* `EXTERNAL_BEARER` profile, so the demo owner must supply a real
|
||||
* proof header. This marker is a fixed, non-secret placeholder: it exists so
|
||||
* the demo path satisfies the bearer contract instead of weakening it.
|
||||
*/
|
||||
|
||||
@@ -57,14 +57,23 @@ export type RestCsrfProfile = Readonly<{
|
||||
headerName: "x-csrf-token" | null;
|
||||
}>;
|
||||
|
||||
const EXTERNAL_BEARER = Object.freeze({
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
transport: "BEARER_HEADER",
|
||||
credentials: "omit",
|
||||
allowedCredentialHeaders: Object.freeze(["authorization"] as const),
|
||||
requiredCredentialHeaders: Object.freeze(["authorization"] as const),
|
||||
});
|
||||
|
||||
export const REST_AUTH_PROFILES = Object.freeze({
|
||||
REFERENCE_EXTERNAL_BEARER: Object.freeze({
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
transport: "BEARER_HEADER",
|
||||
credentials: "omit",
|
||||
allowedCredentialHeaders: Object.freeze(["authorization"] as const),
|
||||
requiredCredentialHeaders: Object.freeze(["authorization"] as const),
|
||||
}),
|
||||
EXTERNAL_BEARER,
|
||||
/**
|
||||
* @deprecated 16-03: use `EXTERNAL_BEARER`. Same transport and headers under
|
||||
* the sample's old name, kept for one release so a downstream operation that
|
||||
* still names it resolves. Remove it in the next minor release with a
|
||||
* CHANGELOG [계약] entry (owner: frontend-platform).
|
||||
*/
|
||||
REFERENCE_EXTERNAL_BEARER: Object.freeze({ ...EXTERNAL_BEARER, authProfileId: "REFERENCE_EXTERNAL_BEARER" }),
|
||||
ANONYMOUS: Object.freeze({
|
||||
authProfileId: "ANONYMOUS",
|
||||
transport: "ANONYMOUS",
|
||||
|
||||
@@ -89,7 +89,7 @@ export const REFERENCE_API_CONTRACT = Object.freeze({
|
||||
responseMediaTypes: ["application/json"],
|
||||
maxResponseBytes: 262_144,
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
pathSchema: "NoRequest",
|
||||
pathParameterNames: [],
|
||||
@@ -117,7 +117,7 @@ export const REFERENCE_API_CONTRACT = Object.freeze({
|
||||
responseMediaTypes: ["application/json"],
|
||||
maxResponseBytes: 32_768,
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
pathSchema: "NoRequest",
|
||||
pathParameterNames: [],
|
||||
@@ -145,7 +145,7 @@ export const REFERENCE_API_CONTRACT = Object.freeze({
|
||||
responseMediaTypes: ["application/json"],
|
||||
maxResponseBytes: 32_768,
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
pathSchema: "ReferenceResourceParams",
|
||||
pathParameterNames: ["resourceId"],
|
||||
|
||||
@@ -108,7 +108,7 @@ export const LIST_REFERENCE_RESOURCES_CONTRACT = Object.freeze({
|
||||
responseByteLimit: 262_144,
|
||||
totalDeadlineMs: 10_000,
|
||||
retryBudget: 2 as const,
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
diagnosticsOperation: "reference.list",
|
||||
traffic: Object.freeze({
|
||||
maxPhysicalRequests: 3,
|
||||
@@ -158,7 +158,7 @@ export const GET_REFERENCE_RESOURCE_CONTRACT = Object.freeze({
|
||||
responseByteLimit: 32_768,
|
||||
totalDeadlineMs: 10_000,
|
||||
retryBudget: 2 as const,
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
diagnosticsOperation: "reference.detail",
|
||||
traffic: Object.freeze({
|
||||
maxPhysicalRequests: 3,
|
||||
@@ -216,7 +216,7 @@ export const CREATE_REFERENCE_RESOURCE_CONTRACT = Object.freeze({
|
||||
* than relying on a runtime special case.
|
||||
*/
|
||||
retryBudget: 0 as const,
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
diagnosticsOperation: "reference.create",
|
||||
traffic: Object.freeze({
|
||||
maxPhysicalRequests: 1,
|
||||
|
||||
@@ -135,7 +135,7 @@ describe("reference feature boundary contracts", () => {
|
||||
pathSchema: "ReferenceResourceParams",
|
||||
pathParameterNames: ["resourceId"],
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
});
|
||||
});
|
||||
|
||||
@@ -279,7 +279,7 @@ describe("V3 installed auth profile authority", () => {
|
||||
});
|
||||
|
||||
it("keeps the shipped bearer profile strict", () => {
|
||||
expect(REST_AUTH_PROFILES.REFERENCE_EXTERNAL_BEARER).toMatchObject({
|
||||
expect(REST_AUTH_PROFILES.EXTERNAL_BEARER).toMatchObject({
|
||||
transport: "BEARER_HEADER",
|
||||
credentials: "omit",
|
||||
requiredCredentialHeaders: ["authorization"],
|
||||
|
||||
@@ -231,7 +231,7 @@ async function executeScenario(
|
||||
const executor = createContractHttpExecutor({
|
||||
baseUrl: "https://api.test",
|
||||
maxRetryAttempts: 2,
|
||||
// The reference contribution declares REFERENCE_EXTERNAL_BEARER, so the
|
||||
// The reference contribution declares EXTERNAL_BEARER, so the
|
||||
// credential owner must supply the required proof header before dispatch.
|
||||
attachCredentials: () => ({
|
||||
kind: "READY",
|
||||
|
||||
@@ -35,7 +35,7 @@ const BEARER_LIST = defineRestOperation({
|
||||
responseMediaTypes: ["application/json"],
|
||||
maxResponseBytes: 32_768,
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
pathSchema: "NoRequest",
|
||||
pathParameterNames: [],
|
||||
|
||||
@@ -29,7 +29,7 @@ function operation(operationId = "GET_RESOURCE") {
|
||||
responseMediaTypes: ["application/json"],
|
||||
maxResponseBytes: 32_768,
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
pathSchema: "ResourceParams",
|
||||
pathParameterNames: ["resourceId"],
|
||||
|
||||
@@ -36,7 +36,7 @@ export function unaryProfile(
|
||||
descriptorArtifactId: "buf.example.resource.v1",
|
||||
descriptorDigest: DESCRIPTOR_DIGEST,
|
||||
allowedProcedures: ["example.resource.v1.ResourceService/GetResource"],
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
corsProfileId: "SAME_ORIGIN_RPC",
|
||||
errorProfileId: "CONNECT_ERROR_V1",
|
||||
@@ -81,7 +81,7 @@ export function unaryOperation(
|
||||
responseSchemaId: "RpcResourceResponse",
|
||||
requestEncoderId: "RpcResourceRequestEncoder",
|
||||
mapperId: "RpcResourceMapper",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
errorProfileId: "CONNECT_ERROR_V1",
|
||||
deadlineProfileId: "RPC_TOTAL_5S",
|
||||
|
||||
@@ -70,7 +70,7 @@ describe("LIVE-02 installed REST auth profile registry", () => {
|
||||
|
||||
expect(registry.size).toBe(before);
|
||||
expect(registry.get("ANONYMOUS")).toBe(identity);
|
||||
expect(registry.get("REFERENCE_EXTERNAL_BEARER")?.credentials).toBe("omit");
|
||||
expect(registry.get("EXTERNAL_BEARER")?.credentials).toBe("omit");
|
||||
});
|
||||
|
||||
it("does not observe a post-installation mutation of the source record", () => {
|
||||
@@ -94,6 +94,7 @@ describe("LIVE-02 installed REST auth profile registry", () => {
|
||||
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);
|
||||
|
||||
@@ -246,8 +246,8 @@ describe("REST auth profile registry", () => {
|
||||
let installed: ReturnType<typeof installRestAuthProfileRegistry> | undefined;
|
||||
try {
|
||||
installed = installRestAuthProfileRegistry({
|
||||
REFERENCE_EXTERNAL_BEARER: {
|
||||
...REST_AUTH_PROFILES.REFERENCE_EXTERNAL_BEARER,
|
||||
EXTERNAL_BEARER: {
|
||||
...REST_AUTH_PROFILES.EXTERNAL_BEARER,
|
||||
allowedCredentialHeaders: allowed as never,
|
||||
},
|
||||
});
|
||||
@@ -255,7 +255,7 @@ describe("REST auth profile registry", () => {
|
||||
return;
|
||||
}
|
||||
expect(
|
||||
installed.get("REFERENCE_EXTERNAL_BEARER")?.allowedCredentialHeaders,
|
||||
installed.get("EXTERNAL_BEARER")?.allowedCredentialHeaders,
|
||||
).toEqual(["authorization"]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -78,7 +78,7 @@ describe("feature-shape growth measurement (11-04)", () => {
|
||||
|
||||
it("keeps platform-owned names that only contain the word", () => {
|
||||
const source =
|
||||
"REFERENCE_EXTERNAL_BEARER REFERENCE_FEATURE_V1 supportReference";
|
||||
"REFERENCE_FEATURE_V1 supportReference";
|
||||
|
||||
expect(renameReferenceFeature(source, "s001", context)).toBe(source);
|
||||
});
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
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";
|
||||
@@ -42,7 +45,7 @@ const SAMPLE_COMMAND = defineRestOperation({
|
||||
responseMediaTypes: ["application/json"],
|
||||
maxResponseBytes: 32_768,
|
||||
providerId: "PRIMARY_API",
|
||||
authProfileId: "REFERENCE_EXTERNAL_BEARER",
|
||||
authProfileId: "EXTERNAL_BEARER",
|
||||
csrfProfileId: "NO_CSRF_BEARER",
|
||||
pathSchema: "NoRequest",
|
||||
pathParameterNames: [],
|
||||
@@ -125,7 +128,7 @@ describe("REST provider/auth/CSRF profiles", () => {
|
||||
expect(() =>
|
||||
validateRestProfileBindings(publicWithBearer, { PRIMARY_API: ["omit"] }),
|
||||
).toThrow(
|
||||
/CREATE_SAMPLE_RESOURCE.*auth "none" needs an ANONYMOUS profile.*REFERENCE_EXTERNAL_BEARER is BEARER_HEADER/,
|
||||
/CREATE_SAMPLE_RESOURCE.*auth "none" needs an ANONYMOUS profile.*EXTERNAL_BEARER is BEARER_HEADER/,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -143,8 +146,8 @@ describe("one installed REST auth profile registry", () => {
|
||||
|
||||
it("rejects a raw profile record that installation would refuse", () => {
|
||||
const incoherent = {
|
||||
REFERENCE_EXTERNAL_BEARER: {
|
||||
...REST_AUTH_PROFILES.REFERENCE_EXTERNAL_BEARER,
|
||||
EXTERNAL_BEARER: {
|
||||
...REST_AUTH_PROFILES.EXTERNAL_BEARER,
|
||||
credentials: "same-origin" as const,
|
||||
},
|
||||
};
|
||||
@@ -160,7 +163,7 @@ describe("one installed REST auth profile registry", () => {
|
||||
provider,
|
||||
INSTALLED_REST_AUTH_PROFILES,
|
||||
).auth,
|
||||
).toBe(INSTALLED_REST_AUTH_PROFILES.get("REFERENCE_EXTERNAL_BEARER"));
|
||||
).toBe(INSTALLED_REST_AUTH_PROFILES.get("EXTERNAL_BEARER"));
|
||||
});
|
||||
|
||||
it("does not resolve an inherited profile id", () => {
|
||||
@@ -177,7 +180,7 @@ describe("one installed REST auth profile registry", () => {
|
||||
const registry = installRestAuthProfileRegistry({
|
||||
...REST_AUTH_PROFILES,
|
||||
CUSTOM_BEARER: {
|
||||
...REST_AUTH_PROFILES.REFERENCE_EXTERNAL_BEARER,
|
||||
...REST_AUTH_PROFILES.EXTERNAL_BEARER,
|
||||
authProfileId: "CUSTOM_BEARER",
|
||||
},
|
||||
});
|
||||
@@ -197,3 +200,38 @@ describe("one installed REST auth profile registry", () => {
|
||||
).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" }),',
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -52,7 +52,7 @@ vi.mock("../../src/features/installed-contract-contributions.ts", async (importO
|
||||
...TEST_CONTRACT_CONTRIBUTION,
|
||||
http: [
|
||||
list,
|
||||
fixture.withProfile(list, "TEST_LIST_ENTITIES_BEARER", "REFERENCE_EXTERNAL_BEARER"),
|
||||
fixture.withProfile(list, "TEST_LIST_ENTITIES_BEARER", "EXTERNAL_BEARER"),
|
||||
] as typeof TEST_CONTRACT_CONTRIBUTION.http,
|
||||
},
|
||||
]);
|
||||
@@ -132,7 +132,7 @@ const ANONYMOUS_OPERATION = TEST_LIST_HTTP_CONTRACT;
|
||||
const BEARER_OPERATION = fixture.withProfile(
|
||||
TEST_LIST_HTTP_CONTRACT,
|
||||
"TEST_LIST_ENTITIES_BEARER",
|
||||
"REFERENCE_EXTERNAL_BEARER",
|
||||
"EXTERNAL_BEARER",
|
||||
);
|
||||
|
||||
function externalOwner(
|
||||
|
||||
Reference in New Issue
Block a user