@beam-network/sdk 0.5.21 → 0.6.1

package/dist/models.d.ts

@@ -1,5 +1,21 @@
 export type SignedUrlFlow = "signed_url";
+export interface SdkPerformanceSummary {
+    schema_version: "sdk-performance/v1";
+    measurements: Array<{
+        name: "sdk.discovery" | "sdk.multipart_create" | "sdk.signing" | "sdk.batch_ack" | "sdk.buffer_wait" | "sdk.preparation";
+        count: number;
+        work_ms: number;
+        max_ms: number;
+    }>;
+    counters: {
+        source_signatures: number;
+        source_reuses: number;
+        route_batches: number;
+    };
+}
 export interface BeamClientOptions {
+    /** Best effort, at most one bounded summary per route stream. Never awaited. */
+    onDiagnostics?: (summary: SdkPerformanceSummary) => void | Promise<void>;
     apiKey?: string;
     natsUrl?: string;
     natsWsUrl?: string;
@@ -141,7 +157,34 @@ export interface IntegrityAuditChallenge {
     range_bytes: number;
     chunks: IntegrityAuditChallengeChunk[];
 }
+export interface TransferPerformance {
+    schema_version: "transfer-performance/v1";
+    runtime_epoch: string;
+    coverage: "complete" | "restarted";
+    elapsed_ms: number;
+    /** Work can overlap; these durations must not be summed into elapsed time. */
+    measurements: Record<string, {
+        count: number;
+        work_ms: number;
+        max_ms: number;
+    }>;
+    events: Record<string, {
+        count: number;
+        first_ms: number;
+        last_ms: number;
+    }>;
+    sdk_counters: {
+        source_signatures: number;
+        source_reuses: number;
+        route_batches: number;
+    };
+    detail_dropped: number;
+    unmeasured?: string[];
+    measurement_clocks?: Record<string, "runtime" | "sdk" | "fraud-service">;
+    sdk_report_received?: boolean;
+}
 export interface TransferStatusInfo {
+    performance?: TransferPerformance | null;
     transfer_id: string;
     name?: string;
     status: string;
@@ -179,7 +222,7 @@ export interface ProviderTransferResumeInput extends Omit<ProviderTransferCreate
     multipartGroups: ProviderMultipartGroupIdentity[];
 }
 export interface TransferTerminalEvent {
-    schema_version: "transfer-client-control/v6";
+    schema_version: "transfer-client-control/v7";
     producer: "transfer-runtime";
     transfer_id: string;
     status: "completed" | "failed" | "cancelled";
@@ -377,11 +420,11 @@ export interface CompactTransferPlanDescriptor {
     destinations: CompactTransferPlanDestination[];
     logical_chunk_count: number;
     delivery_route_count: number;
-    multipart_attempt_slots: 3;
+    multipart_attempt_slots: 1;
     formulas: {
         source_offset: "source_chunk_index * chunk_size";
         delivery_index: "chunk_index * destination_count + destination_index";
-        part_number: "source_chunk_index * 3 + attempt_slot + 1";
+        part_number: "source_chunk_index + 1";
         route_generation_id: "initial-{chunk_index}-{destination_id}";
     };
 }

package/dist/multipart-limits.d.ts

@@ -1,4 +1,4 @@
 export declare const MULTIPART_MAX_PART_NUMBER = 10000;
-export declare const MULTIPART_ATTEMPT_SLOT_COUNT = 3;
+export declare const MULTIPART_ATTEMPT_SLOT_COUNT = 1;
 export declare const MULTIPART_MAX_SOURCE_CHUNKS: number;
 export declare function multipartPartNumber(chunkIndex: number, attemptSlot?: number): number;

package/dist/multipart-limits.js

@@ -1,5 +1,5 @@
 export const MULTIPART_MAX_PART_NUMBER = 10_000;
-export const MULTIPART_ATTEMPT_SLOT_COUNT = 3;
+export const MULTIPART_ATTEMPT_SLOT_COUNT = 1;
 export const MULTIPART_MAX_SOURCE_CHUNKS = Math.floor(MULTIPART_MAX_PART_NUMBER / MULTIPART_ATTEMPT_SLOT_COUNT);
 export function multipartPartNumber(chunkIndex, attemptSlot = 0) {
     if (!Number.isInteger(chunkIndex) || chunkIndex < 0) {
@@ -9,8 +9,8 @@ export function multipartPartNumber(chunkIndex, attemptSlot = 0) {
         throw new Error(`source_chunk_index must be less than ${MULTIPART_MAX_SOURCE_CHUNKS}`);
     }
     if (!Number.isInteger(attemptSlot) || attemptSlot < 0 || attemptSlot >= MULTIPART_ATTEMPT_SLOT_COUNT) {
-        throw new Error("attempt_slot must be 0, 1, or 2");
+        throw new Error("attempt_slot must be 0 for consecutive multipart uploads");
     }
-    const partNumber = chunkIndex * MULTIPART_ATTEMPT_SLOT_COUNT + attemptSlot + 1;
+    const partNumber = chunkIndex + 1;
     return partNumber;
 }

package/dist/nats-control.d.ts

@@ -1,12 +1,21 @@
+import type { IntegrityAuditChallenge } from "./models.js";
 import { type ConnectionOptions } from "nats";
 import type { MultipartGroupManifest, SignedChunkRoute, TransferTerminalSignalWaiter } from "./models.js";
-export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v6";
+export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v7";
 export declare const BEAM_DEFAULT_NATS_URL = "tls://orch-gateway.b1m.ai:4222";
 export declare const BEAM_DEFAULT_NATS_WS_URL = "wss://orch-gateway.b1m.ai:443";
 export declare const BEAM_DEFAULT_MAX_PAYLOAD_BYTES: number;
 export declare const BEAM_ROUTE_TARGET_PAYLOAD_BYTES: number;
 export declare const ROUTE_RECOVERY_SIGN_MESSAGE_TYPE: "transfer.route_recovery.sign";
 export interface RouteRecoverySignChunk {
+    recovery?: {
+        operation: "upload" | "controls" | "list" | "delete" | "renew";
+        mode: "staged" | "direct";
+        attempt_id: string;
+        object_key?: string;
+        etag?: string;
+        continuation_token?: string;
+    };
     source_id: string;
     destination_id: string;
     chunk_index: number;
@@ -14,7 +23,7 @@ export interface RouteRecoverySignChunk {
     source_offset: number;
     chunk_size: number;
     logical_attempt_index: number;
-    attempt_slot: 0 | 1 | 2;
+    attempt_slot: 0;
     part_number: number;
     route_generation_id: string;
     multipart_group_id: string;
@@ -129,10 +138,18 @@ export declare class BeamTransferControl {
     private helloTimer;
     constructor(options: TransferControlOptions);
     close(): Promise<void>;
+    serveIntegritySigner(transferId: string, handler: (challenge: IntegrityAuditChallenge) => Promise<Record<string, unknown>>): Promise<() => void>;
     serveRouteRecoverySigner(transferId: string, handler: (payload: RouteRecoverySignRequestPayload) => Promise<RouteRecoverySignReplyPayload>): Promise<() => void>;
     registerRecoveryLease(lease: TransferRecoveryLease): () => void;
-    releaseRecoveryLease(transferId: string): void;
-    continueRecoveryLease(transferId: string): void;
+    /**
+     * Release a transfer's recovery lease, disposing its retained secrets.
+     *
+     * With `owner`, release only when that exact lease is still registered, so a
+     * fenced-off owner can never release a replacement owner's lease.
+     */
+    releaseRecoveryLease(transferId: string, owner?: TransferRecoveryLease): void;
+    /** Request recovery for the registered lease; with `owner`, only if that lease is still registered. */
+    continueRecoveryLease(transferId: string, owner?: TransferRecoveryLease): void;
     request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, options?: LifecycleRequestOptions): Promise<T>;
     openTerminalSignalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
     splitRoutesForPayload(messageType: TransferClientMessageType, basePayload: Record<string, unknown>, routes: SignedChunkRoute[]): SignedChunkRoute[][];

package/dist/nats-control.js

@@ -1,6 +1,6 @@
 import { encode, decode } from "@msgpack/msgpack";
 import { connect } from "nats";
-export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v6";
+export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v7";
 export const BEAM_DEFAULT_NATS_URL = "tls://orch-gateway.b1m.ai:4222";
 export const BEAM_DEFAULT_NATS_WS_URL = "wss://orch-gateway.b1m.ai:443";
 // NATS enforces max_payload per message. This guard splits signed-route control
@@ -60,6 +60,8 @@ export class BeamTransferControl {
     terminalWaitCancellations = new Set();
     routeRecoverySignerCancellations = new Set();
     recoveryLeases = new Map();
+    // Keyed by lease identity: a replacement owner's recovery must never be
+    // coalesced into (and silently dropped behind) a fenced-off owner's loop.
     recoveryOperations = new Map();
     recoveryRequestedEpoch = new Map();
     runtimeEpochs = new Map();
@@ -106,6 +108,58 @@ export class BeamTransferControl {
         if (nc && !nc.isClosed())
             await nc.drain();
     }
+    async serveIntegritySigner(transferId, handler) {
+        const nc = await this.connection();
+        const subject = this.routeRecoverySignSubject(transferId).replace(/route_recovery_sign$/, "integrity_sign");
+        let active = true;
+        let pending = null;
+        let auditId = "";
+        let challengeFingerprint = "";
+        let awaiting = 0;
+        const subscription = nc.subscribe(subject, { callback: (error, message) => {
+                if (!active || error || !message.reply)
+                    return;
+                if (awaiting >= 32) {
+                    message.respond(new TextEncoder().encode('{"retry":true}'));
+                    return;
+                }
+                awaiting++;
+                void (async () => {
+                    try {
+                        const request = JSON.parse(new TextDecoder().decode(message.data));
+                        if (request.schema_version !== TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION || request.capability !== "integrity-signing/v1"
+                            || request.producer !== "transfer-runtime" || request.environment !== this.environment || request.key_prefix !== this.keyPrefix
+                            || request.transfer_id !== transferId || request.challenge?.transfer_id !== transferId || typeof request.request_id !== "string")
+                            throw new Error("integrity_sign_scope_mismatch");
+                        const fingerprint = JSON.stringify(request.challenge);
+                        if (pending && (auditId !== request.challenge.audit_id || challengeFingerprint !== fingerprint))
+                            throw new Error("integrity_sign_conflicting_audit");
+                        if (!pending) {
+                            auditId = request.challenge.audit_id;
+                            challengeFingerprint = fingerprint;
+                            pending = handler(request.challenge).finally(() => { pending = null; });
+                        }
+                        const payload = await pending;
+                        if (active)
+                            message.respond(new TextEncoder().encode(JSON.stringify({ schema_version: TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION,
+                                capability: "integrity-signing/v1", environment: this.environment, key_prefix: this.keyPrefix,
+                                transfer_id: transferId, request_id: request.request_id, payload })));
+                    }
+                    catch {
+                        message.respond(new TextEncoder().encode('{"retry":true}'));
+                    }
+                    finally {
+                        awaiting--;
+                    }
+                })();
+            } });
+        await nc.flush();
+        const stop = () => { if (!active)
+            return; active = false; subscription.unsubscribe(); this.routeRecoverySignerCancellations.delete(stop); };
+        this.routeRecoverySignerCancellations.add(stop);
+        void this.pollRuntimeHello(transferShardId(transferId, this.shardCount));
+        return stop;
+    }
     async serveRouteRecoverySigner(transferId, handler) {
         const nc = await this.connection();
         const subject = this.routeRecoverySignSubject(transferId);
@@ -165,23 +219,20 @@ export class BeamTransferControl {
         this.ensureHelloMonitor();
         const shardId = transferShardId(lease.transferId, this.shardCount);
         void this.pollRuntimeHello(shardId);
-        return () => {
-            const current = this.recoveryLeases.get(lease.transferId);
-            if (current !== lease)
-                return;
-            this.recoveryLeases.delete(lease.transferId);
-            this.recoveryRequestedEpoch.delete(lease.transferId);
-            lease.disposeSecrets?.();
-            if (!this.recoveryLeases.size && this.helloTimer) {
-                clearInterval(this.helloTimer);
-                this.helloTimer = null;
-            }
-        };
+        return () => this.releaseRecoveryLease(lease.transferId, lease);
     }
-    releaseRecoveryLease(transferId) {
+    /**
+     * Release a transfer's recovery lease, disposing its retained secrets.
+     *
+     * With `owner`, release only when that exact lease is still registered, so a
+     * fenced-off owner can never release a replacement owner's lease.
+     */
+    releaseRecoveryLease(transferId, owner) {
         const lease = this.recoveryLeases.get(transferId);
         if (!lease)
             return;
+        if (owner && lease !== owner)
+            return;
         this.recoveryLeases.delete(transferId);
         this.recoveryRequestedEpoch.delete(transferId);
         lease.disposeSecrets?.();
@@ -190,10 +241,13 @@ export class BeamTransferControl {
             this.helloTimer = null;
         }
     }
-    continueRecoveryLease(transferId) {
+    /** Request recovery for the registered lease; with `owner`, only if that lease is still registered. */
+    continueRecoveryLease(transferId, owner) {
         const lease = this.recoveryLeases.get(transferId);
         if (!lease || this.closed)
             return;
+        if (owner && lease !== owner)
+            return;
         const shardId = transferShardId(transferId, this.shardCount);
         const epoch = this.runtimeEpochs.get(shardId);
         this.recoveryRequestedEpoch.set(transferId, epoch ? `${epoch.runtimeEpoch}:${epoch.transportEpoch}` : `foreground:${randomId()}`);
@@ -436,7 +490,12 @@ export class BeamTransferControl {
     }
     async pollRuntimeHello(shardId) {
         try {
-            await this.request("runtime.hello", {}, { idempotencyKey: `runtime:hello:${shardId}`, shardId });
+            try {
+                await this.request("runtime.hello", { capabilities: ["integrity-signing/v1"] }, { idempotencyKey: `runtime:hello:${shardId}:integrity-signing`, shardId });
+            }
+            catch {
+                await this.request("runtime.hello", {}, { idempotencyKey: `runtime:hello:${shardId}`, shardId });
+            }
         }
         catch {
             // Infinite NATS reconnect continues in the background; the next hello reconciles epochs.
@@ -463,13 +522,14 @@ export class BeamTransferControl {
         }
     }
     recoverLease(lease) {
-        const existing = this.recoveryOperations.get(lease.transferId);
+        const existing = this.recoveryOperations.get(lease);
         if (existing)
             return existing;
-        let operation;
-        operation = (async () => {
+        const owns = () => !this.closed && this.recoveryLeases.get(lease.transferId) === lease;
+        let replaced = false;
+        const operation = (async () => {
             let attempt = 0;
-            while (!this.closed && this.recoveryLeases.get(lease.transferId) === lease) {
+            while (owns()) {
                 const requestedEpoch = this.recoveryRequestedEpoch.get(lease.transferId);
                 const routeGenerationId = randomId();
                 try {
@@ -479,39 +539,53 @@ export class BeamTransferControl {
                         coordinate_checksum: lease.coordinateChecksum,
                         route_generation_id: routeGenerationId
                     }, { transferId: lease.transferId, idempotencyKey: `transfer:${lease.transferId}:resume:${routeGenerationId}` });
+                    if (!owns()) {
+                        // A fenced-off owner must neither act on nor release a replacement's lease.
+                        replaced = true;
+                        return;
+                    }
                     if (response.recovery === "terminal") {
-                        this.releaseRecoveryLease(lease.transferId);
-                        if (this.recoveryOperations.get(lease.transferId) === operation) {
-                            this.recoveryOperations.delete(lease.transferId);
-                        }
+                        this.releaseRecoveryLease(lease.transferId, lease);
                         return;
                     }
                     if (response.route_replay_required || response.recovery === "route_replay_required") {
                         await lease.replayRoutes(routeGenerationId);
+                        if (!owns()) {
+                            replaced = true;
+                            return;
+                        }
                     }
                     if (this.recoveryRequestedEpoch.get(lease.transferId) !== requestedEpoch) {
                         attempt = 0;
                         continue;
                     }
-                    if (this.recoveryOperations.get(lease.transferId) === operation) {
-                        this.recoveryOperations.delete(lease.transferId);
-                    }
                     return;
                 }
                 catch (error) {
+                    if (!owns()) {
+                        replaced = true;
+                        return;
+                    }
                     if (!isRetryableLifecycleError(error)) {
-                        this.releaseRecoveryLease(lease.transferId);
+                        this.releaseRecoveryLease(lease.transferId, lease);
                         return;
                     }
                     attempt += 1;
                     await sleepWithJitter(Math.min(30_000, 500 * (2 ** Math.min(attempt, 6))));
                 }
             }
+            replaced = !this.closed;
         })().finally(() => {
-            if (this.recoveryOperations.get(lease.transferId) === operation)
-                this.recoveryOperations.delete(lease.transferId);
+            if (this.recoveryOperations.get(lease) === operation)
+                this.recoveryOperations.delete(lease);
+            if (!replaced || this.closed)
+                return;
+            // The recovery this loop was driving still matters: hand it to the replacement owner.
+            const current = this.recoveryLeases.get(lease.transferId);
+            if (current && current !== lease)
+                void this.recoverLease(current);
         });
-        this.recoveryOperations.set(lease.transferId, operation);
+        this.recoveryOperations.set(lease, operation);
         return operation;
     }
     async resolveAuthToken() {
@@ -604,6 +678,7 @@ const ROUTE_ATTEMPT_METADATA_KEYS = new Set([
     "part_number",
     "logical_attempt_index",
     "attempt_slot",
+    "etag_required",
     "route_generation_id"
 ]);
 const ROUTE_IDENTITY_METADATA_KEYS = [

package/dist/performance.d.ts

@@ -0,0 +1,12 @@
+import type { SdkPerformanceSummary } from './models.js';
+export declare class SdkPerformanceCollector {
+    private readonly measurements;
+    readonly counters: {
+        source_signatures: number;
+        source_reuses: number;
+        route_batches: number;
+    };
+    observe(name: SdkPerformanceSummary['measurements'][number]['name'], milliseconds: number): void;
+    measure<T>(name: SdkPerformanceSummary['measurements'][number]['name'], work: () => Promise<T>): Promise<T>;
+    snapshot(): SdkPerformanceSummary;
+}

package/dist/performance.js

@@ -0,0 +1,25 @@
+export class SdkPerformanceCollector {
+    measurements = new Map();
+    counters = { source_signatures: 0, source_reuses: 0, route_batches: 0 };
+    observe(name, milliseconds) {
+        if (!Number.isFinite(milliseconds) || milliseconds < 0)
+            return;
+        const value = this.measurements.get(name) ?? { count: 0, work_ms: 0, max_ms: 0 };
+        value.count++;
+        value.work_ms += milliseconds;
+        value.max_ms = Math.max(value.max_ms, milliseconds);
+        this.measurements.set(name, value);
+    }
+    async measure(name, work) {
+        const start = performance.now();
+        try {
+            return await work();
+        }
+        finally {
+            this.observe(name, performance.now() - start);
+        }
+    }
+    snapshot() {
+        return { schema_version: 'sdk-performance/v1', measurements: [...this.measurements].map(([name, value]) => ({ name: name, ...value })), counters: { ...this.counters } };
+    }
+}

package/dist/provider-signing.d.ts

@@ -1,5 +1,14 @@
+import type { RouteRecoverySignChunk } from "./nats-control.js";
 import type { ChunkDestinationSigningTarget, ChunkSigningPlanItem, HuggingFaceProviderConfig, PlanningHttpSource, PreparedDestination, PreparedHttpSource, ProviderDestinationConfig, ProviderSourceConfig, R2ProviderConfig, S3CompatibleProviderConfig, S3ProviderConfig, SignedChunkRoute } from "./models.js";
 export type AnyS3CompatibleProviderConfig = S3ProviderConfig | R2ProviderConfig | S3CompatibleProviderConfig;
+/** Core-only grants: the worker receives just the ordinary upload URL. */
+export declare function signMultipartRecovery(input: {
+    destination: ProviderDestinationConfig;
+    transferId: string;
+    requested: RouteRecoverySignChunk;
+    route: SignedChunkRoute;
+    expiresIn: number;
+}): Promise<SignedChunkRoute>;
 export declare function nowIso(): string;
 export declare function expiresAtIso(expiresIn: number): string;
 export declare function prepareProviderSource(source: ProviderSourceConfig, options?: {
@@ -54,7 +63,15 @@ export declare function inspectDestinationObject(destination: ProviderDestinatio
     versionId: string | undefined;
     metadata: Record<string, string>;
 }>;
+export declare function boundedGrantExpiry(url: string, upperBound: string): string;
+export type SourceRouteGrant = {
+    url: string;
+    headers: Record<string, string>;
+    expiresAt: string;
+};
+export declare function signSourceChunk(input: Parameters<typeof signSourceRoute>[0]): Promise<SourceRouteGrant>;
 export declare function signDestinationRoute(input: {
+    sourceGrant?: Promise<SourceRouteGrant>;
     chunk: ChunkSigningPlanItem;
     target: ChunkDestinationSigningTarget;
     source?: ProviderSourceConfig;
@@ -100,6 +117,16 @@ export declare function signDestinationReadRange(input: {
     url: string;
     headers: Record<string, string>;
 }>;
+declare function signSourceRoute(input: {
+    source?: ProviderSourceConfig;
+    fallbackUrl: string;
+    chunk: ChunkSigningPlanItem;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    url: string;
+    headers: Record<string, string>;
+}>;
 export declare function signDestinationUrl(input: {
     contentMd5?: string;
     destination: ProviderDestinationConfig;
@@ -109,8 +136,10 @@ export declare function signDestinationUrl(input: {
     expiresIn: number;
     fetchImpl?: typeof fetch;
 }): Promise<string>;
+export declare function releaseProviderClients(configs: Array<ProviderSourceConfig | ProviderDestinationConfig>): void;
 export declare function isS3CompatibleProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is AnyS3CompatibleProviderConfig;
 export declare function s3CompatibleEndpoint(source: AnyS3CompatibleProviderConfig): string | undefined;
 export declare function s3CompatibleRegion(source: AnyS3CompatibleProviderConfig): string;
 export declare function s3CompatibleForcePathStyle(source: AnyS3CompatibleProviderConfig, endpoint?: string | undefined): boolean | undefined;
 export declare function isHuggingFaceProvider(config: ProviderSourceConfig | ProviderDestinationConfig): config is HuggingFaceProviderConfig;
+export {};

package/dist/provider-signing.js

@@ -1,11 +1,75 @@
 import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, GetObjectCommand, HeadObjectCommand, ListPartsCommand, PutObjectCommand, S3Client, UploadPartCommand } from "@aws-sdk/client-s3";
+import { UploadPartCopyCommand, DeleteObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import { huggingFaceEndpoint, huggingFaceFileMetadata, huggingFaceRepoType, huggingFaceRevision } from "./huggingface.js";
+/** Core-only grants: the worker receives just the ordinary upload URL. */
+export async function signMultipartRecovery(input) {
+    const { requested: r, destination, expiresIn } = input;
+    const request = r.recovery;
+    if (request?.operation === "renew") {
+        const count = Number(input.route.metadata?.expected_part_count);
+        if (!Number.isInteger(count) || count < 1 || count > 10_000)
+            throw new Error("invalid multipart count");
+        const [complete, abort, head, pages] = await Promise.all([
+            signCompleteMultipartUpload(destination, r.final_object_key, r.upload_id, expiresIn),
+            signAbortMultipartUpload(destination, r.final_object_key, r.upload_id, expiresIn),
+            signFinalObjectHead(destination, r.final_object_key, expiresIn),
+            Promise.all(Array.from({ length: Math.ceil(count / 1000) }, (_, i) => signListMultipartUpload(destination, r.final_object_key, r.upload_id, expiresIn, { maxParts: 1000, partNumberMarker: i * 1000 })))
+        ]);
+        return { ...input.route, metadata: { ...input.route.metadata, complete_url: complete, abort_url: abort, final_head_url: head,
+                list_page_urls: pages, list_page_url: pages[Math.floor((r.part_number - 1) / 1000)], control_urls_expires_at: expiresAtIso(expiresIn) } };
+    }
+    if (!request || request.mode === "direct") {
+        const metadata = { ...input.route.metadata };
+        delete metadata.recovery_staging;
+        return { ...input.route, metadata };
+    }
+    if (!isS3CompatibleProvider(destination))
+        throw new Error("multipart recovery requires an S3-compatible destination");
+    const prefix = `${r.final_object_key}.beam-recovery/${input.transferId}/${encodeURIComponent(r.multipart_group_id).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}/`;
+    const objectKey = `${prefix}${r.part_number}/${request.attempt_id}`;
+    if (request.object_key && request.object_key !== objectKey)
+        throw new Error("recovery staging identity mismatch");
+    const client = createS3CompatibleClient(destination);
+    const sign = (command) => {
+        if (command instanceof PutObjectCommand)
+            return getSignedUrl(client, command, { expiresIn });
+        if (command instanceof HeadObjectCommand)
+            return getSignedUrl(client, command, { expiresIn });
+        if (command instanceof UploadPartCopyCommand)
+            return getSignedUrl(client, command, { expiresIn, unhoistableHeaders: new Set(["x-amz-copy-source", "x-amz-copy-source-if-match"]) });
+        if (command instanceof DeleteObjectCommand)
+            return getSignedUrl(client, command, { expiresIn });
+        return getSignedUrl(client, command, { expiresIn });
+    };
+    const metadata = { ...input.route.metadata };
+    delete metadata.recovery_staging;
+    if (request.operation === "list") {
+        metadata.recovery_listing = { prefix, url: await sign(new ListObjectsV2Command({ Bucket: destination.bucket, Prefix: prefix, ContinuationToken: request.continuation_token, MaxKeys: 1000 })) };
+        return { ...input.route, metadata };
+    }
+    const params = { Bucket: destination.bucket, Key: objectKey };
+    if (request.operation === "delete") {
+        metadata.recovery_delete = { object_key: objectKey, url: await sign(new DeleteObjectCommand(params)) };
+        return { ...input.route, metadata };
+    }
+    const copySource = `${encodeURIComponent(destination.bucket)}/${objectKey.split("/").map(encodeURIComponent).join("/")}`;
+    // R2 does not promise to enforce copy source conditions. Each attempt has its own object.
+    const condition = destination.provider === "s3" && request.etag ? `"${request.etag.replace(/^"|"$/g, "")}"` : undefined;
+    const [head, copy, remove] = await Promise.all([
+        sign(new HeadObjectCommand(params)),
+        sign(new UploadPartCopyCommand({ Bucket: destination.bucket, Key: r.final_object_key, UploadId: r.upload_id, PartNumber: r.part_number, CopySource: copySource, CopySourceIfMatch: condition })),
+        sign(new DeleteObjectCommand(params))
+    ]);
+    metadata.recovery_staging = { object_key: objectKey, attempt_id: request.attempt_id, head_url: head, copy_url: copy, delete_url: remove,
+        copy_headers: { "x-amz-copy-source": copySource, ...(condition ? { "x-amz-copy-source-if-match": condition } : {}) }, expires_at: expiresAtIso(expiresIn) };
+    return { ...input.route, metadata, ...(request.operation === "upload" ? { dest_url: await sign(new PutObjectCommand(params)) } : {}) };
+}
 export function nowIso() {
     return new Date().toISOString();
 }
 export function expiresAtIso(expiresIn) {
-    return new Date(Date.now() + expiresIn * 1000).toISOString();
+    return new Date((Math.floor(Date.now() / 1000) + expiresIn) * 1000).toISOString();
 }
 export async function prepareProviderSource(source, options = {}) {
     const index = options.index ?? 0;
@@ -243,11 +307,34 @@ export async function inspectDestinationObject(destination, objectKey, signal) {
     const result = await createS3CompatibleClient(destination).send(new HeadObjectCommand({ Bucket: destination.bucket, Key: objectKey }), { abortSignal: signal });
     return { size: result.ContentLength, etag: result.ETag, versionId: result.VersionId, metadata: result.Metadata ?? {} };
 }
+// Never advertise a renewed lifetime for a previously issued provider URL.
+export function boundedGrantExpiry(url, upperBound) {
+    let expiry = Date.parse(upperBound);
+    const query = new URL(url).searchParams;
+    for (const prefix of ["X-Amz", "X-Goog"]) {
+        const date = query.get(`${prefix}-Date`), duration = Number(query.get(`${prefix}-Expires`));
+        if (date && /^\d{8}T\d{6}Z$/.test(date) && Number.isFinite(duration) && duration > 0) {
+            const start = Date.parse(`${date.slice(0, 4)}-${date.slice(4, 6)}-${date.slice(6, 8)}T${date.slice(9, 11)}:${date.slice(11, 13)}:${date.slice(13, 15)}Z`);
+            if (Number.isFinite(start))
+                expiry = Math.min(expiry, start + duration * 1000);
+        }
+    }
+    const epoch = Number(query.get("Expires"));
+    if (Number.isFinite(epoch) && epoch > 0)
+        expiry = Math.min(expiry, epoch * 1000);
+    return new Date(expiry).toISOString();
+}
+export async function signSourceChunk(input) {
+    const expiresAt = expiresAtIso(input.expiresIn);
+    const grant = await signSourceRoute(input);
+    return { ...grant, expiresAt: boundedGrantExpiry(grant.url, expiresAt) };
+}
 export async function signDestinationRoute(input) {
     const targetObjectKey = input.target.object_key;
     if (!targetObjectKey) {
         throw new Error("destination signing target is missing object_key");
     }
+    const destinationExpiresAt = expiresAtIso(input.expiresIn);
     const [destUrl, sourceRoute] = await Promise.all([
         input.destUrl ?? signDestinationUrl({
             destination: input.destination,
@@ -257,7 +344,7 @@ export async function signDestinationRoute(input) {
             expiresIn: input.expiresIn,
             fetchImpl: input.fetchImpl,
         }),
-        signSourceRoute({
+        input.sourceGrant ?? signSourceChunk({
             source: input.source,
             fallbackUrl: input.chunk.source_url,
             chunk: input.chunk,
@@ -273,8 +360,8 @@ export async function signDestinationRoute(input) {
         dest_url: destUrl,
         source_offset: input.chunk.source_offset,
         chunk_size: input.chunk.chunk_size,
-        expires_at: expiresAtIso(input.expiresIn),
-        headers: sourceRoute.headers,
+        expires_at: boundedGrantExpiry(destUrl, new Date(Math.min(Date.parse(destinationExpiresAt), Date.parse(sourceRoute.expiresAt))).toISOString()),
+        headers: { ...sourceRoute.headers },
         metadata: {
             ...(input.target.metadata ?? {}),
             ...(input.multipartGroupId ? { multipart_group_id: input.multipartGroupId } : {}),
@@ -411,7 +498,16 @@ export async function signDestinationUrl(input) {
     }
     return unsupportedProviderConfig(input.destination);
 }
-const s3ClientCache = new Map();
+const s3ClientCache = new WeakMap();
+export function releaseProviderClients(configs) {
+    for (const config of configs) {
+        if (!isS3CompatibleProvider(config))
+            continue;
+        const cached = s3ClientCache.get(config);
+        s3ClientCache.delete(config);
+        cached?.client.destroy();
+    }
+}
 function s3ClientCacheKey(source, endpoint) {
     return JSON.stringify({
         provider: source.provider,
@@ -425,9 +521,9 @@ function s3ClientCacheKey(source, endpoint) {
 }
 function createS3CompatibleClient(source, endpoint = s3CompatibleEndpoint(source)) {
     const cacheKey = s3ClientCacheKey(source, endpoint);
-    const cached = s3ClientCache.get(cacheKey);
-    if (cached)
-        return cached;
+    const cached = s3ClientCache.get(source);
+    if (cached?.identity === cacheKey)
+        return cached.client;
     const client = new S3Client({
         region: s3CompatibleRegion(source),
         endpoint,
@@ -439,7 +535,7 @@ function createS3CompatibleClient(source, endpoint = s3CompatibleEndpoint(source
             sessionToken: "session_token" in source ? source.session_token : undefined
         }
     });
-    s3ClientCache.set(cacheKey, client);
+    s3ClientCache.set(source, { identity: cacheKey, client });
     return client;
 }
 export function isS3CompatibleProvider(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@beam-network/sdk",
-    "version": "0.5.21",
+    "version": "0.6.1",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",