@sparkvault/sdk-mobile 0.3.3 → 1.0.1

package/src/auth.ts

@@ -25,6 +25,7 @@ import type {
   SendTotpRequest,
   SparkVaultAccount,
   SparkVaultUser,
+  SubmitSecondFactorRequest,
   VerifyTotpRequest,
 } from './types.js';
 import nacl from 'tweetnacl';
@@ -39,6 +40,12 @@ interface IdentityVerificationResponse {
   kindling?: string;
   expires_at?: number;
   retry_after?: number;
+  /** Primary factor passed, second factor still owed. */
+  second_factor_required?: boolean;
+  /** Pending-login handle for the second-factor submit. */
+  ticket?: string;
+  /** Offered second-factor methods. */
+  methods?: string[];
 }
 
 interface IdentityPasskeyCompletionResponse {
@@ -171,9 +178,6 @@ export class MobileAuthClient {
     if (claims.nbf !== undefined && claims.nbf - clockSkewSeconds > now) {
       throw new SparkVaultValidationError('Identity token is not valid yet');
     }
-    if (typeof claims.nbf === 'number' && claims.nbf > now + clockSkewSeconds) {
-      throw new SparkVaultValidationError('Identity token is not yet valid');
-    }
 
     const expectedIssuer = `${this.config.identityBaseUrl}/${this.config.identityAccountId}`;
     if (claims.iss !== expectedIssuer) {
@@ -249,23 +253,15 @@ export class MobileAuthClient {
 
   async verifyTotp(request: VerifyTotpRequest): Promise<IdentityVerifyResult> {
     const verifyResult = await this.verifyTotpWithRetryErrors(request);
-    if (!verifyResult.verified || !verifyResult.token) {
-      if (verifyResult.kindling) {
-        const error = new SparkVaultMobileError('Invalid code. Please try again.', {
-          code: 400,
-          statusCode: 400,
-        });
-        (error as SparkVaultMobileError & { data?: unknown }).data = {
-          kindling: verifyResult.kindling,
-          expires_at: verifyResult.expires_at,
-        };
-        throw error;
-      }
 
-      throw new SparkVaultMobileError('Verification failed. Please request a new code.', {
-        code: 400,
-        statusCode: 400,
-      });
+    // PIN accepted, but the account requires a second factor. Surface the
+    // ticket so the caller can collect a code and call submitSecondFactor().
+    if (verifyResult.second_factor_required && verifyResult.ticket) {
+      throw this.secondFactorError(verifyResult.ticket, verifyResult.methods);
+    }
+
+    if (!verifyResult.verified || !verifyResult.token) {
+      this.throwVerificationFailure(verifyResult);
     }
 
     return this.toIdentityVerifyResult(verifyResult.token, {
@@ -279,26 +275,94 @@ export class MobileAuthClient {
   async verifyPin(request: PinVerifyRequest): Promise<PinVerifyResponse> {
     const verifyResult = await this.verifyTotpWithRetryErrors(request);
 
+    // PIN accepted, but 2FA is required. Return a pending result so the caller
+    // can collect a second factor and call completeSecondFactorPin().
+    if (verifyResult.second_factor_required && verifyResult.ticket) {
+      return {
+        verified: false,
+        second_factor_required: true,
+        ticket: verifyResult.ticket,
+        methods: verifyResult.methods ?? ['authenticator'],
+      };
+    }
+
     if (!verifyResult.verified || !verifyResult.token) {
-      if (verifyResult.kindling) {
-        const error = new SparkVaultMobileError('Invalid code. Please try again.', {
-          code: 400,
-          statusCode: 400,
-        });
-        (error as SparkVaultMobileError & { data?: unknown }).data = {
-          kindling: verifyResult.kindling,
-          expires_at: verifyResult.expires_at,
-        };
-        throw error;
-      }
+      this.throwVerificationFailure(verifyResult);
+    }
+
+    return this.exchangeIdentityToken(verifyResult.token);
+  }
+
+  /**
+   * Surface a failed primary-factor verification. When the backend returns a
+   * retry kindling, it is grafted onto the error's `data` so the caller can
+   * offer another attempt against the same code session.
+   */
+  private throwVerificationFailure(verifyResult: IdentityVerificationResponse): never {
+    if (verifyResult.kindling) {
+      const error = new SparkVaultMobileError('Invalid code. Please try again.', {
+        code: 400,
+        statusCode: 400,
+      });
+      (error as SparkVaultMobileError & { data?: unknown }).data = {
+        kindling: verifyResult.kindling,
+        expires_at: verifyResult.expires_at,
+      };
+      throw error;
+    }
 
-      throw new SparkVaultMobileError('Verification failed. Please request a new code.', {
+    throw new SparkVaultMobileError('Verification failed. Please request a new code.', {
+      code: 400,
+      statusCode: 400,
+    });
+  }
+
+  /**
+   * Complete a login held at the second-factor gate (from verifyTotp). Submits
+   * a 6-digit authenticator code or a recovery code and returns the verified
+   * identity result. A wrong code throws.
+   */
+  async submitSecondFactor(request: SubmitSecondFactorRequest): Promise<IdentityVerifyResult> {
+    const result = await this.postIdentity<IdentityVerificationResponse>('/second-factor/verify', {
+      ticket: request.ticket,
+      code: request.code,
+    });
+    if (!result.verified || !result.token) {
+      throw new SparkVaultMobileError('That code is not valid. Please try again.', {
         code: 400,
         statusCode: 400,
       });
     }
+    return this.toIdentityVerifyResult(result.token, {
+      identity: result.identity,
+      identityType: result.identity_type,
+      method: result.method,
+      redirect: result.redirect,
+    });
+  }
 
-    return this.exchangeIdentityToken(verifyResult.token);
+  /**
+   * Complete a 2FA-pending app login (from verifyPin's pending response):
+   * submit the second factor, then exchange the identity token for an app
+   * session.
+   */
+  async completeSecondFactorPin(request: SubmitSecondFactorRequest): Promise<PinVerifyResponse> {
+    const result = await this.submitSecondFactor(request);
+    return this.exchangeIdentityToken(result.token);
+  }
+
+  /** Build the typed error verifyTotp throws when a second factor is required. */
+  private secondFactorError(ticket: string, methods?: string[]): SparkVaultMobileError {
+    const error = new SparkVaultMobileError('Two-step verification required.', {
+      code: 401,
+      statusCode: 401,
+    });
+    (error as SparkVaultMobileError & { data?: unknown }).data = {
+      second_factor_required: true,
+      ticket,
+      methods: methods ?? ['authenticator'],
+    };
+    return error;
   }
 
   async completeSignup(

package/src/config.ts

@@ -1,4 +1,8 @@
 import { SparkVaultValidationError } from './errors.js';
+import {
+  SPARKVAULT_PLATFORM_SV_HOSTS,
+  SPARKVAULT_ROOT_DOMAIN,
+} from './platform-domains.generated.js';
 import type {
   FetchLike,
   MobileFileDownloader,
@@ -10,11 +14,15 @@ import type {
 const DEFAULT_API_BASE_URL = 'https://api.sparkvault.com/v1';
 const DEFAULT_IDENTITY_BASE_URL = 'https://api.sparkvault.com/v1/products/identity';
 
-// Hosts that are allowed to serve backend-issued ingot download URLs.
-// Keep in sync with the sdk-js default in packages/sdk-js/src/config.ts.
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Hosts that are allowed to serve backend-issued ingot download URLs, derived
+// from the canonical platform domain registry baked in at build time.
 const DEFAULT_ALLOWED_DOWNLOAD_HOST_PATTERNS: RegExp[] = [
-  /(^|\.)sparkvault\.com$/i,
-  /(^|\.)(x|files|file|send|spark|by|at|db|auth)\.sv$/i,
+  new RegExp(`(^|\\.)${escapeRegExp(SPARKVAULT_ROOT_DOMAIN)}$`, 'i'),
+  new RegExp(`(^|\\.)(${SPARKVAULT_PLATFORM_SV_HOSTS.map(escapeRegExp).join('|')})$`, 'i'),
   /\.amazonaws\.com$/i,
   /\.cloudfront\.net$/i,
 ];

package/src/encoding.ts

@@ -123,7 +123,17 @@ export function base64ToBytes(value: string): Uint8Array {
   }
 
   const padded = sanitized.padEnd(Math.ceil(sanitized.length / 4) * 4, '=');
-  const bytes: number[] = [];
+
+  // Preallocate the exact output size: 3 bytes per quartet, minus one byte per
+  // '=' (a '=' in quartet positions 1-2 throws below, so counting every '=' is
+  // safe). Multi-megabyte upload chunks decode through here, so per-byte array
+  // growth is not acceptable.
+  let paddingCount = 0;
+  for (let i = 0; i < padded.length; i++) {
+    if (padded[i] === '=') paddingCount++;
+  }
+  const bytes = new Uint8Array((padded.length / 4) * 3 - paddingCount);
+  let outIndex = 0;
 
   for (let i = 0; i < padded.length; i += 4) {
     const c1 = padded[i];
@@ -141,10 +151,10 @@ export function base64ToBytes(value: string): Uint8Array {
     }
 
     const triplet = (v1 << 18) | (v2 << 12) | (v3 << 6) | v4;
-    bytes.push((triplet >> 16) & 0xff);
-    if (c3 !== '=') bytes.push((triplet >> 8) & 0xff);
-    if (c4 !== '=') bytes.push(triplet & 0xff);
+    bytes[outIndex++] = (triplet >> 16) & 0xff;
+    if (c3 !== '=') bytes[outIndex++] = (triplet >> 8) & 0xff;
+    if (c4 !== '=') bytes[outIndex++] = triplet & 0xff;
   }
 
-  return new Uint8Array(bytes);
+  return bytes;
 }

package/src/http.ts

@@ -231,9 +231,20 @@ export class MobileHttpClient {
       return false;
     }
 
-    await this.config.tokenStorage.setAccessToken(data.access_token);
+    // Refresh tokens rotate and are one-time-use: persist the pair through a
+    // single adapter call when the adapter supports it, so the write can be
+    // atomic. Two separate writes risk a process kill stranding a new access
+    // token alongside the already-consumed refresh token (forced logout on
+    // the next refresh).
     if (typeof data.refresh_token === 'string' && data.refresh_token) {
-      await this.config.tokenStorage.setRefreshToken(data.refresh_token);
+      if (this.config.tokenStorage.setTokens) {
+        await this.config.tokenStorage.setTokens(data.access_token, data.refresh_token);
+      } else {
+        await this.config.tokenStorage.setAccessToken(data.access_token);
+        await this.config.tokenStorage.setRefreshToken(data.refresh_token);
+      }
+    } else {
+      await this.config.tokenStorage.setAccessToken(data.access_token);
     }
     this.emitAuthEvent('token_refreshed');
     return true;

package/src/identity-dialog.tsx

@@ -402,7 +402,7 @@ export function SparkVaultIdentityDialog({
                 hitSlop={12}
                 style={styles.closeButton}
               >
-                <Text style={[styles.closeText, { color: colors.muted }]}>x</Text>
+                <Text style={[styles.closeText, { color: colors.muted }]}>✕</Text>
               </Pressable>
             </View>
 
@@ -496,7 +496,7 @@ export function SparkVaultIdentityDialog({
                   Confirm this sign-in with your device passkey.
                 </Text>
                 <View style={[styles.passkeyIcon, { backgroundColor: colors.primarySoft }]}>
-                  <Text style={[styles.passkeyIconText, { color: colors.primary }]}>key</Text>
+                  <Text style={styles.passkeyIconText}>🔑</Text>
                 </View>
                 {isBusy ? <ActivityIndicator color={colors.primary} /> : null}
                 {error ? <Text style={[styles.error, { color: colors.error }]}>{error}</Text> : null}
@@ -974,7 +974,6 @@ const styles = StyleSheet.create({
     justifyContent: 'center',
   },
   passkeyIconText: {
-    fontSize: 18,
-    fontWeight: '800',
+    fontSize: 34,
   },
 });

package/src/ingots.ts

@@ -89,8 +89,6 @@ interface IngotAuditLogEntry {
 
 interface IngotAuditLogsResponse {
   entries?: IngotAuditLogEntry[];
-  logs?: IngotAuditLogEntry[];
-  cursor?: string;
   next_cursor?: string;
 }
 
@@ -456,10 +454,10 @@ export class MobileIngotsClient {
         : `/vaults/${vaultId}/ingots/${ingotId}/audit-logs`,
       { vat }
     );
-    const entries = response.data.entries ?? response.data.logs ?? [];
+    const entries = response.data.entries ?? [];
     return {
       logs: entries.map(entry => this.toAccessLog(entry)),
-      next_cursor: response.data.cursor ?? response.data.next_cursor,
+      next_cursor: response.data.next_cursor,
     };
   }
 

package/src/platform-domains.generated.ts

@@ -0,0 +1,17 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/platform-domains.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+export const SPARKVAULT_ROOT_DOMAIN = "sparkvault.com";
+
+export const SPARKVAULT_PLATFORM_SV_HOSTS: readonly string[] = Object.freeze([
+  "auth.sv",
+  "x.sv",
+  "files.sv",
+  "file.sv",
+  "send.sv",
+  "spark.sv",
+  "by.sv",
+  "at.sv",
+  "db.sv",
+]);

package/src/tus.ts

@@ -73,6 +73,12 @@ function ensureNotAborted(signal?: AbortSignal): void {
 }
 
 function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  // base64ToBytes returns exactly-sized buffers, so the chunk hot path is a
+  // zero-copy unwrap; copy only when the view spans part of a larger buffer.
+  // Aliasing is safe: chunks are sent then discarded, never mutated.
+  if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+    return bytes.buffer as ArrayBuffer;
+  }
   const copy = new Uint8Array(bytes.byteLength);
   copy.set(bytes);
   return copy.buffer;
@@ -223,10 +229,11 @@ export class MobileTusUploader {
     const debug = options.debug;
     const cleanUri = options.fileUri.split('#')[0];
     let bytesUploaded = 0;
+    let uploadUrl: string | null = null;
 
     try {
       debug?.log(`Starting TUS upload for ${options.filename}`);
-      const uploadUrl = await createTusUpload(
+      uploadUrl = await createTusUpload(
         this.config,
         parsed,
         options.fileSize,
@@ -267,6 +274,18 @@ export class MobileTusUploader {
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       debug?.error(`Upload failed: ${getErrorMessage(error)}`);
+
+      // A cancelled session must be terminated server-side: the tus DELETE is
+      // what lets Forge remove already-written chunk objects (otherwise they
+      // are orphaned in S3 — nothing else cleans them up) and settle
+      // partial-transfer billing, matching the web client's abort semantics.
+      const cancelled =
+        options.abortSignal?.aborted === true ||
+        (err instanceof TusUploadError && err.phase === 'cancelled');
+      if (cancelled && uploadUrl) {
+        this.terminateUpload(uploadUrl, parsed.istk, debug);
+      }
+
       if (err instanceof TusUploadError) throw err;
       throw TusUploadError.fromError(error, {
         filename: options.filename,
@@ -276,6 +295,28 @@ export class MobileTusUploader {
     }
   }
 
+  /**
+   * Best-effort tus termination after a cancelled upload. Fire-and-forget so
+   * cancel UX stays instant and the cancellation error still propagates — a
+   * failed DELETE only means the orphaned session waits for server-side
+   * expiry. Deliberately NOT bound to the (already aborted) upload signal,
+   * which would kill the DELETE before it left the device.
+   */
+  private terminateUpload(uploadUrl: string, istk: string, debug?: DebugLogger): void {
+    void this.config
+      .fetch(uploadUrl, {
+        method: 'DELETE',
+        headers: {
+          'Tus-Resumable': TUS_VERSION,
+          'X-ISTK': istk,
+        },
+        timeoutMs: this.config.tusPostTimeoutMs,
+      })
+      .catch(err => {
+        debug?.log(`TUS termination after cancel failed: ${getErrorMessage(err)}`);
+      });
+  }
+
   private async readChunk(
     fileReader: MobileFileReader,
     fileUri: string,

package/src/types.ts

@@ -174,7 +174,31 @@ export interface PinVerifySignupPendingResponse {
   expires_at: number;
 }
 
-export type PinVerifyResponse = PinVerifyLoginResponse | PinVerifySignupPendingResponse;
+/**
+ * Returned by verifyPin when the PIN was correct but the account has 2FA
+ * enabled: the caller must collect a second factor and call
+ * completeSecondFactorPin({ ticket, code }) to finish the login.
+ */
+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;
+
+export interface SubmitSecondFactorRequest {
+  /** Pending-login ticket from a second_factor_required response. */
+  ticket: string;
+  /** 6-digit authenticator code or a recovery code. */
+  code: string;
+}
 
 export interface CompleteSignupRequest {
   organization_name: string;

package/src/validation.ts

@@ -25,13 +25,20 @@ export function validateFolderId(folderId: string): void {
   }
 }
 
+/** Windows reserved filenames that cannot be used. */
+const WINDOWS_RESERVED_NAMES = new Set([
+  'CON', 'PRN', 'AUX', 'NUL',
+  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+]);
+
+/**
+ * Sanitize a filename to prevent path traversal and other security issues:
+ * removes null bytes and control characters, strips path traversal sequences,
+ * replaces directory separators, strips leading dots (hidden files), and
+ * prefixes Windows reserved names. Falls back to 'file' when nothing remains.
+ */
 export function sanitizeFilename(filename: string): string {
-  const reservedNames = new Set([
-    'CON', 'PRN', 'AUX', 'NUL',
-    'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
-    'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
-  ]);
-
   let sanitized = filename
     .replace(/\0/g, '')
     .replace(/[\x00-\x1f\x7f]/g, '')
@@ -41,7 +48,7 @@ export function sanitizeFilename(filename: string): string {
     .trim();
 
   const baseName = sanitized.split('.')[0].toUpperCase();
-  if (reservedNames.has(baseName)) {
+  if (WINDOWS_RESERVED_NAMES.has(baseName)) {
     sanitized = `_${sanitized}`;
   }
 

package/src/vaults.ts

@@ -257,20 +257,6 @@ export class MobileVaultsClient {
     return response.data;
   }
 
-  /**
-   * @deprecated Use enableUploadPortal() or enableUploadWidget().
-   */
-  async enableUpload(vaultId: string, vmk: string): Promise<UploadPortalEnabled> {
-    return this.enableUploadPortal(vaultId, vmk);
-  }
-
-  /**
-   * @deprecated Use disableUploadPortal() or disableUploadWidget().
-   */
-  async disableUpload(vaultId: string): Promise<UploadPortalDisabled> {
-    return this.disableUploadPortal(vaultId);
-  }
-
   async updateUploadConfig(
     vaultId: string,
     config: {