@beam-network/sdk 0.5.10 → 0.5.11

package/README.md

@@ -102,6 +102,8 @@ The client signs up to 64 routes concurrently by default and emits 2,048-route l
 
 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.
 
+On completed provider transfers, Runtime may include an `integrity_audit_challenge` in status. Before releasing provider signing state, the TypeScript client signs exact read-only source and final-destination GET ranges and submits `transfer.integrity_audit_grants`; audit submission failures are best-effort and do not change transfer completion.
+
 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.
 
 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.

package/dist/client.d.ts

@@ -33,6 +33,8 @@ export declare class BeamClient {
     private readonly routeSigningConcurrencyOverridden;
     private readonly multipartControlConcurrency;
     private readonly recoverySigners;
+    private readonly integrityAuditSigners;
+    private readonly integrityAuditSubmissions;
     constructor(options?: BeamClientOptions);
     close(): Promise<void>;
     openTransferTerminalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
@@ -77,6 +79,8 @@ export declare class BeamClient {
     prepareProviderTransfer(input: ProviderTransferCreateInput): Promise<TransferPrepareResponse>;
     private signProviderRoute;
     private startProviderRouteRecoverySigner;
+    private submitIntegrityAuditGrantsIfPresent;
+    private submitProviderIntegrityAuditGrants;
     private stopRecoverySigner;
     private stopAllRecoverySigners;
     createAndDistribute(input: RawTransferCreateInput): Promise<TransferCreateResponse>;

package/dist/client.js

@@ -1,4 +1,4 @@
-import { abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationRoute, signFinalObjectHead, signListMultipartUpload } from "./provider-signing.js";
+import { abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationReadRange, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signSourceReadRange } from "./provider-signing.js";
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes, isRecoverableRouteStreamError } from "./nats-control.js";
 export class BeamRouteRecoveryPendingError extends Error {
     transferId;
@@ -53,6 +53,8 @@ export class BeamClient {
     routeSigningConcurrencyOverridden;
     multipartControlConcurrency;
     recoverySigners = new Map();
+    integrityAuditSigners = new Map();
+    integrityAuditSubmissions = new Map();
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
@@ -113,6 +115,7 @@ export class BeamClient {
         validateId(transferId, "transferId");
         const status = await this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
         if (["completed", "failed", "cancelled"].includes(status.status)) {
+            await this.submitIntegrityAuditGrantsIfPresent(status).catch(() => undefined);
             this.control.releaseRecoveryLease(transferId);
             this.stopRecoverySigner(transferId);
         }
@@ -591,13 +594,97 @@ export class BeamClient {
             };
         });
         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
+            });
+        });
+    }
+    async submitIntegrityAuditGrantsIfPresent(status) {
+        const challenge = status.integrity_audit_challenge;
+        if (!challenge)
+            return;
+        const signer = this.integrityAuditSigners.get(challenge.transfer_id);
+        if (!signer)
+            return;
+        const existing = this.integrityAuditSubmissions.get(challenge.audit_id);
+        if (existing) {
+            await existing;
+            return;
+        }
+        const submission = signer(challenge);
+        this.integrityAuditSubmissions.set(challenge.audit_id, submission);
+        await submission;
+    }
+    async submitProviderIntegrityAuditGrants(input) {
+        if (input.challenge.transfer_id !== input.prepared.transfer_id) {
+            throw new Error("integrity audit challenge transfer mismatch");
+        }
+        const submittedAt = new Date().toISOString();
+        const chunks = await mapOrderedWithConcurrency(input.challenge.chunks, Math.min(this.routeSigningConcurrency, input.challenge.chunks.length || 1), async (chunk) => {
+            const planChunk = materializePlanChunk(input.prepared.plan_descriptor, input.prepared.transfer_id, chunk.source_id, chunk.route_chunk_index);
+            if (chunk.source_offset < planChunk.source_offset
+                || chunk.source_offset + chunk.range_length > planChunk.source_offset + planChunk.chunk_size) {
+                throw new Error("integrity audit source range is outside the planned chunk");
+            }
+            const target = planChunk.destinations.find((candidate) => candidate.destination_id === chunk.destination_id
+                && Number(candidate.metadata?.delivery_index) === chunk.delivery_index);
+            if (!target || target.metadata?.final_object_key !== chunk.final_object_key) {
+                throw new Error("integrity audit destination coordinate mismatch");
+            }
+            if (chunk.destination_offset !== chunk.source_offset) {
+                throw new Error("integrity audit destination range mismatch");
+            }
+            const source = input.sourcesById.get(chunk.source_id);
+            const destination = input.destinationsById.get(chunk.destination_id);
+            if (!source || !destination) {
+                throw new Error("integrity audit provider configuration is unavailable");
+            }
+            const [sourceGrant, destinationGrant] = await Promise.all([
+                signSourceReadRange({
+                    source,
+                    offset: chunk.source_offset,
+                    length: chunk.range_length,
+                    expiresIn: input.expiresIn,
+                    fetchImpl: this.fetchImpl
+                }),
+                signDestinationReadRange({
+                    destination,
+                    objectKey: chunk.final_object_key,
+                    offset: chunk.destination_offset,
+                    length: chunk.range_length,
+                    expiresIn: input.expiresIn,
+                    fetchImpl: this.fetchImpl
+                })
+            ]);
+            const grantExpiresAt = expiresAtIso(input.expiresIn);
+            return {
+                ...chunk,
+                source: { ...sourceGrant, expires_at: grantExpiresAt },
+                destination: { ...destinationGrant, expires_at: 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}`
+        });
     }
     stopRecoverySigner(transferId) {
         const stop = this.recoverySigners.get(transferId);
-        if (!stop)
-            return;
-        stop();
-        this.recoverySigners.delete(transferId);
+        if (stop) {
+            stop();
+            this.recoverySigners.delete(transferId);
+        }
+        this.integrityAuditSigners.delete(transferId);
     }
     stopAllRecoverySigners() {
         for (const transferId of [...this.recoverySigners.keys()])

package/dist/models.d.ts

@@ -117,6 +117,29 @@ export interface DestinationStatusInfo {
     bytes_delivered?: number;
     location?: string;
 }
+export interface IntegrityAuditChallengeChunk {
+    challenge_id: string;
+    task_id: string;
+    attempt_id: string | null;
+    orchestrator_id: string;
+    orchestrator_hotkey: string;
+    worker_id: string | null;
+    source_id: string;
+    destination_id: string;
+    route_chunk_index: number;
+    delivery_index: number;
+    source_offset: number;
+    destination_offset: number;
+    range_length: number;
+    final_object_key: string;
+}
+export interface IntegrityAuditChallenge {
+    audit_id: string;
+    transfer_id: string;
+    requested_at: string;
+    range_bytes: number;
+    chunks: IntegrityAuditChallengeChunk[];
+}
 export interface TransferStatusInfo {
     transfer_id: string;
     name?: string;
@@ -146,6 +169,7 @@ export interface TransferStatusInfo {
         completedDestinations: number;
         completedDestinationIds: string[];
     };
+    integrity_audit_challenge?: IntegrityAuditChallenge;
 }
 export interface TransferTerminalEvent {
     schema_version: "transfer-client-control/v6";

package/dist/nats-control.d.ts

@@ -37,7 +37,7 @@ export interface RouteRecoverySignReplyPayload {
     signed_at?: string;
     chunk_routes: SignedChunkRoute[];
 }
-export type TransferClientMessageType = "runtime.hello" | "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.route_stream.begin" | "transfer.route_stream.manifest" | "transfer.route_stream.batch" | "transfer.route_stream.complete" | "transfer.distribute" | "transfer.status" | "transfer.cancel" | "transfer.resume";
+export type TransferClientMessageType = "runtime.hello" | "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.route_stream.begin" | "transfer.route_stream.manifest" | "transfer.route_stream.batch" | "transfer.route_stream.complete" | "transfer.distribute" | "transfer.status" | "transfer.integrity_audit_grants" | "transfer.cancel" | "transfer.resume";
 export interface CompactSignedRouteBatch {
     source_chunks: Array<{
         source_ref: number;

package/dist/provider-signing.d.ts

@@ -47,6 +47,27 @@ export declare function signDestinationRoute(input: {
     multipartGroupId?: string;
     fetchImpl?: typeof fetch;
 }): Promise<SignedChunkRoute>;
+export declare function signSourceReadRange(input: {
+    source: ProviderSourceConfig;
+    offset: number;
+    length: number;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    url: string;
+    headers: Record<string, string>;
+}>;
+export declare function signDestinationReadRange(input: {
+    destination: ProviderDestinationConfig;
+    objectKey: string;
+    offset: number;
+    length: number;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    url: string;
+    headers: Record<string, string>;
+}>;
 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;

package/dist/provider-signing.js

@@ -226,6 +226,48 @@ function rangeHeaderForRange(sourceOffset, chunkSize) {
     const size = Math.max(1, Math.floor(chunkSize));
     return `bytes=${start}-${start + size - 1}`;
 }
+export async function signSourceReadRange(input) {
+    const range = rangeHeaderForRange(input.offset, input.length);
+    if (isS3CompatibleProvider(input.source)) {
+        const client = createS3CompatibleClient(input.source);
+        return {
+            url: await getSignedUrl(client, new GetObjectCommand({
+                Bucket: input.source.bucket,
+                Key: input.source.key,
+                Range: range
+            }), { expiresIn: input.expiresIn }),
+            headers: { Range: range }
+        };
+    }
+    if (isHippiusProvider(input.source)) {
+        return {
+            url: await hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.source.base_url ?? "https://api.hippius.com", input.source.api_token, input.source.bucket, input.source.key, "get", input.expiresIn),
+            headers: { Range: range }
+        };
+    }
+    return unsupportedProviderConfig(input.source);
+}
+export async function signDestinationReadRange(input) {
+    const range = rangeHeaderForRange(input.offset, input.length);
+    if (isS3CompatibleProvider(input.destination)) {
+        const client = createS3CompatibleClient(input.destination);
+        return {
+            url: await getSignedUrl(client, new GetObjectCommand({
+                Bucket: input.destination.bucket,
+                Key: input.objectKey,
+                Range: range
+            }), { expiresIn: input.expiresIn }),
+            headers: { Range: range }
+        };
+    }
+    if (isHippiusProvider(input.destination)) {
+        return {
+            url: await hippiusPresign(input.fetchImpl ?? globalThis.fetch, input.destination.base_url ?? "https://api.hippius.com", input.destination.api_token, input.destination.bucket, input.objectKey, "get", input.expiresIn),
+            headers: { Range: range }
+        };
+    }
+    return unsupportedProviderConfig(input.destination);
+}
 async function signSourceRoute(input) {
     const range = rangeHeaderForChunk(input.chunk);
     if (!input.source) {

package/package.json

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