From 4093ee8fc2e39f106b232d53b14be344742ec134 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:34:28 +0900 Subject: [PATCH] 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 --- .../adapters/03-storage-and-browser-files.md | 3 + docs/reviews/adapters/INVENTORY.md | 267 +++--- .../download-delivery-adapter.ts | 358 +------ .../download-input-validation.ts | 374 ++++++++ .../cache-storage/public-cache-codec.ts | 656 +++++++++++++ .../public-cache-response-validation.ts | 239 +++++ .../public-response-cache-adapter.ts | 886 +----------------- tests/unit/browser-file-download.test.ts | 109 +++ .../unit/public-response-cache-codec.test.ts | 326 +++++++ 9 files changed, 1886 insertions(+), 1332 deletions(-) create mode 100644 src/adapters/browser-files/download-input-validation.ts create mode 100644 src/adapters/cache-storage/public-cache-codec.ts create mode 100644 src/adapters/cache-storage/public-cache-response-validation.ts create mode 100644 tests/unit/public-response-cache-codec.test.ts diff --git a/docs/reviews/adapters/03-storage-and-browser-files.md b/docs/reviews/adapters/03-storage-and-browser-files.md index 6d9959ae..93fb3d38 100644 --- a/docs/reviews/adapters/03-storage-and-browser-files.md +++ b/docs/reviews/adapters/03-storage-and-browser-files.md @@ -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 diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index 1b27c303..353b23f4 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -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를 같은 변경에서 갱신한다. diff --git a/src/adapters/browser-files/download-delivery-adapter.ts b/src/adapters/browser-files/download-delivery-adapter.ts index 04159ca3..55e0505b 100644 --- a/src/adapters/browser-files/download-delivery-adapter.ts +++ b/src/adapters/browser-files/download-delivery-adapter.ts @@ -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[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 { - 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 { - 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 - * `` 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 { - 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( if (raced.kind === "REJECTED") throw raced.reason; throw abortException(); } - -function isPositiveByteLimit(value: number): boolean { - return isValidByteLength(value) && value > 0; -} diff --git a/src/adapters/browser-files/download-input-validation.ts b/src/adapters/browser-files/download-input-validation.ts new file mode 100644 index 00000000..8b5ff3bf --- /dev/null +++ b/src/adapters/browser-files/download-input-validation.ts @@ -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[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 { + 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 { + 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 + * `` 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 { + 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; +} diff --git a/src/adapters/cache-storage/public-cache-codec.ts b/src/adapters/cache-storage/public-cache-codec.ts new file mode 100644 index 00000000..6482c0f3 --- /dev/null +++ b/src/adapters/cache-storage/public-cache-codec.ts @@ -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; +}>; + +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 { + 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(); + 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 { + 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, + 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; + 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, +): 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, +): BrowserFailureResult { + if (result.ok) { + throw new TypeError("Expected a browser data failure."); + } + return result; +} + +export async function sha256Hex( + crypto: PublicCacheCryptoFacade, + bytes: Uint8Array, +): Promise { + 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; + 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; diff --git a/src/adapters/cache-storage/public-cache-response-validation.ts b/src/adapters/cache-storage/public-cache-response-validation.ts new file mode 100644 index 00000000..383081c0 --- /dev/null +++ b/src/adapters/cache-storage/public-cache-response-validation.ts @@ -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> { + 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 { + 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(); + 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, + }); +} diff --git a/src/adapters/cache-storage/public-response-cache-adapter.ts b/src/adapters/cache-storage/public-response-cache-adapter.ts index 160d5f6d..26fc4450 100644 --- a/src/adapters/cache-storage/public-response-cache-adapter.ts +++ b/src/adapters/cache-storage/public-response-cache-adapter.ts @@ -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( @@ -60,10 +88,6 @@ type PublicCacheStorageFacade = Readonly<{ delete(name: string): Promise; }>; -type PublicCacheCryptoFacade = Readonly<{ - digestSha256(bytes: Uint8Array): Promise; -}>; - type PublicResponseCacheDependencySnapshot = Readonly<{ cacheStorage?: PublicCacheStorageFacade; fetcher?: (request: Request) => Promise; @@ -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; }>; -type BrowserFailureResult = Readonly<{ - ok: false; - error: BrowserDataFailure; -}>; - -type CacheReadResult = Readonly<{ - bytes: Uint8Array; - headers: readonly PublicCacheHeader[]; -}>; - type LockManagerLike = { request( name: string, @@ -134,16 +114,6 @@ type LockManagerLike = { ): Promise; }; -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 { - 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(); - 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> { - 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 { - 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(); - 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 { - 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, - 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; - 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, -): 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, -): 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 { - 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; - 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; diff --git a/tests/unit/browser-file-download.test.ts b/tests/unit/browser-file-download.test.ts index 5a538c12..933bb36b 100644 --- a/tests/unit/browser-file-download.test.ts +++ b/tests/unit/browser-file-download.test.ts @@ -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[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[0]> = {}, + ): Promise => { + 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"); + }); }); diff --git a/tests/unit/public-response-cache-codec.test.ts b/tests/unit/public-response-cache-codec.test.ts new file mode 100644 index 00000000..5d5d8573 --- /dev/null +++ b/tests/unit/public-response-cache-codec.test.ts @@ -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 = {}, +): Promise { + 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 { + 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, + 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((resolve) => { + pulled = resolve; + }); + cache.match = async (request: RequestInfo | URL) => { + if (request instanceof Request && request.url === valid.absoluteUrl) { + return new Response( + new ReadableStream({ + pull() { + pulled?.(); + return new Promise(() => {}); + }, + 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, + ): Promise => { + 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 => { + 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"); + }); +});