From a0176e9ff270bbe64f2192b760733966ac54cbd7 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 12:10:56 +0900 Subject: [PATCH] fix(cache-storage): accept browser-managed Vary and require content-type in policy (R-2.5) The default policy has allowedVaryHeaderNames: [], so any Vary header was POLICY_REJECTED. nginx `gzip_vary` and most CDNs send `Vary: Accept-Encoding` on JS and CSS, so the default policy could not stage real assets. Accept-Encoding is a forbidden request header, so a policy could not allowlist it as a request header either. validateVary now skips `accept-encoding`. No script-built Request carries that header, so the stored and lookup requests both lack it and Cache.match still matches exactly. Every other Vary name keeps the existing checks. A policy whose allowedResponseHeaderNames lacked `content-type` passed assertPublicCachePolicy, but activation re-validates the stored Content-Type, so every activation failed as INTEGRITY_FAILED. The policy check now rejects it. The ops runbook lists both rules. Verified: "stages, activates and looks up a Vary: Accept-Encoding response with the default policy" (stage returned ok:false) and "rejects a policy that strips Content-Type from stored responses" (no throw) failed before the fix and pass now. check:architecture, check:types:app, check:types:test, lint, test:component, verify:documentation pass. test:unit passes except removal-fixture, which needs generated artifacts/release files that a fresh worktree lacks. Co-Authored-By: Claude Opus 5.5 --- .../client-cache-and-storage-recovery.md | 6 ++ .../cache-storage/public-cache-policy.ts | 3 + .../public-response-cache-adapter.ts | 5 ++ tests/unit/public-response-cache.test.ts | 63 +++++++++++++++++++ 4 files changed, 77 insertions(+) diff --git a/docs/operations/client-cache-and-storage-recovery.md b/docs/operations/client-cache-and-storage-recovery.md index a600287a..4f606e2a 100644 --- a/docs/operations/client-cache-and-storage-recovery.md +++ b/docs/operations/client-cache-and-storage-recovery.md @@ -31,6 +31,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle `allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이 `TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지 않기 위한 cross-field invariant다. +- `allowedResponseHeaderNames`에 `content-type`이 없는 policy도 composition에서 + `TypeError`로 실패한다. activation이 저장된 `content-type`을 다시 검증하기 + 때문이다. +- `Vary: Accept-Encoding`은 policy 없이 항상 허용한다. `Accept-Encoding`은 + script가 만든 Request에 들어가지 않는 금지 헤더라 저장과 조회 요청 모두 이 + 값이 없다. nginx `gzip_vary`와 대부분의 CDN이 이 헤더를 붙인다. ## 1. 변경할 수 없는 복구 원칙 diff --git a/src/adapters/cache-storage/public-cache-policy.ts b/src/adapters/cache-storage/public-cache-policy.ts index 0c069e62..87bc7fdd 100644 --- a/src/adapters/cache-storage/public-cache-policy.ts +++ b/src/adapters/cache-storage/public-cache-policy.ts @@ -137,6 +137,9 @@ export function assertPublicCachePolicy( // rejected at composition instead of producing an unusable candidate. (policy.allowedVaryHeaderNames.length > 0 && !policy.allowedResponseHeaderNames.includes("vary")) || + // Activation re-validates the stored Content-Type, so stripping it would + // make every activation fail as INTEGRITY_FAILED. + !policy.allowedResponseHeaderNames.includes("content-type") || policy.forbiddenQueryParameterNames.some((name) => name.length === 0) || policy.allowedQueryParameterNames.some((name) => policy.forbiddenQueryParameterNames.includes(name), diff --git a/src/adapters/cache-storage/public-response-cache-adapter.ts b/src/adapters/cache-storage/public-response-cache-adapter.ts index a11a8106..91bf06e8 100644 --- a/src/adapters/cache-storage/public-response-cache-adapter.ts +++ b/src/adapters/cache-storage/public-response-cache-adapter.ts @@ -1314,6 +1314,11 @@ function validateVary( const allowed = new Set(policy.allowedVaryHeaderNames); for (const item of vary.split(",")) { const name = item.trim().toLowerCase(); + // Browser-managed: Accept-Encoding is a forbidden request header, so no + // script-built Request carries it. Stored and lookup requests both lack it + // and Cache.match still matches exactly. nginx `gzip_vary` and most CDNs + // send it on every compressible asset. + if (name === "accept-encoding") continue; if ( name === "*" || name === "authorization" || diff --git a/tests/unit/public-response-cache.test.ts b/tests/unit/public-response-cache.test.ts index d6e94562..4ffb06b0 100644 --- a/tests/unit/public-response-cache.test.ts +++ b/tests/unit/public-response-cache.test.ts @@ -5,6 +5,7 @@ import type { PublicCacheReleaseManifest, } from "../../src/application/ports/browser-file-storage/cache-storage-ports.ts"; import { + assertPublicCachePolicy, createDefaultPublicCachePolicy, resolvePublicCachePolicy, type PublicCacheRuntimePolicy, @@ -49,6 +50,68 @@ describe("public response Cache Storage adapter", () => { ).not.toThrow(); }); + it("rejects a policy that strips Content-Type from stored responses", () => { + const base = createDefaultPublicCachePolicy( + "https://assets.example.test", + ); + // Activation re-validates the stored Content-Type, so without it every + // activation would fail as INTEGRITY_FAILED. + expect(() => + assertPublicCachePolicy({ + ...base, + allowedResponseHeaderNames: base.allowedResponseHeaderNames.filter( + (name) => name !== "content-type", + ), + }), + ).toThrow(TypeError); + }); + + it("stages, activates and looks up a Vary: Accept-Encoding response with the default policy", async () => { + const policy = createDefaultPublicCachePolicy( + "https://assets.example.test", + ); + const bytes = new Uint8Array([7, 7, 7, 7]); + const asset: PublicCacheAsset = { + absoluteUrl: "https://assets.example.test/gzip-vary.js", + expectedByteLength: bytes.byteLength, + expectedContentType: "application/javascript", + integrity: { + algorithm: "SHA-256", + digestHex: await digestHex(bytes), + }, + }; + const adapter = createPublicResponseCacheAdapter({ + cacheStorage: new MemoryCacheStorage() as unknown as CacheStorage, + crypto: globalThis.crypto, + mutationLock: immediateLock, + policy, + // nginx `gzip_vary on` and most CDNs add this header to JS and CSS. + fetcher: async () => + new Response(bytes, { + headers: { + "cache-control": "public, max-age=31536000, immutable", + "content-type": "application/javascript", + vary: "Accept-Encoding", + }, + }), + }); + const manifest = await manifestFor("gzip-vary-release", [asset], policy); + + expect(await adapter.admin.stageRelease(manifest)).toMatchObject({ + ok: true, + }); + expect( + await adapter.admin.activateRelease( + manifest.releaseRegistryId, + manifest.manifestDigestHex, + ), + ).toMatchObject({ ok: true }); + const match = await adapter.responses.matchActiveExact({ + absoluteUrl: asset.absoluteUrl, + }); + expect(match.ok && match.value !== null).toBe(true); + }); + it("restages an evicted entry even when the release marker remains", async () => { const policy = createDefaultPublicCachePolicy( "https://assets.example.test",