import { describe, expect, it, vi } from "vitest"; import type { BrowserDataObservation } from "../../src/application/ports/browser-file-storage/shared.ts"; import { sha256Hex } from "../../src/adapters/browser-transfer/presigned/incremental-sha256.ts"; import { CHECKSUM_HEADER, CONTROL_ENDPOINT, DOWNLOAD_HREF, POLICY_HEADER, REQUEST_BINDING_SHA256, UPLOAD_SESSION_ID, collect, createHarness, downloadCapabilityPayload, downloadResponse, jsonResponse, responseWithUrl, uploadCapabilityPayload, } from "./presigned-transfer-fixture.ts"; describe("presigned upload part execution", () => { it("snapshots, verifies and uploads a PUT part with a separate response receipt", async () => { const original = new Uint8Array([9, 8, 7]); const checksum = sha256Hex(original); const payload = uploadCapabilityPayload({ bytes: original, checksum, }); let releaseDigest: (() => void) | undefined; const digestGate = new Promise((resolve) => { releaseDigest = resolve; }); const sentBodies: number[][] = []; const dataCalls: RequestInit[] = []; const fetcher = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { if (String(input) === CONTROL_ENDPOINT) return jsonResponse(payload); dataCalls.push(init ?? {}); sentBodies.push([ ...new Uint8Array(init?.body as ArrayBuffer), ]); return responseWithUrl( new Response(null, { status: 200, headers: { [POLICY_HEADER]: "v1", "Content-Length": "0", ETag: "\"part-etag-1\"", }, }), String(payload.href), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher, digestBytes: async (bytes) => { await digestGate; return sha256Hex(bytes); }, }); const issued = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: original.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issued.ok).toBe(true); if (!issued.ok) return; const request = { capability: issued.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: original.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes: original, signal: new AbortController().signal, }; const pending = executor.uploadParts.put(request); original.fill(0); request.sessionId = "mutated-session"; request.requestBindingSha256 = "d".repeat(64); request.checksumSha256 = "f".repeat(64); releaseDigest?.(); expect(await pending).toEqual({ ok: true, value: { bytesWritten: 3, checksumSha256: checksum, receiptToken: "part-etag-1", }, }); expect(sentBodies).toEqual([[9, 8, 7]]); expect(dataCalls[0]).toMatchObject({ method: "PUT", credentials: "omit", redirect: "error", referrerPolicy: "no-referrer", }); expect( (dataCalls[0]?.headers as Headers).get(CHECKSUM_HEADER), ).toBe(checksum); }); it.each(["sessionId", "requestBindingSha256"] as const)( "rejects an actual PUT whose %s differs from the capability", async (field) => { const bytes = new Uint8Array([3, 2, 1]); const checksum = sha256Hex(bytes); const payload = uploadCapabilityPayload({ bytes, checksum }); const fetcher = vi.fn(async () => jsonResponse(payload), ) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher }); const issued = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issued.ok).toBe(true); if (!issued.ok) return; expect( await executor.uploadParts.put({ capability: issued.value, sessionId: field === "sessionId" ? "different-session" : UPLOAD_SESSION_ID, requestBindingSha256: field === "requestBindingSha256" ? "d".repeat(64) : REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, }), ).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" }, }); expect(fetcher).toHaveBeenCalledTimes(1); }, ); it("rejects URL-shaped upload receipts", async () => { const bytes = new Uint8Array([4, 5, 6]); const checksum = sha256Hex(bytes); const payload = uploadCapabilityPayload({ bytes, checksum }); const fetcher = vi.fn(async (input: RequestInfo | URL) => { if (String(input) === CONTROL_ENDPOINT) { return jsonResponse(payload); } return responseWithUrl( new Response(null, { status: 200, headers: { [POLICY_HEADER]: "v1", "Content-Length": "0", ETag: "\"https://objects.example/authorizing-token\"", }, }), String(payload.href), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher }); const issued = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issued.ok).toBe(true); if (!issued.ok) return; expect( await executor.uploadParts.put({ capability: issued.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, }), ).toMatchObject({ ok: false, error: { code: "INTEGRITY_FAILED" }, }); }); it("drains a bounded successful PUT acknowledgement without cancelling it", async () => { const bytes = new Uint8Array([4, 5, 6]); const checksum = sha256Hex(bytes); const payload = uploadCapabilityPayload( { bytes, checksum }, { expectedResponseByteLength: 2 }, ); let cancelled = false; const fetcher = vi.fn(async (input: RequestInfo | URL) => { if (String(input) === CONTROL_ENDPOINT) { return jsonResponse(payload); } const body = new ReadableStream({ start(controller) { controller.enqueue(new Uint8Array([8, 9])); controller.close(); }, cancel() { cancelled = true; }, }); return responseWithUrl( new Response(body, { status: 200, headers: { [POLICY_HEADER]: "v1", "Content-Length": "2", ETag: "\"part-etag-1\"", }, }), String(payload.href), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher }); const issued = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issued.ok).toBe(true); if (!issued.ok) return; expect( await executor.uploadParts.put({ capability: issued.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, }), ).toMatchObject({ ok: true, value: { receiptToken: "part-etag-1" }, }); expect(cancelled).toBe(false); }); it("accepts an empty 204 PUT acknowledgement", async () => { const bytes = new Uint8Array([4, 5, 6]); const checksum = sha256Hex(bytes); const payload = uploadCapabilityPayload( { bytes, checksum }, { expectedStatus: 204, expectedResponseByteLength: 0, }, ); const fetcher = vi.fn(async (input: RequestInfo | URL) => String(input) === CONTROL_ENDPOINT ? jsonResponse(payload) : responseWithUrl( new Response(null, { status: 204, headers: { [POLICY_HEADER]: "v1", ETag: "\"part-etag-204\"", }, }), String(payload.href), ), ) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher }); const issued = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issued.ok).toBe(true); if (!issued.ok) return; expect( await executor.uploadParts.put({ capability: issued.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, }), ).toMatchObject({ ok: true, value: { receiptToken: "part-etag-204" }, }); }); it("cancels a PUT acknowledgement whose declared length violates its binding", async () => { const bytes = new Uint8Array([4, 5, 6]); const checksum = sha256Hex(bytes); const payload = uploadCapabilityPayload({ bytes, checksum }); let cancelled = false; const fetcher = vi.fn(async (input: RequestInfo | URL) => { if (String(input) === CONTROL_ENDPOINT) { return jsonResponse(payload); } const body = new ReadableStream({ pull() {}, cancel() { cancelled = true; }, }); return responseWithUrl( new Response(body, { status: 200, headers: { [POLICY_HEADER]: "v1", "Content-Length": "1", ETag: "\"part-etag-1\"", }, }), String(payload.href), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher }); const issued = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issued.ok).toBe(true); if (!issued.ok) return; expect( await executor.uploadParts.put({ capability: issued.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, }), ).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" }, }); expect(cancelled).toBe(true); }); it("observes only safe operation, outcome, failure and byte buckets", async () => { const bytes = new Uint8Array([7, 8, 9]); const downloadPayload = downloadCapabilityPayload(bytes); const checksum = sha256Hex(bytes); const uploadPayload = uploadCapabilityPayload({ bytes, checksum }); const observations: BrowserDataObservation[] = []; const fetcher = vi.fn( async (input: RequestInfo | URL, init?: RequestInit) => { if (String(input) === CONTROL_ENDPOINT) { const request = JSON.parse(String(init?.body)) as { method: string; }; return jsonResponse( request.method === "GET" ? downloadPayload : uploadPayload, ); } if (String(input) === DOWNLOAD_HREF) { return downloadResponse( bytes.slice().buffer, downloadPayload, ); } return responseWithUrl( new Response(null, { status: 200, headers: { [POLICY_HEADER]: "v1", "Content-Length": "0", ETag: "\"part-etag-secret\"", }, }), String(uploadPayload.href), ); }, ) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher, observer: { record(observation) { observations.push(observation); }, }, }); const issuedDownload = await provider.issueDownload({ resourceId: "resource-1", signal: new AbortController().signal, }); expect(issuedDownload.ok).toBe(true); if (!issuedDownload.ok) return; const opened = await executor.downloadSources.open({ resourceId: "resource-1", capability: issuedDownload.value, signal: new AbortController().signal, }); expect(opened.ok).toBe(true); if (!opened.ok) return; expect((await collect(opened.value)).every((result) => result.ok)).toBe( true, ); const issuedUpload = await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); expect(issuedUpload.ok).toBe(true); if (!issuedUpload.ok) return; expect( await executor.uploadParts.put({ capability: issuedUpload.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, }), ).toMatchObject({ ok: true }); expect(observations).toEqual([ { operation: "PRESIGNED_TRANSFER", outcome: "SUCCEEDED", byteBucket: "LT1MIB", }, { operation: "PRESIGNED_TRANSFER", outcome: "SUCCEEDED", byteBucket: "LT1MIB", }, { operation: "DOWNLOAD", outcome: "SUCCEEDED", byteBucket: "LT1MIB", }, { operation: "PRESIGNED_TRANSFER", outcome: "SUCCEEDED", byteBucket: "LT1MIB", }, // 01-10. A PUT attempt is PRESIGNED_TRANSFER; UPLOAD_PART is the // resumable runtime's one record per part. { operation: "PRESIGNED_TRANSFER", outcome: "SUCCEEDED", byteBucket: "LT1MIB", }, ]); const serialized = JSON.stringify(observations); for (const secret of [ DOWNLOAD_HREF, "do-not-log-this", checksum, "capability-download-1", "capability-upload-1", "part-etag-secret", "resource-1", ]) { expect(serialized).not.toContain(secret); } }); }); /** * R-1.2. The control plane accepts base64url IDs (`[A-Za-z0-9_-]{8,512}`), but * the presigned layer re-checked them with its own grammar and refused IDs that * start with `-`/`_` or exceed 256 characters, so every part issue for such a * session failed as INVALID_INPUT. */ describe("presigned layer accepts every control-plane opaque ID", () => { const controlPlaneIds = [ ["a leading '-'", `-${"aZ09_-".repeat(7)}`], ["a leading '_'", `_${"aZ09_-".repeat(7)}`], ["512 characters", "Q".repeat(512)], ] as const; it.each(controlPlaneIds)( "issues and PUTs an upload part for a session ID with %s", async (_label, sessionId) => { const bytes = new Uint8Array([4, 5, 6]); const checksum = sha256Hex(bytes); const idempotencyKey = `_${sessionId.slice(1, 43)}`; const payload = uploadCapabilityPayload( { bytes, checksum }, { binding: { ...uploadCapabilityPayload({ bytes, checksum }).binding, sessionId, idempotencyKey, }, }, ); const fetcher = vi.fn(async (input: RequestInfo | URL) => { if (String(input) === CONTROL_ENDPOINT) return jsonResponse(payload); return responseWithUrl( new Response(null, { status: 200, headers: { [POLICY_HEADER]: "v1", "Content-Length": "0", ETag: "\"part-etag-1\"", }, }), String(payload.href), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher }); const binding = { sessionId, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey, }; const issued = await provider.issueUploadPart({ ...binding, mediaType: "application/octet-stream", signal: new AbortController().signal, }); expect(issued).toMatchObject({ ok: true }); if (!issued.ok) return; await expect( executor.uploadParts.put({ ...binding, capability: issued.value, bytes, signal: new AbortController().signal, }), ).resolves.toMatchObject({ ok: true }); }, ); it.each(controlPlaneIds)( "issues a download capability for a resource ID with %s", async (_label, resourceId) => { const payload = downloadCapabilityPayload(new Uint8Array([1, 2]), { binding: { kind: "DOWNLOAD", resourceId }, }); const fetcher = vi.fn(async () => jsonResponse(payload), ) as unknown as typeof fetch; const { provider } = createHarness({ fetcher }); await expect( provider.issueDownload({ resourceId, signal: new AbortController().signal, }), ).resolves.toMatchObject({ ok: true }); }, ); }); describe("presigned vault slot release (01-07)", () => { const scenarios = { "the digest does not match": { digest: async () => "f".repeat(64), abortDuringDigest: false, sessionId: UPLOAD_SESSION_ID, code: "INTEGRITY_FAILED", }, "the caller aborts during the digest": { digest: async (bytes: Uint8Array) => sha256Hex(bytes), abortDuringDigest: true, sessionId: UPLOAD_SESSION_ID, code: "ABORTED", }, "the PUT binding check refuses it": { digest: async (bytes: Uint8Array) => sha256Hex(bytes), abortDuringDigest: false, sessionId: "another-session", code: "POLICY_REJECTED", }, } as const; it.each(Object.keys(scenarios) as (keyof typeof scenarios)[])( "frees the only vault slot when %s", async (name) => { const scenario = scenarios[name]; const bytes = new Uint8Array([9, 8, 7]); const checksum = sha256Hex(bytes); let issued = 0; const fetcher = vi.fn(async (input: RequestInfo | URL) => { if (String(input) !== CONTROL_ENDPOINT) { throw new Error("no PUT is expected"); } issued += 1; return jsonResponse( uploadCapabilityPayload( { bytes, checksum }, { capabilityReceipt: `capability-upload-${issued}` }, ), ); }) as unknown as typeof fetch; const controller = new AbortController(); const { provider, executor } = createHarness({ fetcher, maxActiveCapabilities: 1, digestBytes: async (value) => { if (scenario.abortDuringDigest) controller.abort(); return await scenario.digest(value); }, }); const issue = async () => await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); const first = await issue(); if (!first.ok) throw new Error("issue failed"); const put = await executor.uploadParts.put({ capability: first.value, sessionId: scenario.sessionId, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: controller.signal, }); expect(put).toMatchObject({ ok: false, error: { code: scenario.code } }); expect((await issue()).ok).toBe(true); }, ); const earlyExits = { "the caller signal is already aborted": { override: { signal: AbortSignal.abort() }, code: "ABORTED", }, "the byte length does not match the bytes": { override: { byteLength: 4 }, code: "INTEGRITY_FAILED", }, "the input is invalid": { override: { idempotencyKey: "" }, code: "INVALID_INPUT", }, "the signal is not an AbortSignal": { override: { signal: {} as AbortSignal }, code: "INVALID_INPUT", }, } as const; it.each(Object.keys(earlyExits) as (keyof typeof earlyExits)[])( "frees the only vault slot when put() returns early because %s", async (name) => { const bytes = new Uint8Array([9, 8, 7]); const checksum = sha256Hex(bytes); let issued = 0; const fetcher = vi.fn(async (input: RequestInfo | URL) => { if (String(input) !== CONTROL_ENDPOINT) { throw new Error("no PUT is expected"); } issued += 1; return jsonResponse( uploadCapabilityPayload( { bytes, checksum }, { capabilityReceipt: `capability-upload-${issued}` }, ), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher, maxActiveCapabilities: 1, }); const issue = async () => await provider.issueUploadPart({ sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, mediaType: "application/octet-stream", idempotencyKey: "part-attempt-1", signal: new AbortController().signal, }); const first = await issue(); if (!first.ok) throw new Error("issue failed"); const { override, code } = earlyExits[name]; const put = await executor.uploadParts.put({ capability: first.value, sessionId: UPLOAD_SESSION_ID, requestBindingSha256: REQUEST_BINDING_SHA256, uploadBindingSha256: "b".repeat(64), partNumber: 1, offset: 0, byteLength: bytes.byteLength, checksumSha256: checksum, idempotencyKey: "part-attempt-1", bytes, signal: new AbortController().signal, ...override, }); expect(put).toMatchObject({ ok: false, error: { code } }); expect((await issue()).ok).toBe(true); }, ); it.each([ ["the caller signal is already aborted", AbortSignal.abort(), "ABORTED"], ["the signal is not an AbortSignal", {} as AbortSignal, "INVALID_INPUT"], ] as const)( "frees the only vault slot when open() returns early because %s", async (_name, signal, code) => { const bytes = new Uint8Array([1, 2, 3]); let issued = 0; const fetcher = vi.fn(async () => { issued += 1; return jsonResponse( downloadCapabilityPayload(bytes, { capabilityReceipt: `capability-download-${issued}`, }), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher, maxActiveCapabilities: 1, }); const issue = async () => await provider.issueDownload({ resourceId: "resource-1", signal: new AbortController().signal, }); const first = await issue(); if (!first.ok) throw new Error("issue failed"); const opened = await executor.downloadSources.open({ resourceId: "resource-1", capability: first.value, signal, }); expect(opened).toMatchObject({ ok: false, error: { code } }); expect((await issue()).ok).toBe(true); }, ); it("frees the only vault slot when a download open is refused", async () => { const bytes = new Uint8Array([1, 2, 3]); let issued = 0; const fetcher = vi.fn(async () => { issued += 1; return jsonResponse( downloadCapabilityPayload(bytes, { capabilityReceipt: `capability-download-${issued}`, }), ); }) as unknown as typeof fetch; const { provider, executor } = createHarness({ fetcher, maxActiveCapabilities: 1, }); const issue = async () => await provider.issueDownload({ resourceId: "resource-1", signal: new AbortController().signal, }); const first = await issue(); if (!first.ok) throw new Error("issue failed"); const opened = await executor.downloadSources.open({ resourceId: "resource-2", capability: first.value, signal: new AbortController().signal, }); expect(opened).toMatchObject({ ok: false, error: { code: "POLICY_REJECTED" }, }); expect((await issue()).ok).toBe(true); }); });