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>
159 lines
5.0 KiB
TypeScript
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>>;
|
|
}
|