From 183a4a373dc9dbe69a32b5cf35c03a05a075fbbd Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 01:55:44 +0900 Subject: [PATCH] =?UTF-8?q?feat(contracts):=20=EC=A7=9D=20=EB=B0=B1?= =?UTF-8?q?=EC=97=94=EB=93=9C=20CSRF=20=ED=97=A4=EB=8D=94=20x-xsrf-token?= =?UTF-8?q?=EC=9D=84=20=EC=9E=90=EA=B2=A9=EC=A6=9D=EB=AA=85=20=ED=97=A4?= =?UTF-8?q?=EB=8D=94=EC=97=90=20=EB=8D=94=ED=95=9C=EB=8B=A4=20(1101/09-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 짝 백엔드는 쿠키 세션의 CSRF를 Spring CookieCsrfTokenRepository로 검사하고, 기본 헤더 이름은 X-XSRF-TOKEN이다(백엔드 SecurityConfig.java, docs/registries/env-keys.yaml APP_SESSION_CSRF_HEADER_NAME). 프론트의 닫힌 자격증명 헤더 목록(VD-23, rest-profiles.ts CREDENTIAL_HEADER_NAMES)에는 x-csrf-token만 있다. 제품 인증 프로필이 x-xsrf-token을 allowed·required에 적으면 프로필 레지스트리 설치가 모듈 로드 때 throw한다. 그래서 memento가 템플릿 파일을 고쳤고, 09-02(da1e128)의 제품 제공자 테스트 fixture는 x-csrf-token으로 우회해 적었다. 고른 방법 - 목록이 닫힌 이유(VD-23 5-1): 자격증명 제공자가 transport 소유 헤더 (accept, content-type, idempotency-key)나 금지 헤더를 넣지 못하게 하고, 프로필이 정확한 allowed·required 집합을 갖게 하려는 것이다. x-xsrf-token은 그 어느 쪽도 아닌 proof 헤더라 목록에 더해도 이 이유를 깨지 않는다. - 목록에 x-xsrf-token 하나를 더한다. 실제로 보낼 수 있는지는 여전히 프로필의 allowed 집합이 정한다. 템플릿 기본 프로필(EXTERNAL_BEARER, ANONYMOUS)은 바뀌지 않는다. - 09-02 fixture의 memento BFF 쓰기 프로필과 제공자를 x-xsrf-token으로 바꿔 우회를 없앤다. 이 fixture가 RED 테스트다. 버린 대안 - 헤더 이름을 프로필이 자유롭게 정하게 열기: 닫힌 목록이 막는 shadowing· 금지 헤더 위험이 돌아온다. - 백엔드가 X-CSRF-TOKEN을 받게 설정: 백엔드 기본값을 바꾸는 일이고 이 repo 범위 밖이다. 백엔드 repo는 고치지 않는다. 위험·한계 - RestCsrfProfile.headerName 타입("x-csrf-token" | null)은 그대로다. CSRF 프로필은 템플릿 상수(REST_CSRF_PROFILES)뿐이고 제품이 더할 확장 지점이 없다. 제품 쿠키 프로필은 인증 프로필의 헤더 집합으로 표현한다. - V2 legacy 허용 목록(client.ts LEGACY_ALLOWED_CREDENTIAL_HEADERS)은 "기존 동작 그대로"가 목적이라 바꾸지 않았다. - 외부 세션 어댑터(external-session-adapter.ts)도 같은 목록을 읽으므로 이제 x-xsrf-token을 받는다. 보낼지는 V3 프로필 검사가 정한다. 검증 - RED: tests/unit/product-composition-fixture.test.ts를 x-xsrf-token으로 바꾸자 파일 전체 실패("REST auth profile allowedCredentialHeaders is not an exact set", 모듈 로드). - GREEN: 같은 파일과 tests/unit/runtime-adapters-auth-profile·runtime- adapters-credential-order·contract-snapshot-bypass, tests/integration/ legacy-http-credential-authority 5 files 44 tests 통과. tsc app·test 통과, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15 --- src/contracts/rest-profiles.ts | 5 +++++ tests/unit/product-composition-fixture.test.ts | 11 ++++++----- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/src/contracts/rest-profiles.ts b/src/contracts/rest-profiles.ts index 1bbdfd8c..ea7e9af1 100644 --- a/src/contracts/rest-profiles.ts +++ b/src/contracts/rest-profiles.ts @@ -20,10 +20,15 @@ export type RestProviderProfile = Readonly<{ * VD-23. The complete closed set of headers a credential owner may contribute. * Transport-owned headers (`accept`, `content-type`, `idempotency-key`) and * every forbidden request header are deliberately absent. + * + * `x-xsrf-token` is the paired backend's default CSRF header (Spring + * `CookieCsrfTokenRepository`, `APP_SESSION_CSRF_HEADER_NAME`). A profile + * still has to name it in its own allowed set before a provider may send it. */ export const CREDENTIAL_HEADER_NAMES = Object.freeze([ "authorization", "x-csrf-token", + "x-xsrf-token", "x-tenant-context", ] as const); diff --git a/tests/unit/product-composition-fixture.test.ts b/tests/unit/product-composition-fixture.test.ts index fac1d988..0088f31f 100644 --- a/tests/unit/product-composition-fixture.test.ts +++ b/tests/unit/product-composition-fixture.test.ts @@ -65,7 +65,7 @@ vi.mock("../../src/contracts/product-contracts.ts", async () => { const { z } = await import("../../src/contracts/zod.ts"); const cookieProfile = ( authProfileId: string, - header: readonly "x-csrf-token"[], + header: readonly ("x-csrf-token" | "x-xsrf-token")[], ) => Object.freeze({ authProfileId, @@ -80,7 +80,8 @@ vi.mock("../../src/contracts/product-contracts.ts", async () => { }), PRODUCT_REST_AUTH_PROFILES: Object.freeze({ MEMENTO_BFF_READ: cookieProfile("MEMENTO_BFF_READ", []), - MEMENTO_BFF_WRITE: cookieProfile("MEMENTO_BFF_WRITE", ["x-csrf-token"]), + // The paired backend's default CSRF header (Spring CookieCsrfTokenRepository). + MEMENTO_BFF_WRITE: cookieProfile("MEMENTO_BFF_WRITE", ["x-xsrf-token"]), TECH_LOG_STUDIO_BOOTSTRAP: cookieProfile("TECH_LOG_STUDIO_BOOTSTRAP", []), TECH_LOG_STUDIO_SESSION: cookieProfile("TECH_LOG_STUDIO_SESSION", ["x-csrf-token"]), }), @@ -175,7 +176,7 @@ vi.mock("../../src/bootstrap/product-composition.ts", async () => { const token = context.readCookie("XSRF-TOKEN"); return token === undefined ? { kind: "UNAVAILABLE" as const } - : { kind: "READY" as const, headers: { "x-csrf-token": token } }; + : { kind: "READY" as const, headers: { "x-xsrf-token": token } }; }, // tech-log Studio: the token's own issuing call carries none. TECH_LOG_STUDIO_BOOTSTRAP: () => ({ kind: "READY" as const, headers: {} }), @@ -357,7 +358,7 @@ describe("09-02 product needs through the product-owned files only", () => { expect(outcome.kind).toBe("SUCCESS"); expect(sent(fetcher, 0).credentials).toBe("include"); - expect([...sent(fetcher, 0).headers.keys()]).not.toContain("x-csrf-token"); + expect([...sent(fetcher, 0).headers.keys()]).not.toContain("x-xsrf-token"); }); it("memento: BFF writes carry the XSRF cookie and fail closed without it", async () => { @@ -365,7 +366,7 @@ describe("09-02 product needs through the product-owned files only", () => { await expect( withCookie.http.execute(list(OPERATIONS.bffWrite), { limit: 1 }, { routeId: "R" }), ).resolves.toMatchObject({ kind: "SUCCESS" }); - expect(sent(withCookie.fetcher, 0).headers.get("x-csrf-token")).toBe("xsrf-1"); + expect(sent(withCookie.fetcher, 0).headers.get("x-xsrf-token")).toBe("xsrf-1"); current?.infrastructure.dispose(); const without = await compose();