@beam-network/sdk 0.6.0 → 0.6.1

package/README.md

@@ -156,19 +156,19 @@ For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport
 
 Provider transfers use `transfer-client-control/v7`. Every reply carries Runtime and transport epochs; prepare and every route-stream message carry a UUID route generation. S3, R2, and S3-compatible destinations retain direct multipart UploadPart/ListParts/HEAD handling. Hippius and Hugging Face destinations take a plain PUT per chunk instead, so they carry no multipart group manifest.
 
-The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches. Encoded MessagePack requests target 4 MiB physical batches under `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. Lifecycle control refreshes cached SDK auth before the final 30 seconds of token lifetime and retries `auth_token_expired` replies with the same request identity and payload but a fresh token, preserving Core request-conflict protection during large route streams. A single route above the 4 MiB target but within the configured guard publishes alone; a single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
+The client signs up to 64 routes concurrently by default and emits 1,024-route logical batches. Encoded MessagePack requests target 4 MiB physical batches under `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. Lifecycle control refreshes cached SDK auth before the final 30 seconds of token lifetime and retries `auth_token_expired` replies with the same request identity and payload but a fresh token, preserving Core request-conflict protection during large route streams. A single route above the 4 MiB target but within the configured guard publishes alone; a single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
 
 Callers that need durable recovery accounting can provide `onMultipartGroupReady`. The SDK invokes it after creating a multipart upload and before streaming that group’s signed routes. Its payload contains transfer, source, destination, object-key, upload, size, part-count, and expiry identities only; it never includes credentials, request headers, or signed URLs. A rejected callback aborts the newly created upload and fails preparation closed.
 
 `resumeProviderTransfer` requires the complete saved callback payloads in `multipartGroups`. It validates every transfer/source/destination/object/size/part coordinate, then uses the same route-stream implementation as creation with those upload IDs. Missing, duplicate, or changed identities fail before new provider uploads or route publication. If a process died before recording an upload identity, treat it as uncertain cleanup instead of inventing a replacement. The `onPrepared` callback also runs during resume, before routes are streamed.
 
-Create and resume accept an ownership `signal`. Aborting it stops initial routes, multipart creation, and recovery signing/replay; it does not cancel the transfer or abort a replacement owner's uploads. User cancellation still uses `cancelTransfer` and verified provider cleanup. `prepareProviderSource` accepts the same signal for metadata requests.
+Create and resume accept an ownership `signal`. Aborting it stops initial routes, multipart creation, and recovery signing/replay; it does not cancel the transfer or abort a replacement owner's uploads. Recovery leases, signers, and background resume/replay are keyed by owner identity: a fenced-off owner never replays into, releases, or stops the signers of a replacement owner registered for the same transfer, and a replacement always gets its own recovery. User cancellation still uses `cancelTransfer` and verified provider cleanup. `prepareProviderSource` accepts the same signal for metadata requests.
 
 The stream ID derives from the transfer, selected flow, and immutable plan identity, and each ordered batch ID includes its route-coordinate checksum. Manual multi-destination attachment requires `delivery_index` on every route. Lifecycle mutations retry transient failures up to three times with the same request identity. A non-recoverable provider setup or route failure raises `BeamProviderTransferError`, whose `errors`, `transferCancelled`, and `multipartCleanupComplete` fields retain the original provider, cancellation, and cleanup outcomes. `waitForTransfer` subscribes to the API-key-owned, at-most-once terminal signal before its first status read and reconciles every signal through authoritative status; subscription failure degrades to the same jittered 15-to-30-second status fallback. Call `close()` when the client is no longer needed; it also closes outstanding terminal waiters.
 
 During the pre-completion `integrity_check` phase, Runtime may include an `integrity_audit_challenge` in status. The TypeScript client signs exact read-only source and final-destination GET ranges and submits `transfer.integrity_audit_grants`. S3-compatible source and destination grants use the prepared source ETag and Runtime-verified final-object ETag as `If-Match` conditions. Submission failures retry on the next status poll and appear as a URL-safe `integrity_audit_submission_error` on that status response; the transfer completes with a warning if the check cannot finish by its deadline.
 
