@sparkvault/sdk-mobile 6.0.2 → 7.0.0

package/src/tus.ts

@@ -1,5 +1,6 @@
 import type { ResolvedMobileConfig } from './config.js';
-import { base64EncodeUtf8 } from './encoding.js';
+import { FORGE_URL_REFUSAL, readForgeSessionUrl, readForgeTransferUrl, resolveForgeSessionUrl } from './app-sdk/forge-url.js';
+import { SPARKVAULT_OWNED_HOST_PATTERNS } from './app-sdk/platform-domains.js';
 import {
   BackgroundTransferError,
   gateErrorFromBody,
@@ -55,8 +56,8 @@ export interface TusSessionProbe {
 export interface TusUploadFromUriOptions {
   fileUri: string;
   fileSize: number;
+  /** Names the file in error context and debug logs; Forge never receives it. */
   filename: string;
-  contentType: string;
   /**
    * Forge tus endpoint plus ISTK (`forge_url` from the ingot create).
    * Required to create a session; on resume it only supplies the ISTK when
@@ -101,29 +102,72 @@ export interface TusUploadFromUriOptions {
 
 const TUS_VERSION = '1.0.0';
 
-export function parseForgeUrl(forgeUrl: string): ParsedForgeUrl {
-  let url: URL;
-  try {
-    url = new URL(forgeUrl);
-  } catch {
-    throw new SparkVaultValidationError('Invalid Forge URL format');
-  }
+/** What a refused Forge URL was refused for, in the words this SDK's errors use. */
+const FORGE_URL_REFUSAL_MESSAGES: Readonly<Record<string, string>> = {
+  [FORGE_URL_REFUSAL.INVALID]: 'Invalid Forge URL format',
+  [FORGE_URL_REFUSAL.NOT_HTTPS]: 'Forge URL must use HTTPS protocol',
+  [FORGE_URL_REFUSAL.UNSAFE_PARTS]: 'Forge URL must not carry credentials or a fragment',
+  [FORGE_URL_REFUSAL.HOST]: 'Forge URL host is not an allowed transfer host',
+  [FORGE_URL_REFUSAL.OPERATION]: 'Forge URL is not an upload endpoint',
+  [FORGE_URL_REFUSAL.ISTK]: 'Forge URL must carry exactly one base64url ISTK parameter',
+};
 
-  if (url.protocol !== 'https:') {
-    throw new SparkVaultValidationError('Forge URL must use HTTPS protocol');
+/**
+ * Read a Core-issued Forge upload URL with the platform's transfer URL rule
+ * (app-sdk/forge-url.js): https, no credentials or fragment, the encrypt
+ * endpoint on an allowed host, and one base64url ISTK.
+ *
+ * @param allowedHostPatterns - Hosts trusted with the upload; the platform's
+ *   own hosts by default (a configured SDK passes `allowedDownloadHostPatterns`).
+ * @throws SparkVaultValidationError when the URL is refused.
+ */
+export function parseForgeUrl(
+  forgeUrl: string,
+  allowedHostPatterns: readonly RegExp[] = SPARKVAULT_OWNED_HOST_PATTERNS
+): ParsedForgeUrl {
+  const read = readForgeTransferUrl(forgeUrl, {
+    operation: 'encrypt',
+    isAllowedHost: allowsHost(allowedHostPatterns),
+  });
+  if (!read.ok) {
+    throw new SparkVaultValidationError(FORGE_URL_REFUSAL_MESSAGES[read.reason] ?? 'Invalid Forge URL', {
+      reason: read.reason,
+    });
   }
+  return {
+    baseUrl: read.origin,
+    tusEndpoint: read.endpoint,
+    istk: read.istk,
+  };
+}
 
-  const istk = url.searchParams.get('istk');
-  if (!istk) {
-    throw new SparkVaultValidationError('Forge URL missing ISTK parameter');
+/**
+ * Read a kept tus session URL (the one `onSessionCreated` handed out) with the
+ * platform's session URL rule (app-sdk/forge-url.js) before the session is
+ * sent anything. Every request to a session carries the ISTK, and a PATCH the
+ * file's bytes, so a kept session is held to the rule a created one was: a
+ * session directly under the upload endpoint on an allowed host. The one
+ * reader for every path that sends a kept session a request: resume, probe
+ * and terminate.
+ *
+ * @throws SparkVaultValidationError when the URL is refused.
+ */
+function readKeptSessionUrl(uploadUrl: string, allowedHostPatterns: readonly RegExp[]): string {
+  const session = readForgeSessionUrl(uploadUrl, {
+    operation: 'encrypt',
+    isAllowedHost: allowsHost(allowedHostPatterns),
+  });
+  if (!session.ok) {
+    throw new SparkVaultValidationError('uploadUrl is not an upload session on an allowed transfer host', {
+      reason: session.reason,
+    });
   }
+  return session.url;
+}
 
-  const baseUrl = `${url.protocol}//${url.host}`;
-  return {
-    baseUrl,
-    tusEndpoint: `${baseUrl}${url.pathname}`,
-    istk,
-  };
+/** The forge-url rule's host check over a configured list of host patterns. */
+export function allowsHost(allowedHostPatterns: readonly RegExp[]): (hostname: string) => boolean {
+  return hostname => allowedHostPatterns.some(pattern => pattern.test(hostname));
 }
 
 /**
@@ -287,18 +331,20 @@ type TusSessionSource =
   | { mode: 'create'; parsed: ParsedForgeUrl }
   | { mode: 'resume'; uploadUrl: string; istk: string };
 
-function resolveSessionSource(options: TusUploadFromUriOptions): TusSessionSource {
+function resolveSessionSource(options: TusUploadFromUriOptions, allowedHostPatterns: readonly RegExp[]): TusSessionSource {
   if (options.resume) {
-    const istk = options.resume.istk ?? (options.forgeUrl ? parseForgeUrl(options.forgeUrl).istk : null);
+    const uploadUrl = readKeptSessionUrl(options.resume.uploadUrl, allowedHostPatterns);
+    const istk = options.resume.istk
+      ?? (options.forgeUrl ? parseForgeUrl(options.forgeUrl, allowedHostPatterns).istk : null);
     if (!istk) {
       throw new SparkVaultValidationError('resume.istk or forgeUrl is required to resume a TUS upload session');
     }
-    return { mode: 'resume', uploadUrl: options.resume.uploadUrl, istk };
+    return { mode: 'resume', uploadUrl, istk };
   }
   if (!options.forgeUrl) {
     throw new SparkVaultValidationError('forgeUrl is required to create a TUS upload session');
   }
-  return { mode: 'create', parsed: parseForgeUrl(options.forgeUrl) };
+  return { mode: 'create', parsed: parseForgeUrl(options.forgeUrl, allowedHostPatterns) };
 }
 
 async function createTusUpload(
@@ -306,12 +352,12 @@ async function createTusUpload(
   parsed: ParsedForgeUrl,
   fileSize: number,
   filename: string,
-  contentType: string,
   signal?: AbortSignal
 ): Promise<{ uploadUrl: string; chunkSize: number }> {
   ensureNotAborted(signal);
 
-  const metadata = `filename ${base64EncodeUtf8(filename)},filetype ${base64EncodeUtf8(contentType || 'application/octet-stream')}`;
+  // Forge's create contract is these three headers: the ingot's name and type
+  // were set by Core when the ingot was created, and Forge publishes Core's.
   const response = await tusRequest(
     config,
     parsed.tusEndpoint,
@@ -320,7 +366,6 @@ async function createTusUpload(
       headers: {
         'Tus-Resumable': TUS_VERSION,
         'Upload-Length': String(fileSize),
-        'Upload-Metadata': metadata,
         'X-ISTK': parsed.istk,
       },
       signal,
@@ -349,17 +394,17 @@ async function createTusUpload(
     });
   }
 
-  const location = response.headers.get('Location');
-  if (!location) {
-    throw new TusUploadError('TUS create response missing Location header', {
+  // Every chunk carries the file's bytes, so the session must live under the
+  // endpoint it was created at.
+  const uploadUrl = resolveForgeSessionUrl(response.headers.get('Location'), parsed.tusEndpoint);
+  if (!uploadUrl) {
+    throw new TusUploadError('TUS create response Location header is missing or outside the upload endpoint', {
       filename,
       fileSize,
       phase: 'create',
     });
   }
 
-  const uploadUrl = location.startsWith('http') ? location : `${parsed.baseUrl}${location}`;
-
   // Forge fixes the session's chunk geometry and rejects any non-final chunk
   // that is not exactly the negotiated size, so the chunk size is the server's
   // to dictate via `X-Chunk-Size` (mirrors sdk-js). A client-side guess could
@@ -792,7 +837,7 @@ export class MobileTusUploader {
       throw new SparkVaultValidationError('fileReader adapter is required for URI uploads');
     }
 
-    const source = resolveSessionSource(options);
+    const source = resolveSessionSource(options, this.config.allowedDownloadHostPatterns);
     const istk = source.mode === 'create' ? source.parsed.istk : source.istk;
     const debug = options.debug;
     const cleanUri = options.fileUri.split('#')[0];
@@ -843,7 +888,6 @@ export class MobileTusUploader {
           source.parsed,
           options.fileSize,
           options.filename,
-          options.contentType,
           options.abortSignal
         );
         sessionUrl = created.uploadUrl;
@@ -988,10 +1032,14 @@ export class MobileTusUploader {
    * throws `sessionLost` on a mismatch) to judge. Lets a caller reconcile
    * sessions on relaunch (a completed one just needs its ingot verified; a
    * lost one needs a fresh create) before spending an upload slot on it.
+   *
+   * @throws SparkVaultValidationError, before any request, when `uploadUrl`
+   *   is not an upload session on an allowed transfer host.
    */
   async probeSession(session: { uploadUrl: string; istk: string }): Promise<TusSessionProbe | null> {
+    const uploadUrl = readKeptSessionUrl(session.uploadUrl, this.config.allowedDownloadHostPatterns);
     try {
-      return await headTusSession(this.config, session.uploadUrl, session.istk);
+      return await headTusSession(this.config, uploadUrl, session.istk);
     } catch (err) {
       if (err instanceof TusUploadError && err.sessionLost) return null;
       throw err;
@@ -1021,17 +1069,22 @@ export class MobileTusUploader {
    * Forge sent) so the caller can retry later. Not bound to any
    * abort signal: a terminate is the last thing a caller does with a
    * session, never something to cancel.
+   *
+   * @throws SparkVaultValidationError, before any request, when `uploadUrl`
+   *   is not an upload session on an allowed transfer host.
    */
   async terminateSession(session: { uploadUrl: string; istk: string }): Promise<void> {
+    const uploadUrl = readKeptSessionUrl(session.uploadUrl, this.config.allowedDownloadHostPatterns);
+
     // A terminate is the one place the SDK knows the OS job must die with
     // the session: a DELETE under a job the engine is still chaining would
     // leave it PATCHing a gone session until it fails on its own.
     const backgroundTransfer = this.config.backgroundTransfer;
     if (backgroundTransfer) {
-      await this.cancelBackgroundTransfer(backgroundTransfer, session.uploadUrl);
+      await this.cancelBackgroundTransfer(backgroundTransfer, uploadUrl);
     }
 
-    const response = await this.requestTerminate(session.uploadUrl, session.istk);
+    const response = await this.requestTerminate(uploadUrl, session.istk);
 
     if (response.ok || isSessionGone(response.status)) return;
 

package/src/types.ts

@@ -5,7 +5,9 @@ export type PoolState = 'ok' | 'notice' | 'warning' | 'exhausted';
 export interface PoolStatus {
   used_gb: number;
   limit_gb: number | null;
+  /** Used fraction of the pool: 0.85 is 85% full, 1 is full (above 1 when over). */
   pct: number;
+  /** The server's severity for the pool, from the canonical thresholds; display keys off it. */
   state: PoolState;
 }
 
@@ -137,6 +139,12 @@ export interface RemoveMemberResponse {
   user_id: string;
   removed_at: number;
   dvaks_revoked: number;
+  /**
+   * True when this removal ends the subscription: the member renewed the last
+   * license it renews, and it was not already set to end. It ends at the
+   * period end.
+   */
+  wind_down: boolean;
 }
 
 export interface ResendInviteResponse {
@@ -177,7 +185,7 @@ export interface SparkVaultSubscription {
   renewal_date: number | null;
   renewal_amount_usd: string;
   seats: {
-    /** Cycle-unique billed counts (flex billing: what the renewal invoices). */
+    /** Licenses the subscription renews with — what the next renewal bills. */
     full: number;
     viewer: number;
     licensed: number;
@@ -187,6 +195,18 @@ export interface SparkVaultSubscription {
     assigned_viewer: number;
     /** Roster members with no license (no access until licensed; free). */
     unlicensed_members: number;
+    /** Licenses paid for the current billing period (a removed license stays
+     *  paid until the renewal). */
+    paid: { full: number; viewer: number };
+    /** Paid licenses nobody holds — assignable at no charge until the renewal. */
+    available: { full: number; viewer: number };
+    /**
+     * Licenses are prepaid per period on a web subscription: a removed one
+     * stays paid until the renewal, free to give to someone else until then.
+     * False on a store subscription (its one license lands on a member by
+     * itself) and on an account with no web subscription.
+     */
+    prepaid: boolean;
   };
   blocks: {
     /** Effective capacity blocks (this subscription plus any add-on rail). */
@@ -204,6 +224,21 @@ export interface SparkVaultSubscription {
 /** Native in-app purchase store channel for receipt validation. */
 export type IapPlatform = 'ios' | 'android';
 
+/** The store rail a validated purchase is billed on. */
+export type IapChannel = 'appstore' | 'play';
+
+/**
+ * POST /v1/billing/iap/validate — whether Core provisioned the purchase: a
+ * provisioning status, not a subscription (read the subscription again with
+ * `billing.getSubscription()` to show what changed). A purchase the store
+ * reports as not entitling (expired, refunded, revoked or not yet paid) is
+ * answered, not refused, and provisions nothing; every other refusal is an
+ * error. `addon` marks a capacity add-on stacked on the license.
+ */
+export type IapValidation =
+  | { provisioned: true; channel: IapChannel; addon?: true }
+  | { provisioned: false; reason: 'not_entitling' };
+
 export type IdentityType = 'email' | 'phone';
 export type VerifiedIdentityType = IdentityType | 'social';
 
@@ -542,9 +577,104 @@ export interface UnsealVaultResponse {
   ttl_seconds: number;
 }
 
+/** One page of GET /v1/vaults. */
 export interface ListVaultsResponse {
   vaults: Vault[];
-  total: number;
+  count: number;
+  has_more: boolean;
+  next_cursor?: string;
+}
+
+/** A vault's public sharing policy (GET /v1/vaults/{id}/sharing). */
+export interface VaultSharingConfig {
+  vault_id: string;
+  public_sharing_enabled: boolean;
+  all_ingots_public: boolean;
+  session_length_seconds: number | null;
+  enabled_at: number | null;
+}
+
+/** The sharing policy a caller sets when enabling or updating vault sharing. */
+export interface VaultSharingOptions {
+  all_ingots_public?: boolean;
+  session_length_seconds?: number;
+}
+
+export interface EnableVaultSharingResponse {
+  vault_id: string;
+  public_sharing_enabled: boolean;
+  all_ingots_public: boolean;
+  session_length_seconds: number;
+  enabled_at: number;
+}
+
+export interface DisableVaultSharingResponse {
+  vault_id: string;
+  public_sharing_enabled: false;
+  disabled_at: number;
+  shares_revoked: number;
+}
+
+export interface UpdateVaultSharingResponse {
+  vault_id: string;
+  public_sharing_enabled: boolean;
+  all_ingots_public: boolean;
+  session_length_seconds: number;
+  updated_at: number;
+}
+
+/** How long a vault keeps its access log (GET /v1/vaults/{id}/access-log-retention). */
+export interface AccessLogRetention {
+  vault_id: string;
+  access_log_retention_seconds: number;
+}
+
+export interface UpdateAccessLogRetentionResponse extends AccessLogRetention {
+  updated_at: number;
+}
+
+/** A vault's upload portal and widget settings (GET /v1/vaults/{id}/upload). */
+export interface UploadConfig {
+  vault_id: string;
+  upload_portal_enabled: boolean;
+  upload_portal_enabled_at: number | null;
+  upload_widget_enabled: boolean;
+  upload_widget_enabled_at: number | null;
+  max_size_bytes: number | null;
+  notification_email: string | null;
+  portal_url?: string;
+}
+
+export interface UploadPortalEnabled {
+  vault_id: string;
+  upload_portal_enabled: true;
+  enabled_at: number;
+  portal_url: string;
+}
+
+export interface UploadWidgetEnabled {
+  vault_id: string;
+  upload_widget_enabled: true;
+  enabled_at: number;
+}
+
+export interface UploadPortalDisabled {
+  vault_id: string;
+  upload_portal_enabled: false;
+  disabled_at: number;
+}
+
+export interface UploadWidgetDisabled {
+  vault_id: string;
+  upload_widget_enabled: false;
+  disabled_at: number;
+}
+
+export interface UploadConfigUpdate {
+  vault_id: string;
+  max_size_bytes: number;
+  notification_email: string | null;
+  updated_at: number;
 }
 
 export interface Ingot {
@@ -553,7 +683,8 @@ export interface Ingot {
   content_type: string;
   size_bytes: number;
   storage_location: 'dynamodb' | 's3';
-  status?: 'uploading' | 'encrypting' | 'active' | 'failed';
+  /** `uploading` until Forge activates the upload, then `active`. */
+  status?: 'uploading' | 'active';
   folder_id?: string | null;
   created_at: number;
   accessed_at?: number;
@@ -586,16 +717,29 @@ export interface ListIngotsResponse {
   next_cursor?: string;
 }
 
+/**
+ * GET /vaults/:id/contents: one folder whole, in one response — the folder
+ * (null at the vault root), the trail from the root to it, its direct
+ * subfolders (pinned first) and every ingot directly in it.
+ */
+export interface FolderContentsResponse {
+  folder: { folder_id: string; name: string; parent_id: string | null } | null;
+  breadcrumb: Array<{ folder_id: string | null; name: string }>;
+  folders: Folder[];
+  ingots: Ingot[];
+}
+
 export interface UploadResult {
   ingot_id: string;
   name: string;
   size_bytes: number;
   storage_location: 's3';
   /**
-   * Whether this upload minted the ingot (true) or was handed an existing row
-   * by the server's same-name upsert / a resumed session (false). A caller
-   * that discards its ingot on a failure path needs this to tell "mine to
-   * discard" from "someone else's live row".
+   * 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
+   * allowed, a replace, or a resumed session. A caller that discards its
+   * ingot on a failure path needs this to tell "mine to discard" from
+   * "someone else's live row".
    */
   created?: boolean;
   /**
@@ -623,9 +767,19 @@ export interface IngotInvite {
   created_at: number;
 }
 
+/**
+ * An ingot access-log entry: a download that delivered the file, a SparkLink
+ * open of it included. The server records an access as the download that
+ * delivered it, so `download` is the one action.
+ */
 export interface IngotAccessLog {
+  /**
+   * The entry's time (Unix seconds) as a string. The server issues no entry id,
+   * so entries in the same second share it.
+   */
   log_id: string;
-  action: 'download' | 'view';
+  action: 'download';
+  /** Who accessed: a member's email, an API key's name, or a SparkLink visitor's identity */
   identity: string;
   ip_address: string;
   user_agent: string;
@@ -638,18 +792,14 @@ export interface IngotAccessStats {
   last_accessed_at?: number;
 }
 
+/** A folder as every folder route answers it (Core's FolderRepository.toPublicFormat). */
 export interface Folder {
   folder_id: string;
-  vault_id: string;
   name: string;
   parent_id: string | null;
-  is_system: boolean;
   pinned: boolean;
   created_at: number;
   updated_at?: number;
-  path?: string;
-  depth?: number;
-  ingot_count?: number;
 }
 
 export interface CreateFolderRequest {
@@ -663,9 +813,9 @@ export interface UpdateFolderRequest {
   pinned?: boolean;
 }
 
+/** GET /v1/vaults/{id}/folders: the vault's whole folder list. */
 export interface ListFoldersResponse {
   folders: Folder[];
-  total: number;
 }
 
 export interface FolderBreadcrumbItem {
@@ -919,7 +1069,7 @@ export type SparkShareStatus =
       link_code: string;
       visibility: string;
       invites: string[];
-      /** Single-use lifecycle: 'active' → 'consumed' (opened once) | 'revoked'. */
+      /** Single-use lifecycle: 'active' → 'consumed' (opened once). */
       status: string;
       expires_at?: number;
       created_at?: number;

package/src/users.ts

@@ -7,15 +7,17 @@ import type {
   RemoveMemberResponse,
   ResendInviteResponse,
 } from './types.js';
+import { apiPath } from './request-path.js';
+import { validateResourceId } from './validation.js';
 
 /**
  * Organization team client (member admins only — the API gates these on the
  * admin role and returns 403 otherwise).
  *
- * Licensing is a billing action (flex: nothing charges mid-cycle — the renewal
- * bills each cycle's unique license holders), so the only seat-affecting
- * operation exposed here is `invite`, which defaults new members to
- * `unlicensed` and never charges. Assigning or changing a paid license is
+ * Licensing is a billing action (licenses are prepaid: assigning or upgrading
+ * one charges the rest of the current billing period at once), so the only
+ * seat-affecting operation exposed here is `invite`, which defaults new members
+ * to `unlicensed` and never charges. Assigning or changing a paid license is
  * intentionally absent — clients route that to the web dashboard so native
  * apps never initiate an out-of-band purchase.
  */
@@ -28,33 +30,41 @@ export class MobileUsersClient {
 
   /** List organization members (active and invited), with optional search/filter. */
   async list(options: ListMembersOptions = {}): Promise<ListMembersResponse> {
-    const params = new URLSearchParams();
-    if (options.search) params.set('search', options.search);
-    if (options.status) params.set('status', options.status);
-    if (typeof options.limit === 'number') params.set('limit', String(options.limit));
-    if (options.cursor) params.set('cursor', options.cursor);
-    const query = params.toString();
-    const response = await this.http.get<ListMembersResponse>(
-      query ? `/users?${query}` : '/users'
-    );
+    const response = await this.http.get<ListMembersResponse>(apiPath`/users`, {
+      query: {
+        search: options.search,
+        status: options.status,
+        limit: typeof options.limit === 'number' ? options.limit : undefined,
+        cursor: options.cursor,
+      },
+    });
     return response.data;
   }
 
   /** Invite a coworker by email. Defaults to an unlicensed seat (no charge). */
   async invite(request: InviteMemberRequest): Promise<InviteMemberResponse> {
-    const response = await this.http.post<InviteMemberResponse>('/users/invite', request);
+    const response = await this.http.post<InviteMemberResponse>(apiPath`/users/invite`, request);
     return response.data;
   }
 
-  /** Remove a member and revoke their DVAKs. Access ends immediately; the current cycle still bills them, and they stop counting next cycle. */
+  /**
+   * Remove a member and revoke their DVAKs. Access ends immediately. A license
+   * they held stays paid until the end of the billing period — nothing is
+   * refunded — and is not renewed; until then it can be given to someone else
+   * at no charge. `wind_down` is true when this removal ends the
+   * subscription — theirs was the last license it renews, and it was not
+   * already set to end: it ends at the period end.
+   */
   async remove(userId: string): Promise<RemoveMemberResponse> {
-    const response = await this.http.delete<RemoveMemberResponse>(`/users/${userId}`);
+    validateResourceId(userId, 'user ID', 'userId');
+    const response = await this.http.delete<RemoveMemberResponse>(apiPath`/users/${userId}`);
     return response.data;
   }
 
   /** Resend a pending invitation email (resets the 7-day expiry). */
   async resendInvite(userId: string): Promise<ResendInviteResponse> {
-    const response = await this.http.post<ResendInviteResponse>(`/users/${userId}/resend-invite`);
+    validateResourceId(userId, 'user ID', 'userId');
+    const response = await this.http.post<ResendInviteResponse>(apiPath`/users/${userId}/resend-invite`);
     return response.data;
   }
 }

package/src/validation.ts

@@ -1,28 +1,32 @@
+import { isResourceId } from './app-sdk/ids.js';
 import { SparkVaultValidationError } from './errors.js';
+import { SAVED_FILENAME_FALLBACK, toStorableFilename } from './app-sdk/filename.js';
 
-export function isSafeId(id: string): boolean {
-  if (!id || typeof id !== 'string') return false;
-  if (id.includes('/') || id.includes('\\') || id.includes('..') || id.includes('\0')) return false;
-  if (id.length < 8 || id.length > 128) return false;
-  return /^[a-zA-Z0-9_-]+$/.test(id);
+/** Whether a value is a well-formed SparkVault resource id (the platform's one rule). */
+export { isResourceId as isSafeId };
+
+/**
+ * Refuse a value that is not a SparkVault resource id before it names a route.
+ *
+ * @param label - How the message names the id, e.g. 'spark ID'.
+ * @param field - The argument's name, reported in the error details.
+ */
+export function validateResourceId(value: unknown, label: string, field: string): void {
+  if (!isResourceId(value)) {
+    throw new SparkVaultValidationError(`Invalid ${label} format`, { [field]: value });
+  }
 }
 
 export function validateVaultId(vaultId: string): void {
-  if (!isSafeId(vaultId)) {
-    throw new SparkVaultValidationError('Invalid vault ID format', { vaultId });
-  }
+  validateResourceId(vaultId, 'vault ID', 'vaultId');
 }
 
 export function validateIngotId(ingotId: string): void {
-  if (!isSafeId(ingotId)) {
-    throw new SparkVaultValidationError('Invalid ingot ID format', { ingotId });
-  }
+  validateResourceId(ingotId, 'ingot ID', 'ingotId');
 }
 
 export function validateFolderId(folderId: string): void {
-  if (!folderId || typeof folderId !== 'string' || !folderId.startsWith('fld_') || !isSafeId(folderId)) {
-    throw new SparkVaultValidationError('Invalid folder ID format', { folderId });
-  }
+  validateResourceId(folderId, 'folder ID', 'folderId');
 }
 
 /** Windows reserved filenames that cannot be used. */
@@ -33,17 +37,19 @@ const WINDOWS_RESERVED_NAMES = new Set([
 ]);
 
 /**
- * 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.
+ * The file name to store or save text under, by the platform's one file-name
+ * rule (@sparkvault/app-sdk/filename, mirrored into ./app-sdk/filename.js):
+ * path separators, control characters and the bidi controls that disguise an
+ * extension (`invoice<U+202E>fdp.exe` shows as `invoiceexe.pdf`) become `_`,
+ * and so do the characters SparkVault refuses in a name (: * ? " < > |), so a
+ * name derived from a note's title uploads. With every separator gone no name
+ * can climb a directory, so a `..` inside a name is kept. On top of the rule,
+ * for the device's file system: leading dots are stripped (a hidden file) and
+ * Windows reserved names are prefixed. Falls back to the platform's one
+ * fallback name (SAVED_FILENAME_FALLBACK) when nothing remains.
  */
 export function sanitizeFilename(filename: string): string {
-  let sanitized = filename
-    .replace(/\0/g, '')
-    .replace(/[\x00-\x1f\x7f]/g, '')
-    .replace(/\.\./g, '')
-    .replace(/[\/\\]/g, '_')
+  let sanitized = toStorableFilename(filename)
     .replace(/^\.+/, '')
     .trim();
 
@@ -52,5 +58,5 @@ export function sanitizeFilename(filename: string): string {
     sanitized = `_${sanitized}`;
   }
 
-  return sanitized || 'file';
+  return sanitized || SAVED_FILENAME_FALLBACK;
 }