diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index c22a5b87..4cf83d62 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -72,6 +72,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | 메시지 | 원인 | 고칠 곳 | |---|---|---| | `/: unknown authProfileId ` (계약 조립 오류의 `reason`) | 없는 인증 프로필 | `contracts/-contract-contribution.ts`의 `frontend.authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` | +| `/: with cookie profile must require x-csrf-token or x-xsrf-token` (계약 조립 오류의 `reason`) | 쿠키 인증 프로필로 쓰기 요청을 보내는데 프로필이 CSRF 헤더를 요구하지 않는다 | `src/contracts/product-contracts.ts`의 그 프로필 `requiredCredentialHeaders`. 짝 백엔드는 `x-xsrf-token` | | `Product REST auth profile reuses a template profile id.` | 제품 프로필 ID가 템플릿 것과 같다 | `src/contracts/product-contracts.ts` | ### 계약·스키마·mapper diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 5976fbbe..4ac7ffec 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -540,6 +540,20 @@ function assertHttpContract( } } assertExecutionPolicy(installed.frontend, label, authProfiles); + // A browser attaches an ambient cookie to any site's request, so a + // cookie-authenticated write needs a header only the page can set. + const profile = authProfiles.get(installed.frontend.authProfileId); + if ( + !isRead && + profile?.transport === "SAME_ORIGIN_COOKIE" && + !profile.requiredCredentialHeaders.some( + (header) => header === "x-csrf-token" || header === "x-xsrf-token", + ) + ) { + fail( + `${label}: ${contract.method} with cookie profile ${profile.authProfileId} must require x-csrf-token or x-xsrf-token`, + ); + } if ( installed.frontend.retryBudget > 0 && contract.retrySemantics === "NEVER" diff --git a/tests/unit/rest-profile-contract.test.ts b/tests/unit/rest-profile-contract.test.ts index 09be86f6..8451c7a3 100644 --- a/tests/unit/rest-profile-contract.test.ts +++ b/tests/unit/rest-profile-contract.test.ts @@ -56,6 +56,57 @@ describe("one installed REST auth profile registry", () => { }); }); +/** + * A cookie-authenticated write must carry a CSRF proof header: the browser + * attaches the cookie to any site's request, so the header is what tells the + * server the page itself sent it. The V2 client refused such a binding; the + * installed HTTP contract has to refuse it too. + */ +describe("cookie profiles on writes", () => { + const cookie = (authProfileId: string, csrf: readonly ("x-csrf-token" | "x-xsrf-token")[]) => ({ + authProfileId, + transport: "SAME_ORIGIN_COOKIE" as const, + credentials: "include" as const, + allowedCredentialHeaders: [...csrf], + requiredCredentialHeaders: [...csrf], + }); + const registry = installRestAuthProfileRegistry({ + ...REST_AUTH_PROFILES, + COOKIE_READ: cookie("COOKIE_READ", []), + COOKIE_WRITE: cookie("COOKIE_WRITE", ["x-xsrf-token"]), + }); + const withProfile = (index: number, authProfileId: string) => { + const row = TEST_CONTRACT_CONTRIBUTION.http[index]!; + return { + ...TEST_CONTRACT_CONTRIBUTION, + http: [{ ...row, frontend: { ...row.frontend, authProfileId } }], + }; + }; + // TEST_CONTRACT_CONTRIBUTION.http: [list (GET), detail (GET), create (POST)] + + it("refuses a write whose cookie profile requires no CSRF header", () => { + expect(() => + composeContractContributions([withProfile(2, "COOKIE_READ")], registry), + ).toThrow( + expect.objectContaining({ + reason: + "test-feature/TEST_CREATE_ENTITY: POST with cookie profile COOKIE_READ must require x-csrf-token or x-xsrf-token", + }), + ); + }); + + it("accepts a write that requires a CSRF header, and a cookie read without one", () => { + expect( + composeContractContributions([withProfile(2, "COOKIE_WRITE")], registry) + .httpByOperationId.size, + ).toBe(1); + expect( + composeContractContributions([withProfile(0, "COOKIE_READ")], 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