@beam-network/sdk 0.5.19 → 0.5.21

package/README.md

@@ -161,7 +161,7 @@ Create and resume accept an ownership `signal`. Aborting it stops initial routes
 
 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.
+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.
 

package/dist/client.js

@@ -120,8 +120,15 @@ export class BeamClient {
     async transferStatus(transferId) {
         validateId(transferId, "transferId");
         const status = await this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
+        if (status.integrity_audit_challenge) {
+            try {
+                await this.submitIntegrityAuditGrantsIfPresent(status);
+            }
+            catch (error) {
+                status.integrity_audit_submission_error = integrityAuditErrorSummary(error);
+            }
+        }
         if (["completed", "failed", "cancelled"].includes(status.status)) {
-            await this.submitIntegrityAuditGrantsIfPresent(status).catch(() => undefined);
             this.control.releaseRecoveryLease(transferId);
             this.stopRecoverySigner(transferId);
         }
@@ -927,7 +934,7 @@ export class BeamClient {
             return;
         const signer = this.integrityAuditSigners.get(challenge.transfer_id);
         if (!signer)
-            return;
+            throw new Error("integrity audit signer unavailable");
         const existing = this.integrityAuditSubmissions.get(challenge.audit_id);
         if (existing) {
             await existing;
@@ -935,7 +942,13 @@ export class BeamClient {
         }
         const submission = signer(challenge);
         this.integrityAuditSubmissions.set(challenge.audit_id, submission);
-        await submission;
+        try {
+            await submission;
+        }
+        catch (error) {
+            this.integrityAuditSubmissions.delete(challenge.audit_id);
+            throw error;
+        }
     }
     async submitProviderIntegrityAuditGrants(input) {
         if (input.challenge.transfer_id !== input.prepared.transfer_id) {
@@ -958,12 +971,17 @@ export class BeamClient {
             }
             const source = input.sourcesById.get(chunk.source_id);
             const destination = input.destinationsById.get(chunk.destination_id);
+            const plannedSource = input.prepared.plan_descriptor.sources.find((candidate) => candidate.source_id === chunk.source_id);
             if (!source || !destination) {
                 throw new Error("integrity audit provider configuration is unavailable");
             }
+            const sourceEtag = plannedSource?.metadata?.etag;
+            const sourceVersionId = plannedSource?.metadata?.version_id;
             const [sourceGrant, destinationGrant] = await Promise.all([
                 signSourceReadRange({
                     source,
+                    ...(typeof sourceEtag === "string" ? { ifMatch: sourceEtag } : {}),
+                    ...(typeof sourceVersionId === "string" ? { versionId: sourceVersionId } : {}),
                     offset: chunk.source_offset,
                     length: chunk.range_length,
                     expiresIn: input.expiresIn,
@@ -972,6 +990,7 @@ export class BeamClient {
                 signDestinationReadRange({
                     destination,
                     objectKey: chunk.final_object_key,
+                    ...(chunk.final_object_etag ? { ifMatch: chunk.final_object_etag } : {}),
                     offset: chunk.destination_offset,
                     length: chunk.range_length,
                     expiresIn: input.expiresIn,
@@ -1343,6 +1362,15 @@ async function mapOrderedWithConcurrency(values, concurrency, map) {
     await Promise.all(workers);
     return results;
 }
+function integrityAuditErrorSummary(error) {
+    if (!(error instanceof Error))
+        return "unknown_error";
+    const message = error.message.trim();
+    if (!message || /https?:\/\/|x-amz|password|secret|token|authorization|credential/i.test(message)) {
+        return error.name || "unknown_error";
+    }
+    return message.slice(0, 200);
+}
 function positiveInteger(value, label) {
     if (!Number.isInteger(value) || value < 1)
         throw new Error(`${label} must be a positive integer.`);

package/dist/models.d.ts

@@ -132,6 +132,7 @@ export interface IntegrityAuditChallengeChunk {
     destination_offset: number;
     range_length: number;
     final_object_key: string;
+    final_object_etag: string | null;
 }
 export interface IntegrityAuditChallenge {
     audit_id: string;
@@ -170,6 +171,7 @@ export interface TransferStatusInfo {
         completedDestinationIds: string[];
     };
     integrity_audit_challenge?: IntegrityAuditChallenge;
+    integrity_audit_submission_error?: string;
 }
 export interface ProviderTransferResumeInput extends Omit<ProviderTransferCreateInput, "idempotencyKey" | "routeGenerationId"> {
     transferId: string;

package/dist/provider-signing.d.ts

@@ -91,6 +91,7 @@ export declare function signSourceReadRange(input: {
 export declare function signDestinationReadRange(input: {
     destination: ProviderDestinationConfig;
     objectKey: string;
+    ifMatch?: string;
     offset: number;
     length: number;
     expiresIn: number;

package/dist/provider-signing.js

@@ -337,11 +337,14 @@ export async function signDestinationReadRange(input) {
             url: await getSignedUrl(client, new GetObjectCommand({
                 Bucket: input.destination.bucket,
                 Key: input.objectKey,
-                Range: range
+                Range: range,
+                IfMatch: input.ifMatch
             }), { expiresIn: input.expiresIn }),
-            headers: { Range: range }
+            headers: { Range: range, ...(input.ifMatch ? { "If-Match": input.ifMatch } : {}) }
         };
     }
+    if (input.ifMatch)
+        throw new Error("conditional destination ranges require S3-compatible storage");
     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),

package/package.json

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