@sparkvault/sdk-mobile 7.1.11 → 7.1.13

package/src/ingots.ts

@@ -121,8 +121,12 @@ export interface UploadFromUriOptions extends UploadOptions {
   debug?: DebugLogger;
 }
 
-/** 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, 'name' | 'onNameConflict' | 'onIngotCreated'> {
+/**
+ * A replace addresses its ingot by id: no name is placed and the ingot stays
+ * in its folder, so the create-only hooks and the folder target do not apply.
+ */
+export interface ReplaceFromUriOptions
+  extends Omit<UploadFromUriOptions, 'name' | 'folder' | 'folderId' | 'onNameConflict' | 'onIngotCreated'> {
   ingotId: string;
   /**
    * A new name for the ingot, stored in the same request as the content.
@@ -195,11 +199,6 @@ export interface DownloadToFileResult {
   sizeBytes: number;
 }
 
-export interface AddInviteOptions {
-  /** Invite lifetime in seconds. Omit to inherit the link's existing expiry. */
-  expiresInSeconds?: number;
-}
-
 export interface CreateUploadOptions {
   vaultId: string;
   vat: string;
@@ -330,6 +329,22 @@ function publicationOf(ingot: Ingot): Pick<UploadResult, 'content_version'> {
   return { content_version: ingot.content_version ?? null };
 }
 
+/** A response header's value by name, whatever case the adapter spelled it in; undefined when absent. */
+function headerOf(headers: Record<string, string> | undefined, name: string): string | undefined {
+  return Object.entries(headers ?? {}).find(([header]) => header.toLowerCase() === name)?.[1];
+}
+
+/**
+ * The body length a response declared (`Content-Length`), or undefined when
+ * it declared none, or something that is not a non-negative whole number.
+ */
+function declaredLengthOf(headers: Record<string, string> | undefined): number | undefined {
+  const declared = headerOf(headers, 'content-length');
+  if (declared === undefined || !/^\d+$/.test(declared.trim())) return undefined;
+  const length = Number(declared);
+  return Number.isSafeInteger(length) ? length : undefined;
+}
+
 /**
  * Forge's id for an upload: the last segment of its session URL, where
  * resolveForgeSessionUrl placed the session Forge's create answered with.
@@ -411,7 +426,6 @@ export class MobileIngotsClient {
       ingot_id: init.ingotId,
       name,
       size_bytes: init.sizeBytes ?? options.fileSize,
-      storage_location: 's3',
       // A server that does not report it minted the row (the upsert is the
       // only other outcome, and it always says so).
       created,
@@ -464,7 +478,6 @@ export class MobileIngotsClient {
       ingot_id: options.ingotId,
       name: options.name,
       size_bytes: options.fileSize,
-      storage_location: 's3',
       created: false,
       status: ingot.status,
       ...publicationOf(ingot),
@@ -600,7 +613,6 @@ export class MobileIngotsClient {
       ingot_id: response.data.ingot_id,
       name,
       size_bytes: fileSize,
-      storage_location: 's3',
       // A replace never mints an ingot: the row is the caller's existing one.
       created: false,
       status: ingot.status,
@@ -799,11 +811,11 @@ export class MobileIngotsClient {
             result.uri,
             fileUri,
             result.sizeBytes,
-            expectedSizeBytes
+            expectedSizeBytes,
+            declaredLengthOf(result.headers)
           );
           // Bind cached metadata to the actual stream, never the earlier URL response.
-          const contentVersion = Object.entries(result.headers ?? {})
-            .find(([name]) => name.toLowerCase() === 'x-content-version')?.[1] || null;
+          const contentVersion = headerOf(result.headers, 'x-content-version') || null;
           if (options.expectedContentVersion && contentVersion && options.expectedContentVersion !== contentVersion) {
             await this.deleteFileIfPresent(fileDownloader, verified.filePath);
             throw new SparkVaultMobileError('File changed while downloading. Please try again.', {
@@ -868,18 +880,12 @@ export class MobileIngotsClient {
     return response.data;
   }
 
-  async addInvite(
-    vaultId: string,
-    ingotId: string,
-    vat: string,
-    identity: string,
-    options: AddInviteOptions = {}
-  ): Promise<IngotInvite> {
+  async addInvite(vaultId: string, ingotId: string, vat: string, identity: string): Promise<IngotInvite> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
     const response = await this.http.post<IngotInvite>(
       apiPath`/vaults/${vaultId}/ingots/${ingotId}/sharing/invite`,
-      { identity, expires_in_seconds: options.expiresInSeconds },
+      { identity },
       { vat }
     );
     return response.data;
@@ -925,19 +931,7 @@ export class MobileIngotsClient {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
     const ingot = await this.get(vaultId, ingotId, vat);
-    return {
-      total_downloads: ingot.access_count ?? 0,
-      last_accessed_at: ingot.last_accessed_at ?? ingot.accessed_at,
-    };
-  }
-
-  async purgeAccessLogs(vaultId: string, ingotId: string, vat: string): Promise<void> {
-    validateVaultId(vaultId);
-    validateIngotId(ingotId);
-    void vat;
-    throw new SparkVaultValidationError(
-      'Ingot audit logs are read-only. Configure vault access-log retention to expire old entries.'
-    );
+    return { total_downloads: ingot.access_count ?? 0 };
   }
 
   /**
@@ -992,12 +986,24 @@ export class MobileIngotsClient {
     return ingot;
   }
 
+  /**
+   * The staged file is the download only when its length is the file's. The
+   * caller's `expectedSizeBytes` (the ingot's `size_bytes`) is the length the
+   * vault lists, so a file of any other length is the wrong content for good
+   * (SparkVaultValidationError, never retried). Without it, the response's own
+   * `Content-Length` stands in: a body that ended cleanly short of it is a
+   * transfer some hop cut and reframed, not the file, so the file goes and the
+   * attempt fails as a transport failure does (`download_truncated`, retried
+   * on a fresh link). A response that declares no length can only be checked
+   * for being non-empty.
+   */
   private async verifyDownloadedFile(
     fileDownloader: MobileFileDownloader,
     preferredUri: string,
     expectedUri: string,
     knownSizeBytes?: number,
-    expectedSizeBytes?: number
+    expectedSizeBytes?: number,
+    declaredSizeBytes?: number
   ): Promise<DownloadToFileResult> {
     const filePath = preferredUri || expectedUri;
     const info = await fileDownloader.getInfo(filePath);
@@ -1011,14 +1017,22 @@ export class MobileIngotsClient {
       throw new SparkVaultMobileError('Download failed - file is empty');
     }
 
-    if (expectedSizeBytes !== undefined && expectedSizeBytes > 0 && sizeBytes !== expectedSizeBytes) {
+    if (expectedSizeBytes !== undefined && expectedSizeBytes > 0) {
+      if (sizeBytes !== expectedSizeBytes) {
+        await this.deleteFileIfPresent(fileDownloader, filePath);
+        // Deterministic server-content mismatch — retrying the same ingot will
+        // yield the same bytes, so this must surface as a non-retryable validation
+        // failure rather than a transient transport error.
+        throw new SparkVaultValidationError('Download failed - file size did not match expected ingot size', {
+          expectedSizeBytes,
+          actualSizeBytes: sizeBytes,
+        });
+      }
+    } else if (declaredSizeBytes !== undefined && sizeBytes !== declaredSizeBytes) {
       await this.deleteFileIfPresent(fileDownloader, filePath);
-      // Deterministic server-content mismatch — retrying the same ingot will
-      // yield the same bytes, so this must surface as a non-retryable validation
-      // failure rather than a transient transport error.
-      throw new SparkVaultValidationError('Download failed - file size did not match expected ingot size', {
-        expectedSizeBytes,
-        actualSizeBytes: sizeBytes,
+      throw new SparkVaultMobileError('Download failed - the file is not the length the server declared', {
+        code: 'download_truncated',
+        details: { declaredSizeBytes, actualSizeBytes: sizeBytes },
       });
     }
 

package/src/products/identity.ts

@@ -20,9 +20,8 @@ import type {
   PasskeyRegisterChallenge,
   PasskeySession,
   PasskeyStatus,
-  RequestPinRequest,
-  RequestPinResponse,
   SendOtpRequest,
+  SendOtpResponse,
   SparkVaultUser,
   SubmitSecondFactorRequest,
   VerifyOtpRequest,
@@ -127,10 +126,6 @@ export class MobileIdentityClient {
     }
   }
 
-  isConfigPreloaded(): boolean {
-    return this.configCache !== null;
-  }
-
   async getJwks(options: { forceRefresh?: boolean } = {}): Promise<IdentityJwks> {
     const now = Date.now();
     const expired = now - this.jwksCachedAt > JWKS_CACHE_TTL_MS;
@@ -247,31 +242,14 @@ export class MobileIdentityClient {
     return key;
   }
 
-  async sendOtp(request: SendOtpRequest): Promise<RequestPinResponse> {
+  async sendOtp(request: SendOtpRequest): Promise<SendOtpResponse> {
     const identity = this.normalizeIdentity(request.identity, request.identityType);
-    const result = await this.postIdentity<{
-      kindling: string;
-      expires_at?: number;
-      retry_after?: number;
-    }>(apiPath`/otp/send`, {
+    const result = await this.postIdentity<SendOtpResponse>(apiPath`/otp/send`, {
       recipient: identity,
       method: request.method,
     });
 
-    return {
-      kindling: result.kindling,
-      expires_at: result.expires_at ?? Math.floor(Date.now() / 1000) + 900,
-      retry_after: result.retry_after,
-      is_signup: false,
-    };
-  }
-
-  async requestPin(request: RequestPinRequest): Promise<RequestPinResponse> {
-    return this.sendOtp({
-      identity: request.email,
-      identityType: 'email',
-      method: 'email',
-    });
+    return { kindling: result.kindling, expires_at: result.expires_at };
   }
 
   async verifyOtp(request: VerifyOtpRequest): Promise<IdentityVerifyResult> {
@@ -371,7 +349,12 @@ export class MobileIdentityClient {
     }
   }
 
-  async getPasskeyAuthOptions(_identity?: string, _identityType?: IdentityType): Promise<PasskeyAuthChallenge> {
+  /**
+   * Start a discoverable passkey ceremony: the request names no identity, so
+   * the authenticator offers every passkey it holds for the Identity relying
+   * party, and the one chosen names its person (its user handle is the SVID).
+   */
+  async getPasskeyAuthOptions(): Promise<PasskeyAuthChallenge> {
     return this.postIdentity<PasskeyAuthChallenge>(apiPath`/passkey/verify`, {});
   }
 
@@ -507,9 +490,7 @@ export class MobileIdentityClient {
         recipient: this.normalizeIdentity(request.recipient, inferIdentityType(request.recipient)),
       });
     } catch (err) {
-      const apiError = err as SparkVaultMobileError & {
-        data?: { kindling?: string; expires_at?: number };
-      };
+      const apiError = err as SparkVaultMobileError;
       const message = apiError.message || 'Verification failed';
       const code = apiError.statusCode ?? apiError.code;
 
@@ -599,15 +580,10 @@ export class MobileIdentityClient {
     return (data.data ?? data) as T;
   }
 
-  private async postIdentity<T>(
-    path: ApiPath,
-    body: Record<string, unknown>,
-    options: { bearerToken?: string } = {}
-  ): Promise<T> {
-    const headers = this.identityHeaders(options.bearerToken);
+  private async postIdentity<T>(path: ApiPath, body: Record<string, unknown>): Promise<T> {
     const response = await this.config.fetch(identityUrl(this.config, path), {
       method: 'POST',
-      headers,
+      headers: this.identityHeaders(),
       body: JSON.stringify(body),
       timeoutMs: this.config.timeoutMs,
     });
@@ -615,30 +591,24 @@ export class MobileIdentityClient {
     if (!response.ok) {
       const errorBody = await response.json().catch(() => ({} as ApiErrorBody));
       const message = errorBody.error?.message ?? errorBody.message ?? 'Identity verification failed';
-      const error = new SparkVaultMobileError(message, {
+      throw new SparkVaultMobileError(message, {
         code: errorBody.error?.code ?? response.status,
         statusCode: response.status,
         details: errorBody.error?.details,
         meta: errorBody.meta,
       });
-      (error as SparkVaultMobileError & { data?: unknown }).data = errorBody.data ?? errorBody;
-      throw error;
     }
 
     const data = await response.json();
     return (data.data ?? data) as T;
   }
 
-  private identityHeaders(bearerToken?: string): Record<string, string> {
-    const headers: Record<string, string> = {
+  private identityHeaders(): Record<string, string> {
+    return {
       'Content-Type': 'application/json',
       Accept: 'application/json',
       'User-Agent': this.config.userAgent,
     };
-    if (bearerToken) {
-      headers.Authorization = `Bearer ${bearerToken}`;
-    }
-    return headers;
   }
 
   private identityLookupBody(identity: string, identityType?: IdentityType): Record<string, string> {

package/src/sparks.ts

@@ -3,10 +3,10 @@ import type { ShareSparkResponse, SparkShareStatus, UnshareSparkResponse } from
 import { apiPath } from './request-path.js';
 import { validateResourceId } from './validation.js';
 
+/** A Spark as GET /sparks lists it: never its payload, which only `get` reads. */
 export interface Spark {
   spark_id: string;
   status: string;
-  payload?: string;
   content_type?: string;
 }
 
@@ -37,7 +37,6 @@ export interface CreateSparkOptions {
    */
   ttlMinutes?: number;
   kindling?: string;
-  name?: string;
 }
 
 export interface CreateSparkResponse {
@@ -79,7 +78,6 @@ export class MobileSparksClient {
       content_type: options.contentType,
       ttl_minutes: options.ttlMinutes,
       kindling: options.kindling,
-      name: options.name,
     });
     return response.data;
   }

package/src/tus.ts

@@ -37,7 +37,6 @@ import type {
 } from './types.js';
 
 export interface ParsedForgeUrl {
-  baseUrl: string;
   tusEndpoint: string;
   istk: string;
 }
@@ -169,11 +168,7 @@ export function parseForgeUrl(
       reason: read.reason,
     });
   }
-  return {
-    baseUrl: read.origin,
-    tusEndpoint: read.endpoint,
-    istk: read.istk,
-  };
+  return { tusEndpoint: read.endpoint, istk: read.istk };
 }
 
 /**

package/src/types.ts

@@ -48,16 +48,9 @@ export interface ApiErrorBody {
     details?: Record<string, unknown>;
   };
   message?: string;
-  data?: unknown;
   meta?: ApiMeta;
 }
 
-export interface RateLimitInfo {
-  limit: number;
-  remaining: number;
-  reset: number;
-}
-
 /** Account-scoped role. Owners and admins manage the organization and team. */
 export type OrgRole = 'owner' | 'admin' | 'user';
 
@@ -282,7 +275,6 @@ export interface IdentityBranding {
   companyName: string | null;
   logoLight: string | null;
   logoDark: string | null;
-  backdrop_blur?: boolean;
   themeMode?: 'light' | 'dark';
 }
 
@@ -380,52 +372,37 @@ export interface VerifyOtpRequest {
   recipient: string;
 }
 
-export interface RequestPinRequest {
-  email: string;
-  organization_name?: string;
-}
-
-export interface RequestPinResponse {
+/** A code sent: the kindling its verify names, and when the code expires (Unix seconds). */
+export interface SendOtpResponse {
   kindling: string;
   expires_at: number;
-  retry_after?: number;
-  is_signup: boolean;
 }
 
 export interface PinVerifyLoginResponse {
   access_token: string;
   refresh_token: string;
-  token_type: 'Bearer';
-  expires_in: number;
   user: SparkVaultUser;
 }
 
+/**
+ * A verified identity with no SparkVault user yet: `signup_token` (an
+ * identity-only access token) authorizes `account.completeSignup`.
+ */
 export interface PinVerifySignupPendingResponse {
   verified: true;
   needs_signup_info: true;
   signup_token: string;
-  expires_at: number;
 }
 
 /**
- * Variant of the Core exchange result indicating the account has 2FA enabled:
- * the caller must collect a second factor via
- * `products.identity.submitSecondFactor({ ticket, code })` and re-exchange the
- * resulting Identity token via `account.exchangeIdentityToken`.
+ * The Core exchange of a verified Identity token. A second factor is collected
+ * at the Identity Product before its token exists (`products.identity.verifyOtp`
+ * throws for it, and `submitSecondFactor` finishes it), so the exchange is a
+ * login or a pending signup, never a second-factor challenge.
  */
-export interface PinVerifySecondFactorPendingResponse {
-  verified: false;
-  second_factor_required: true;
-  /** Opaque pending-login handle to submit the second factor against. */
-  ticket: string;
-  /** Methods the user may use, e.g. ['authenticator','recovery_code']. */
-  methods: string[];
-}
-
 export type PinVerifyResponse =
   | PinVerifyLoginResponse
-  | PinVerifySignupPendingResponse
-  | PinVerifySecondFactorPendingResponse;
+  | PinVerifySignupPendingResponse;
 
 export interface SubmitSecondFactorRequest {
   /** Pending-login ticket from a second_factor_required response. */
@@ -442,8 +419,6 @@ export interface CompleteSignupRequest {
 export interface CompleteSignupResponse {
   access_token: string;
   refresh_token: string;
-  token_type?: 'Bearer';
-  expires_in?: number;
   user: SparkVaultUser;
   account: SparkVaultAccount;
 }
@@ -454,10 +429,14 @@ export interface PasskeyAuthOptions {
   challenge: string;
   timeout: number;
   rpId: string;
+  /**
+   * The person's credentials when the ceremony is scoped to an identifier:
+   * ids only, since a transport list would hand an unauthenticated probe a
+   * device fingerprint.
+   */
   allowCredentials?: Array<{
     id: string;
     type: 'public-key';
-    transports?: string[];
   }>;
   userVerification: 'required' | 'preferred' | 'discouraged';
 }
@@ -523,15 +502,15 @@ export interface PasskeyCredential {
 
 export interface PasskeyStatus {
   has_passkey: boolean;
-  registered_at?: number;
-  last_used_at?: number;
 }
 
+/**
+ * POST /auth/identity/verify: a session for the verified identity's member, or,
+ * with `user` and `account` null, an identity-only token for a signup.
+ */
 export interface IdentitySessionResponse {
   access_token: string;
   refresh_token: string;
-  token_type?: 'Bearer';
-  expires_in?: number;
   user: SparkVaultUser | null;
   account: SparkVaultAccount | null;
 }
@@ -549,18 +528,16 @@ export interface Vault {
   unseal_count?: number;
 }
 
+/** A vault is created with its name alone; a description is set with `update`. */
 export interface CreateVaultRequest {
   name: string;
-  description?: string;
 }
 
 export interface CreateVaultResponse {
   vault_id: string;
   name: string;
-  description?: string;
   vmk: string;
   vmk_warning: string;
-  status: 'sealed';
   created_at: number;
 }
 
@@ -700,7 +677,6 @@ export interface Ingot {
   name: string;
   content_type: string;
   size_bytes: number;
-  storage_location: 'dynamodb' | 's3';
   /** `uploading` until Forge activates the upload, then `active`. */
   status?: 'uploading' | 'active';
   folder_id?: string | null;
@@ -712,10 +688,7 @@ export interface Ingot {
    */
   managed_by?: string | null;
   created_at: number;
-  accessed_at?: number;
-  last_accessed_at?: number;
   access_count?: number;
-  expires_at?: number;
   /**
    * Client-computed, vault-keyed HMAC of the plaintext (43-char base64url),
    * or null when the uploader did not supply one. Used for upload dedup and
@@ -736,9 +709,14 @@ export interface HashCheckResponse {
   found: HashCheckMatch[];
 }
 
+/**
+ * One page of GET /vaults/:id/ingots or /ingots/search. `count` is this
+ * page's length: the server reports no total.
+ */
 export interface ListIngotsResponse {
   ingots: Ingot[];
-  total: number;
+  count: number;
+  has_more: boolean;
   next_cursor?: string;
 }
 
@@ -762,7 +740,6 @@ export interface UploadResult {
    */
   name: string;
   size_bytes: number;
-  storage_location: 's3';
   /**
    * Whether this upload minted the ingot (true) or went into an existing row
    * (false): the one holding the name, as the create's name-conflict policy
@@ -842,8 +819,6 @@ export interface IngotAccessLog {
 
 export interface IngotAccessStats {
   total_downloads: number;
-  unique_visitors?: number;
-  last_accessed_at?: number;
 }
 
 /** A folder as every folder route answers it (Core's FolderRepository.toPublicFormat). */
@@ -886,16 +861,13 @@ export interface TokenStorageAdapter {
   clearTokens(): Promise<void>;
   getUser?<T = SparkVaultUser>(): Promise<T | null>;
   setUser?<T = SparkVaultUser>(user: T): Promise<void>;
-  getAccount?<T = SparkVaultAccount>(): Promise<T | null>;
   setAccount?<T = SparkVaultAccount>(account: T): Promise<void>;
-  clearAll?(): Promise<void>;
 }
 
 export type FetchLike = (
   url: string,
   options?: RequestInit & {
     timeoutMs?: number;
-    responseType?: XMLHttpRequestResponseType;
   }
 ) => Promise<Response>;
 
@@ -1106,7 +1078,6 @@ export interface MobileFileDownloader {
 
 export interface DebugLogger {
   log(message: string): void;
-  warn(message: string): void;
   error(message: string): void;
   success(message: string): void;
 }

package/src/vaults.test-d.ts

@@ -7,11 +7,13 @@
  * `*.test.ts`, which tsconfig excludes.
  *
  * Mirrored server sources: apps/api/src/folders/list.js (listFolders answers
- * `{ folders }`, the whole list and nothing else) and apps/api/src/vaults/list.js
- * (one page: `{ vaults, count, has_more, next_cursor? }`).
+ * `{ folders }`, the whole list and nothing else), apps/api/src/vaults/list.js
+ * (one page: `{ vaults, count, has_more, next_cursor? }`) and
+ * apps/api/src/vaults/create.js (createVault answers `{ vault_id, name, vmk,
+ * vmk_warning, created_at }`).
  */
 
-import type { ListFoldersResponse, ListVaultsResponse } from './types.js';
+import type { CreateVaultResponse, ListFoldersResponse, ListVaultsResponse } from './types.js';
 
 /** Fails to compile unless `T` resolves to exactly `true`. */
 type Assert<T extends true> = T;
@@ -26,4 +28,5 @@ export type VaultsWireContract = [
   // never sends would read as undefined wherever a caller trusted it.
   Assert<Equals<keyof ListFoldersResponse, 'folders'>>,
   Assert<Equals<keyof ListVaultsResponse, 'vaults' | 'count' | 'has_more' | 'next_cursor'>>,
+  Assert<Equals<keyof CreateVaultResponse, 'vault_id' | 'name' | 'vmk' | 'vmk_warning' | 'created_at'>>,
 ];

package/src/vaults.ts

@@ -41,13 +41,9 @@ export class MobileVaultsClient {
     return response.data;
   }
 
-  async list(options?: {
-    status?: 'sealed' | 'unsealed';
-    limit?: number;
-    cursor?: string;
-  }): Promise<ListVaultsResponse> {
+  async list(options?: { limit?: number; cursor?: string }): Promise<ListVaultsResponse> {
     const response = await this.http.get<ListVaultsResponse>(apiPath`/vaults`, {
-      query: { status: options?.status, limit: options?.limit || undefined, cursor: options?.cursor },
+      query: { limit: options?.limit || undefined, cursor: options?.cursor },
     });
     return response.data;
   }
@@ -58,11 +54,11 @@ export class MobileVaultsClient {
    * filtered down to nothing still carries a cursor. A failed page fails the
    * listing: a vault picker must never show a silently partial account.
    */
-  async listAll(options?: { status?: 'sealed' | 'unsealed' }): Promise<Vault[]> {
+  async listAll(): Promise<Vault[]> {
     const vaults: Vault[] = [];
     let cursor: string | undefined;
     do {
-      const page = await this.list({ ...options, limit: VAULT_LIST_PAGE_LIMIT, cursor });
+      const page = await this.list({ limit: VAULT_LIST_PAGE_LIMIT, cursor });
       vaults.push(...page.vaults);
       cursor = page.has_more ? page.next_cursor : undefined;
     } while (cursor);