@sparkvault/sdk-mobile 7.0.0 → 7.0.2

package/src/app-sdk/upload-publication.js

@@ -0,0 +1,164 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/upload-publication.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The upload publication contract between Forge and Core's activation, and
+ * the facts of a transfer token both services spell: its shape, and Core's
+ * revocation of an upload's token.
+ *
+ * Forge stamps UPLOAD_PUBLICATION_PROTOCOL on every upload session it creates
+ * and on the final state it hands Core's activation (POST
+ * /v1/vaults/:vault_id/ingots/:ingot_id/activate); activation refuses any
+ * other version. The two services deploy separately, so a change to what
+ * either side sends or expects moves this number: a session or a finalize
+ * from the other side's contract then fails closed ("restart the upload")
+ * instead of publishing under a contract the other side does not hold.
+ *
+ * Version 2: an upload's own metadata (content type, original file name,
+ * uploader, content HMAC) travels on its upload token and its session, and
+ * activation publishes it from the session; the final state Forge sends
+ * carries only the storage facts Forge owns.
+ *
+ * Isomorphic: no Node imports.
+ */
+
+export const UPLOAD_PUBLICATION_PROTOCOL = 2;
+
+/**
+ * An upload's id as both services spell it: `tus_` and the 32 lowercase hex
+ * digits of 16 random bytes. An encrypt token that names one (`upload_id`)
+ * was staged by Core under it, and Forge keys the upload's session, its chunk
+ * prefix and its VAK wrapping by it, so Core finds and settles the upload by
+ * the session's id.
+ */
+export const UPLOAD_ID_PATTERN = /^tus_[0-9a-f]{32}$/;
+
+/** The random bytes an ISTK, the bearer token of one Forge transfer, is spelled from. */
+export const ISTK_BYTES = 32;
+
+/**
+ * An ISTK as Core mints one: the unpadded base64url of its ISTK_BYTES random
+ * bytes, 43 characters. Forge reads a presented token as a forge-transactions
+ * key only in this shape: the table keys other records too (an upload's token
+ * pointer, `UPLOAD_TOKEN#{upload_id}`), which no request may read as a token.
+ */
+export const ISTK_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${Math.ceil((ISTK_BYTES * 4) / 3)}}$`);
+
+/**
+ * How much of an ISTK names a transfer's charge on the usage ledger: enough to
+ * be unique to the token, never the whole bearer credential.
+ */
+export const TRANSFER_REFERENCE_ISTK_CHARS = 24;
+
+/**
+ * The ledger reference of an upload's transfer charge,
+ * `forge_ingot_transfer_upload_<first 24 ISTK chars>`: every charge of one
+ * upload carries it — Core's activation, Core's charge of an upload that never
+ * publishes, Forge's cancel — so whichever lands first is the upload's one
+ * ledger row and the others are duplicates.
+ *
+ * @param {string} istk - The upload's ISTK, as its session carries it
+ * @returns {string}
+ * @throws {TypeError} When the ISTK is not a string of at least
+ *   TRANSFER_REFERENCE_ISTK_CHARS characters
+ */
+export function uploadTransferReference(istk) {
+  if (typeof istk !== 'string' || istk.length < TRANSFER_REFERENCE_ISTK_CHARS) {
+    throw new TypeError(
+      `An upload's transfer reference is named from its ISTK, a string of at least ${TRANSFER_REFERENCE_ISTK_CHARS} characters`
+    );
+  }
+  return `forge_ingot_transfer_upload_${istk.slice(0, TRANSFER_REFERENCE_ISTK_CHARS)}`;
+}
+
+/**
+ * The codes Core's activation refuses an upload with, which Forge's refusal
+ * map reads (the status is Core's):
+ * - UPLOAD_CONTRACT_MISMATCH (409): a finalize or session from another
+ *   publication contract than Core's, a mixed deployment that converges — the
+ *   upload is kept and its finalize tried again.
+ * - UPLOAD_PROTOCOL_RETIRED (410): a session from a contract Core no longer
+ *   publishes, which never can be.
+ * - UPLOAD_SUPERSEDED (410): a session a later staging of its ingot
+ *   superseded, which never can be.
+ * - UPLOAD_POOL_FULL (402): an upload the owner's storage pool cannot take at
+ *   publication, which is final.
+ */
+export const UPLOAD_REFUSAL_CODES = Object.freeze({
+  UPLOAD_CONTRACT_MISMATCH: 'UPLOAD_CONTRACT_MISMATCH',
+  UPLOAD_PROTOCOL_RETIRED: 'UPLOAD_PROTOCOL_RETIRED',
+  UPLOAD_SUPERSEDED: 'UPLOAD_SUPERSEDED',
+  UPLOAD_POOL_FULL: 'UPLOAD_POOL_FULL'
+});
+
+/**
+ * The refusals of Core's that a new upload of the same file cannot remedy:
+ * the owner's storage pool cannot take it (UPLOAD_POOL_FULL), or a later
+ * upload of its ingot replaced it (UPLOAD_SUPERSEDED). Any other code Core
+ * ends an upload with ends its session alone, which a new upload starts
+ * over. Every client reads a terminal answer's code by it
+ * (transfer-retry.js): one of these is a refusal it reports in Core's words,
+ * any other a gone session.
+ */
+export const UPLOAD_FINAL_REFUSAL_CODES = Object.freeze([
+  UPLOAD_REFUSAL_CODES.UPLOAD_POOL_FULL,
+  UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED
+]);
+
+/**
+ * The words an upload a later staging of its ingot superseded is refused in
+ * (UPLOAD_SUPERSEDED), whichever service meets it: Core's activation, Core's
+ * mint of a token it revoked before issuing it, and Forge meeting a token Core
+ * revoked when the later staging superseded its upload.
+ */
+export const UPLOAD_SUPERSEDED_MESSAGE =
+  'A later upload replaced this one before it finished. The later upload is the one kept, so this one was discarded.';
+
+/**
+ * Core's revocation of an upload's encrypt token: the `status` it writes on
+ * the token's forge-transactions record, and the `revoked_reason` beside it,
+ * written by the write that ends the upload's staging. Each reason is the
+ * refusal every reader of the token answers the upload with from then on,
+ * as Core's activation refuses such an upload: Core's mint of a token it
+ * revoked before issuing it, and Forge on every request the token, or a
+ * session it opened, makes.
+ *
+ * - UPLOAD_SUPERSEDED: a later staging of its ingot superseded the upload
+ *   (410 UPLOAD_SUPERSEDED, in UPLOAD_SUPERSEDED_MESSAGE's words), which no
+ *   new upload remedies;
+ * - INGOT_DELETED: the ingot it was staged onto was deleted, by a delete or
+ *   the cascade of its folder, vault or account (a 404 naming the ingot, as
+ *   activation answers an upload whose ingot is gone), which ends the upload
+ *   alone: a new upload can store the file again.
+ */
+export const UPLOAD_TOKEN_REVOCATION = Object.freeze({
+  status: 'revoked',
+  reasons: Object.freeze({
+    UPLOAD_SUPERSEDED: UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED,
+    INGOT_DELETED: 'INGOT_DELETED'
+  })
+});
+
+const REVOCATION_REASONS = Object.values(UPLOAD_TOKEN_REVOCATION.reasons);
+
+/**
+ * Why Core revoked the upload token a forge-transactions record is
+ * (UPLOAD_TOKEN_REVOCATION's reasons), or null for any other record, or none:
+ * the one reading Core's mint and every Forge read of a token apply.
+ *
+ * @param {Object|null|undefined} record - A forge-transactions record, or none
+ * @returns {string|null}
+ */
+export function uploadTokenRevocationReason(record) {
+  if (record?.status !== UPLOAD_TOKEN_REVOCATION.status) return null;
+  return REVOCATION_REASONS.includes(record.revoked_reason) ? record.revoked_reason : null;
+}
+
+/**
+ * The response header that names the code Core refused an upload with for
+ * good: Forge sends it on every terminal answer to a tus request, a HEAD's
+ * (which has no body) included, so a client tells an upload the owner's pool
+ * cannot take from one a later upload superseded without reading a body.
+ */
+export const UPLOAD_REFUSAL_HEADER = 'X-Upload-Refusal';

