diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 168ea50b..cb69078e 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -174,6 +174,12 @@ URL을 발급하면 안 된다. 더 빠르면 그 기기에서는 capability가 만료로 보인다. - 만료/403은 임의 retry가 아니라 control plane의 새 capability 발급으로 복구한다. - ambiguous network failure 뒤 upload part를 새 bytes로 덮어쓰지 않는다. +- 실행기는 resolve한 capability를 어떤 경로로 끝나든 vault에서 뺀다. 성공하면 + `consume()`이, 바인딩 거절·만료·replay claim 실패·digest 중단이나 불일치로 + 끝나면 `revoke()`가 뺀다(`presigned-transfer-executor.ts`). 실행기에 닿기 전에 + 버려진 capability(runtime 응답 검증 실패, part 실행기 사전 검사 실패, fail-fast로 + `put()` 전에 멈춘 형제 worker)는 만료까지 `maxActiveCapabilities` 자리를 + 차지하고, 다음 `register()`가 만료 항목을 정리한다. - client-side single-use map은 UX 최적화일 뿐이다. cross-tab/replay authority는 server 또는 composition-owned atomic consumer다. - signed response의 URL, query, raw header와 exception text를 관측성에 남기지 않는다. diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index f71a98cd..0fc2af90 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -105,6 +105,10 @@ export function createPresignedTransferExecutor( ): PresignedTransferExecutor { const resolve = options.vault.resolve.bind(options.vault); const consume = options.vault.consume.bind(options.vault); + // 01-07. A resolved identity that is never consumed is retired on the way + // out, so a refused, expired or aborted transfer does not hold a vault slot + // until its expiry. Idempotent after consume(). + const revoke = options.vault.revoke.bind(options.vault); const claim = options.replayGuard.claim.bind(options.replayGuard); const hardMaxTransferBytes = positiveSafeInteger( options.hardMaxTransferBytes, @@ -184,6 +188,7 @@ export function createPresignedTransferExecutor( capability.binding.resourceId !== resourceId || !validCommonBinding(binding, capability, hardMaxTransferBytes) ) { + revoke(capability); return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER"); } const active = validateExpiry( @@ -191,9 +196,11 @@ export function createPresignedTransferExecutor( minimumRemainingLifetimeMs, now(), ); - if (!active.ok) return active; - const claimed = claim(capability); - if (!claimed.ok) return claimed; + const claimed = active.ok ? claim(capability) : active; + if (!claimed.ok) { + revoke(capability); + return claimed; + } const consumed = consume(capability); if (!consumed.ok) return consumed; @@ -319,6 +326,7 @@ export function createPresignedTransferExecutor( capability.expectedSha256 !== request.checksumSha256 || bytes.byteLength !== capability.byteLength ) { + revoke(capability); return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER"); } // TR-RR-02. The abort scope is created first, so the digest — which can be @@ -414,6 +422,7 @@ export function createPresignedTransferExecutor( return transferFailure(request.signal, scope.timedOut()); } finally { scope.release(); + revoke(capability); } } diff --git a/tests/unit/presigned-transfer-upload.test.ts b/tests/unit/presigned-transfer-upload.test.ts index f6905fe6..6e68313d 100644 --- a/tests/unit/presigned-transfer-upload.test.ts +++ b/tests/unit/presigned-transfer-upload.test.ts @@ -639,3 +639,125 @@ describe("presigned layer accepts every control-plane opaque ID", () => { }, ); }); + +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); + }, + ); + + 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); + }); +});