@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/src/ingots.ts

@@ -1,12 +1,16 @@
+import { readForgeTransferUrl } from './app-sdk/forge-url.js';
+import { INGOT_ACCESS_EVENT_TYPES, readIngotAccess } from './app-sdk/ingot-access-log.js';
 import type { ResolvedMobileConfig } from './config.js';
 import {
+  IngotNameHeldError,
   IngotNotReadyError,
   isRetryableDownloadError,
   SparkVaultMobileError,
   SparkVaultValidationError,
+  TusUploadError,
 } from './errors.js';
 import type { MobileHttpClient } from './http.js';
-import { MobileTusUploader } from './tus.js';
+import { allowsHost, MobileTusUploader, type TusSessionProbe } from './tus.js';
 import type {
   DebugLogger,
   HashCheckResponse,
@@ -16,6 +20,7 @@ import type {
   IngotInvite,
   IngotSharingConfig,
   ListIngotsResponse,
+  FolderContentsResponse,
   IngotUploadSession,
   MobileFileDownloader,
   UploadAbortBehavior,
@@ -24,7 +29,26 @@ import type {
   UploadTransferPolicy,
   UploadTransport,
 } from './types.js';
-import { validateIngotId, validateVaultId } from './validation.js';
+import { validateIngotId, validateResourceId, validateVaultId } from './validation.js';
+import { apiPath } from './request-path.js';
+
+/**
+ * What the server does when a create's name is already held in the target
+ * folder (case-insensitive). The server decides on the holder it read before
+ * writing anything, so a caller that must not replace content says so here:
+ * - `upsert` (the server default): the upload replaces the holder's content.
+ * - `complete_pending`: a holder whose own upload never finalized is completed
+ *   (`created: false`); a published holder is refused with
+ *   `IngotNameHeldError`, untouched.
+ * - `refuse`: any holder, its upload finished or not, is refused with
+ *   `IngotNameHeldError`, untouched; the create only ever mints.
+ * - `new_name`: the holder is never touched; the ingot is minted under the
+ *   first free numbered name the server picks ("report (2).pdf"), returned
+ *   as the result's `name`.
+ */
+export const NAME_CONFLICT_POLICIES = ['upsert', 'complete_pending', 'refuse', 'new_name'] as const;
+
+export type NameConflictPolicy = (typeof NAME_CONFLICT_POLICIES)[number];
 
 export interface UploadOptions {
   vaultId: string;
@@ -55,20 +79,31 @@ export interface UploadOptions {
 export interface UploadFromUriOptions extends UploadOptions {
   fileUri: string;
   fileSize: number;
+  /** What a name already held in the target folder does; omitted means the server's `upsert`. */
+  onNameConflict?: NameConflictPolicy;
   /**
-   * Invoked once the API has minted (or, via its same-name upsert, handed
-   * back) the ingot and before any Forge session exists. `created: false`
-   * means the bytes about to be sent will REPLACE an existing ingot's content
-   * once they finalize; a caller that must never overwrite throws here, and
-   * the throw propagates as-is with nothing sent and no session to clean up.
+   * Invoked once the server has placed the upload and before any Forge
+   * session exists: `created` is true when it minted the ingot and false when
+   * it staged the upload onto the row holding the name (as `onNameConflict`
+   * allowed), and `name` is the name the ingot is stored under (the server's
+   * numbered name under `new_name`). The placement has already been written
+   * by then, so this hook observes; a caller that must not replace content
+   * says so through `onNameConflict`. A throw here still stops the upload
+   * before a byte moves and propagates as-is.
    */
-  onIngotCreated?: (ingot: { ingotId: string; created: boolean }) => void;
+  onIngotCreated?: (ingot: { ingotId: string; created: boolean; name: string }) => void;
   /**
    * Invoked once the Forge tus session exists and before the first byte is
    * sent, so the caller can persist it and `resumeUpload` after a failed
    * 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. */
@@ -86,7 +121,8 @@ export interface UploadFromUriOptions extends UploadOptions {
   debug?: DebugLogger;
 }
 
-export interface ReplaceFromUriOptions extends UploadFromUriOptions {
+/** A replace addresses its ingot by id: no name is placed, so the create-only hooks do not apply. */
+export interface ReplaceFromUriOptions extends Omit<UploadFromUriOptions, 'onNameConflict' | 'onIngotCreated'> {
   ingotId: string;
 }
 
@@ -98,9 +134,14 @@ export interface ResumeUploadOptions {
   fileUri: string;
   fileSize: number;
   name: string;
-  contentType: 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. */
@@ -161,17 +202,20 @@ export interface CreateUploadOptions {
   folderId?: string;
   /** Vault-keyed plaintext HMAC (43-char base64url); see UploadOptions.contentHmac. */
   contentHmac?: string;
+  /** What a name already held in the target folder does; omitted means the server's `upsert`. */
+  onNameConflict?: NameConflictPolicy;
 }
 
 export interface CreateUploadResult {
   ingotId: string;
   /** Forge tus endpoint plus upload-session token (ISTK) for the resumable upload. */
   forgeUrl: string;
+  /** The name the ingot is stored under: the server's numbered name under `new_name`. */
   name?: string;
   sizeBytes?: number;
   /**
-   * Whether the server minted this ingot (true) or handed back an existing
-   * row via its same-name upsert (false). Absent when the server did not say.
+   * Whether the server minted this ingot (true) or staged the upload onto
+   * the row already holding the name (false). Absent when the server did not say.
    */
   created?: boolean;
 }
@@ -196,29 +240,23 @@ interface IngotUploadInitResponse {
   created?: boolean;
 }
 
-interface IngotAuditLogEntry {
-  id?: string;
-  log_id?: string;
-  event_id?: string;
-  event_type?: string;
-  action?: string;
-  actor?: {
-    email?: string;
-    id?: string;
-    user_id?: string;
-    api_key_id?: string;
-  };
-  actor_email?: string;
-  actor_id?: string;
-  identity?: string;
-  ip_address?: string;
-  user_agent?: string;
-  timestamp?: number;
-  created_at?: number;
+/** An ingot audit entry in the server's public shape. */
+interface IngotAuditEntry {
+  timestamp: number;
+  event_type: string;
+  actor_id?: string | null;
+  actor_type?: string;
+  actor_display?: string;
+  ip_address?: string | null;
+  user_agent?: string | null;
+  metadata?: { identity?: string | null; [key: string]: unknown } | null;
+  encrypted?: boolean;
+  vault_id?: string;
+  ingot_id?: string;
 }
 
 interface IngotAuditLogsResponse {
-  entries?: IngotAuditLogEntry[];
+  entries?: IngotAuditEntry[];
   next_cursor?: string;
 }
 
@@ -243,6 +281,28 @@ function toTypedDownloadError(err: unknown): unknown {
   return err;
 }
 
+/**
+ * A create refused over its holder (`complete_pending` over a published one,
+ * `refuse` over any) answers 409 CONFLICT with `details.reason === 'NAME_HELD'`
+ * and the holder the server read. Every other 409 on the create (a folder
+ * being deleted, a cross-manager name) carries no holder and stays a plain
+ * `SparkVaultMobileError`.
+ */
+function toTypedCreateError(err: unknown): unknown {
+  if (!(err instanceof SparkVaultMobileError) || err.statusCode !== 409 || err.details?.reason !== 'NAME_HELD') {
+    return err;
+  }
+  const { ingot_id: ingotId, status, size_bytes: sizeBytes } = err.details;
+  if (typeof ingotId !== 'string' || typeof status !== 'string' || typeof sizeBytes !== 'number') {
+    return err;
+  }
+  return new IngotNameHeldError(err.message, {
+    holder: { ingotId, status, sizeBytes },
+    details: err.details,
+    meta: err.meta,
+  });
+}
+
 export class MobileIngotsClient {
   // Server-side finalization (encryption) of a just-uploaded ingot runs
   // asynchronously and scales with file size, so a large video can sit in
@@ -280,21 +340,23 @@ export class MobileIngotsClient {
       folder: options.folder,
       folderId: options.folderId,
       contentHmac: options.contentHmac,
+      onNameConflict: options.onNameConflict,
     });
     const created = init.created ?? true;
+    const name = init.name ?? options.name;
 
-    // The ingot row exists but no Forge session does: a caller that refuses
-    // to replace an existing ingot (created: false) aborts here, before a
-    // byte moves, and its error reaches it untouched.
-    options.onIngotCreated?.({ ingotId: init.ingotId, created });
+    // The placement is written but no Forge session exists yet: a throw from
+    // the hook stops the upload before a byte moves and reaches the caller
+    // untouched.
+    options.onIngotCreated?.({ ingotId: init.ingotId, created, name });
 
     await this.tus.uploadFromUri({
       fileUri: options.fileUri,
       fileSize: options.fileSize,
-      filename: options.name,
-      contentType: options.contentType,
+      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,
@@ -303,11 +365,15 @@ 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,
-      name: init.name ?? options.name,
+      name,
       size_bytes: init.sizeBytes ?? options.fileSize,
       storage_location: 's3',
       // A server that does not report it minted the row (the upsert is the
@@ -325,8 +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`.
+   * 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);
@@ -339,8 +407,8 @@ export class MobileIngotsClient {
       fileUri: options.fileUri,
       fileSize: options.fileSize,
       filename: options.name,
-      contentType: options.contentType,
       resume: options.session,
+      onSessionExpiry: options.onSessionExpiry,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
       onProgress: options.onProgress,
@@ -349,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,
@@ -366,10 +438,10 @@ export class MobileIngotsClient {
    * longer has it. Lets a caller reconcile sessions on relaunch — a session
    * at `offset === length` only needs its ingot verified, a lost one needs a
    * fresh `uploadFromUri` — without spending an upload slot to find out.
+   * 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);
   }
 
@@ -379,6 +451,8 @@ export class MobileIngotsClient {
    * the partial transfer's billing instead of waiting for expiry. Resolves
    * once the session is gone, including when Forge no longer had it
    * (404/410); any other failure rejects so the caller can retry later.
+   * An `uploadUrl` that is not an upload session on an allowed transfer host
+   * is refused (SparkVaultValidationError) before the ISTK is sent anywhere.
    */
   terminateUploadSession(session: { uploadUrl: string; istk: string }): Promise<void> {
     return this.tus.terminateSession(session);
@@ -406,11 +480,14 @@ export class MobileIngotsClient {
     if (options.contentHmac) {
       body.content_hmac = options.contentHmac;
     }
-    const response = await this.http.post<IngotUploadInitResponse>(
-      `/vaults/${options.vaultId}/ingots`,
-      body,
-      { vat: options.vat }
-    );
+    if (options.onNameConflict) {
+      body.on_name_conflict = options.onNameConflict;
+    }
+    const response = await this.http
+      .post<IngotUploadInitResponse>(apiPath`/vaults/${options.vaultId}/ingots`, body, { vat: options.vat })
+      .catch((err: unknown) => {
+        throw toTypedCreateError(err);
+      });
 
     if (!response.data.ingot_id || !response.data.forge_url) {
       throw new SparkVaultMobileError('Server returned invalid response for ingot creation');
@@ -435,7 +512,7 @@ export class MobileIngotsClient {
     }
 
     const response = await this.http.put<IngotUploadInitResponse>(
-      `/vaults/${vaultId}/ingots/${ingotId}`,
+      apiPath`/vaults/${vaultId}/ingots/${ingotId}`,
       {
         name,
         content_type: contentType,
@@ -453,10 +530,10 @@ export class MobileIngotsClient {
       fileUri,
       fileSize,
       filename: name,
-      contentType,
       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,
@@ -465,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,
@@ -490,7 +571,7 @@ export class MobileIngotsClient {
   ): Promise<HashCheckResponse> {
     validateVaultId(vaultId);
     const response = await this.http.post<HashCheckResponse>(
-      `/vaults/${vaultId}/ingots/hash-check`,
+      apiPath`/vaults/${vaultId}/ingots/hash-check`,
       { hashes },
       { vat }
     );
@@ -500,7 +581,7 @@ export class MobileIngotsClient {
   async rename(vaultId: string, ingotId: string, vat: string, name: string): Promise<Ingot> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
-    const response = await this.http.patch<Ingot>(`/vaults/${vaultId}/ingots/${ingotId}`, { name }, { vat });
+    const response = await this.http.patch<Ingot>(apiPath`/vaults/${vaultId}/ingots/${ingotId}`, { name }, { vat });
     return response.data;
   }
 
@@ -510,44 +591,37 @@ export class MobileIngotsClient {
     options?: { limit?: number; cursor?: string }
   ): Promise<ListIngotsResponse> {
     validateVaultId(vaultId);
-    const params = new URLSearchParams();
-    if (options?.limit) params.append('limit', options.limit.toString());
-    if (options?.cursor) params.append('cursor', options.cursor);
-
-    const query = params.toString();
-    const response = await this.http.get<ListIngotsResponse>(
-      query ? `/vaults/${vaultId}/ingots?${query}` : `/vaults/${vaultId}/ingots`,
-      { vat }
-    );
+    const response = await this.http.get<ListIngotsResponse>(apiPath`/vaults/${vaultId}/ingots`, {
+      vat,
+      query: { limit: options?.limit || undefined, cursor: options?.cursor },
+    });
     return response.data;
   }
 
+  /**
+   * List a folder, or the vault root, whole: the folder, its breadcrumb, its
+   * direct subfolders and every ingot directly in it, in one response.
+   */
   async listContents(
     vaultId: string,
     vat: string,
     options?: {
       folder_id?: string | null;
-      cursor?: string;
-      limit?: number;
+      /** Ingot sort field (name | size | content_type | created | access_count | bandwidth); `created` by default */
       sort_by?: string;
+      /** `desc` by default */
       sort_order?: 'asc' | 'desc';
-      type?: string;
     }
-  ): Promise<ListIngotsResponse> {
+  ): Promise<FolderContentsResponse> {
     validateVaultId(vaultId);
-    const params = new URLSearchParams();
-    if (options?.folder_id) params.append('folder_id', options.folder_id);
-    if (options?.cursor) params.append('cursor', options.cursor);
-    if (options?.limit) params.append('limit', options.limit.toString());
-    if (options?.sort_by) params.append('sort_by', options.sort_by);
-    if (options?.sort_order) params.append('sort_order', options.sort_order);
-    if (options?.type && options.type !== 'all') params.append('type', options.type);
-
-    const query = params.toString();
-    const response = await this.http.get<ListIngotsResponse>(
-      query ? `/vaults/${vaultId}/contents?${query}` : `/vaults/${vaultId}/contents`,
-      { vat }
-    );
+    const response = await this.http.get<FolderContentsResponse>(apiPath`/vaults/${vaultId}/contents`, {
+      vat,
+      query: {
+        folder_id: options?.folder_id,
+        sort_by: options?.sort_by,
+        sort_order: options?.sort_order,
+      },
+    });
     return response.data;
   }
 
@@ -566,35 +640,36 @@ export class MobileIngotsClient {
     }
   ): Promise<ListIngotsResponse> {
     validateVaultId(vaultId);
-    const params = new URLSearchParams();
-    if (options?.q) params.append('q', options.q);
-    if (options?.file_type && options.file_type !== 'all') params.append('file_type', options.file_type);
-    if (options?.folder_id) params.append('folder_id', options.folder_id);
-    if (options?.min_size !== undefined) params.append('min_size', options.min_size.toString());
-    if (options?.max_size !== undefined) params.append('max_size', options.max_size.toString());
-    if (options?.limit) params.append('limit', options.limit.toString());
-    if (options?.cursor) params.append('cursor', options.cursor);
-    if (options?.sort_order) params.append('sort_order', options.sort_order);
-
-    const query = params.toString();
-    const response = await this.http.get<ListIngotsResponse>(
-      query ? `/vaults/${vaultId}/ingots/search?${query}` : `/vaults/${vaultId}/ingots/search`,
-      { vat }
-    );
+    const response = await this.http.get<ListIngotsResponse>(apiPath`/vaults/${vaultId}/ingots/search`, {
+      vat,
+      query: {
+        q: options?.q,
+        file_type: options?.file_type === 'all' ? undefined : options?.file_type,
+        folder_id: options?.folder_id,
+        min_size: options?.min_size,
+        max_size: options?.max_size,
+        limit: options?.limit || undefined,
+        cursor: options?.cursor,
+        sort_order: options?.sort_order,
+      },
+    });
     return response.data;
   }
 
   async get(vaultId: string, ingotId: string, vat: string, options?: { consistent?: boolean }): Promise<Ingot> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
-    const response = await this.http.get<Ingot>(`/vaults/${vaultId}/ingots/${ingotId}${options?.consistent ? "?consistent=true" : ""}`, { vat });
+    const response = await this.http.get<Ingot>(apiPath`/vaults/${vaultId}/ingots/${ingotId}`, {
+      vat,
+      query: { consistent: options?.consistent ? 'true' : undefined },
+    });
     return response.data;
   }
 
   async delete(vaultId: string, ingotId: string, vat: string): Promise<void> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
-    await this.http.delete(`/vaults/${vaultId}/ingots/${ingotId}`, { vat });
+    await this.http.delete(apiPath`/vaults/${vaultId}/ingots/${ingotId}`, { vat });
   }
 
   /**
@@ -610,7 +685,7 @@ export class MobileIngotsClient {
 
     const response = await this.http
       .post<{ download_url?: string; content_version?: string | null }>(
-        `/vaults/${vaultId}/ingots/${ingotId}/download`,
+        apiPath`/vaults/${vaultId}/ingots/${ingotId}/download`,
         undefined,
         { vat }
       )
@@ -719,7 +794,7 @@ export class MobileIngotsClient {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
     const response = await this.http.get<IngotSharingConfig>(
-      `/vaults/${vaultId}/ingots/${ingotId}/sharing`,
+      apiPath`/vaults/${vaultId}/ingots/${ingotId}/sharing`,
       { vat }
     );
     return response.data;
@@ -737,7 +812,7 @@ export class MobileIngotsClient {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
     const response = await this.http.put<IngotSharingConfig>(
-      `/vaults/${vaultId}/ingots/${ingotId}/sharing`,
+      apiPath`/vaults/${vaultId}/ingots/${ingotId}/sharing`,
       config,
       { vat }
     );
@@ -754,7 +829,7 @@ export class MobileIngotsClient {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
     const response = await this.http.post<IngotInvite>(
-      `/vaults/${vaultId}/ingots/${ingotId}/sharing/invite`,
+      apiPath`/vaults/${vaultId}/ingots/${ingotId}/sharing/invite`,
       { identity, expires_in_seconds: options.expiresInSeconds },
       { vat }
     );
@@ -764,7 +839,8 @@ export class MobileIngotsClient {
   async revokeInvite(vaultId: string, ingotId: string, vat: string, inviteId: string): Promise<void> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
-    await this.http.delete(`/vaults/${vaultId}/ingots/${ingotId}/sharing/invite/${inviteId}`, { vat });
+    validateResourceId(inviteId, 'invite ID', 'inviteId');
+    await this.http.delete(apiPath`/vaults/${vaultId}/ingots/${ingotId}/sharing/invite/${inviteId}`, { vat });
   }
 
   async getAccessLogs(
@@ -775,22 +851,25 @@ export class MobileIngotsClient {
   ): Promise<{ logs: IngotAccessLog[]; next_cursor?: string }> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
-    const params = new URLSearchParams();
-    if (options?.limit) params.append('limit', options.limit.toString());
-    if (options?.cursor) params.append('cursor', options.cursor);
-
-    const query = params.toString();
     const response = await this.http.get<IngotAuditLogsResponse>(
-      query
-        ? `/vaults/${vaultId}/ingots/${ingotId}/audit-logs?${query}`
-        : `/vaults/${vaultId}/ingots/${ingotId}/audit-logs`,
-      { vat }
+      apiPath`/vaults/${vaultId}/ingots/${ingotId}/audit-logs`,
+      {
+        vat,
+        query: {
+          limit: options?.limit || undefined,
+          cursor: options?.cursor,
+          event_types: INGOT_ACCESS_EVENT_TYPES.join(','),
+        },
+      }
     );
-    const entries = response.data.entries ?? [];
-    return {
-      logs: entries.map(entry => this.toAccessLog(entry)),
-      next_cursor: response.data.next_cursor,
-    };
+    const logs: IngotAccessLog[] = [];
+    for (const entry of response.data.entries ?? []) {
+      const access = readIngotAccess(entry);
+      if (access) {
+        logs.push({ log_id: String(access.timestamp), ...access });
+      }
+    }
+    return { logs, next_cursor: response.data.next_cursor };
   }
 
   async getAccessStats(vaultId: string, ingotId: string, vat: string): Promise<IngotAccessStats> {
@@ -813,39 +892,39 @@ 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 `failed` status throws (a genuine server encryption error the
-   * caller should surface). A still-`processing` 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);
 
     while (ingot.status !== 'active') {
-      if (ingot.status === 'failed') {
-        throw new SparkVaultMobileError('Upload failed: server encryption error');
-      }
-
       const remaining = deadline - Date.now();
       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)));
@@ -856,28 +935,6 @@ export class MobileIngotsClient {
     return ingot;
   }
 
-  private toAccessLog(entry: IngotAuditLogEntry): IngotAccessLog {
-    const eventType = entry.event_type ?? entry.action ?? '';
-    const action = eventType.includes('download') ? 'download' : 'view';
-    const actor = entry.actor;
-    return {
-      log_id: entry.log_id ?? entry.event_id ?? entry.id ?? String(entry.timestamp ?? entry.created_at ?? ''),
-      action,
-      identity:
-        actor?.email ??
-        entry.actor_email ??
-        entry.identity ??
-        actor?.id ??
-        actor?.user_id ??
-        actor?.api_key_id ??
-        entry.actor_id ??
-        'Unknown',
-      ip_address: entry.ip_address ?? '',
-      user_agent: entry.user_agent ?? '',
-      timestamp: entry.timestamp ?? entry.created_at ?? 0,
-    };
-  }
-
   private async verifyDownloadedFile(
     fileDownloader: MobileFileDownloader,
     preferredUri: string,
@@ -953,26 +1010,14 @@ export class MobileIngotsClient {
     });
   }
 
+  /** Refuse a download link that is not a Forge decrypt URL on a trusted host (forge-url's rule). */
   private validateDownloadUrl(downloadUrl: string): void {
-    let url: URL;
-    try {
-      url = new URL(downloadUrl);
-    } catch {
-      throw new SparkVaultValidationError('Invalid download URL from server');
-    }
-
-    if (url.protocol !== 'https:') {
-      throw new SparkVaultValidationError('Invalid download URL from server', {
-        reason: 'non_https_download_url',
-      });
-    }
-
-    const allowed = this.config.allowedDownloadHostPatterns.some(pattern => pattern.test(url.hostname));
-    if (!allowed) {
-      throw new SparkVaultValidationError('Invalid download URL from server', {
-        reason: 'download_host_not_allowed',
-        hostname: url.hostname,
-      });
+    const read = readForgeTransferUrl(downloadUrl, {
+      operation: 'decrypt',
+      isAllowedHost: allowsHost(this.config.allowedDownloadHostPatterns),
+    });
+    if (!read.ok) {
+      throw new SparkVaultValidationError('Invalid download URL from server', { reason: read.reason });
     }
   }