package/src/config.ts

@@ -31,6 +31,11 @@ export interface SparkVaultMobileConfig {
   userAgent?: string;
   timeoutMs?: number;
   fileTransferTimeoutMs?: number;
+  /**
+   * Timeout of a tus create POST and DELETE. A HEAD and the receipt (the
+   * PATCH at the final offset) wait HEAD_AND_RECEIPT_TIMEOUT_MS instead:
+   * Forge answers either only after its own call to Core.
+   */
   tusPostTimeoutMs?: number;
   /** Stall watchdog per tus chunk PATCH: aborts after this long with NO upload progress (not an absolute deadline). */
   tusChunkTimeoutMs?: number;
@@ -53,6 +58,21 @@ export interface SparkVaultMobileConfig {
    * upload, and every upload when this is unset, streams over XHR.
    */
   backgroundUploader?: MobileBackgroundUploader;
+  /**
+   * Whether the device has a network path right now (an app wires it to its
+   * OS network signal). Read when an upload request got no answer: while it
+   * answers false the upload waits for `onOnline` instead of spending its
+   * retries, then asks Forge where the session stands. Only a definite
+   * "offline" should answer false; a path that may come up is online. Given
+   * together with `onOnline`, or not at all.
+   */
+  isOnline?: () => boolean;
+  /**
+   * Subscribe to the network coming back; returns the unsubscribe. The pair
+   * of `isOnline`. A wait it ends is otherwise ended only by the upload's
+   * `abortSignal`.
+   */
+  onOnline?: (listener: () => void) => () => void;
   logger?: Partial<SparkVaultLogger>;
   /**
    * Host allowlist for the backend-issued Forge transfer URLs the SDK sends an
@@ -62,6 +82,12 @@ export interface SparkVaultMobileConfig {
   allowedDownloadHostPatterns?: RegExp[];
 }
 
+/** The device's network signal, as the upload's offline wait reads it (`isOnline` with `onOnline`). */
+export interface MobileConnectivity {
+  isOnline(): boolean;
+  onOnline(listener: () => void): () => void;
+}
+
 export interface ResolvedMobileConfig {
   tokenStorage: TokenStorageAdapter;
   apiBaseUrl: string;
@@ -78,10 +104,23 @@ export interface ResolvedMobileConfig {
   fileDownloader?: MobileFileDownloader;
   backgroundTransfer?: MobileBackgroundTransfer;
   backgroundUploader?: MobileBackgroundUploader;
+  connectivity?: MobileConnectivity;
   logger: SparkVaultLogger;
   allowedDownloadHostPatterns: RegExp[];
 }
 
+/** The `isOnline` / `onOnline` pair as one signal, or none: one without the other cannot wait for the network. */
+function resolveConnectivity(config: SparkVaultMobileConfig): MobileConnectivity | undefined {
+  const { isOnline, onOnline } = config;
+  if (isOnline === undefined && onOnline === undefined) return undefined;
+  if (typeof isOnline !== 'function' || typeof onOnline !== 'function') {
+    throw new SparkVaultValidationError('isOnline and onOnline are given together, as functions', {
+      field: typeof isOnline === 'function' ? 'onOnline' : 'isOnline',
+    });
+  }
+  return { isOnline, onOnline };
+}
+
 function normalizeBaseUrl(url: string, field: string): string {
   if (!url || typeof url !== 'string') {
     throw new SparkVaultValidationError(`${field} must be a non-empty string`, { field });
@@ -157,6 +196,7 @@ export function resolveMobileConfig(config: SparkVaultMobileConfig): ResolvedMob
     fileDownloader: config.fileDownloader,
     backgroundTransfer: config.backgroundTransfer,
     backgroundUploader: config.backgroundUploader,
+    connectivity: resolveConnectivity(config),
     logger: { ...noopLogger, ...config.logger },
     allowedDownloadHostPatterns: config.allowedDownloadHostPatterns ?? [...SPARKVAULT_OWNED_HOST_PATTERNS],
   };

package/src/errors.ts

@@ -181,28 +181,62 @@ export class TusUploadError extends SparkVaultMobileError {
   readonly cause: Error | null;
   readonly filename: string | null;
   readonly fileSize: number | null;
-  readonly phase: 'create' | 'upload' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
+  /**
+   * Where the upload stopped: `finalize` is after the transfer, when every
+   * byte was on Forge but the ingot was not confirmed published.
+   */
+  readonly phase: 'create' | 'upload' | 'finalize' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
   /**
    * True when Forge no longer has the session (it answered a status
-   * `isSessionGone` recognises: expired or terminated), or the session
-   * cannot carry this file. The persisted session is worthless, so the
-   * caller starts a fresh upload instead of retrying it.
+   * `isSessionGone` recognises, or the expiry it named has passed), or the
+   * session cannot carry this file. The persisted session is worthless, so
+   * the caller starts a fresh upload instead of retrying it.
    */
   readonly sessionLost: boolean;
+  /**
+   * The `Retry-After` of the answer that ended the upload, in ms: the
+   * earliest a next attempt can expect another answer. Null when that answer
+   * named none, or no answer arrived.
+   */
+  readonly retryAfterMs: number | null;
+  /**
+   * True when every byte is on Forge and the session is intact but the ingot
+   * was not confirmed published: the vault did not read it `active` within
+   * the activation poll budget, or Forge was still saving the file at the
+   * upload's idle limit (code `upload_received_publishing`; it finishes
+   * without this device). The caller retries later by resuming the session
+   * it persisted, which asks Forge for the receipt again and sends no bytes.
+   */
+  readonly retryLater: boolean;
+  /**
+   * The code Core ended this upload with, as Forge named it. With code
+   * `upload_refused` a final refusal (`UPLOAD_POOL_FULL`: the account's
+   * storage pool cannot take it; `UPLOAD_SUPERSEDED`: a later upload replaced
+   * it), whose message is Core's own sentence and which no new upload of the
+   * same file remedies; with `sessionLost` any other code (`NOT_FOUND`: the
+   * file the upload was for is gone; `UPLOAD_PROTOCOL_RETIRED`; a 412's),
+   * which a fresh upload starts over from. Null when the answer named none.
+   */
+  readonly coreCode: string | null;
 
   constructor(
     message: string,
     options: {
       cause?: Error | null;
       httpStatus?: number | null;
+      /** The error's code when it names an outcome of its own; otherwise the HTTP status, or `tus_upload_error`. */
+      code?: string;
       filename?: string | null;
       fileSize?: number | null;
       phase?: TusUploadError['phase'];
       sessionLost?: boolean;
+      retryAfterMs?: number | null;
+      retryLater?: boolean;
+      coreCode?: string | null;
     } = {}
   ) {
     super(message, {
-      code: options.httpStatus ?? 'tus_upload_error',
+      code: options.code ?? options.httpStatus ?? 'tus_upload_error',
       statusCode: options.httpStatus ?? undefined,
     });
     this.name = 'TusUploadError';
@@ -211,6 +245,9 @@ export class TusUploadError extends SparkVaultMobileError {
     this.fileSize = options.fileSize ?? null;
     this.phase = options.phase ?? 'unknown';
     this.sessionLost = options.sessionLost ?? false;
+    this.retryAfterMs = options.retryAfterMs ?? null;
+    this.retryLater = options.retryLater ?? false;
+    this.coreCode = options.coreCode ?? null;
     Object.setPrototypeOf(this, TusUploadError.prototype);
   }
 

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   createSparkVaultMobileClient,
 } from './client.js';
 export type {
+  MobileConnectivity,
   SparkVaultMobileConfig,
   ResolvedMobileConfig,
 } from './config.js';
@@ -92,6 +93,7 @@ export {
   MobileUsersClient,
 } from './users.js';
 export {
+  isSessionExpired,
   isSessionGone,
   MobileTusUploader,
   parseForgeUrl,

package/src/ingots.ts

@@ -7,9 +7,10 @@ import {
   isRetryableDownloadError,
   SparkVaultMobileError,
   SparkVaultValidationError,
+  TusUploadError,
 } from './errors.js';
 import type { MobileHttpClient } from './http.js';
-import { allowsHost, MobileTusUploader } from './tus.js';
+import { allowsHost, MobileTusUploader, type TusSessionProbe } from './tus.js';
 import type {
   DebugLogger,
   HashCheckResponse,
@@ -97,6 +98,12 @@ export interface UploadFromUriOptions extends UploadOptions {
    * attempt or a relaunch instead of re-sending bytes Forge already holds.
    */
   onSessionCreated?: (session: IngotUploadSession) => void;
+  /**
+   * Invoked whenever the session's expiry changes (see
+   * `TusUploadFromUriOptions.onSessionExpiry`): a caller that persists the
+   * session keeps its `expiresAt` current with it.
+   */
+  onSessionExpiry?: (expiresAt: number | null) => void;
   /** See `UploadTransport`; default `foreground`. */
   transport?: UploadTransport;
   /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
@@ -127,8 +134,14 @@ export interface ResumeUploadOptions {
   fileUri: string;
   fileSize: number;
   name: string;
-  /** The persisted tus session handed to `onSessionCreated`. */
-  session: { uploadUrl: string; istk: string };
+  /**
+   * The persisted tus session handed to `onSessionCreated`, with the expiry
+   * the caller keeps for it (`onSessionExpiry`): a session past it is
+   * refused as `sessionLost` before any request.
+   */
+  session: { uploadUrl: string; istk: string; expiresAt?: number | null };
+  /** See `UploadFromUriOptions.onSessionExpiry`. */
+  onSessionExpiry?: (expiresAt: number | null) => void;
   /** See `UploadTransport`; default `foreground`. */
   transport?: UploadTransport;
   /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
@@ -343,6 +356,7 @@ export class MobileIngotsClient {
       filename: name,
       forgeUrl: init.forgeUrl,
       onSessionCreated: session => options.onSessionCreated?.({ ...session, ingotId: init.ingotId, created }),
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress: options.onProgress,
@@ -351,7 +365,11 @@ export class MobileIngotsClient {
       debug: options.debug,
     });
 
-    const ingot = await this.verifyIngotActive(options.vaultId, init.ingotId, options.vat, options.debug);
+    const ingot = await this.verifyIngotActive(
+      { vaultId: options.vaultId, ingotId: init.ingotId, vat: options.vat },
+      { filename: name, fileSize: options.fileSize },
+      options.debug
+    );
 
     return {
       ingot_id: init.ingotId,
@@ -373,10 +391,10 @@ export class MobileIngotsClient {
    * sent, then the ingot is verified active exactly as a fresh upload is.
    *
    * A `TusUploadError` with `sessionLost` means Forge no longer has the
-   * session (expired or terminated); the caller drops it and starts over
-   * with `uploadFromUri`. A session `uploadUrl` that is not an upload session
-   * on an allowed transfer host is refused (SparkVaultValidationError) before
-   * the ISTK or a byte is sent anywhere.
+   * session (its expiry passed, or it was terminated); the caller drops it
+   * and starts over with `uploadFromUri`. A session `uploadUrl` that is not
+   * an upload session on an allowed transfer host is refused
+   * (SparkVaultValidationError) before the ISTK or a byte is sent anywhere.
    */
   async resumeUpload(options: ResumeUploadOptions): Promise<UploadResult> {
     validateVaultId(options.vaultId);
@@ -390,6 +408,7 @@ export class MobileIngotsClient {
       fileSize: options.fileSize,
       filename: options.name,
       resume: options.session,
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress: options.onProgress,
@@ -398,7 +417,11 @@ export class MobileIngotsClient {
       debug: options.debug,
     });
 
-    const ingot = await this.verifyIngotActive(options.vaultId, options.ingotId, options.vat, options.debug);
+    const ingot = await this.verifyIngotActive(
+      { vaultId: options.vaultId, ingotId: options.ingotId, vat: options.vat },
+      { filename: options.name, fileSize: options.fileSize },
+      options.debug
+    );
 
     return {
       ingot_id: options.ingotId,
@@ -418,9 +441,7 @@ export class MobileIngotsClient {
    * An `uploadUrl` that is not an upload session on an allowed transfer host
    * is refused (SparkVaultValidationError) before the ISTK is sent anywhere.
    */
-  probeUploadSession(
-    session: { uploadUrl: string; istk: string }
-  ): Promise<{ offset: number; length: number; chunkSize: number } | null> {
+  probeUploadSession(session: { uploadUrl: string; istk: string }): Promise<TusSessionProbe | null> {
     return this.tus.probeSession(session);
   }
 
@@ -512,6 +533,7 @@ export class MobileIngotsClient {
       forgeUrl: response.data.forge_url,
       // A replace never mints an ingot: the row is the caller's existing one.
       onSessionCreated: session => options.onSessionCreated?.({ ...session, ingotId, created: false }),
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress,
@@ -520,7 +542,11 @@ export class MobileIngotsClient {
       debug,
     });
 
-    const ingot = await this.verifyIngotActive(vaultId, response.data.ingot_id, vat, debug);
+    const ingot = await this.verifyIngotActive(
+      { vaultId, ingotId: response.data.ingot_id, vat },
+      { filename: name, fileSize },
+      debug
+    );
 
     return {
       ingot_id: response.data.ingot_id,
@@ -866,22 +892,24 @@ export class MobileIngotsClient {
   }
 
   /**
-   * Wait for a just-uploaded ingot to finish server-side finalization.
+   * Read a just-uploaded ingot until the server reports it `active`.
    *
-   * The bytes are already fully uploaded and the ingot record exists before
-   * this runs, so this NEVER re-creates or re-uploads anything - it only polls
-   * status. A still-`uploading` ingot after the poll budget
-   * is returned as success, not thrown: the transport completed and the ingot
-   * exists, so treating it as a failure would make the caller re-run the whole
-   * upload and mint a DUPLICATE ingot (re-streaming the entire file and
-   * double-billing storage). Finalization completes asynchronously server-side.
+   * The upload resolved on Forge's receipt (a 2xx to the PATCH at the final
+   * offset, which Forge answers only once the ingot is published), so a read
+   * that is not `active` yet is a read lagging that publication, which the
+   * poll waits out. It never re-creates or re-uploads anything. A row still
+   * not `active` past the poll budget is never reported as a success: it
+   * throws a `TusUploadError` whose `retryLater` is set (every byte is
+   * received, publication is unconfirmed), so the caller resumes the session
+   * it persisted later, which asks Forge for the receipt again and sends no
+   * bytes, rather than recording a backup the vault may not hold.
    */
   private async verifyIngotActive(
-    vaultId: string,
-    ingotId: string,
-    vat: string,
+    ingotRef: { vaultId: string; ingotId: string; vat: string },
+    upload: { filename: string; fileSize: number },
     debug?: DebugLogger
   ): Promise<Ingot> {
+    const { vaultId, ingotId, vat } = ingotRef;
     const deadline = Date.now() + MobileIngotsClient.INGOT_STATUS_POLL_BUDGET_MS;
     let delay = MobileIngotsClient.INGOT_STATUS_POLL_INITIAL_MS;
     let ingot = await this.get(vaultId, ingotId, vat);
@@ -891,9 +919,12 @@ export class MobileIngotsClient {
       if (remaining <= 0) {
         debug?.log(
           `Ingot ${ingotId} still '${ingot.status}' after ${MobileIngotsClient.INGOT_STATUS_POLL_BUDGET_MS}ms; ` +
-            'upload transport is complete, finalizing asynchronously'
+            'the upload is received and will be confirmed on a later attempt'
+        );
+        throw new TusUploadError(
+          `Upload received; the vault has not confirmed ingot ${ingotId} published yet (status ${ingot.status ?? 'unknown'})`,
+          { ...upload, phase: 'finalize', retryLater: true }
         );
-        return ingot;
       }
 
       await new Promise(resolve => setTimeout(resolve, Math.min(delay, remaining)));