-Hippius uses canonical non-multipart `signed_url` routes, so its manifest is empty and group-level final HEAD verification is not available from that provider flow.
+Hippius uses canonical non-multipart `signed_url` routes (initial and recovered routes both PUT to the planned `<final>/<plan_nonce>/chunk-NNNNNN` key), so its manifest is empty and group-level final HEAD verification is not available from that provider flow.
 
 NATS requires this guard because the broker rejects messages above its configured `max_payload`. This limit applies only to lifecycle/control metadata; transfer file bytes do not flow through NATS.
 
@@ -189,3 +189,9 @@ Only short-lived range/upload routes go to workers. Multipart creation, verifica
 Manual releases from `dev` require a committed `-dev.N` version and publish only to npm tag `dev`; the stable tag is unchanged.
 
 Multipart control helpers (`createMultipartUpload`, `listMultipartParts`, `completeMultipartUpload`, `inspectDestinationObject`, and `abortMultipartUpload`) accept an optional `AbortSignal` and cancel through the existing provider HTTP transport. Pass it as `signal` in object arguments or as the last positional argument. Cancellation stops waiting and network activity; it cannot undo a provider operation already accepted. After an interrupted completion, inspect the durable upload/object identity before retrying or reporting cleanup complete.
+
+### Preparation diagnostics
+
+Route streaming flushes at 1,024 routes, with no timer, and sends the final partial batch at stream completion. Signing overlaps acknowledged publication through bounded buffering; existing encoded-payload limits still apply. A source grant is reused across destinations only within the same signing generation and actual expiry.
+
+The optional `onDiagnostics` callback receives bounded preparation measurements and source-grant reuse counts. Callbacks are best effort, may be dropped under load, and do not affect transfer outcomes. Durations may overlap; do not sum them into elapsed transfer time. Transfer status also exposes a typed `performance` summary when supported by Core.

package/dist/client.d.ts

@@ -44,8 +44,11 @@ export declare class BeamClient {
     private readonly routeSigningConcurrency;
     private readonly routeSigningConcurrencyOverridden;
     private readonly multipartControlConcurrency;
+    private readonly onDiagnostics;
+    private diagnosticPending;
     private readonly recoverySigners;
     private readonly integrityAuditSigners;
+    private readonly integrityGrantCache;
     private readonly integrityAuditSubmissions;
     private readonly huggingFaceUploads;
     constructor(options?: BeamClientOptions);
@@ -105,7 +108,9 @@ export declare class BeamClient {
     private startProviderRouteRecoverySigner;
     private recoveryMultipartUploadState;
     private submitIntegrityAuditGrantsIfPresent;
-    private submitProviderIntegrityAuditGrants;
+    private signedIntegrityGrants;
+    private buildProviderIntegrityAuditGrants;
+    /** Stop a transfer's recovery and integrity signers; with `owner`, only if that owner installed them. */
     private stopRecoverySigner;
     private stopAllRecoverySigners;
     createAndDistribute(input: RawTransferCreateInput): Promise<TransferCreateResponse>;

package/dist/client.js

@@ -1,4 +1,5 @@
-import { signMultipartRecovery, abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationReadRange, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signSourceReadRange, isHuggingFaceProvider } from "./provider-signing.js";
+import { SdkPerformanceCollector } from "./performance.js";
+import { signMultipartRecovery, abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, releaseProviderClients, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationReadRange, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signSourceReadRange, signSourceChunk, boundedGrantExpiry, isHuggingFaceProvider } from "./provider-signing.js";
 import { describe as describeHuggingFace, hashSourceStream, huggingFaceCommit, huggingFaceCompleteLfsUpload, huggingFaceLfsBatch, huggingFacePreupload, huggingFaceVerifyLfsUpload, readSourceSample } from "./huggingface.js";
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes, isRecoverableRouteStreamError } from "./nats-control.js";
 export class BeamRouteRecoveryPendingError extends Error {
@@ -53,11 +54,15 @@ export class BeamClient {
     routeSigningConcurrency;
     routeSigningConcurrencyOverridden;
     multipartControlConcurrency;
+    onDiagnostics;
+    diagnosticPending = false;
     recoverySigners = new Map();
     integrityAuditSigners = new Map();
+    integrityGrantCache = new Map();
     integrityAuditSubmissions = new Map();
     huggingFaceUploads = new Map();
     constructor(options = {}) {
+        this.onDiagnostics = options.onDiagnostics;
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
         }
@@ -237,7 +242,7 @@ export class BeamClient {
         };
         const routeStreamLock = new AsyncMutex();
         const releaseInitialStream = await routeStreamLock.acquire();
-        this.control.registerRecoveryLease({
+        const recoveryLease = {
             transferId,
             planFingerprint: input.planFingerprint,
             coordinateChecksum: input.coordinateChecksum,
@@ -249,19 +254,20 @@ export class BeamClient {
                         throw new Error(attached.error ?? attached.message ?? "route replay failed");
                 });
             }
-        });
+        };
+        this.control.registerRecoveryLease(recoveryLease);
         try {
             const attached = await streamRoutes(input.chunkRoutes, input.multipartGroupManifest, input.routeGenerationId, input.urlsExpiresAt);
             if (!attached.success)
-                this.control.releaseRecoveryLease(transferId);
+                this.control.releaseRecoveryLease(transferId, recoveryLease);
             return attached;
         }
         catch (error) {
             if (isRecoverableRouteStreamError(error)) {
-                this.control.continueRecoveryLease(transferId);
+                this.control.continueRecoveryLease(transferId, recoveryLease);
                 throw new BeamRouteRecoveryPendingError(transferId, error);
             }
-            this.control.releaseRecoveryLease(transferId);
+            this.control.releaseRecoveryLease(transferId, recoveryLease);
             throw error;
         }
         finally {
@@ -294,8 +300,10 @@ export class BeamClient {
             destinationsById.set(preparedDestination.destination_id, destination);
         });
         await input.throwIfCancelled?.();
+        const discoveryStarted = performance.now();
         const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl, signal: input.signal })));
         await input.throwIfCancelled?.();
