refactor(cache-storage): split the cache and download codecs out of their adapters (Q-6.2-11)

public-response-cache-adapter.ts (1986 lines) and download-delivery-adapter.ts
(1491 lines) mixed the facade with codecs and validators. Moved verbatim:
- cache-storage/public-cache-codec.ts: manifest normalization and canonical
  digest input, marker/active-pointer validation, bounded control JSON,
  owned cache names, CacheValidationFailure -> Result mapping.
- cache-storage/public-cache-response-validation.ts: response admission
  (status, directives, Content-Type, Vary, bounded body, digest).
- browser-files/download-input-validation.ts: request snapshot, input/limit
  checks, presigned and browser-managed capability validation, handoff target.
The adapters drop to 1164 and 1157 lines.

Two non-verbatim edits: validateDownloadInput takes a structural
DownloadInputValidationOptions instead of DownloadDeliveryAdapterOptions (no
import cycle), and readBodyBounded races reads on the kernel
createAbortableOperation instead of its own abort listener. Moving it out of
a primitive-importing file would otherwise have raised the hand-rolled abort
ratchet to 20/19; the abort outcome (ABORTED, reader cancelled) is unchanged.

Verified: characterization tests added first and passing before the move
(cache manifest/response/control-JSON failure codes, lookup abort during a
pending body read; download input validation codes); a line diff confirms the
moved code is verbatim apart from the two edits above. Inventory 139/139,
lane gates, check:browser-file-storage-boundaries pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:39:59 +09:00
co-authored by Claude Opus 5.5
parent d67fe1ab35
commit 4093ee8fc2
9 changed files with 1886 additions and 1332 deletions
@@ -43,6 +43,7 @@
| `src/adapters/browser-files/browser-file-vault.ts` | transient native File/handle 보관, opaque ref, inspection receipt, bounded range/source | file port/shared/result/policy registry. File이 application 경계를 넘지 않고 receipt가 exact file/profile에 묶이는 설계가 좋다. |
| `src/adapters/browser-files/create-browser-file-runtime.ts` | vault/picker/preview/download를 선택적으로 조립하고 일괄 dispose | 위 adapters 및 application contracts. optional capability를 제품 선택 없이 bootstrap에 암묵 조립하지 않는 점을 유지. preview 조립 전 GAP-01 gate 필요. |
| `src/adapters/browser-files/download-delivery-adapter.ts` | browser handoff, foreground save stream, bounded object URL download, integrity/progress/cancellation | file/authorized-download ports, policy registry, object URL lease, Result. STO-02와 STO-08; stream close truth/backpressure는 유지. |
| `src/adapters/browser-files/download-input-validation.ts` | download 요청 snapshot, policy/limit/activation 검증, presigned·browser-managed capability 검증, canonical handoff target 해석 | file/authorized-download ports, policy registry, `file-policy.ts`, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/browser-files/file-observer.ts` | file-safe observation DTO를 공통 browser observation으로 변환 | shared port/result. raw filename/ref 비노출 유지. |
| `src/adapters/browser-files/file-policy.ts` | policy input validation, MIME/extension/signature/hard byte caps, immutable resolved policy | file/shared contracts. closed allowlist 및 absolute ceiling을 유지. |
| `src/adapters/browser-files/index.ts` | browser-file public exports | 위 모듈. native implementation detail export 확장을 피한다. |
@@ -53,7 +54,9 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/cache-storage/index.ts` | public cache policy/adapter barrel | optional public static cache만 export; private/range cache로 일반화하지 않는다. |
| `src/adapters/cache-storage/public-cache-codec.ts` | manifest 정규화·canonical digest 입력, marker/active pointer 검증, bounded control JSON 읽기, owned cache 이름, 검증 실패 → Result 매핑 | cache ports/result/policy. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-cache-policy.ts` | same-origin/public-only release 정책, URL/header/query/size/retention hard limits | cache ports/shared. STO-03 policy cross-field invariant 누락. 기본 policy에는 `vary`가 있어 기본-path 테스트는 통과한다. |
| `src/adapters/cache-storage/public-cache-response-validation.ts` | network/cached response 수용 검증: status, cache directive, Content-Type, Vary, bounded body, digest | `public-cache-codec.ts`, policy, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-response-cache-adapter.ts` | manifest canonicalization/digest, anonymous fetch, bounded body 검증, candidate marker-last staging, explicit activation, exact lookup/reverify, owned cleanup/inspect | cache ports/result/policy, CacheStorage/fetch/Crypto/Web Lock snapshot. STO-03~05 및 GAP-02. private/auth/opaque/206 거절과 current+previous 보존은 유지. |
### 1.4 `storage` root / IndexedDB
+135 -132
View File
@@ -18,137 +18,140 @@
| 8 | `src/adapters/browser-files/browser-file-vault.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 9 | `src/adapters/browser-files/create-browser-file-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 10 | `src/adapters/browser-files/download-delivery-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 11 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 16 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/presigned/http-common.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 45 | `src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts` | [Browser transfer](./04-browser-transfer.md) |
| 46 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 47 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 48 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 49 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 50 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 51 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 52 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 128 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 129 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 130 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 11 | `src/adapters/browser-files/download-input-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 16 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/http-common.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 45 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 46 | `src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts` | [Browser transfer](./04-browser-transfer.md) |
| 47 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 48 | `src/adapters/cache-storage/public-cache-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 49 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 50 | `src/adapters/cache-storage/public-cache-response-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 51 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 52 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 84 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 85 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 86 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 101 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 102 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 103 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 108 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 109 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 110 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 131 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **141/141**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **144/144**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
@@ -1,5 +1,4 @@
import type {
BrowserManagedDownloadCapability,
BrowserManagedDownloadCapabilityResolver,
DownloadDeliveryPort,
DownloadOutcome,
@@ -12,7 +11,6 @@ import type {
TransferProgress,
} from "../../application/ports/browser-file-storage/shared.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
PresignedDownloadSourcePort,
} from "../../application/ports/browser-transfer/presigned-transfer.ts";
@@ -31,18 +29,23 @@ import {
observeBrowserFile,
type BrowserFileObserver,
} from "./file-observer.ts";
import {
sanitizeSuggestedFileName,
type SuggestedFileNamePolicy,
} from "./file-policy.ts";
import {
ObjectUrlLeaseRegistry,
type ObjectUrlLease,
} from "./object-url-lease.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import {
BrowserFilePolicyRegistry,
type ResolvedDownloadPolicy,
} from "./browser-file-policy-registry.ts";
activeDeliveryInput,
isPositiveByteLimit,
resolveBrowserManagedTarget,
safeGeneratedToken,
validByteSource,
validPresignedByteSource,
validateBrowserManagedCapability,
validateDownloadInput,
type DeliveryInput,
type DeliveryRequest,
} from "./download-input-validation.ts";
export type BrowserDownloadHost = Readonly<{
handoff(href: string, suggestedFileName: string): void;
@@ -138,9 +141,6 @@ export type DownloadDeliveryAdapterOptions = Readonly<{
observer?: BrowserFileObserver;
}>;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
const SHA256 = /^[a-f0-9]{64}$/i;
/**
* Keeps a one-shot Blob URL alive across browser download scheduling and
* process handoff. Runtime dispose() still revokes every active lease
@@ -863,163 +863,6 @@ async function boundedObjectUrlHandoff(context: Readonly<{
}
}
type DeliveryRequest =
Parameters<DownloadDeliveryPort["deliver"]>[0];
type DeliveryInput = Readonly<
Omit<
DeliveryRequest,
"maxTransferBytes" | "maxBufferedBytes"
> &
ResolvedDownloadPolicy & {
expectedSha256?: string;
}
>;
function activeDeliveryInput(
input: DeliveryRequest,
policy: ResolvedDownloadPolicy,
): DeliveryInput {
const source = snapshotDownloadSource(input.source);
const expectedSha256 =
source.kind === "GENERATED"
? source.expectedSha256
: undefined;
return Object.freeze({
policy: input.policy,
source,
suggestedFileName: input.suggestedFileName,
signal: input.signal,
onProgress: input.onProgress,
...policy,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function snapshotDownloadSource(
source: DownloadSource,
): DownloadSource {
const kind = source.kind;
if (kind === "BROWSER_MANAGED_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capabilityReceipt: source.capabilityReceipt,
});
}
if (kind === "AUTHORIZED_STREAM_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capability: source.capability,
});
}
if (kind !== "GENERATED") {
throw new TypeError("Download source kind is invalid.");
}
const sourceBytes = source.bytes;
const stream = sourceBytes.stream;
const byteLength = sourceBytes.byteLength;
if (typeof stream !== "function") {
throw new TypeError("Download byte source is invalid.");
}
const bytes: FileByteSource = Object.freeze({
byteLength,
stream: stream.bind(sourceBytes),
});
const expectedSha256 = source.expectedSha256;
return Object.freeze({
kind,
bytes,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function validateDownloadInput(
input: DeliveryInput,
options: DownloadDeliveryAdapterOptions,
userActivation: Readonly<{ isActive: boolean }> | undefined,
): BrowserDataResult<string> {
if (
input.signal.aborted ||
input.suggestedFileName.length === 0 ||
!MEDIA_TYPE.test(input.mediaType) ||
!isValidByteLength(input.maxTransferBytes) ||
input.maxTransferBytes === 0 ||
!isValidByteLength(input.maxBufferedBytes) ||
input.maxBufferedBytes === 0 ||
(input.expectedSha256 !== undefined &&
!SHA256.test(input.expectedSha256)) ||
(input.source.kind === "AUTHORIZED_STREAM_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!validPresignedCapabilityForInput(
input.source.capability,
input.source.resourceId,
input.mediaType,
input.maxTransferBytes,
options.now?.() ?? Date.now(),
) ||
options.openAuthorizedSource === undefined)) ||
(input.source.kind === "BROWSER_MANAGED_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!safeOpaqueId(input.source.capabilityReceipt))) ||
(input.strategy === "PROMPT_AND_STREAM" &&
options.showSaveFilePicker === undefined)
) {
return browserDataFailure(
input.signal.aborted ? "ABORTED" : "INVALID_INPUT",
"DOWNLOAD",
);
}
if (
input.maxTransferBytes > options.hardMaxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
(input.maxBufferedBytes > options.hardMaxObjectUrlBytes ||
input.maxBufferedBytes > input.maxTransferBytes))
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
if (
(input.strategy === "BROWSER_MANAGED" &&
input.source.kind !== "BROWSER_MANAGED_RESOURCE") ||
(input.strategy !== "BROWSER_MANAGED" &&
input.source.kind === "BROWSER_MANAGED_RESOURCE") ||
(input.integrity === "REQUIRED" &&
input.source.kind === "GENERATED" &&
input.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (input.source.kind === "GENERATED") {
try {
if (!validByteSource(input.source.bytes)) {
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (
input.source.bytes.byteLength !== null &&
input.source.bytes.byteLength > input.maxTransferBytes
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
if (userActivation && !userActivation.isActive) {
return browserDataFailure("PERMISSION_DENIED", "DOWNLOAD");
}
try {
return browserDataSuccess(
sanitizeSuggestedFileName(input.suggestedFileName, {
safeExtension: input.safeExtension,
maxUtf8Bytes: options.filenameMaxUtf8Bytes,
} satisfies SuggestedFileNamePolicy),
);
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
/**
* TR-RR-04. A presigned byte source owns a fetch reader and a capability lease,
* and its port requires `close()`. The delivery consumer never called it, so
@@ -1105,14 +948,6 @@ async function resolveByteSource(
: browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
function validByteSource(source: FileByteSource): boolean {
return (
typeof source.stream === "function" &&
(source.byteLength === null ||
isValidByteLength(source.byteLength))
);
}
function isVerifiedPresignedSource(
source: FileByteSource,
): source is PresignedDownloadByteSource {
@@ -1122,61 +957,6 @@ function isVerifiedPresignedSource(
);
}
function validPresignedByteSource(
source: PresignedDownloadByteSource,
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
return (
validByteSource(source) &&
source.capability === capability &&
source.integrity === "VERIFIED_ON_SUCCESSFUL_EXHAUSTION" &&
source.byteLength === capability.byteLength &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
}
function validPresignedCapabilityForInput(
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
try {
return (
Boolean(capability) &&
typeof capability === "object" &&
Object.isFrozen(capability) &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
isValidByteLength(capability.byteLength) &&
isPositiveByteLimit(capability.maxBytes) &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(capability.expiresAtEpochMs) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
} catch {
return false;
}
}
async function* abortableFileChunks(
source: FileByteSource,
owner: AbortableOperation,
@@ -1259,116 +1039,6 @@ function mapDownloadException(
return mapBrowserDataException(error, "DOWNLOAD");
}
function validateBrowserManagedCapability(
capability: BrowserManagedDownloadCapability,
input: DeliveryInput,
nowEpochMs: number,
): BrowserDataResult<BrowserManagedDownloadCapability> {
if (
input.source.kind !== "BROWSER_MANAGED_RESOURCE" ||
!capability ||
typeof capability !== "object" ||
typeof capability.href !== "string" ||
capability.href.length === 0 ||
capability.capabilityReceipt !==
input.source.capabilityReceipt ||
capability.resourceId !== input.source.resourceId ||
capability.mediaType.trim().toLowerCase() !==
input.mediaType ||
capability.safeExtension.trim().toLowerCase() !==
input.safeExtension ||
!isPositiveByteLimit(capability.maxBytes) ||
capability.maxBytes > input.maxTransferBytes ||
!Number.isSafeInteger(capability.expiresAtEpochMs) ||
!Number.isSafeInteger(nowEpochMs) ||
(capability.expectedSha256 !== undefined &&
!SHA256.test(capability.expectedSha256)) ||
(input.integrity === "REQUIRED" &&
capability.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (capability.expiresAtEpochMs <= nowEpochMs) {
return browserDataFailure("EXPIRED_RESOURCE", "DOWNLOAD", {
recovery: "RETRY",
});
}
return browserDataSuccess(
Object.freeze({
capabilityReceipt: capability.capabilityReceipt,
href: capability.href,
resourceId: capability.resourceId,
mediaType: input.mediaType,
safeExtension: input.safeExtension,
maxBytes: capability.maxBytes,
...(capability.expectedSha256
? {
expectedSha256:
capability.expectedSha256.toLowerCase(),
}
: {}),
expiresAtEpochMs: capability.expiresAtEpochMs,
}),
);
}
type ResolvedBrowserManagedTarget = Readonly<{ absoluteHref: string }>;
/**
* STO-02. Parse once, canonicalize, then execute the canonical value.
*
* Returning a boolean and handing the raw href to the host let the browser
* re-resolve a relative target against `document.baseURI`, so a hostile
* `<base>` could send the navigation to a different origin than the one this
* policy just approved.
*/
function resolveBrowserManagedTarget(
href: string,
baseOrigin: string,
policy: Readonly<{
allowCrossOrigin: boolean;
allowQuery: boolean;
}>,
): BrowserDataResult<ResolvedBrowserManagedTarget> {
let base: URL;
let target: URL;
try {
base = new URL(baseOrigin);
target = new URL(href, base);
} catch {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (
!["http:", "https:"].includes(target.protocol) ||
target.username.length > 0 ||
target.password.length > 0 ||
(!policy.allowCrossOrigin && target.origin !== base.origin) ||
(!policy.allowQuery && target.search.length > 0) ||
target.hash.length > 0
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
return browserDataSuccess(
Object.freeze({ absoluteHref: target.href }),
);
}
function safeOpaqueId(value: unknown): value is string {
if (typeof value !== "string") return false;
if (value.length === 0 || value.length > 256) return false;
for (const character of value) {
const code = character.codePointAt(0);
if (code === undefined || code <= 0x20 || code === 0x7f) {
return false;
}
}
return true;
}
function safeGeneratedToken(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
type ProgressReporter = Readonly<{
report(
phase: TransferProgress["phase"],
@@ -1485,7 +1155,3 @@ async function raceOwner<Value>(
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
}
function isPositiveByteLimit(value: number): boolean {
return isValidByteLength(value) && value > 0;
}
@@ -0,0 +1,374 @@
import type {
BrowserManagedDownloadCapability,
DownloadDeliveryPort,
DownloadSource,
FileByteSource,
} from "../../application/ports/browser-file-storage/file.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
} from "../../application/ports/browser-transfer/presigned-transfer.ts";
import { isValidByteLength } from "../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../browser-file-storage/result.ts";
import {
sanitizeSuggestedFileName,
type SuggestedFileNamePolicy,
} from "./file-policy.ts";
import type { ResolvedDownloadPolicy } from "./browser-file-policy-registry.ts";
/**
* Q-6.2-11. Input admission for download delivery: request snapshot, policy
* and limit checks, presigned and browser-managed capability validation, and
* canonical handoff target resolution. Moved verbatim out of the adapter.
*/
/** The adapter options that input validation reads. */
export type DownloadInputValidationOptions = Readonly<{
hardMaxObjectUrlBytes: number;
hardMaxTransferBytes: number;
openAuthorizedSource?: unknown;
showSaveFilePicker?: unknown;
filenameMaxUtf8Bytes?: number;
now?: () => number;
}>;
export const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
export const SHA256 = /^[a-f0-9]{64}$/i;
export type DeliveryRequest =
Parameters<DownloadDeliveryPort["deliver"]>[0];
export type DeliveryInput = Readonly<
Omit<
DeliveryRequest,
"maxTransferBytes" | "maxBufferedBytes"
> &
ResolvedDownloadPolicy & {
expectedSha256?: string;
}
>;
export function activeDeliveryInput(
input: DeliveryRequest,
policy: ResolvedDownloadPolicy,
): DeliveryInput {
const source = snapshotDownloadSource(input.source);
const expectedSha256 =
source.kind === "GENERATED"
? source.expectedSha256
: undefined;
return Object.freeze({
policy: input.policy,
source,
suggestedFileName: input.suggestedFileName,
signal: input.signal,
onProgress: input.onProgress,
...policy,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
export function snapshotDownloadSource(
source: DownloadSource,
): DownloadSource {
const kind = source.kind;
if (kind === "BROWSER_MANAGED_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capabilityReceipt: source.capabilityReceipt,
});
}
if (kind === "AUTHORIZED_STREAM_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capability: source.capability,
});
}
if (kind !== "GENERATED") {
throw new TypeError("Download source kind is invalid.");
}
const sourceBytes = source.bytes;
const stream = sourceBytes.stream;
const byteLength = sourceBytes.byteLength;
if (typeof stream !== "function") {
throw new TypeError("Download byte source is invalid.");
}
const bytes: FileByteSource = Object.freeze({
byteLength,
stream: stream.bind(sourceBytes),
});
const expectedSha256 = source.expectedSha256;
return Object.freeze({
kind,
bytes,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
export function validateDownloadInput(
input: DeliveryInput,
options: DownloadInputValidationOptions,
userActivation: Readonly<{ isActive: boolean }> | undefined,
): BrowserDataResult<string> {
if (
input.signal.aborted ||
input.suggestedFileName.length === 0 ||
!MEDIA_TYPE.test(input.mediaType) ||
!isValidByteLength(input.maxTransferBytes) ||
input.maxTransferBytes === 0 ||
!isValidByteLength(input.maxBufferedBytes) ||
input.maxBufferedBytes === 0 ||
(input.expectedSha256 !== undefined &&
!SHA256.test(input.expectedSha256)) ||
(input.source.kind === "AUTHORIZED_STREAM_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!validPresignedCapabilityForInput(
input.source.capability,
input.source.resourceId,
input.mediaType,
input.maxTransferBytes,
options.now?.() ?? Date.now(),
) ||
options.openAuthorizedSource === undefined)) ||
(input.source.kind === "BROWSER_MANAGED_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!safeOpaqueId(input.source.capabilityReceipt))) ||
(input.strategy === "PROMPT_AND_STREAM" &&
options.showSaveFilePicker === undefined)
) {
return browserDataFailure(
input.signal.aborted ? "ABORTED" : "INVALID_INPUT",
"DOWNLOAD",
);
}
if (
input.maxTransferBytes > options.hardMaxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
(input.maxBufferedBytes > options.hardMaxObjectUrlBytes ||
input.maxBufferedBytes > input.maxTransferBytes))
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
if (
(input.strategy === "BROWSER_MANAGED" &&
input.source.kind !== "BROWSER_MANAGED_RESOURCE") ||
(input.strategy !== "BROWSER_MANAGED" &&
input.source.kind === "BROWSER_MANAGED_RESOURCE") ||
(input.integrity === "REQUIRED" &&
input.source.kind === "GENERATED" &&
input.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (input.source.kind === "GENERATED") {
try {
if (!validByteSource(input.source.bytes)) {
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (
input.source.bytes.byteLength !== null &&
input.source.bytes.byteLength > input.maxTransferBytes
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
if (userActivation && !userActivation.isActive) {
return browserDataFailure("PERMISSION_DENIED", "DOWNLOAD");
}
try {
return browserDataSuccess(
sanitizeSuggestedFileName(input.suggestedFileName, {
safeExtension: input.safeExtension,
maxUtf8Bytes: options.filenameMaxUtf8Bytes,
} satisfies SuggestedFileNamePolicy),
);
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
export function validByteSource(source: FileByteSource): boolean {
return (
typeof source.stream === "function" &&
(source.byteLength === null ||
isValidByteLength(source.byteLength))
);
}
export function validPresignedByteSource(
source: PresignedDownloadByteSource,
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
return (
validByteSource(source) &&
source.capability === capability &&
source.integrity === "VERIFIED_ON_SUCCESSFUL_EXHAUSTION" &&
source.byteLength === capability.byteLength &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
}
export function validPresignedCapabilityForInput(
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
try {
return (
Boolean(capability) &&
typeof capability === "object" &&
Object.isFrozen(capability) &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
isValidByteLength(capability.byteLength) &&
isPositiveByteLimit(capability.maxBytes) &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(capability.expiresAtEpochMs) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
} catch {
return false;
}
}
export function validateBrowserManagedCapability(
capability: BrowserManagedDownloadCapability,
input: DeliveryInput,
nowEpochMs: number,
): BrowserDataResult<BrowserManagedDownloadCapability> {
if (
input.source.kind !== "BROWSER_MANAGED_RESOURCE" ||
!capability ||
typeof capability !== "object" ||
typeof capability.href !== "string" ||
capability.href.length === 0 ||
capability.capabilityReceipt !==
input.source.capabilityReceipt ||
capability.resourceId !== input.source.resourceId ||
capability.mediaType.trim().toLowerCase() !==
input.mediaType ||
capability.safeExtension.trim().toLowerCase() !==
input.safeExtension ||
!isPositiveByteLimit(capability.maxBytes) ||
capability.maxBytes > input.maxTransferBytes ||
!Number.isSafeInteger(capability.expiresAtEpochMs) ||
!Number.isSafeInteger(nowEpochMs) ||
(capability.expectedSha256 !== undefined &&
!SHA256.test(capability.expectedSha256)) ||
(input.integrity === "REQUIRED" &&
capability.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (capability.expiresAtEpochMs <= nowEpochMs) {
return browserDataFailure("EXPIRED_RESOURCE", "DOWNLOAD", {
recovery: "RETRY",
});
}
return browserDataSuccess(
Object.freeze({
capabilityReceipt: capability.capabilityReceipt,
href: capability.href,
resourceId: capability.resourceId,
mediaType: input.mediaType,
safeExtension: input.safeExtension,
maxBytes: capability.maxBytes,
...(capability.expectedSha256
? {
expectedSha256:
capability.expectedSha256.toLowerCase(),
}
: {}),
expiresAtEpochMs: capability.expiresAtEpochMs,
}),
);
}
export type ResolvedBrowserManagedTarget = Readonly<{ absoluteHref: string }>;
/**
* STO-02. Parse once, canonicalize, then execute the canonical value.
*
* Returning a boolean and handing the raw href to the host let the browser
* re-resolve a relative target against `document.baseURI`, so a hostile
* `<base>` could send the navigation to a different origin than the one this
* policy just approved.
*/
export function resolveBrowserManagedTarget(
href: string,
baseOrigin: string,
policy: Readonly<{
allowCrossOrigin: boolean;
allowQuery: boolean;
}>,
): BrowserDataResult<ResolvedBrowserManagedTarget> {
let base: URL;
let target: URL;
try {
base = new URL(baseOrigin);
target = new URL(href, base);
} catch {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (
!["http:", "https:"].includes(target.protocol) ||
target.username.length > 0 ||
target.password.length > 0 ||
(!policy.allowCrossOrigin && target.origin !== base.origin) ||
(!policy.allowQuery && target.search.length > 0) ||
target.hash.length > 0
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
return browserDataSuccess(
Object.freeze({ absoluteHref: target.href }),
);
}
export function safeOpaqueId(value: unknown): value is string {
if (typeof value !== "string") return false;
if (value.length === 0 || value.length > 256) return false;
for (const character of value) {
const code = character.codePointAt(0);
if (code === undefined || code <= 0x20 || code === 0x7f) {
return false;
}
}
return true;
}
export function safeGeneratedToken(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
export function isPositiveByteLimit(value: number): boolean {
return isValidByteLength(value) && value > 0;
}
@@ -0,0 +1,656 @@
import type {
PublicCacheAsset,
PublicCacheHeader,
PublicCacheReleaseManifest,
} from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type {
BrowserDataFailure,
BrowserDataFailureCode,
BrowserDataOperation,
BrowserDataResult,
} from "../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
isAllowedPublicCacheOrigin,
type PublicCacheRuntimePolicy,
} from "./public-cache-policy.ts";
/**
* Q-6.2-11. Release manifest, marker and active-pointer codec for the public
* response cache: normalization, canonical digest input, bounded control JSON
* decoding, owned cache naming, and the mapping of a validation failure to a
* browser-data Result. Moved verbatim out of the adapter.
*/
export type PublicCacheCryptoFacade = Readonly<{
digestSha256(bytes: Uint8Array): Promise<ArrayBuffer>;
}>;
export type NormalizedAsset = Readonly<{
absoluteUrl: string;
expectedByteLength: number;
expectedContentType: string;
digestHex: string;
requestHeaders: readonly PublicCacheHeader[];
}>;
export type NormalizedReleaseManifest = Readonly<{
releaseRegistryId: string;
manifestDigestHex: string;
assets: readonly NormalizedAsset[];
}>;
export type ReleaseMarker = Readonly<{
schemaVersion: 1;
verified: true;
releaseRegistryId: string;
manifestDigestHex: string;
entryCount: number;
totalBytes: number;
stagedAtEpochMs: number;
assets: readonly NormalizedAsset[];
}>;
export type ActiveReleasePointer = Readonly<{
schemaVersion: 1;
releaseRegistryId: string;
manifestDigestHex: string;
candidateCacheName: string;
rollbackCandidateCacheNames: readonly string[];
activatedAtEpochMs: number;
}>;
export type BrowserFailureResult = Readonly<{
ok: false;
error: BrowserDataFailure;
}>;
export class CacheValidationFailure extends Error {
readonly code: BrowserDataFailureCode;
constructor(code: BrowserDataFailureCode) {
super("Public cache validation failed.");
this.name = "CacheValidationFailure";
this.code = code;
}
}
export async function normalizeAndVerifyManifest(
manifest: PublicCacheReleaseManifest,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
): Promise<NormalizedReleaseManifest> {
const snapshot = Object.freeze({
releaseRegistryId: manifest.releaseRegistryId,
manifestDigestHex: manifest.manifestDigestHex,
assets: normalizeAssets(manifest.assets, policy),
});
if (
!policy.isReleaseRegistryIdAllowed(snapshot.releaseRegistryId) ||
!SHA256_HEX.test(snapshot.manifestDigestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const actualDigest = await sha256Hex(
crypto,
new TextEncoder().encode(
canonicalManifest(snapshot.releaseRegistryId, snapshot.assets),
),
);
if (actualDigest !== snapshot.manifestDigestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return snapshot;
}
export function normalizeAssets(
assets: readonly PublicCacheAsset[],
policy: PublicCacheRuntimePolicy,
): readonly NormalizedAsset[] {
if (
!Array.isArray(assets) ||
assets.length < 1 ||
assets.length > policy.maxEntriesPerRelease
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const normalized = assets.map((asset) =>
normalizeAsset(asset, policy),
);
const keys = normalized.map(assetKey);
if (new Set(keys).size !== keys.length) {
throw new CacheValidationFailure("CONFLICT");
}
const declaredTotal = normalized.reduce(
(total, asset) => total + asset.expectedByteLength,
0,
);
if (
!Number.isSafeInteger(declaredTotal) ||
declaredTotal > policy.maxReleaseBytes
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
return Object.freeze(normalized);
}
export function normalizeAsset(
asset: PublicCacheAsset,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
if (
!asset ||
typeof asset !== "object" ||
!Number.isSafeInteger(asset.expectedByteLength) ||
asset.expectedByteLength < 0 ||
asset.expectedByteLength > policy.maxEntryBytes ||
asset.integrity?.algorithm !== "SHA-256" ||
!SHA256_HEX.test(asset.integrity.digestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
return Object.freeze({
absoluteUrl: normalizePublicUrl(asset.absoluteUrl, policy),
expectedByteLength: asset.expectedByteLength,
expectedContentType: normalizeContentType(
asset.expectedContentType,
policy,
),
digestHex: asset.integrity.digestHex,
requestHeaders: normalizeRequestHeaders(
asset.requestHeaders,
policy,
),
});
}
export function normalizeLookupRequest(
absoluteUrl: string,
requestHeaders: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
return {
absoluteUrl: normalizePublicUrl(absoluteUrl, policy),
expectedByteLength: 0,
expectedContentType: "",
digestHex: ZERO_SHA256,
requestHeaders: normalizeRequestHeaders(requestHeaders, policy),
};
}
export function normalizeContentType(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (
typeof input !== "string" ||
input.length < 1 ||
input.length > 256 ||
/[\r\n\0]/u.test(input) ||
!policy.isContentTypeAllowed(input)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return input
.split(";")
.map((part) => part.trim())
.filter((part) => part.length > 0)
.map((part, index) =>
index === 0 ? part.toLowerCase() : part,
)
.join("; ");
}
export function normalizePublicUrl(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (typeof input !== "string" || input.length > 2_048) {
throw new CacheValidationFailure("INVALID_INPUT");
}
let url: URL;
try {
url = new URL(input);
} catch {
throw new CacheValidationFailure("INVALID_INPUT");
}
if (
url.origin !== policy.origin ||
!isAllowedPublicCacheOrigin(url) ||
url.username.length > 0 ||
url.password.length > 0 ||
url.hash.length > 0 ||
url.href === markerRequestUrl(policy) ||
url.href === activePointerRequestUrl(policy)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const forbidden = new Set(policy.forbiddenQueryParameterNames);
const allowed = new Set(policy.allowedQueryParameterNames);
const seenNames = new Set<string>();
for (const [rawName, value] of url.searchParams.entries()) {
const name = rawName.toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
seenNames.has(name) ||
!policy.isQueryParameterValueAllowed(name, value)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
seenNames.add(name);
}
return url.href;
}
export function normalizeRequestHeaders(
input: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedRequestHeaderNames);
const forbidden = new Set([
"authorization",
"cookie",
"proxy-authorization",
"range",
]);
const headers = new Headers();
for (const pair of input ?? []) {
if (
!Array.isArray(pair) ||
pair.length !== 2 ||
typeof pair[0] !== "string" ||
typeof pair[1] !== "string"
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const name = pair[0].toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
pair[1].length > 1_024 ||
/[\r\n\0]/u.test(pair[1])
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
headers.append(name, pair[1].trim());
}
return Object.freeze(
[...headers.entries()]
.sort(([left], [right]) => left.localeCompare(right))
.map(
([name, value]) =>
Object.freeze([name, value]) as PublicCacheHeader,
),
);
}
export async function readBoundedJson(
response: Response,
maximumBytes: number,
): Promise<unknown> {
const contentLength = response.headers.get("content-length");
if (
!Number.isSafeInteger(maximumBytes) ||
maximumBytes <= 0 ||
(contentLength !== null &&
(!/^\d+$/u.test(contentLength) ||
Number(contentLength) > maximumBytes))
) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
if (!response.body) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const reader = response.body.getReader();
// Q-6.2-6. Chunks are kept as read; the budget is enforced on their total,
// never by preallocating it.
const chunks: Uint8Array[] = [];
let byteLength = 0;
let completelyRead = false;
try {
while (true) {
const chunk = await reader.read();
if (chunk.done) {
completelyRead = true;
break;
}
if (chunk.value.byteLength > maximumBytes - byteLength) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
chunks.push(chunk.value);
byteLength += chunk.value.byteLength;
}
} catch (error) {
if (!completelyRead) {
cancelReaderSafely(
reader,
"Cache control JSON exceeded its read budget.",
);
}
throw error;
} finally {
reader.releaseLock();
}
const bytes = new Uint8Array(byteLength);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
let text: string;
try {
text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
try {
return JSON.parse(text);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
}
export function cancelReaderSafely(
reader: ReadableStreamDefaultReader<Uint8Array>,
reason: string,
): void {
try {
void reader.cancel(reason).catch(() => undefined);
} catch {
// Cancellation is best effort once the bounded consumer has stopped.
}
}
export function isReleaseMarker(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ReleaseMarker {
if (
!value ||
typeof value !== "object" ||
!("schemaVersion" in value) ||
value.schemaVersion !== 1 ||
!("verified" in value) ||
value.verified !== true ||
!("releaseRegistryId" in value) ||
typeof value.releaseRegistryId !== "string" ||
!policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) ||
!("manifestDigestHex" in value) ||
typeof value.manifestDigestHex !== "string" ||
!SHA256_HEX.test(value.manifestDigestHex) ||
!("entryCount" in value) ||
typeof value.entryCount !== "number" ||
!Number.isSafeInteger(value.entryCount) ||
!("totalBytes" in value) ||
typeof value.totalBytes !== "number" ||
!Number.isSafeInteger(value.totalBytes) ||
!("stagedAtEpochMs" in value) ||
typeof value.stagedAtEpochMs !== "number" ||
!Number.isSafeInteger(value.stagedAtEpochMs) ||
!("assets" in value) ||
!Array.isArray(value.assets) ||
value.assets.length > policy.maxEntriesPerRelease
) {
return false;
}
try {
const normalized = normalizeAssets(
value.assets.map((asset) => markerAssetToPublicAsset(asset)),
policy,
);
return stableJson(normalized) === stableJson(value.assets);
} catch {
return false;
}
}
export function markerAssetToPublicAsset(value: unknown): PublicCacheAsset {
if (!value || typeof value !== "object") {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const asset = value as Partial<NormalizedAsset>;
return {
absoluteUrl: asset.absoluteUrl ?? "",
expectedByteLength: asset.expectedByteLength ?? -1,
expectedContentType: asset.expectedContentType ?? "",
integrity: {
algorithm: "SHA-256",
digestHex: asset.digestHex ?? "",
},
requestHeaders: asset.requestHeaders,
};
}
export function isActivePointer(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ActiveReleasePointer {
return Boolean(
value &&
typeof value === "object" &&
"schemaVersion" in value &&
value.schemaVersion === 1 &&
"releaseRegistryId" in value &&
typeof value.releaseRegistryId === "string" &&
policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) &&
"manifestDigestHex" in value &&
typeof value.manifestDigestHex === "string" &&
SHA256_HEX.test(value.manifestDigestHex) &&
"candidateCacheName" in value &&
typeof value.candidateCacheName === "string" &&
value.candidateCacheName ===
releaseCacheName(
policy,
value.releaseRegistryId,
value.manifestDigestHex,
) &&
"rollbackCandidateCacheNames" in value &&
Array.isArray(value.rollbackCandidateCacheNames) &&
value.rollbackCandidateCacheNames.length <=
policy.retainedPreviousReleaseCount &&
new Set(value.rollbackCandidateCacheNames).size ===
value.rollbackCandidateCacheNames.length &&
value.rollbackCandidateCacheNames.every(
(name) =>
typeof name === "string" &&
name !== value.candidateCacheName &&
isOwnedReleaseCacheName(name, policy),
) &&
"activatedAtEpochMs" in value &&
typeof value.activatedAtEpochMs === "number" &&
Number.isSafeInteger(value.activatedAtEpochMs),
);
}
export function isOwnedReleaseCacheName(
name: string,
policy: PublicCacheRuntimePolicy,
): boolean {
if (!name.startsWith(`${policy.ownedCachePrefix}release:`)) {
return false;
}
const remainder = name.slice(
`${policy.ownedCachePrefix}release:`.length,
);
const separator = remainder.lastIndexOf(":");
if (separator < 1) return false;
const releaseRegistryId = remainder.slice(0, separator);
const digestHex = remainder.slice(separator + 1);
return (
policy.isReleaseRegistryIdAllowed(releaseRegistryId) &&
SHA256_HEX.test(digestHex)
);
}
export function canonicalManifest(
releaseRegistryId: string,
assets: readonly NormalizedAsset[],
): string {
return [
"ca-public-cache-manifest-v1",
`release:${releaseRegistryId}`,
...[...assets]
.sort((left, right) => assetKey(left).localeCompare(assetKey(right)))
.map(
(asset) =>
`${assetKey(asset)}:${asset.expectedByteLength}:${JSON.stringify(asset.expectedContentType)}:${asset.digestHex}`,
),
"",
].join("\n");
}
export function assetKey(
asset: Pick<NormalizedAsset, "absoluteUrl" | "requestHeaders">,
): string {
return JSON.stringify([asset.absoluteUrl, asset.requestHeaders]);
}
export function markerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(markerRequestUrl(policy), { method: "GET" });
}
export function activePointerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(activePointerRequestUrl(policy), { method: "GET" });
}
export function markerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/candidate`;
}
export function activePointerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/active`;
}
export function controlCacheName(policy: PublicCacheRuntimePolicy): string {
return `${policy.ownedCachePrefix}control`;
}
export function releaseCacheName(
policy: PublicCacheRuntimePolicy,
releaseRegistryId: string,
manifestDigestHex: string,
): string {
return `${policy.ownedCachePrefix}release:${releaseRegistryId}:${manifestDigestHex}`;
}
export function jsonResponse(value: unknown): Response {
return new Response(JSON.stringify(value), {
status: 200,
headers: {
"cache-control": "no-store",
"content-type": "application/json; charset=utf-8",
},
});
}
export function validationFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
return error instanceof CacheValidationFailure
? failureForCode(error.code, operation)
: asFailure(browserDataFailure("INVALID_INPUT", operation));
}
export function exceptionFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (error instanceof CacheValidationFailure) {
return failureForCode(error.code, operation);
}
const mapped = mapBrowserDataException(error, operation);
if (mapped.ok) {
return asFailure(
browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return mapped;
}
export function failureForCode(
code: BrowserDataFailureCode,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (code === "ABORTED") {
return asFailure(browserDataFailure(code, operation));
}
if (code === "INTEGRITY_FAILED" || code === "CORRUPT_DATA") {
return asFailure(
browserDataFailure(code, operation, { recovery: "REHYDRATE" }),
);
}
if (code === "QUOTA_EXCEEDED") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "ONLINE_ONLY",
}),
);
}
if (code === "BLOCKED" || code === "UNAVAILABLE") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return asFailure(browserDataFailure(code, operation));
}
export function asFailure(
result: BrowserDataResult<never>,
): BrowserFailureResult {
if (result.ok) {
throw new TypeError("Expected a browser data failure.");
}
return result;
}
export async function sha256Hex(
crypto: PublicCacheCryptoFacade,
bytes: Uint8Array,
): Promise<string> {
const digest = await crypto.digestSha256(bytes);
let hex = "";
for (const byte of new Uint8Array(digest)) {
hex += byte.toString(16).padStart(2, "0");
}
return hex;
}
export function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new CacheValidationFailure("CORRUPT_DATA");
}
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
export const ZERO_SHA256 = "0".repeat(64);
export const MAX_CONTROL_JSON_BYTES = 2 * 1024 * 1024;
@@ -0,0 +1,239 @@
import type { PublicCacheHeader } from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import { browserDataSuccess } from "../browser-file-storage/result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
import {
CacheValidationFailure,
cancelReaderSafely,
exceptionFailure,
normalizeContentType,
sha256Hex,
type NormalizedAsset,
type PublicCacheCryptoFacade,
} from "./public-cache-codec.ts";
import type { PublicCacheRuntimePolicy } from "./public-cache-policy.ts";
/**
* Q-6.2-11. Admission of a network or cached response for one manifest asset:
* status, cache directives, content type, Vary, bounded body read and digest.
* Moved verbatim out of the adapter.
*/
export type CacheReadResult = Readonly<{
bytes: Uint8Array;
headers: readonly PublicCacheHeader[];
}>;
export async function readAndValidateResponse(
response: Response,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
signal: AbortSignal | undefined,
): Promise<BrowserDataResult<CacheReadResult>> {
try {
if (
response.status !== 200 ||
!response.ok ||
response.redirected ||
response.type === "opaque" ||
response.type === "opaqueredirect" ||
response.type === "error" ||
(response.url.length > 0 &&
new URL(response.url).href !== asset.absoluteUrl)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const cacheControl = response.headers.get("cache-control") ?? "";
const directives = new Set(
cacheControl
.split(",")
.map((part) => part.trim().split("=", 1)[0]?.toLowerCase())
.filter((part): part is string => Boolean(part)),
);
if (
directives.has("private") ||
directives.has("no-store") ||
directives.has("no-cache") ||
(response.headers.get("pragma") ?? "")
.toLowerCase()
.includes("no-cache") ||
response.headers.has("set-cookie") ||
response.headers.has("set-cookie2") ||
response.headers.has("www-authenticate")
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const contentType = response.headers.get("content-type");
if (!contentType || !policy.isContentTypeAllowed(contentType)) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
if (
normalizeContentType(contentType, policy) !==
asset.expectedContentType
) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
validateVary(response.headers.get("vary"), asset, policy);
const declaredLength = response.headers.get("content-length");
if (
declaredLength !== null &&
(!/^\d+$/u.test(declaredLength) ||
Number(declaredLength) > policy.maxEntryBytes)
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const bytes = await readBodyBounded(
response,
asset.expectedByteLength,
policy.maxEntryBytes,
signal,
);
const digestHex = await sha256Hex(crypto, bytes);
if (digestHex !== asset.digestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const headers = sanitizedResponseHeaders(response.headers, policy);
return browserDataSuccess({ bytes, headers });
} catch (error) {
return exceptionFailure(error, "CACHE_STAGE");
}
}
export async function readBodyBounded(
response: Response,
expectedByteLength: number,
maxEntryBytes: number,
signal: AbortSignal | undefined,
): Promise<Uint8Array> {
if (expectedByteLength > maxEntryBytes) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
if (!response.body) {
if (expectedByteLength === 0) return new Uint8Array();
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const output = new Uint8Array(expectedByteLength);
const reader = response.body.getReader();
let offset = 0;
// The kernel owner ends a pending read on abort instead of a listener pair.
const owner = createAbortableOperation({ signal });
const abortRead = (): CacheValidationFailure => {
cancelReaderSafely(reader, "Public cache body read was aborted.");
return new CacheValidationFailure("ABORTED");
};
try {
while (true) {
if (owner.signal.aborted) throw abortRead();
const raced = await owner.race(reader.read());
if (raced.kind === "REJECTED") throw raced.reason;
if (raced.kind === "TERMINAL" || owner.signal.aborted) {
throw abortRead();
}
const part = raced.value;
if (part.done) break;
if (
!(part.value instanceof Uint8Array) ||
offset + part.value.byteLength > expectedByteLength ||
offset + part.value.byteLength > maxEntryBytes
) {
cancelReaderSafely(
reader,
"Public cache body exceeded its read budget.",
);
throw new CacheValidationFailure(
offset + part.value.byteLength > maxEntryBytes
? "LIMIT_EXCEEDED"
: "INTEGRITY_FAILED",
);
}
output.set(part.value, offset);
offset += part.value.byteLength;
}
} finally {
owner.close();
reader.releaseLock();
}
if (offset !== expectedByteLength) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return output;
}
export function validateVary(
vary: string | null,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
): void {
const expected = new Set(
asset.requestHeaders.map(([name]) => name.toLowerCase()),
);
const actual = new Set<string>();
if (!vary) {
if (expected.size > 0) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return;
}
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" ||
name === "cookie" ||
!allowed.has(name)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
actual.add(name);
}
if (
actual.size !== expected.size ||
[...actual].some((name) => !expected.has(name))
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
}
export function sanitizedResponseHeaders(
headers: Headers,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedResponseHeaderNames);
const sanitized: PublicCacheHeader[] = [];
for (const [name, value] of headers.entries()) {
if (!allowed.has(name)) {
if (policy.unknownResponseHeaderAction === "REJECT") {
throw new CacheValidationFailure("POLICY_REJECTED");
}
continue;
}
sanitized.push(Object.freeze([name, value]));
}
return Object.freeze(sanitized);
}
export function createNativeRequest(
asset: NormalizedAsset,
signal?: AbortSignal,
): Request {
return new Request(asset.absoluteUrl, {
method: "GET",
headers: new Headers(
asset.requestHeaders.map(([name, value]) => [name, value]),
),
credentials: "omit",
cache: "no-store",
redirect: "error",
referrerPolicy: "no-referrer",
mode: "same-origin",
signal,
});
}
@@ -2,7 +2,6 @@ import type {
CachedPublicResponse,
PublicCacheAsset,
PublicCacheCleanupReport,
PublicCacheHeader,
PublicCacheInspection,
PublicCacheReleaseManifest,
PublicCacheReleaseSummary,
@@ -10,7 +9,6 @@ import type {
} from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type {
BrowserDataFailure,
BrowserDataFailureCode,
BrowserDataOperation,
BrowserDataResult,
ByteSource,
@@ -19,18 +17,48 @@ import {
abortedResult,
browserDataFailure,
browserDataSuccess,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
import {
cacheByteBucket,
cacheEntryBucket,
isAllowedPublicCacheOrigin,
observePublicCacheSafely,
resolvePublicCachePolicy,
type PublicCacheRuntimePolicy,
type PublicCacheSafeObserver,
} from "./public-cache-policy.ts";
import {
CacheValidationFailure,
MAX_CONTROL_JSON_BYTES,
SHA256_HEX,
activePointerRequest,
asFailure,
assetKey,
canonicalManifest,
controlCacheName,
exceptionFailure,
isActivePointer,
isReleaseMarker,
jsonResponse,
markerRequest,
normalizeAndVerifyManifest,
normalizeAssets,
normalizeLookupRequest,
readBoundedJson,
releaseCacheName,
sha256Hex,
validationFailure,
type ActiveReleasePointer,
type BrowserFailureResult,
type NormalizedAsset,
type NormalizedReleaseManifest,
type PublicCacheCryptoFacade,
type ReleaseMarker,
} from "./public-cache-codec.ts";
import {
createNativeRequest,
readAndValidateResponse,
} from "./public-cache-response-validation.ts";
export interface PublicCacheMutationLock {
run<Value>(
@@ -60,10 +88,6 @@ type PublicCacheStorageFacade = Readonly<{
delete(name: string): Promise<boolean>;
}>;
type PublicCacheCryptoFacade = Readonly<{
digestSha256(bytes: Uint8Array): Promise<ArrayBuffer>;
}>;
type PublicResponseCacheDependencySnapshot = Readonly<{
cacheStorage?: PublicCacheStorageFacade;
fetcher?: (request: Request) => Promise<Response>;
@@ -72,40 +96,6 @@ type PublicResponseCacheDependencySnapshot = Readonly<{
observer?: PublicCacheSafeObserver;
}>;
type NormalizedAsset = Readonly<{
absoluteUrl: string;
expectedByteLength: number;
expectedContentType: string;
digestHex: string;
requestHeaders: readonly PublicCacheHeader[];
}>;
type NormalizedReleaseManifest = Readonly<{
releaseRegistryId: string;
manifestDigestHex: string;
assets: readonly NormalizedAsset[];
}>;
type ReleaseMarker = Readonly<{
schemaVersion: 1;
verified: true;
releaseRegistryId: string;
manifestDigestHex: string;
entryCount: number;
totalBytes: number;
stagedAtEpochMs: number;
assets: readonly NormalizedAsset[];
}>;
type ActiveReleasePointer = Readonly<{
schemaVersion: 1;
releaseRegistryId: string;
manifestDigestHex: string;
candidateCacheName: string;
rollbackCandidateCacheNames: readonly string[];
activatedAtEpochMs: number;
}>;
/**
* Q-6.2-6. A lookup-ready view of a verified marker. The cache name already
* encodes the manifest digest and the digest binds every asset field, so a
@@ -116,16 +106,6 @@ type VerifiedLookupMarker = Readonly<{
assetsByKey: ReadonlyMap<string, NormalizedAsset>;
}>;
type BrowserFailureResult = Readonly<{
ok: false;
error: BrowserDataFailure;
}>;
type CacheReadResult = Readonly<{
bytes: Uint8Array;
headers: readonly PublicCacheHeader[];
}>;
type LockManagerLike = {
request<Value>(
name: string,
@@ -134,16 +114,6 @@ type LockManagerLike = {
): Promise<Value>;
};
class CacheValidationFailure extends Error {
readonly code: BrowserDataFailureCode;
constructor(code: BrowserDataFailureCode) {
super("Public cache validation failed.");
this.name = "CacheValidationFailure";
this.code = code;
}
}
function snapshotPublicCacheDependencies(
dependencies: PublicResponseCacheDependencies,
): PublicResponseCacheDependencySnapshot {
@@ -974,431 +944,6 @@ export async function computePublicCacheManifestDigestHex(
);
}
async function normalizeAndVerifyManifest(
manifest: PublicCacheReleaseManifest,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
): Promise<NormalizedReleaseManifest> {
const snapshot = Object.freeze({
releaseRegistryId: manifest.releaseRegistryId,
manifestDigestHex: manifest.manifestDigestHex,
assets: normalizeAssets(manifest.assets, policy),
});
if (
!policy.isReleaseRegistryIdAllowed(snapshot.releaseRegistryId) ||
!SHA256_HEX.test(snapshot.manifestDigestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const actualDigest = await sha256Hex(
crypto,
new TextEncoder().encode(
canonicalManifest(snapshot.releaseRegistryId, snapshot.assets),
),
);
if (actualDigest !== snapshot.manifestDigestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return snapshot;
}
function normalizeAssets(
assets: readonly PublicCacheAsset[],
policy: PublicCacheRuntimePolicy,
): readonly NormalizedAsset[] {
if (
!Array.isArray(assets) ||
assets.length < 1 ||
assets.length > policy.maxEntriesPerRelease
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const normalized = assets.map((asset) =>
normalizeAsset(asset, policy),
);
const keys = normalized.map(assetKey);
if (new Set(keys).size !== keys.length) {
throw new CacheValidationFailure("CONFLICT");
}
const declaredTotal = normalized.reduce(
(total, asset) => total + asset.expectedByteLength,
0,
);
if (
!Number.isSafeInteger(declaredTotal) ||
declaredTotal > policy.maxReleaseBytes
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
return Object.freeze(normalized);
}
function normalizeAsset(
asset: PublicCacheAsset,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
if (
!asset ||
typeof asset !== "object" ||
!Number.isSafeInteger(asset.expectedByteLength) ||
asset.expectedByteLength < 0 ||
asset.expectedByteLength > policy.maxEntryBytes ||
asset.integrity?.algorithm !== "SHA-256" ||
!SHA256_HEX.test(asset.integrity.digestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
return Object.freeze({
absoluteUrl: normalizePublicUrl(asset.absoluteUrl, policy),
expectedByteLength: asset.expectedByteLength,
expectedContentType: normalizeContentType(
asset.expectedContentType,
policy,
),
digestHex: asset.integrity.digestHex,
requestHeaders: normalizeRequestHeaders(
asset.requestHeaders,
policy,
),
});
}
function normalizeLookupRequest(
absoluteUrl: string,
requestHeaders: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
return {
absoluteUrl: normalizePublicUrl(absoluteUrl, policy),
expectedByteLength: 0,
expectedContentType: "",
digestHex: ZERO_SHA256,
requestHeaders: normalizeRequestHeaders(requestHeaders, policy),
};
}
function normalizeContentType(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (
typeof input !== "string" ||
input.length < 1 ||
input.length > 256 ||
/[\r\n\0]/u.test(input) ||
!policy.isContentTypeAllowed(input)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return input
.split(";")
.map((part) => part.trim())
.filter((part) => part.length > 0)
.map((part, index) =>
index === 0 ? part.toLowerCase() : part,
)
.join("; ");
}
function normalizePublicUrl(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (typeof input !== "string" || input.length > 2_048) {
throw new CacheValidationFailure("INVALID_INPUT");
}
let url: URL;
try {
url = new URL(input);
} catch {
throw new CacheValidationFailure("INVALID_INPUT");
}
if (
url.origin !== policy.origin ||
!isAllowedPublicCacheOrigin(url) ||
url.username.length > 0 ||
url.password.length > 0 ||
url.hash.length > 0 ||
url.href === markerRequestUrl(policy) ||
url.href === activePointerRequestUrl(policy)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const forbidden = new Set(policy.forbiddenQueryParameterNames);
const allowed = new Set(policy.allowedQueryParameterNames);
const seenNames = new Set<string>();
for (const [rawName, value] of url.searchParams.entries()) {
const name = rawName.toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
seenNames.has(name) ||
!policy.isQueryParameterValueAllowed(name, value)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
seenNames.add(name);
}
return url.href;
}
function normalizeRequestHeaders(
input: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedRequestHeaderNames);
const forbidden = new Set([
"authorization",
"cookie",
"proxy-authorization",
"range",
]);
const headers = new Headers();
for (const pair of input ?? []) {
if (
!Array.isArray(pair) ||
pair.length !== 2 ||
typeof pair[0] !== "string" ||
typeof pair[1] !== "string"
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const name = pair[0].toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
pair[1].length > 1_024 ||
/[\r\n\0]/u.test(pair[1])
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
headers.append(name, pair[1].trim());
}
return Object.freeze(
[...headers.entries()]
.sort(([left], [right]) => left.localeCompare(right))
.map(
([name, value]) =>
Object.freeze([name, value]) as PublicCacheHeader,
),
);
}
async function readAndValidateResponse(
response: Response,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
signal: AbortSignal | undefined,
): Promise<BrowserDataResult<CacheReadResult>> {
try {
if (
response.status !== 200 ||
!response.ok ||
response.redirected ||
response.type === "opaque" ||
response.type === "opaqueredirect" ||
response.type === "error" ||
(response.url.length > 0 &&
new URL(response.url).href !== asset.absoluteUrl)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const cacheControl = response.headers.get("cache-control") ?? "";
const directives = new Set(
cacheControl
.split(",")
.map((part) => part.trim().split("=", 1)[0]?.toLowerCase())
.filter((part): part is string => Boolean(part)),
);
if (
directives.has("private") ||
directives.has("no-store") ||
directives.has("no-cache") ||
(response.headers.get("pragma") ?? "")
.toLowerCase()
.includes("no-cache") ||
response.headers.has("set-cookie") ||
response.headers.has("set-cookie2") ||
response.headers.has("www-authenticate")
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const contentType = response.headers.get("content-type");
if (!contentType || !policy.isContentTypeAllowed(contentType)) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
if (
normalizeContentType(contentType, policy) !==
asset.expectedContentType
) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
validateVary(response.headers.get("vary"), asset, policy);
const declaredLength = response.headers.get("content-length");
if (
declaredLength !== null &&
(!/^\d+$/u.test(declaredLength) ||
Number(declaredLength) > policy.maxEntryBytes)
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const bytes = await readBodyBounded(
response,
asset.expectedByteLength,
policy.maxEntryBytes,
signal,
);
const digestHex = await sha256Hex(crypto, bytes);
if (digestHex !== asset.digestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const headers = sanitizedResponseHeaders(response.headers, policy);
return browserDataSuccess({ bytes, headers });
} catch (error) {
return exceptionFailure(error, "CACHE_STAGE");
}
}
async function readBodyBounded(
response: Response,
expectedByteLength: number,
maxEntryBytes: number,
signal: AbortSignal | undefined,
): Promise<Uint8Array> {
if (expectedByteLength > maxEntryBytes) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
if (!response.body) {
if (expectedByteLength === 0) return new Uint8Array();
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const output = new Uint8Array(expectedByteLength);
const reader = response.body.getReader();
let offset = 0;
let aborted = signal?.aborted ?? false;
const onAbort = (): void => {
aborted = true;
cancelReaderSafely(reader, "Public cache body read was aborted.");
};
signal?.addEventListener("abort", onAbort, { once: true });
try {
while (true) {
if (aborted) {
cancelReaderSafely(reader, "Public cache body read was aborted.");
throw new CacheValidationFailure("ABORTED");
}
const part = await reader.read();
if (aborted) {
throw new CacheValidationFailure("ABORTED");
}
if (part.done) break;
if (
!(part.value instanceof Uint8Array) ||
offset + part.value.byteLength > expectedByteLength ||
offset + part.value.byteLength > maxEntryBytes
) {
cancelReaderSafely(
reader,
"Public cache body exceeded its read budget.",
);
throw new CacheValidationFailure(
offset + part.value.byteLength > maxEntryBytes
? "LIMIT_EXCEEDED"
: "INTEGRITY_FAILED",
);
}
output.set(part.value, offset);
offset += part.value.byteLength;
}
} finally {
signal?.removeEventListener("abort", onAbort);
reader.releaseLock();
}
if (offset !== expectedByteLength) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return output;
}
function validateVary(
vary: string | null,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
): void {
const expected = new Set(
asset.requestHeaders.map(([name]) => name.toLowerCase()),
);
const actual = new Set<string>();
if (!vary) {
if (expected.size > 0) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return;
}
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" ||
name === "cookie" ||
!allowed.has(name)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
actual.add(name);
}
if (
actual.size !== expected.size ||
[...actual].some((name) => !expected.has(name))
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
}
function sanitizedResponseHeaders(
headers: Headers,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedResponseHeaderNames);
const sanitized: PublicCacheHeader[] = [];
for (const [name, value] of headers.entries()) {
if (!allowed.has(name)) {
if (policy.unknownResponseHeaderAction === "REJECT") {
throw new CacheValidationFailure("POLICY_REJECTED");
}
continue;
}
sanitized.push(Object.freeze([name, value]));
}
return Object.freeze(sanitized);
}
function createNativeRequest(
asset: NormalizedAsset,
signal?: AbortSignal,
): Request {
return new Request(asset.absoluteUrl, {
method: "GET",
headers: new Headers(
asset.requestHeaders.map(([name, value]) => [name, value]),
),
credentials: "omit",
cache: "no-store",
redirect: "error",
referrerPolicy: "no-referrer",
mode: "same-origin",
signal,
});
}
async function readMarker(
cache: PublicCacheFacade,
policy: PublicCacheRuntimePolicy,
@@ -1462,229 +1007,6 @@ async function readActivePointer(
}
}
async function readBoundedJson(
response: Response,
maximumBytes: number,
): Promise<unknown> {
const contentLength = response.headers.get("content-length");
if (
!Number.isSafeInteger(maximumBytes) ||
maximumBytes <= 0 ||
(contentLength !== null &&
(!/^\d+$/u.test(contentLength) ||
Number(contentLength) > maximumBytes))
) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
if (!response.body) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const reader = response.body.getReader();
// Q-6.2-6. Chunks are kept as read; the budget is enforced on their total,
// never by preallocating it.
const chunks: Uint8Array[] = [];
let byteLength = 0;
let completelyRead = false;
try {
while (true) {
const chunk = await reader.read();
if (chunk.done) {
completelyRead = true;
break;
}
if (chunk.value.byteLength > maximumBytes - byteLength) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
chunks.push(chunk.value);
byteLength += chunk.value.byteLength;
}
} catch (error) {
if (!completelyRead) {
cancelReaderSafely(
reader,
"Cache control JSON exceeded its read budget.",
);
}
throw error;
} finally {
reader.releaseLock();
}
const bytes = new Uint8Array(byteLength);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
let text: string;
try {
text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
try {
return JSON.parse(text);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
}
function cancelReaderSafely(
reader: ReadableStreamDefaultReader<Uint8Array>,
reason: string,
): void {
try {
void reader.cancel(reason).catch(() => undefined);
} catch {
// Cancellation is best effort once the bounded consumer has stopped.
}
}
function isReleaseMarker(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ReleaseMarker {
if (
!value ||
typeof value !== "object" ||
!("schemaVersion" in value) ||
value.schemaVersion !== 1 ||
!("verified" in value) ||
value.verified !== true ||
!("releaseRegistryId" in value) ||
typeof value.releaseRegistryId !== "string" ||
!policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) ||
!("manifestDigestHex" in value) ||
typeof value.manifestDigestHex !== "string" ||
!SHA256_HEX.test(value.manifestDigestHex) ||
!("entryCount" in value) ||
typeof value.entryCount !== "number" ||
!Number.isSafeInteger(value.entryCount) ||
!("totalBytes" in value) ||
typeof value.totalBytes !== "number" ||
!Number.isSafeInteger(value.totalBytes) ||
!("stagedAtEpochMs" in value) ||
typeof value.stagedAtEpochMs !== "number" ||
!Number.isSafeInteger(value.stagedAtEpochMs) ||
!("assets" in value) ||
!Array.isArray(value.assets) ||
value.assets.length > policy.maxEntriesPerRelease
) {
return false;
}
try {
const normalized = normalizeAssets(
value.assets.map((asset) => markerAssetToPublicAsset(asset)),
policy,
);
return stableJson(normalized) === stableJson(value.assets);
} catch {
return false;
}
}
function markerAssetToPublicAsset(value: unknown): PublicCacheAsset {
if (!value || typeof value !== "object") {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const asset = value as Partial<NormalizedAsset>;
return {
absoluteUrl: asset.absoluteUrl ?? "",
expectedByteLength: asset.expectedByteLength ?? -1,
expectedContentType: asset.expectedContentType ?? "",
integrity: {
algorithm: "SHA-256",
digestHex: asset.digestHex ?? "",
},
requestHeaders: asset.requestHeaders,
};
}
function isActivePointer(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ActiveReleasePointer {
return Boolean(
value &&
typeof value === "object" &&
"schemaVersion" in value &&
value.schemaVersion === 1 &&
"releaseRegistryId" in value &&
typeof value.releaseRegistryId === "string" &&
policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) &&
"manifestDigestHex" in value &&
typeof value.manifestDigestHex === "string" &&
SHA256_HEX.test(value.manifestDigestHex) &&
"candidateCacheName" in value &&
typeof value.candidateCacheName === "string" &&
value.candidateCacheName ===
releaseCacheName(
policy,
value.releaseRegistryId,
value.manifestDigestHex,
) &&
"rollbackCandidateCacheNames" in value &&
Array.isArray(value.rollbackCandidateCacheNames) &&
value.rollbackCandidateCacheNames.length <=
policy.retainedPreviousReleaseCount &&
new Set(value.rollbackCandidateCacheNames).size ===
value.rollbackCandidateCacheNames.length &&
value.rollbackCandidateCacheNames.every(
(name) =>
typeof name === "string" &&
name !== value.candidateCacheName &&
isOwnedReleaseCacheName(name, policy),
) &&
"activatedAtEpochMs" in value &&
typeof value.activatedAtEpochMs === "number" &&
Number.isSafeInteger(value.activatedAtEpochMs),
);
}
function isOwnedReleaseCacheName(
name: string,
policy: PublicCacheRuntimePolicy,
): boolean {
if (!name.startsWith(`${policy.ownedCachePrefix}release:`)) {
return false;
}
const remainder = name.slice(
`${policy.ownedCachePrefix}release:`.length,
);
const separator = remainder.lastIndexOf(":");
if (separator < 1) return false;
const releaseRegistryId = remainder.slice(0, separator);
const digestHex = remainder.slice(separator + 1);
return (
policy.isReleaseRegistryIdAllowed(releaseRegistryId) &&
SHA256_HEX.test(digestHex)
);
}
function canonicalManifest(
releaseRegistryId: string,
assets: readonly NormalizedAsset[],
): string {
return [
"ca-public-cache-manifest-v1",
`release:${releaseRegistryId}`,
...[...assets]
.sort((left, right) => assetKey(left).localeCompare(assetKey(right)))
.map(
(asset) =>
`${assetKey(asset)}:${asset.expectedByteLength}:${JSON.stringify(asset.expectedContentType)}:${asset.digestHex}`,
),
"",
].join("\n");
}
function assetKey(
asset: Pick<NormalizedAsset, "absoluteUrl" | "requestHeaders">,
): string {
return JSON.stringify([asset.absoluteUrl, asset.requestHeaders]);
}
function byteSourceFrom(bytes: Uint8Array): ByteSource {
const stored = Uint8Array.from(bytes);
return Object.freeze({
@@ -1699,44 +1021,6 @@ function byteSourceFrom(bytes: Uint8Array): ByteSource {
});
}
function markerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(markerRequestUrl(policy), { method: "GET" });
}
function activePointerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(activePointerRequestUrl(policy), { method: "GET" });
}
function markerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/candidate`;
}
function activePointerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/active`;
}
function controlCacheName(policy: PublicCacheRuntimePolicy): string {
return `${policy.ownedCachePrefix}control`;
}
function releaseCacheName(
policy: PublicCacheRuntimePolicy,
releaseRegistryId: string,
manifestDigestHex: string,
): string {
return `${policy.ownedCachePrefix}release:${releaseRegistryId}:${manifestDigestHex}`;
}
function jsonResponse(value: unknown): Response {
return new Response(JSON.stringify(value), {
status: 200,
headers: {
"cache-control": "no-store",
"content-type": "application/json; charset=utf-8",
},
});
}
function summaryFromMarker(
marker: ReleaseMarker,
): PublicCacheReleaseSummary {
@@ -1849,74 +1133,6 @@ function unsupported(
);
}
function validationFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
return error instanceof CacheValidationFailure
? failureForCode(error.code, operation)
: asFailure(browserDataFailure("INVALID_INPUT", operation));
}
function exceptionFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (error instanceof CacheValidationFailure) {
return failureForCode(error.code, operation);
}
const mapped = mapBrowserDataException(error, operation);
if (mapped.ok) {
return asFailure(
browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return mapped;
}
function failureForCode(
code: BrowserDataFailureCode,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (code === "ABORTED") {
return asFailure(browserDataFailure(code, operation));
}
if (code === "INTEGRITY_FAILED" || code === "CORRUPT_DATA") {
return asFailure(
browserDataFailure(code, operation, { recovery: "REHYDRATE" }),
);
}
if (code === "QUOTA_EXCEEDED") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "ONLINE_ONLY",
}),
);
}
if (code === "BLOCKED" || code === "UNAVAILABLE") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return asFailure(browserDataFailure(code, operation));
}
function asFailure(
result: BrowserDataResult<never>,
): BrowserFailureResult {
if (result.ok) {
throw new TypeError("Expected a browser data failure.");
}
return result;
}
function rebaseFailure(
failure: BrowserDataFailure,
operation: BrowserDataOperation,
@@ -1946,41 +1162,3 @@ function observeFailure(
});
return result;
}
async function sha256Hex(
crypto: PublicCacheCryptoFacade,
bytes: Uint8Array,
): Promise<string> {
const digest = await crypto.digestSha256(bytes);
let hex = "";
for (const byte of new Uint8Array(digest)) {
hex += byte.toString(16).padStart(2, "0");
}
return hex;
}
function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new CacheValidationFailure("CORRUPT_DATA");
}
const SHA256_HEX = /^[a-f0-9]{64}$/u;
const ZERO_SHA256 = "0".repeat(64);
const MAX_CONTROL_JSON_BYTES = 2 * 1024 * 1024;
+109
View File
@@ -1151,4 +1151,113 @@ describe("browser download delivery", () => {
await new Promise((resolve) => setTimeout(resolve, 0));
expect(events).toEqual(["abort"]);
});
it("keeps input validation failure codes (Q-6.2-11 characterization)", async () => {
const adapter = (
overrides: Partial<Parameters<typeof createDownloadDeliveryAdapter>[0]> = {},
) =>
createDownloadDeliveryAdapter({
...HARD_LIMITS,
policies,
host: { handoff: vi.fn() },
browserManagedCapabilities: capabilityResolver(
(resourceId) => `/downloads/${resourceId}`,
),
baseOrigin: "https://app.example",
showSaveFilePicker: async () => writableHandle([]),
userActivation: { isActive: true },
...overrides,
});
const code = async (
source: DownloadSource,
strategy: DownloadStrategy,
overrides: Partial<Parameters<typeof createDownloadDeliveryAdapter>[0]> = {},
): Promise<string> => {
const result = await adapter(overrides).deliver(
deliveryInput(source, strategy),
);
return result.ok ? result.value.kind : result.error.code;
};
const generated = (
bytes: FileByteSource = byteSource([new Uint8Array([1])]),
expectedSha256?: string,
): DownloadSource => ({
kind: "GENERATED",
bytes,
...(expectedSha256 === undefined ? {} : { expectedSha256 }),
});
const managed = (resourceId: string): DownloadSource => ({
kind: "BROWSER_MANAGED_RESOURCE",
resourceId,
capabilityReceipt,
});
expect(await code(generated(), "BOUNDED_OBJECT_URL")).toBe(
"BROWSER_HANDOFF",
);
expect(
await code({ kind: "UNKNOWN" } as never, "BOUNDED_OBJECT_URL"),
).toBe("INVALID_INPUT");
expect(
await code(
generated({ byteLength: 1, stream: "no" } as never),
"BOUNDED_OBJECT_URL",
),
).toBe("INVALID_INPUT");
expect(
await code(
generated(byteSource([new Uint8Array([1])], -1)),
"BOUNDED_OBJECT_URL",
),
).toBe("INTEGRITY_FAILED");
expect(
await code(generated(undefined, "not-a-digest"), "BOUNDED_OBJECT_URL"),
).toBe("INVALID_INPUT");
expect(await code(generated(), "BROWSER_MANAGED")).toBe(
"POLICY_REJECTED",
);
expect(await code(managed("artifact-1"), "BOUNDED_OBJECT_URL")).toBe(
"POLICY_REJECTED",
);
expect(await code(managed(""), "BROWSER_MANAGED")).toBe("INVALID_INPUT");
expect(await code(managed("has space"), "BROWSER_MANAGED")).toBe(
"INVALID_INPUT",
);
expect(
await code(generated(), "BOUNDED_OBJECT_URL", {
userActivation: { isActive: false },
}),
).toBe("PERMISSION_DENIED");
expect(
await code(generated(), "BOUNDED_OBJECT_URL", {
filenameMaxUtf8Bytes: 2,
}),
).toBe("INVALID_INPUT");
expect(
await code(generated(), "BOUNDED_OBJECT_URL", {
createTransferId: () => "transfer with space",
}),
).toBe("UNAVAILABLE");
expect(
await code(managed("artifact-1"), "BROWSER_MANAGED", {
browserManagedCapabilities: capabilityResolver(
() => "https://user:secret@app.example/downloads/artifact-1",
),
}),
).toBe("POLICY_REJECTED");
expect(
await code(managed("artifact-1"), "BROWSER_MANAGED", {
browserManagedCapabilities: capabilityResolver(undefined, {
expiresAtEpochMs: 1,
}),
}),
).toBe("EXPIRED_RESOURCE");
expect(
await code(managed("artifact-1"), "BROWSER_MANAGED", {
browserManagedCapabilities: capabilityResolver(undefined, {
mediaType: "text/html",
}),
}),
).toBe("POLICY_REJECTED");
});
});
@@ -0,0 +1,326 @@
import { describe, expect, it } from "vitest";
import type { PublicCacheAsset } from "../../src/application/ports/browser-file-storage/cache-storage-ports.ts";
import { createDefaultPublicCachePolicy } from "../../src/adapters/cache-storage/public-cache-policy.ts";
import { createPublicResponseCacheAdapter } from "../../src/adapters/cache-storage/public-response-cache-adapter.ts";
import {
MemoryCacheStorage,
digestHex,
immediateLock,
manifestFor,
} from "./public-response-cache-fixture.ts";
/**
* Q-6.2-11. Characterization of the manifest codec and response validation
* before they moved out of the adapter: every rejection keeps its code.
*/
const ORIGIN = "https://assets.example.test";
const policy = createDefaultPublicCachePolicy(ORIGIN);
const BYTES = new Uint8Array([1, 2, 3, 4]);
async function asset(
overrides: Partial<PublicCacheAsset> = {},
): Promise<PublicCacheAsset> {
return {
absoluteUrl: `${ORIGIN}/app.js`,
expectedByteLength: BYTES.byteLength,
expectedContentType: "application/javascript",
integrity: { algorithm: "SHA-256", digestHex: await digestHex(BYTES) },
...overrides,
};
}
function adapterWith(
respond: () => Response = () =>
new Response(Uint8Array.from(BYTES), {
headers: {
"cache-control": "public",
"content-type": "application/javascript",
},
}),
cacheStorage = new MemoryCacheStorage(),
) {
return createPublicResponseCacheAdapter({
cacheStorage: cacheStorage as unknown as CacheStorage,
crypto: globalThis.crypto,
mutationLock: immediateLock,
policy,
fetcher: async () => respond(),
});
}
async function stageCode(
assets: readonly PublicCacheAsset[],
respond?: () => Response,
): Promise<string> {
const manifest = {
releaseRegistryId: "codec-release",
assets,
manifestDigestHex: "0".repeat(64),
};
try {
Object.assign(manifest, await manifestFor("codec-release", assets, policy));
} catch {
// An invalid manifest has no digest; staging must still reject it.
}
const result = await adapterWith(respond).admin.stageRelease(manifest);
return result.ok ? "OK" : result.error.code;
}
describe("public cache codec and response validation (characterization)", () => {
it("keeps manifest normalization failure codes", async () => {
const valid = await asset();
expect(await stageCode([])).toBe("LIMIT_EXCEEDED");
expect(await stageCode([valid, valid])).toBe("CONFLICT");
expect(
await stageCode([
await asset({
integrity: { algorithm: "SHA-1" as "SHA-256", digestHex: "0" },
}),
]),
).toBe("INVALID_INPUT");
expect(
await stageCode([await asset({ expectedByteLength: -1 })]),
).toBe("INVALID_INPUT");
for (const absoluteUrl of [
"https://user:secret@assets.example.test/app.js",
"https://other.example.test/app.js",
`${ORIGIN}/app.js#fragment`,
`${ORIGIN}/app.js?token=secret`,
`${ORIGIN}/.well-known/ca-public-cache-v1/candidate`,
]) {
expect(await stageCode([await asset({ absoluteUrl })])).toBe(
"POLICY_REJECTED",
);
}
expect(await stageCode([await asset({ absoluteUrl: "not a url" })])).toBe(
"INVALID_INPUT",
);
expect(
await stageCode([await asset({ expectedContentType: "text/html" })]),
).toBe("POLICY_REJECTED");
expect(
await stageCode([
await asset({ requestHeaders: [["authorization", "Bearer x"]] }),
]),
).toBe("POLICY_REJECTED");
expect(
await stageCode([
await asset({
requestHeaders: [["accept"] as unknown as readonly [string, string]],
}),
]),
).toBe("INVALID_INPUT");
const wrongDigest = await adapterWith().admin.stageRelease({
releaseRegistryId: "codec-release",
assets: [valid],
manifestDigestHex: "0".repeat(64),
});
expect(wrongDigest).toMatchObject({
ok: false,
error: { code: "INTEGRITY_FAILED" },
});
const badRelease = await adapterWith().admin.stageRelease({
...(await manifestFor("codec-release", [valid], policy)),
releaseRegistryId: "bad release id",
});
expect(badRelease).toMatchObject({
ok: false,
error: { code: "INVALID_INPUT" },
});
});
it("keeps response validation failure codes", async () => {
const valid = await asset();
const response = (
headers: Record<string, string>,
body: Uint8Array = BYTES,
init: ResponseInit = {},
) => () =>
new Response(Uint8Array.from(body), {
...init,
headers: {
"cache-control": "public",
"content-type": "application/javascript",
...headers,
},
});
expect(await stageCode([valid], response({}))).toBe("OK");
expect(
await stageCode([valid], response({}, BYTES, { status: 203 })),
).toBe("POLICY_REJECTED");
expect(
await stageCode([valid], response({ "cache-control": "no-store" })),
).toBe("POLICY_REJECTED");
expect(await stageCode([valid], response({ pragma: "no-cache" }))).toBe(
"POLICY_REJECTED",
);
expect(
await stageCode([valid], response({ "www-authenticate": "Basic" })),
).toBe("POLICY_REJECTED");
expect(
await stageCode([valid], response({ "content-type": "text/html" })),
).toBe("POLICY_REJECTED");
expect(
await stageCode([valid], response({ "content-type": "text/css" })),
).toBe("INTEGRITY_FAILED");
expect(await stageCode([valid], response({ vary: "Cookie" }))).toBe(
"POLICY_REJECTED",
);
expect(
await stageCode([valid], response({ "content-length": "99999999999" })),
).toBe("LIMIT_EXCEEDED");
expect(
await stageCode([valid], response({}, new Uint8Array([1, 2, 3, 4, 5]))),
).toBe("INTEGRITY_FAILED");
expect(
await stageCode([valid], response({}, new Uint8Array([1, 2, 3]))),
).toBe("INTEGRITY_FAILED");
expect(
await stageCode([valid], response({}, new Uint8Array([4, 3, 2, 1]))),
).toBe("INTEGRITY_FAILED");
});
it("cancels a pending cached body read when the lookup is aborted", async () => {
const valid = await asset();
const manifest = await manifestFor("codec-release", [valid], policy);
const storage = new MemoryCacheStorage();
const adapter = adapterWith(undefined, storage);
expect(await adapter.admin.stageRelease(manifest)).toMatchObject({
ok: true,
});
expect(
await adapter.admin.activateRelease(
manifest.releaseRegistryId,
manifest.manifestDigestHex,
),
).toMatchObject({ ok: true });
const name = [...storage.caches.keys()].find((key) =>
key.includes(":codec-release:"),
)!;
const cache = storage.caches.get(name)!;
const match = cache.match.bind(cache);
let cancelled = 0;
let pulled: (() => void) | undefined;
const bodyRequested = new Promise<void>((resolve) => {
pulled = resolve;
});
cache.match = async (request: RequestInfo | URL) => {
if (request instanceof Request && request.url === valid.absoluteUrl) {
return new Response(
new ReadableStream<Uint8Array>({
pull() {
pulled?.();
return new Promise<void>(() => {});
},
cancel() {
cancelled += 1;
},
}),
{
headers: {
"cache-control": "public",
"content-type": "application/javascript",
},
},
);
}
return await match(request);
};
const controller = new AbortController();
const lookup = adapter.responses.matchActiveExact({
absoluteUrl: valid.absoluteUrl,
signal: controller.signal,
});
await bodyRequested;
controller.abort();
expect(await lookup).toMatchObject({
ok: false,
error: { code: "ABORTED" },
});
expect(cancelled).toBe(1);
});
it("keeps control JSON decoding failure codes", async () => {
const valid = await asset();
const manifest = await manifestFor("codec-release", [valid], policy);
const lookupAfter = async (
tamper: (storage: MemoryCacheStorage) => Promise<void>,
): Promise<string> => {
const storage = new MemoryCacheStorage();
const adapter = adapterWith(undefined, storage);
expect(await adapter.admin.stageRelease(manifest)).toMatchObject({
ok: true,
});
expect(
await adapter.admin.activateRelease(
manifest.releaseRegistryId,
manifest.manifestDigestHex,
),
).toMatchObject({ ok: true });
await tamper(storage);
const result = await adapter.responses.matchActiveExact({
absoluteUrl: valid.absoluteUrl,
});
return result.ok ? "OK" : result.error.code;
};
const replace = async (
storage: MemoryCacheStorage,
path: "active" | "candidate",
body: BodyInit,
): Promise<void> => {
const name = [...storage.caches.keys()].find((key) =>
path === "active"
? key.endsWith(":control")
: key.includes(":codec-release:"),
)!;
await storage.caches
.get(name)!
.put(
new Request(`${ORIGIN}/.well-known/ca-public-cache-v1/${path}`),
new Response(body, {
headers: { "content-type": "application/json" },
}),
);
};
expect(await lookupAfter(async () => {})).toBe("OK");
expect(
await lookupAfter((storage) => replace(storage, "active", "{not json")),
).toBe("CORRUPT_DATA");
expect(
await lookupAfter((storage) =>
replace(storage, "active", new Uint8Array([0xff, 0xfe])),
),
).toBe("CORRUPT_DATA");
expect(
await lookupAfter((storage) =>
replace(storage, "active", JSON.stringify({ schemaVersion: 2 })),
),
).toBe("CORRUPT_DATA");
expect(
await lookupAfter(async (storage) => {
const name = [...storage.caches.keys()].find((key) =>
key.includes(":codec-release:"),
)!;
const cache = storage.caches.get(name)!;
const marker = await (await cache.match(
new Request(`${ORIGIN}/.well-known/ca-public-cache-v1/candidate`),
))!.json();
await replace(
storage,
"candidate",
JSON.stringify({ ...marker, entryCount: 2 }),
);
}),
).toBe("CORRUPT_DATA");
expect(
await lookupAfter((storage) =>
replace(storage, "candidate", JSON.stringify({ verified: false })),
),
).toBe("CORRUPT_DATA");
});
});