Files
memento-frontend/src/application/ports/browser-transfer/presigned-transfer.ts
T
DongHyeonkaandClaude Opus 5 cc4e875c2d fix: bound browser transfer leases and effect reporting
BT-X-01: add the shared abortable-operation utility with golden tests for first
terminal owner, idempotent close, listener and timer cleanup under a throwing
scheduler, observed late rejection and late-handle compensation. It carries no
subsystem result taxonomy.

BT-PRE-01: make the presigned download lease lazy and single-start. open() now
validates, claims and consumes the capability without any network I/O; the
fetch, the transfer deadline and the expiry recheck happen at first stream
consumption. The source gained close(), which discards an unused lease with no
I/O and otherwise cancels the body and releases the scope exactly once.

BT-UP-01: require removeEventListener in the AbortSignal structural guard and
isolate release cleanup so a hostile facade cannot replace a typed terminal
result with a rejection.

BT-UP-03: deleteDatabase cannot be cancelled after dispatch, so a blocked
deadline now returns PENDING with effect UNKNOWN instead of a failure that reads
as NOT_APPLIED. A realm-scoped (factory, databaseName) registry prevents
recreating the partition until the native request settles.

BT-UP-04: reject non-finite and negative upload clocks as a dependency failure
instead of letting them bypass every capability expiry comparison.

BT-IMG-02: replace the naive Cache-Control quote stripping with a quote- and
escape-aware tokenizer, so max-age="60 or 60" is no longer read as 60 and a
comma inside a quoted extension is not a directive boundary.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 00:13:54 +09:00

159 lines
5.0 KiB
TypeScript

import type { FileByteSource } from "../browser-file-storage/file.ts";
import type { BrowserDataResult } from "../browser-file-storage/shared.ts";
import type {
AuthorizedDownloadCapability,
AuthorizedDownloadCapabilityReceipt,
} from "./authorized-download.ts";
import type { ResumableUploadProtocol } from "./resumable-upload.ts";
declare const presignedTransferCapabilityBrand: unique symbol;
/**
* Server-issued, telemetry-safe identifier. It is not a URL, credential,
* object-store key or authorization token.
*/
export type PresignedTransferCapabilityReceipt =
AuthorizedDownloadCapabilityReceipt;
export type PresignedTransferMethod = "GET" | "PUT";
export type PresignedTransferBinding =
| Readonly<{
kind: "DOWNLOAD";
resourceId: string;
}>
| Readonly<{
kind: "UPLOAD_PART";
protocol: ResumableUploadProtocol;
sessionId: string;
requestBindingSha256: string;
/**
* SHA-256 over the canonical session, request and whole-file fingerprint
* binding. The raw session fields remain owned by the upload control
* plane; they must never be smuggled into resourceId.
*/
uploadBindingSha256: string;
partNumber: number;
offset: number;
idempotencyKey: string;
}>;
/**
* Opaque capability handle crossing the application boundary. The adapter owns
* the corresponding URL, query values and request headers in an in-memory
* identity vault. Implementations must reject structurally equal or fabricated
* handles, even if every visible field matches.
*/
export type PresignedDownloadCapability = AuthorizedDownloadCapability;
export type PresignedUploadPartCapability = Readonly<{
capabilityReceipt: PresignedTransferCapabilityReceipt;
method: "PUT";
binding: Extract<
PresignedTransferBinding,
Readonly<{ kind: "UPLOAD_PART" }>
>;
mediaType: string;
byteLength: number;
maxBytes: number;
expectedSha256: string;
expiresAtEpochMs: number;
readonly [presignedTransferCapabilityBrand]:
"PresignedTransferCapability";
}>;
export type PresignedTransferCapability =
| PresignedDownloadCapability
| PresignedUploadPartCapability;
export interface PresignedTransferCapabilityProvider {
/**
* Calls a composition-owned backend/BFF capability endpoint. Callers choose
* only an opaque resource ID; they cannot supply a transfer URL or headers.
*/
issueDownload(input: Readonly<{
resourceId: string;
signal: AbortSignal;
}>): Promise<BrowserDataResult<PresignedDownloadCapability>>;
}
export interface PresignedUploadPartCapabilityProvider {
issueUploadPart(input: Readonly<{
sessionId: string;
requestBindingSha256: string;
uploadBindingSha256: string;
partNumber: number;
offset: number;
byteLength: number;
checksumSha256: string;
mediaType: string;
idempotencyKey: string;
signal: AbortSignal;
}>): Promise<BrowserDataResult<PresignedUploadPartCapability>>;
}
/**
* Atomic local replay seam. The server/object-store capability must also
* enforce single use or equivalent idempotency because a browser guard is not
* an authorization boundary.
*/
export interface PresignedTransferReplayGuard {
claim(
capability: PresignedTransferCapability,
): BrowserDataResult<true>;
}
/**
* Successful exhaustion proves length and SHA-256 before the terminal success
* of the closed-Result stream. Consumers must not commit a destination until
* the iterable finishes without a failure result.
*/
export type PresignedDownloadByteSource = FileByteSource &
Readonly<{
byteLength: number;
capability: PresignedDownloadCapability;
integrity: "VERIFIED_ON_SUCCESSFUL_EXHAUSTION";
/**
* BT-PRE-01. Discards the lease. Before the first `stream()` this performs
* no network I/O at all; during streaming it cancels the body and releases
* the timer and listeners exactly once. Every consumer must call it in a
* `finally`, including on a pre-stream failure.
*/
close(): void;
}>;
export interface PresignedDownloadSourcePort {
open(input: Readonly<{
resourceId: string;
capability: PresignedDownloadCapability;
signal: AbortSignal;
}>): Promise<BrowserDataResult<PresignedDownloadByteSource>>;
}
export type PresignedUploadPartOutcome = Readonly<{
bytesWritten: number;
checksumSha256: string;
/**
* Non-authorizing object-store acknowledgement (for example a normalized
* ETag). It is safe to persist only as part of the exact completed-part
* binding and must never be reused as a transfer capability.
*/
receiptToken: string;
}>;
export interface PresignedUploadPartPort {
put(input: Readonly<{
capability: PresignedUploadPartCapability;
sessionId: string;
requestBindingSha256: string;
uploadBindingSha256: string;
partNumber: number;
offset: number;
byteLength: number;
checksumSha256: string;
idempotencyKey: string;
bytes: Uint8Array;
signal: AbortSignal;
}>): Promise<BrowserDataResult<PresignedUploadPartOutcome>>;
}