fix(contracts): REST 보안 프로필 오류가 operation·프로필·깨진 조건을 말한다 (16-03)

문제: `resolveRestSecurityProfiles`는 프로필이 없거나 조합이 틀리면 일곱
조건을 한 번에 보고 "REST security profiles are incoherent."만 던진다.
참조 기능을 복사해 `REFERENCE_EXTERNAL_BEARER`를 바꾸면 이 한 문장으로
레지스트리를 읽는 게이트가 모두 멈추고, 개발자는 스택에서
rest-profiles.ts를 열어 조건을 하나씩 대조해야 한다.

고른 방법: 조건마다 깨졌을 때의 문장을 만들어 모은 뒤, operation id와
함께 한 오류로 던진다. 예: "REST security profiles are incoherent for
CREATE_SAMPLE_RESOURCE: unknown authProfileId ORDER_EXTERNAL_BEARER."
operation 인자 타입에 선택 필드 `operationId`를 더했다(추가만). 호출부
두 곳(`validateRestProfileBindings`, V2 client)은 이미 operation 전체를
넘기므로 고칠 곳이 없다. 기존 문장 앞부분은 그대로라 "incoherent"를 찾는
테스트·로그 검색은 계속 맞는다.

버린 대안: 첫 번째로 깨진 조건에서 바로 throw하기. 조건이 둘 이상
깨진 경우(예: 이름도 틀리고 CSRF도 틀림) 고칠 때마다 다음 오류를 다시
봐야 한다.

위험·한계:
- 리뷰 16-03의 (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 옛 이름을
  별칭으로 두는 부분은 하지 않았다. FE-REG-API 행이 바뀌어 레지스트리
  기준선을 다시 써야 하고, `update-registry-baseline.ts`는 소유자와
  사유(REGISTRY_BASELINE_OWNER/REASON)를 승인 파일에 남긴다. 그 승인은
  사용자 몫이다. 제거 드릴 잔여 정규식이 이 이름을 못 잡는 문제도 그
  작업에 남는다.
- 초기 JS +189 B gzip(202,806 → 202,995 B, 여유 1,805 B). rest-profiles가
  초기 청크에 있어 오류 문장이 그대로 실린다.

검증:
- RED: tests/unit/rest-profile-contract.test.ts의 새 테스트가
  "expected [Function] to throw error matching /incoherent.*
  CREATE_SAMPLE_RESOURCE.*u…/ but got 'REST security profiles are
  incoherent.'"로 실패.
- GREEN: 같은 파일 8건 통과(미등록 프로필, auth "none"+bearer 두 경우).
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,930건, tests/integration
  (프로세스를 띄우는 3개 제외) 131건, tests/{contract,features,
  runtime-schema,component,architecture,platform} 626건 통과. tsc app·test
  통과. 바꾼 파일 eslint 통과.
This commit is contained in:
DongHyeonka
2026-11-01 22:56:29 +09:00
parent de48db25d9
commit abf3ce521d
2 changed files with 59 additions and 16 deletions
+34 -16
View File
@@ -273,6 +273,7 @@ export function createRestProviderProfile(
export function resolveRestSecurityProfiles(
operation: Readonly<{
operationId?: string;
method: string;
auth: "none" | "external-session";
authProfileId?: string;
@@ -282,27 +283,44 @@ export function resolveRestSecurityProfiles(
authProfiles: RestAuthProfileSource = INSTALLED_REST_AUTH_PROFILES,
csrfProfiles: Readonly<Record<string, RestCsrfProfile>> = REST_CSRF_PROFILES,
): Readonly<{ auth: RestAuthProfile; csrf: RestCsrfProfile }> {
const auth = installedAuthProfiles(authProfiles).get(
operation.authProfileId ?? "",
);
const authProfileId = operation.authProfileId ?? "";
const auth = installedAuthProfiles(authProfiles).get(authProfileId);
const csrfProfileId = operation.csrfProfileId ?? "";
const csrf = Object.hasOwn(csrfProfiles, csrfProfileId)
? csrfProfiles[csrfProfileId]
: undefined;
const unsafe = !["GET", "HEAD", "OPTIONS"].includes(operation.method);
if (
!auth ||
!csrf ||
!provider.allowedCredentialsModes.includes(auth.credentials) ||
(operation.auth === "none" && auth.transport !== "ANONYMOUS") ||
(operation.auth === "external-session" &&
auth.transport === "ANONYMOUS") ||
(auth.transport === "BEARER_HEADER" && csrf.mode !== "NONE") ||
(unsafe &&
auth.transport === "SAME_ORIGIN_COOKIE" &&
csrf.mode !== "HEADER")
) {
throw new TypeError("REST security profiles are incoherent.");
// 16-03. Every broken condition is named, with the operation and profile
// ids, so a renamed or missing profile does not have to be found by
// comparing each rule by hand.
const broken = [
!auth && `unknown authProfileId ${authProfileId || "(none)"}`,
!csrf && `unknown csrfProfileId ${csrfProfileId || "(none)"}`,
auth &&
!provider.allowedCredentialsModes.includes(auth.credentials) &&
`provider ${provider.providerId} does not allow credentials "${auth.credentials}" of ${authProfileId}`,
auth &&
operation.auth === "none" &&
auth.transport !== "ANONYMOUS" &&
`auth "none" needs an ANONYMOUS profile, ${authProfileId} is ${auth.transport}`,
auth &&
operation.auth === "external-session" &&
auth.transport === "ANONYMOUS" &&
`auth "external-session" cannot use the ANONYMOUS profile ${authProfileId}`,
auth?.transport === "BEARER_HEADER" &&
csrf &&
csrf.mode !== "NONE" &&
`bearer profile ${authProfileId} cannot use CSRF mode ${csrf.mode} of ${csrfProfileId}`,
unsafe &&
auth?.transport === "SAME_ORIGIN_COOKIE" &&
csrf &&
csrf.mode !== "HEADER" &&
`${operation.method} with cookie profile ${authProfileId} needs a HEADER CSRF profile, ${csrfProfileId} is ${csrf.mode}`,
].filter((condition): condition is string => typeof condition === "string");
if (!auth || !csrf || broken.length > 0) {
throw new TypeError(
`REST security profiles are incoherent for ${operation.operationId ?? "an operation"}: ${broken.join("; ")}.`,
);
}
return Object.freeze({ auth, csrf });
}
+25
View File
@@ -103,6 +103,31 @@ describe("REST provider/auth/CSRF profiles", () => {
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.*REFERENCE_EXTERNAL_BEARER is BEARER_HEADER/,
);
});
});
/**