+        const discoveryMs = performance.now() - discoveryStarted;
         const huggingFace = await this.planHuggingFaceUploads({
             sources: retainedRecoveryInput.sources,
             preparedSources,
@@ -346,6 +354,9 @@ export class BeamClient {
         const routeStreamLock = new AsyncMutex();
         const releaseInitialStream = await routeStreamLock.acquire();
         const streamPreparedRoutes = async (routeGenerationId, recoveryReplay) => {
+            const telemetry = new SdkPerformanceCollector();
+            if (!recoveryReplay)
+                telemetry.observe("sdk.discovery", discoveryMs);
             const pendingRoutes = new Set();
             let signingConcurrency = this.routeSigningConcurrency;
             let signedInWindow = 0;
@@ -376,6 +387,15 @@ export class BeamClient {
                     signedUrlFlow: requestedSignedUrlFlow
                 });
                 routeStream = new RouteStreamSender(this.control, {
+                    telemetry,
+                    onDiagnostics: (summary) => {
+                        if (!this.onDiagnostics || this.diagnosticPending)
+                            return;
+                        this.diagnosticPending = true;
+                        setTimeout(() => {
+                            void Promise.resolve().then(() => this.onDiagnostics?.(summary)).catch(() => { }).finally(() => { this.diagnosticPending = false; });
+                        }, 0);
+                    },
                     streamId,
                     transferId: prepared.transfer_id,
                     routeGenerationId,
@@ -388,7 +408,7 @@ export class BeamClient {
                 routeStreamBeginAttempted = true;
                 await routeStream.begin();
                 multipartGroupWaiters = createMultipartGroupWaiters(prepared, destinationsById);
-                multipartManifestTask = createMultipartGroupManifest({
+                multipartManifestTask = telemetry.measure("sdk.multipart_create", () => createMultipartGroupManifest({
                     prepared,
                     destinationsById,
                     multipartUploads,
@@ -405,7 +425,7 @@ export class BeamClient {
                         multipartGroupWaiters.get(state.manifest.multipart_group_id)?.resolve(state);
                     },
                     onGroupFailed: (groupId, error) => multipartGroupWaiters.get(groupId)?.reject(error)
-                });
+                }));
                 const streamNextCompletedRoute = async () => {
                     const settled = await Promise.race([...pendingRoutes].map((pending) => pending.then((route) => ({ pending, route }))));
                     pendingRoutes.delete(settled.pending);
@@ -423,6 +443,12 @@ export class BeamClient {
                 };
                 for (const chunk of materializePlanChunks(prepared.plan_descriptor, prepared.transfer_id)) {
                     await throwIfCancelled?.(prepared.transfer_id);
+                    // This promise belongs to this chunk and signing generation only. Its
+                    // immutable credential/range identity and actual expiry cannot be renewed.
+                    const sourceGrant = signSourceChunk({ source: sourcesById.get(chunk.source_id), fallbackUrl: chunk.source_url, chunk, expiresIn, fetchImpl: this.fetchImpl });
+                    void sourceGrant.catch(() => { });
+                    telemetry.counters.source_signatures++;
+                    telemetry.counters.source_reuses += Math.max(0, chunk.destinations.length - 1);
                     for (const target of chunk.destinations) {
                         const pendingRoute = (async () => {
                             await throwIfCancelled?.(prepared.transfer_id);
@@ -442,10 +468,11 @@ export class BeamClient {
                                 : await multipartGroupWaiters.get(multipartGroupId)?.promise;
                             if (!isDirectPutDestination(destination) && !upload)
                                 throw new Error(`multipart group manifest is missing for ${chunk.source_id}:${target.destination_id}`);
-                            return this.signProviderRoute({
+                            return telemetry.measure("sdk.signing", () => this.signProviderRoute({
                                 chunk,
                                 target,
                                 source,
+                                sourceGrant,
                                 destination,
                                 expiresIn,
                                 ...(upload ? { upload } : {}),
@@ -456,7 +483,7 @@ export class BeamClient {
                                 partNumber: typeof metadata.part_number === "number"
                                     ? metadata.part_number
                                     : multipartPartNumber(chunk.source_chunk_index),
-                            });
+                            }));
                         })();
                         pendingRoutes.add(pendingRoute);
                         if (pendingRoutes.size >= signingConcurrency)
@@ -475,8 +502,8 @@ export class BeamClient {
             }
             catch (error) {
                 if (input.signal?.aborted) {
-                    this.stopRecoverySigner(prepared.transfer_id);
-                    this.control.releaseRecoveryLease(prepared.transfer_id);
+                    this.stopRecoverySigner(prepared.transfer_id, recoveryLease);
+                    this.control.releaseRecoveryLease(prepared.transfer_id, recoveryLease);
                     await Promise.allSettled(pendingRoutes);
                     if (multipartManifestTask)
                         await Promise.allSettled([multipartManifestTask]);
@@ -489,10 +516,10 @@ export class BeamClient {
                     await Promise.allSettled([multipartManifestTask]);
                 if (!recoveryReplay) {
                     if (foregroundCancelled) {
-                        this.control.continueRecoveryLease(prepared.transfer_id);
+                        this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                     }
                     else if (isRecoverableRouteStreamError(error)) {
-                        this.control.continueRecoveryLease(prepared.transfer_id);
+                        this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                         throw new BeamRouteRecoveryPendingError(prepared.transfer_id, error);
                     }
                     else {
@@ -510,27 +537,16 @@ export class BeamClient {
                             // The retained recovery input owns the same destination objects used by
                             // multipart cleanup. Releasing it earlier scrubs their scoped credentials
                             // before abortMultipartUpload can clean up already-created uploads.
-                            this.control.releaseRecoveryLease(prepared.transfer_id);
+                            this.control.releaseRecoveryLease(prepared.transfer_id, recoveryLease);
                         }
                     }
                 }
                 throw error;
             }
         };
-        await this.startProviderRouteRecoverySigner({
-            prepared,
-            sourcesById,
-            destinationsById,
-            multipartUploads: recoveryMultipartUploads,
-            signal: input.signal,
-            expiresIn
-        });
-        const stopOwnedRecovery = () => {
-            this.stopRecoverySigner(prepared.transfer_id);
-            this.control.releaseRecoveryLease(prepared.transfer_id);
-        };
-        input.signal?.addEventListener("abort", stopOwnedRecovery, { once: true });
-        this.control.registerRecoveryLease({
+        // The lease object is this owner's identity: releases, recovery requests, and
+        // signer shutdowns below only act while it is still the registered lease.
+        const recoveryLease = {
             transferId: prepared.transfer_id,
             planFingerprint: prepared.plan_fingerprint,
             coordinateChecksum: prepared.coordinate_checksum,
@@ -539,23 +555,39 @@ export class BeamClient {
             },
             disposeSecrets: () => {
                 input.signal?.removeEventListener("abort", stopOwnedRecovery);
+                releaseProviderClients([...retainedRecoveryInput.sources, ...retainedRecoveryInput.destinations]);
                 clearRecoverySecrets(retainedRecoveryInput);
             }
+        };
+        await this.startProviderRouteRecoverySigner({
+            owner: recoveryLease,
+            prepared,
+            sourcesById,
+            destinationsById,
+            multipartUploads: recoveryMultipartUploads,
+            signal: input.signal,
+            expiresIn
         });
+        const stopOwnedRecovery = () => {
+            this.stopRecoverySigner(prepared.transfer_id, recoveryLease);
+            this.control.releaseRecoveryLease(prepared.transfer_id, recoveryLease);
+        };
+        input.signal?.addEventListener("abort", stopOwnedRecovery, { once: true });
+        this.control.registerRecoveryLease(recoveryLease);
         try {
             try {
                 assertOwnership();
                 await input.onPrepared?.(prepared);
             }
             catch (error) {
-                this.control.continueRecoveryLease(prepared.transfer_id);
+                this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                 throw error;
             }
             try {
                 await input.throwIfCancelled?.(prepared.transfer_id);
             }
             catch (error) {
-                this.control.continueRecoveryLease(prepared.transfer_id);
+                this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                 throw error;
             }
             await streamPreparedRoutes(prepared.route_generation_id, false);
@@ -740,6 +772,7 @@ export class BeamClient {
                     metadata: directPutRouteMetadata(input.target.metadata)
                 },
                 source: input.source,
+                sourceGrant: input.sourceGrant,
                 destination: input.destination,
                 expiresIn: input.expiresIn,
                 destUrl,
@@ -751,6 +784,7 @@ export class BeamClient {
                 chunk: input.chunk,
                 target: { ...input.target, metadata: partRouteMetadata(input.target.metadata) },
                 source: input.source,
+                sourceGrant: input.sourceGrant,
                 destination: input.destination,
                 expiresIn: input.expiresIn,
                 fetchImpl: this.fetchImpl
@@ -768,6 +802,7 @@ export class BeamClient {
                 metadata: partRouteMetadata(input.target.metadata)
             },
             source: input.source,
+            sourceGrant: input.sourceGrant,
             destination: input.destination,
             expiresIn: input.expiresIn,
             uploadId: upload.uploadId,
@@ -791,6 +826,7 @@ export class BeamClient {
             input.signal?.throwIfAborted();
             if (payload.route_generation_id.length === 0)
                 throw new Error("route recovery generation is required");
+            const sourceGrants = new Map();
             const routes = await mapOrderedWithConcurrency(payload.chunks, this.routeSigningConcurrency, async (requested) => {
                 input.signal?.throwIfAborted();
                 if (requested.route_generation_id !== payload.route_generation_id) {
@@ -821,11 +857,22 @@ export class BeamClient {
                         multipartUploads: input.multipartUploads,
                         expiresIn: input.expiresIn
                     });
+                const sourceKey = JSON.stringify([chunk.source_id, chunk.chunk_index]);
+                let sourceGrant = sourceGrants.get(sourceKey);
+                if (!sourceGrant) {
+                    sourceGrant = signSourceChunk({ source, chunk, fallbackUrl: chunk.source_url, expiresIn: input.expiresIn, fetchImpl: this.fetchImpl });
+                    sourceGrants.set(sourceKey, sourceGrant);
+                    void sourceGrant.catch(() => { });
+                }
                 const route = await this.signProviderRoute({
+                    sourceGrant,
                     chunk,
                     target: {
                         ...target,
-                        object_key: requested.final_object_key,
+                        // Direct-PUT destinations (Hippius, Hugging Face) keep the planned
+                        // per-chunk key exactly as initial materialization does; only
+                        // multipart destinations sign parts against the final object key.
+                        object_key: isDirectPutDestination(destination) ? target.object_key : requested.final_object_key,
                         metadata: {
                             ...(target.metadata ?? {}),
                             ...(requested.destination_metadata ?? {}),
@@ -861,16 +908,33 @@ export class BeamClient {
                 chunk_routes: routes
             };
         });
-        this.recoverySigners.set(input.prepared.transfer_id, stop);
-        this.integrityAuditSigners.set(input.prepared.transfer_id, async (challenge) => {
-            await this.submitProviderIntegrityAuditGrants({
-                challenge,
-                prepared: input.prepared,
-                sourcesById: input.sourcesById,
-                destinationsById: input.destinationsById,
-                expiresIn: input.expiresIn
+        if (input.signal?.aborted) {
+            stop();
+            return;
+        }
+        this.stopRecoverySigner(input.prepared.transfer_id);
+        this.integrityAuditSigners.set(input.prepared.transfer_id, (challenge) => this.buildProviderIntegrityAuditGrants({
+            challenge, prepared: input.prepared, sourcesById: input.sourcesById, destinationsById: input.destinationsById, expiresIn: input.expiresIn
+        }));
+        const registration = { owner: input.owner, stop };
+        this.recoverySigners.set(input.prepared.transfer_id, registration);
+        try {
+            const stopIntegrity = await this.control.serveIntegritySigner(input.prepared.transfer_id, challenge => {
+                input.signal?.throwIfAborted();
+                return this.signedIntegrityGrants(challenge);
             });
-        });
+            if (input.signal?.aborted || this.recoverySigners.get(input.prepared.transfer_id) !== registration) {
+                stop();
+                stopIntegrity();
+                return;
+            }
+            registration.stop = () => { stop(); stopIntegrity(); };
+        }
+        catch {
+            // Status-driven signing remains available if the optional subscription fails.
+            if (input.signal?.aborted)
+                this.stopRecoverySigner(input.prepared.transfer_id, input.owner);
+        }
     }
     async recoveryMultipartUploadState(input) {
         const existing = input.multipartUploads.get(input.requested.multipart_group_id);
@@ -937,21 +1001,56 @@ export class BeamClient {
         if (!signer)
             throw new Error("integrity audit signer unavailable");
         const existing = this.integrityAuditSubmissions.get(challenge.audit_id);
-        if (existing) {
+        const cached = this.integrityGrantCache.get(challenge.audit_id);
+        if (cached && cached.fingerprint !== JSON.stringify(challenge))
+            throw new Error("integrity audit identity changed");
+        if (existing && cached && cached.expiresAt > Date.now() + 30_000) {
             await existing;
             return;
         }
-        const submission = signer(challenge);
+        const submission = this.signedIntegrityGrants(challenge).then(async (payload) => {
+            const result = await this.control.request("transfer.integrity_audit_grants", payload, {
+                transferId: challenge.transfer_id, idempotencyKey: `transfer:${challenge.transfer_id}:integrity-audit:${challenge.audit_id}:${payload.submitted_at}`
+            });
+            if (result.published !== true)
+                throw new Error("integrity audit delivery unavailable");
+        });
         this.integrityAuditSubmissions.set(challenge.audit_id, submission);
         try {
             await submission;
         }
         catch (error) {
-            this.integrityAuditSubmissions.delete(challenge.audit_id);
+            if (this.integrityAuditSubmissions.get(challenge.audit_id) === submission)
+                this.integrityAuditSubmissions.delete(challenge.audit_id);
             throw error;
         }
     }
-    async submitProviderIntegrityAuditGrants(input) {
+    signedIntegrityGrants(challenge) {
+        const fingerprint = JSON.stringify(challenge);
+        const cached = this.integrityGrantCache.get(challenge.audit_id);
+        if (cached && cached.fingerprint !== fingerprint)
+            return Promise.reject(new Error("integrity audit identity changed"));
+        if (cached && cached.expiresAt > Date.now() + 30_000)
+            return cached.payload;
+        if (!cached && this.integrityGrantCache.size >= 1024)
+            return Promise.reject(new Error("integrity signer capacity unavailable"));
+        const signer = this.integrityAuditSigners.get(challenge.transfer_id);
+        if (!signer)
+            return Promise.reject(new Error("integrity audit signer unavailable"));
+        this.integrityAuditSubmissions.delete(challenge.audit_id);
+        const entry = { transferId: challenge.transfer_id, expiresAt: 0, fingerprint, payload: Promise.resolve({}) };
+        entry.payload = signer(challenge).then(payload => {
+            const chunks = payload.chunks;
+            entry.expiresAt = Math.min(...chunks.flatMap(chunk => [Date.parse(chunk.source.expires_at), Date.parse(chunk.destination.expires_at)]));
+            return payload;
+        }).catch(error => { if (this.integrityGrantCache.get(challenge.audit_id) === entry)
+            this.integrityGrantCache.delete(challenge.audit_id); throw error; });
+        // Pending grants are shared too. Actual expiry replaces this sentinel on completion.
+        entry.expiresAt = Infinity;
+        this.integrityGrantCache.set(challenge.audit_id, entry);
+        return entry.payload;
+    }
+    async buildProviderIntegrityAuditGrants(input) {
         if (input.challenge.transfer_id !== input.prepared.transfer_id) {
             throw new Error("integrity audit challenge transfer mismatch");
         }
@@ -978,6 +1077,7 @@ export class BeamClient {
             }
             const sourceEtag = plannedSource?.metadata?.etag;
             const sourceVersionId = plannedSource?.metadata?.version_id;
+            const grantExpiresAt = new Date(Math.floor(Date.now() / 1000) * 1000 + input.expiresIn * 1000).toISOString();
             const [sourceGrant, destinationGrant] = await Promise.all([
                 signSourceReadRange({
                     source,
@@ -998,31 +1098,30 @@ export class BeamClient {
                     fetchImpl: this.fetchImpl
                 })
             ]);
-            const grantExpiresAt = expiresAtIso(input.expiresIn);
             const { orchestrator_id: _orchestratorId, orchestrator_hotkey: _orchestratorHotkey, worker_id: _workerId, ...grantChunk } = chunk;
             return {
                 ...grantChunk,
-                source: { ...sourceGrant, expires_at: grantExpiresAt },
-                destination: { ...destinationGrant, expires_at: grantExpiresAt }
+                source: { ...sourceGrant, expires_at: boundedGrantExpiry(sourceGrant.url, grantExpiresAt) },
+                destination: { ...destinationGrant, expires_at: boundedGrantExpiry(destinationGrant.url, grantExpiresAt) }
             };
         });
-        await this.control.request("transfer.integrity_audit_grants", {
-            transfer_id: input.challenge.transfer_id,
-            audit_id: input.challenge.audit_id,
-            submitted_at: submittedAt,
-            chunks
-        }, {
-            transferId: input.challenge.transfer_id,
-            idempotencyKey: `transfer:${input.challenge.transfer_id}:integrity-audit:${input.challenge.audit_id}`
-        });
+        return { transfer_id: input.challenge.transfer_id, audit_id: input.challenge.audit_id, submitted_at: submittedAt, chunks };
     }
-    stopRecoverySigner(transferId) {
-        const stop = this.recoverySigners.get(transferId);
-        if (stop) {
-            stop();
+    /** Stop a transfer's recovery and integrity signers; with `owner`, only if that owner installed them. */
+    stopRecoverySigner(transferId, owner) {
+        const signer = this.recoverySigners.get(transferId);
+        if (owner && signer?.owner !== owner)
+            return;
+        if (signer) {
+            signer.stop();
             this.recoverySigners.delete(transferId);
         }
         this.integrityAuditSigners.delete(transferId);
+        for (const [auditId, entry] of this.integrityGrantCache)
+            if (entry.transferId === transferId) {
+                this.integrityGrantCache.delete(auditId);
+                this.integrityAuditSubmissions.delete(auditId);
+            }
     }
     stopAllRecoverySigners() {
         for (const transferId of [...this.recoverySigners.keys()])
@@ -1118,7 +1217,7 @@ export class BeamClient {
         }
     }
 }
-const ROUTE_STREAM_BATCH_ROUTES = 2_048;
+const ROUTE_STREAM_BATCH_ROUTES = 1_024;
 class AsyncMutex {
     tail = Promise.resolve();
     async acquire() {
@@ -1143,6 +1242,8 @@ class AsyncMutex {
 class RouteStreamSender {
     control;
     options;
+    started = performance.now();
+    telemetry;
     streamId;
     checksum = new RouteKeysChecksum();
     batch = [];
@@ -1155,6 +1256,7 @@ class RouteStreamSender {
         this.control = control;
         this.options = options;
         this.streamId = options.streamId;
+        this.telemetry = options.telemetry ?? new SdkPerformanceCollector();
     }
     async begin() {
         await this.control.request("transfer.route_stream.begin", compact({
@@ -1216,7 +1318,11 @@ class RouteStreamSender {
         await this.sendTail;
         if (this.sendError)
             throw this.sendError;
+        this.telemetry.observe("sdk.preparation", performance.now() - this.started);
+        const sdkPerformance = this.telemetry.snapshot();
+        this.options.onDiagnostics?.(sdkPerformance);
         return this.control.request("transfer.route_stream.complete", {
+            sdk_performance: sdkPerformance,
             transfer_id: this.options.transferId,
             route_generation_id: this.options.routeGenerationId,
             stream_id: this.streamId,
@@ -1231,7 +1337,7 @@ class RouteStreamSender {
     async enqueueFlush() {
         if (!this.batch.length)
             return;
-        await this.sendTail;
+        await this.telemetry.measure("sdk.buffer_wait", () => this.sendTail);
         if (this.sendError)
             throw this.sendError;
         const routes = this.batch.splice(0, this.batch.length);
@@ -1255,7 +1361,8 @@ class RouteStreamSender {
                     const routeChecksum = chunkChecksum.value();
                     const coordinateChecksum = await routeCoordinateChecksum(chunk);
                     const batchId = `${this.streamId}:${batchIndex}:${coordinateChecksum}`;
-                    await this.control.request("transfer.route_stream.batch", {
+                    this.telemetry.counters.route_batches++;
+                    await this.telemetry.measure("sdk.batch_ack", () => this.control.request("transfer.route_stream.batch", {
                         transfer_id: this.options.transferId,
                         route_generation_id: this.options.routeGenerationId,
                         stream_id: this.streamId,
@@ -1267,7 +1374,7 @@ class RouteStreamSender {
                     }, {
                         transferId: this.options.transferId,
                         idempotencyKey: `transfer:${this.options.transferId}:route-stream:${this.streamId}:batch:${batchIndex}:${coordinateChecksum}`
-                    });
+                    }));
                 }
                 catch (error) {
                     this.sendError = error;
@@ -1511,6 +1618,9 @@ function createDeferred() {
         resolve = resolvePromise;
         reject = rejectPromise;
     });
+    // A waiter may be rejected after its route loop already stopped (for example when
+    // ownership is fenced mid-stream); awaiting callers still observe the rejection.
+    promise.catch(() => undefined);
     return { promise, resolve, reject };
 }
 function createMultipartGroupWaiters(prepared, destinationsById) {

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;

package/dist/nats-control.d.ts

@@ -1,3 +1,4 @@
+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/v7";
@@ -137,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

@@ -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() {

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

@@ -63,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;
@@ -109,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;
@@ -118,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

@@ -69,7 +69,7 @@ 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;
@@ -307,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,
@@ -321,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,
@@ -337,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 } : {}),
@@ -475,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,
@@ -489,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,
@@ -503,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.6.0",
+    "version": "0.6.1",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",