@sparkvault/sdk-mobile 6.0.2 → 7.0.0

package/src/ingots.ts

@@ -1,12 +1,15 @@
+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,
 } from './errors.js';
 import type { MobileHttpClient } from './http.js';
-import { MobileTusUploader } from './tus.js';
+import { allowsHost, MobileTusUploader } from './tus.js';
 import type {
   DebugLogger,
   HashCheckResponse,
@@ -16,6 +19,7 @@ import type {
   IngotInvite,
   IngotSharingConfig,
   ListIngotsResponse,
+  FolderContentsResponse,
   IngotUploadSession,
   MobileFileDownloader,
   UploadAbortBehavior,
@@ -24,7 +28,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,14 +78,19 @@ 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
@@ -86,7 +114,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,7 +127,6 @@ export interface ResumeUploadOptions {
   fileUri: string;
   fileSize: number;
   name: string;
-  contentType: string;
   /** The persisted tus session handed to `onSessionCreated`. */
   session: { uploadUrl: string; istk: string };
   /** See `UploadTransport`; default `foreground`. */
@@ -161,17 +189,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 +227,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 +268,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,19 +327,20 @@ 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 }),
       transport: options.transport,
@@ -307,7 +355,7 @@ export class MobileIngotsClient {
 
     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
@@ -326,7 +374,9 @@ export class MobileIngotsClient {
    *
    * A `TusUploadError` with `sessionLost` means Forge no longer has the
    * session (expired or terminated); the caller drops it and starts over
-   * with `uploadFromUri`.
+   * 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,7 +389,6 @@ export class MobileIngotsClient {
       fileUri: options.fileUri,
       fileSize: options.fileSize,
       filename: options.name,
-      contentType: options.contentType,
       resume: options.session,
       transport: options.transport,
       transferPolicy: options.transferPolicy,
@@ -366,6 +415,8 @@ 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 }
@@ -379,6 +430,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 +459,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 +491,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,7 +509,6 @@ 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 }),
@@ -490,7 +545,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 +555,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 +565,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 +614,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 +659,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 +768,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 +786,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 +803,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 +813,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 +825,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> {
@@ -817,8 +870,7 @@ export class MobileIngotsClient {
    *
    * 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
+   * 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
@@ -835,10 +887,6 @@ export class MobileIngotsClient {
     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(
@@ -856,28 +904,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 +979,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 });
     }
   }
 

package/src/mutex.ts

@@ -1,7 +1,6 @@
+/** Runs one operation at a time; callers arriving while it runs share its result. */
 export interface DedupMutex<T> {
   dedupe(fn: () => Promise<T>): Promise<T>;
-  isRunning(): boolean;
-  reset(): void;
 }
 
 export function createDedupMutex<T>(): DedupMutex<T> {
@@ -16,11 +15,5 @@ export function createDedupMutex<T>(): DedupMutex<T> {
       }
       return current;
     },
-    isRunning(): boolean {
-      return current !== null;
-    },
-    reset(): void {
-      current = null;
-    },
   };
 }

package/src/notify.test-d.ts

@@ -11,7 +11,7 @@
  * which would put these assertions exactly where the compiler cannot see them.
  *
  * The row shape is shared verbatim with `@sparkvault/sdk-js`, whose own contract
- * file asserts the same three members — both must move together, and the mirrored
+ * file asserts the same four members — both must move together, and the mirrored
  * server source is `apps/api/src/notify/inbox.js` (`projectRow`).
  */
 
@@ -39,4 +39,6 @@ export type NotifyWireContract = [
   // The pointer is withheld on a recalled row and absent on a cleartext one, so
   // it is optional in both directions and must be guarded before use.
   Assert<Equals<NotificationRow['sparklink_code'], string | undefined>>,
+  // The URL the pointer opens travels with it: absent exactly when the pointer is.
+  Assert<Equals<NotificationRow['pointer_url'], string | undefined>>,
 ];