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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 12:15:58 +09:00
co-authored by Claude Opus 5.5
parent de954d2ebf
commit a0176e9ff2
4 changed files with 77 additions and 0 deletions
@@ -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. 변경할 수 없는 복구 원칙
@@ -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),
@@ -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" ||
+63
View File
@@ -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",