@sparkvault/sdk-mobile 6.0.2 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkvault/sdk-mobile",
-  "version": "6.0.2",
+  "version": "7.0.0",
   "description": "Mobile SDK for SparkVault Identity, vault, folder, and ingot workflows",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "node scripts/generate-platform-domains.mjs && tsc",
+    "build": "node scripts/generate-app-sdk-mirrors.mjs && tsc",
     "prepack": "pnpm build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
@@ -55,6 +55,8 @@
     "directory": "packages/sdk-mobile"
   },
   "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/plugin-transform-flow-strip-types": "^7.27.1",
     "@sparkvault/app-sdk": "workspace:*",
     "@types/react": "~19.1.0",
     "react": "19.1.0",

package/src/account.ts

@@ -10,6 +10,7 @@ import type {
   SparkVaultUser,
   UpdateAccountRequest,
 } from './types.js';
+import { apiPath } from './request-path.js';
 
 /**
  * First-party SparkVault Core session, profile, and account client. Exchanges a
@@ -27,7 +28,7 @@ export class MobileAccountClient {
 
   async exchangeIdentityToken(identityToken: string): Promise<PinVerifyResponse> {
     const sessionResponse = await this.http.post<IdentitySessionResponse>(
-      '/auth/identity/verify',
+      apiPath`/auth/identity/verify`,
       { token: identityToken },
       { skipAuth: true }
     );
@@ -57,7 +58,7 @@ export class MobileAccountClient {
     request: CompleteSignupRequest
   ): Promise<CompleteSignupResponse> {
     const response = await this.http.post<CompleteSignupResponse>(
-      '/auth/complete-signup',
+      apiPath`/auth/complete-signup`,
       request,
       {
         skipAuth: true,
@@ -81,7 +82,7 @@ export class MobileAccountClient {
   }
 
   async getProfile(): Promise<SparkVaultUser> {
-    const response = await this.http.get<SparkVaultUser>('/profile');
+    const response = await this.http.get<SparkVaultUser>(apiPath`/profile`);
     if (this.config.tokenStorage.setUser) {
       await this.config.tokenStorage.setUser(response.data);
     }
@@ -89,7 +90,7 @@ export class MobileAccountClient {
   }
 
   async updateProfile(updates: { name?: string }): Promise<SparkVaultUser> {
-    const response = await this.http.put<SparkVaultUser>('/profile', updates);
+    const response = await this.http.put<SparkVaultUser>(apiPath`/profile`, updates);
     if (this.config.tokenStorage.setUser) {
       await this.config.tokenStorage.setUser(response.data);
     }
@@ -97,7 +98,7 @@ export class MobileAccountClient {
   }
 
   async getAccount(): Promise<SparkVaultAccount> {
-    const response = await this.http.get<SparkVaultAccount>('/account');
+    const response = await this.http.get<SparkVaultAccount>(apiPath`/account`);
     if (this.config.tokenStorage.setAccount) {
       await this.config.tokenStorage.setAccount(response.data);
     }
@@ -106,20 +107,24 @@ export class MobileAccountClient {
 
   /**
    * Update organization settings (member admins only). Sends a JSON body — the
-   * logo-upload variant of PUT /account is web-only. The PUT returns a partial
-   * settings projection, so re-read the full account to refresh the cache and
-   * return a complete, canonical SparkVaultAccount.
+   * logo-upload variant of PUT /account is web-only. The PUT answers with the
+   * account as it now stands (the same projection GET /account serves), which
+   * refreshes the cache as is: a read right after the write could land on a
+   * replica that has not seen it yet.
    */
   async updateAccount(updates: UpdateAccountRequest): Promise<SparkVaultAccount> {
-    await this.http.put('/account', updates);
-    return this.getAccount();
+    const response = await this.http.put<SparkVaultAccount>(apiPath`/account`, updates);
+    if (this.config.tokenStorage.setAccount) {
+      await this.config.tokenStorage.setAccount(response.data);
+    }
+    return response.data;
   }
 
   async revokeRefreshToken(refreshToken?: string): Promise<void> {
     const token = refreshToken ?? await this.config.tokenStorage.getRefreshToken();
     if (!token) return;
 
-    await this.http.post('/auth/logout', { refresh_token: token }).catch(err => {
+    await this.http.post(apiPath`/auth/logout`, { refresh_token: token }).catch(err => {
       this.config.logger.warn('Logout API call failed', { error: String(err) });
     });
   }

package/src/app-sdk/email-address.js

@@ -0,0 +1,94 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/email-address.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The one email-address grammar: the addresses SparkVault can deliver to, so
+ * the only ones a front door may accept. A door that took an address the
+ * email transport then refuses answers its caller with a success while the
+ * recipient gets nothing (a Notify send, a SparkLink invite, a share), so the
+ * accepting doors and the transport ask this one question.
+ *
+ * An address is read in its canonical form (trimmed, lowercased) and is valid
+ * when it has an RFC 5322 dot-atom-text local part in ASCII, exactly one `@`,
+ * a domain of at least two labels of letters, digits and inner hyphens, and
+ * fits the RFC 5321 lengths (address 320, local part 64, domain 255).
+ *
+ * The canonical form is also the one every stored email key is spelled in:
+ * Identity's directory normalizes an email identifier through
+ * canonicalEmailAddress, and Core keys its account and login-claim rows and
+ * compares a signed-in address through it, so one spelling of an address
+ * finds every row another spelling wrote.
+ *
+ * Pure and import-free, so every runtime that decides deliverability loads it
+ * alike.
+ */
+
+const LOCAL_PART = /^[a-z0-9.!#$%&'*+/=?^_`{|}~-]+$/;
+const DOMAIN_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** RFC 5321 length limits, in characters. */
+export const EMAIL_ADDRESS_LIMITS = Object.freeze({
+  ADDRESS: 320,
+  LOCAL_PART: 64,
+  DOMAIN: 255
+});
+
+/** Why an address is not valid, as emailAddressProblem reports it. */
+export const EMAIL_ADDRESS_PROBLEMS = Object.freeze({
+  FORMAT: 'format',
+  TOO_LONG: 'too_long',
+  LOCAL_PART_TOO_LONG: 'local_part_too_long',
+  DOMAIN_TOO_LONG: 'domain_too_long'
+});
+
+/**
+ * The canonical form of an address: trimmed and lowercased.
+ *
+ * @param {string} value
+ * @returns {string}
+ * @throws {TypeError} when `value` is not a string: it has no canonical form,
+ *   and a caller that would key or compare by one must not carry on without it
+ */
+export function canonicalEmailAddress(value) {
+  if (typeof value !== 'string') {
+    throw new TypeError('An email address is a string');
+  }
+  return value.trim().toLowerCase();
+}
+
+/**
+ * What makes `value` an address SparkVault cannot deliver to, or null when
+ * nothing does.
+ *
+ * @param {*} value
+ * @returns {string|null} One of EMAIL_ADDRESS_PROBLEMS, or null
+ */
+export function emailAddressProblem(value) {
+  if (typeof value !== 'string') return EMAIL_ADDRESS_PROBLEMS.FORMAT;
+  const address = canonicalEmailAddress(value);
+  const at = address.indexOf('@');
+  if (at <= 0 || at !== address.lastIndexOf('@')) return EMAIL_ADDRESS_PROBLEMS.FORMAT;
+
+  const localPart = address.slice(0, at);
+  const domain = address.slice(at + 1);
+  const labels = domain.split('.');
+  if (!LOCAL_PART.test(localPart) || labels.length < 2 || !labels.every((label) => DOMAIN_LABEL.test(label))) {
+    return EMAIL_ADDRESS_PROBLEMS.FORMAT;
+  }
+
+  if (address.length > EMAIL_ADDRESS_LIMITS.ADDRESS) return EMAIL_ADDRESS_PROBLEMS.TOO_LONG;
+  if (localPart.length > EMAIL_ADDRESS_LIMITS.LOCAL_PART) return EMAIL_ADDRESS_PROBLEMS.LOCAL_PART_TOO_LONG;
+  if (domain.length > EMAIL_ADDRESS_LIMITS.DOMAIN) return EMAIL_ADDRESS_PROBLEMS.DOMAIN_TOO_LONG;
+  return null;
+}
+
+/**
+ * Whether SparkVault can deliver to `value`.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isValidEmailAddress(value) {
+  return emailAddressProblem(value) === null;
+}

package/src/app-sdk/encoding.js

@@ -0,0 +1,250 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/encoding.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Base64 and base64url (RFC 4648 §4 and §5): the platform's one codec.
+ *
+ * Dependency-free, and the codec uses no runtime globals (no Buffer, atob or
+ * btoa), so the same code runs on the server, in browsers and in React Native:
+ * sdk-js bundles this module, and sdk-mobile (which publishes standalone)
+ * carries a build-time copy pinned byte-for-byte by its drift test.
+ *
+ * - `bytesToBase64` writes the standard alphabet with `=` padding;
+ *   `bytesToBase64url` writes the URL-safe alphabet without padding.
+ * - `base64ToBytes` and `base64urlToBytes` each read one alphabet, by the WHATWG
+ *   forgiving-base64 rules `atob` implements: ASCII whitespace is ignored,
+ *   padding is optional but, when present, is one or two `=` completing the
+ *   final quartet, and bits past the last whole byte are dropped. Any other
+ *   character (the other alphabet's included), `=` anywhere else, or a single
+ *   character left over after the last whole quartet refuses the text.
+ * - `{ canonical: true }` accepts only the exact text the matching encoder
+ *   writes (no whitespace, the encoder's padding, zero trailing bits), for a
+ *   value whose spelling is itself compared or signed.
+ *
+ * - `base64EncodeUtf8` writes standard base64 of a string's UTF-8 bytes, the
+ *   one form that carries any Unicode through an HTTP header value (a header
+ *   holds latin1 bytes only); `base64DecodeUtf8` reads back exactly what it
+ *   writes. These two use TextEncoder and TextDecoder, which Node and every
+ *   browser provide; sdk-mobile converts UTF-8 itself for the React Native
+ *   engines that need not.
+ * - `isUint8Array` is the platform's one Uint8Array test; every app-sdk check
+ *   for a Uint8Array applies it.
+ *
+ * A refused text decodes to null, never to other bytes: each caller raises its
+ * own error at its own trust boundary.
+ *
+ * A page that cannot import an ES module runs this module's own codec
+ * (ENCODING_SCRIPT).
+ */
+
+const PAD = 0x3d; // '='
+
+/** Characters per String.fromCharCode call: far below every engine's argument limit. */
+const CHAR_CODE_CHUNK = 0x2000;
+
+function alphabet(characters, padded) {
+  const codes = new Uint8Array(64);
+  const values = new Int8Array(128).fill(-1);
+  for (let index = 0; index < 64; index += 1) {
+    codes[index] = characters.charCodeAt(index);
+    values[codes[index]] = index;
+  }
+  return { codes, values, padded };
+}
+
+const BASE64_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const BASE64URL_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+const BASE64 = alphabet(BASE64_CHARACTERS, true);
+const BASE64URL = alphabet(BASE64URL_CHARACTERS, false);
+
+/** Tab, line feed, form feed, carriage return or space. */
+function isAsciiWhitespace(code) {
+  return code === 0x09 || code === 0x0a || code === 0x0c || code === 0x0d || code === 0x20;
+}
+
+/**
+ * Whether a value is a Uint8Array from any realm (a browser frame, a test
+ * DOM), a Node Buffer included: the platform's one Uint8Array test, since a
+ * realm's own `instanceof Uint8Array` refuses another realm's arrays.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isUint8Array(value) {
+  return ArrayBuffer.isView(value) && Object.prototype.toString.call(value) === '[object Uint8Array]';
+}
+
+function fromCharCodes(codes) {
+  let text = '';
+  for (let start = 0; start < codes.length; start += CHAR_CODE_CHUNK) {
+    text += String.fromCharCode.apply(null, codes.subarray(start, start + CHAR_CODE_CHUNK));
+  }
+  return text;
+}
+
+function encode(bytes, table) {
+  if (!isUint8Array(bytes)) {
+    throw new TypeError('Base64 encoding takes a Uint8Array');
+  }
+  const { codes } = table;
+  const tail = bytes.length % 3;
+  const whole = bytes.length - tail;
+  let tailLength = 0;
+  if (tail > 0) tailLength = table.padded ? 4 : tail + 1;
+  const chars = new Uint8Array((whole / 3) * 4 + tailLength);
+
+  let out = 0;
+  for (let index = 0; index < whole; index += 3) {
+    const group = (bytes[index] << 16) | (bytes[index + 1] << 8) | bytes[index + 2];
+    chars[out++] = codes[group >> 18];
+    chars[out++] = codes[(group >> 12) & 63];
+    chars[out++] = codes[(group >> 6) & 63];
+    chars[out++] = codes[group & 63];
+  }
+  if (tail > 0) {
+    const group = (bytes[whole] << 16) | (tail === 2 ? bytes[whole + 1] << 8 : 0);
+    chars[out++] = codes[group >> 18];
+    chars[out++] = codes[(group >> 12) & 63];
+    if (tail === 2) chars[out++] = codes[(group >> 6) & 63];
+    chars.fill(PAD, out);
+  }
+  return fromCharCodes(chars);
+}
+
+function decode(text, table, canonical) {
+  if (typeof text !== 'string') return null;
+  const { values } = table;
+
+  // First pass: refuse anything malformed and count the digits, so the output
+  // is allocated once at its exact size (multi-megabyte reads decode here).
+  let digits = 0;
+  let padding = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (isAsciiWhitespace(code)) {
+      if (canonical) return null;
+    } else if (code === PAD) {
+      padding += 1;
+    } else if (padding > 0 || code > 127 || values[code] < 0) {
+      return null;
+    } else {
+      digits += 1;
+    }
+  }
+  const remainder = digits % 4;
+  if (remainder === 1) return null;
+  if (padding > 0 && (padding > 2 || (digits + padding) % 4 !== 0)) return null;
+  if (canonical && padding !== (table.padded ? (4 - remainder) % 4 : 0)) return null;
+
+  const bytes = new Uint8Array((digits * 3) >> 2);
+  let buffer = 0;
+  let bits = 0;
+  let out = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (code === PAD) break;
+    if (isAsciiWhitespace(code)) continue;
+    buffer = ((buffer << 6) | values[code]) & 0xfff;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[out++] = buffer >> bits;
+    }
+  }
+  if (canonical && (buffer & ((1 << bits) - 1)) !== 0) return null;
+  return bytes;
+}
+
+/**
+ * Encode bytes as standard base64, padded.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} when `bytes` is not a Uint8Array
+ */
+export function bytesToBase64(bytes) {
+  return encode(bytes, BASE64);
+}
+
+/**
+ * Encode bytes as base64url, unpadded.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} when `bytes` is not a Uint8Array
+ */
+export function bytesToBase64url(bytes) {
+  return encode(bytes, BASE64URL);
+}
+
+/**
+ * Decode standard base64.
+ * @param {unknown} text
+ * @param {{ canonical?: boolean }} [options] - `canonical`: accept only what `bytesToBase64` writes
+ * @returns {Uint8Array | null} the bytes, or null when the text is not base64
+ */
+export function base64ToBytes(text, { canonical = false } = {}) {
+  return decode(text, BASE64, canonical);
+}
+
+/**
+ * Decode base64url.
+ * @param {unknown} text
+ * @param {{ canonical?: boolean }} [options] - `canonical`: accept only what `bytesToBase64url` writes
+ * @returns {Uint8Array | null} the bytes, or null when the text is not base64url
+ */
+export function base64urlToBytes(text, { canonical = false } = {}) {
+  return decode(text, BASE64URL, canonical);
+}
+
+/**
+ * Encode a string as standard base64, padded, of its UTF-8 bytes.
+ * @param {string} value
+ * @returns {string}
+ */
+export function base64EncodeUtf8(value) {
+  return bytesToBase64(new TextEncoder().encode(value));
+}
+
+/**
+ * Decode what `base64EncodeUtf8` writes, strictly: canonical standard base64
+ * of well-formed UTF-8, so a mangled value is refused rather than read as
+ * whatever text a lenient decoder makes of it.
+ * @param {unknown} text
+ * @returns {string | null} the string, or null when the text is not canonical base64 of UTF-8
+ */
+export function base64DecodeUtf8(text) {
+  const bytes = base64ToBytes(text, { canonical: true });
+  if (bytes === null) return null;
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    // A fatal decoder signals bytes that are not UTF-8 only by throwing.
+    return null;
+  }
+}
+
+/**
+ * This module's codec as the source of a classic browser script, for a page
+ * that cannot import an ES module (Identity's passkey popup, the x.sv reveal
+ * page): it declares `bytesToBase64`, `bytesToBase64url`, `base64ToBytes` and
+ * `base64urlToBytes` and everything they read at the script's top level, built
+ * from the functions and constants above, so the page runs this codec, not a
+ * copy. A new module-scope binding any of them reads must be added here.
+ * Marked pure so a bundle that never reads it (the browser SDK's) drops it.
+ */
+export const ENCODING_SCRIPT = /* @__PURE__ */ [
+  `var PAD = ${PAD};`,
+  `var CHAR_CODE_CHUNK = ${CHAR_CODE_CHUNK};`,
+  alphabet,
+  `var BASE64 = alphabet(${JSON.stringify(BASE64_CHARACTERS)}, true);`,
+  `var BASE64URL = alphabet(${JSON.stringify(BASE64URL_CHARACTERS)}, false);`,
+  isAsciiWhitespace,
+  isUint8Array,
+  fromCharCodes,
+  encode,
+  decode,
+  bytesToBase64,
+  bytesToBase64url,
+  base64ToBytes,
+  base64urlToBytes
+].join('\n');

package/src/app-sdk/entropy-contract.js

@@ -0,0 +1,56 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/entropy-contract.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The request contract of the entropy endpoint (POST /v1/entropy/generate):
+ * the output formats it serves and how many bytes one request may ask for.
+ *
+ * Core's route enforces it; the console and both SDKs hold a request to it
+ * before sending, so a request the server would refuse is refused where it is
+ * made. Dependency-free: sdk-js bundles it and sdk-mobile carries a generated
+ * copy.
+ */
+
+/** Output formats the endpoint serves. `bytes` returns a number array; every other format a string. */
+export const ENTROPY_FORMATS = Object.freeze([
+  'hex',
+  'base64',
+  'base64url',
+  'alphanumeric',
+  'alphanumeric-mixed',
+  'password',
+  'numeric',
+  'uuid',
+  'bytes',
+]);
+
+/** The hardware ceiling on one entropy draw, in bytes. */
+export const MAX_DRAW_BYTES = 1024;
+
+/**
+ * Formats whose characters are drawn from an alphabet by rejection sampling.
+ * They open with two raw bytes per output character, so one request's output
+ * caps at half a draw. `numeric` rejects so few bytes that it opens with one
+ * byte per digit and keeps the full ceiling.
+ */
+export const CHARSET_FORMATS = Object.freeze(['alphanumeric', 'alphanumeric-mixed', 'password']);
+
+/**
+ * @param {unknown} format
+ * @returns {boolean} Whether the endpoint serves this output format
+ */
+export function isEntropyFormat(format) {
+  return ENTROPY_FORMATS.includes(format);
+}
+
+/**
+ * The most bytes one request may ask for in a format (`num_bytes` runs from 1
+ * to this). A `uuid` always draws 16 bytes, whatever the request names.
+ *
+ * @param {string} format - One of ENTROPY_FORMATS
+ * @returns {number}
+ */
+export function maxBytesFor(format) {
+  return CHARSET_FORMATS.includes(format) ? MAX_DRAW_BYTES / 2 : MAX_DRAW_BYTES;
+}

package/src/app-sdk/filename.js

@@ -0,0 +1,174 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/filename.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The one rule for which characters a file name may hold, shared by every
+ * runtime that stores a name (Core refuses them at ingest, and clients check
+ * before they send) and every runtime that saves a stored name to a device
+ * (Forge's Content-Disposition, the web console's download, the x.sv reveal
+ * page, the mobile share sheet). A download saves under the file's current
+ * name by this rule, or under SAVED_FILENAME_FALLBACK when it has none.
+ *
+ * UNSAFE characters are never stored, and are replaced in any name saved to a
+ * device: path separators, control characters (C0, DEL and C1), and the
+ * invisible bidirectional controls that make a name display a different
+ * extension than it has (`invoice<U+202E>fdp.exe` shows as `invoiceexe.pdf`).
+ *
+ * NON-PORTABLE characters (`: * ? " < > |`) are refused by the file systems a
+ * name is saved to, so they are never stored either. A saved name keeps them:
+ * a stored name cannot hold one, and Forge carries a name's exact text in the
+ * RFC 5987 `filename*` parameter.
+ *
+ * Pure and import-free, so a browser, a container and a Lambda load it alike;
+ * sdk-mobile mirrors it at build time (scripts/generate-app-sdk-mirrors.mjs).
+ */
+
+/** Path separators, control characters and bidirectional text controls. */
+const UNSAFE_FILENAME_CHARACTERS = /[\\/\p{Cc}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/u;
+
+/** Characters the file systems a name is saved to refuse. */
+const NON_PORTABLE_FILENAME_CHARACTERS = /[:*?"<>|]/;
+
+/** Why a name cannot be stored, as storableFilenameProblem reports it. */
+export const FILENAME_PROBLEMS = Object.freeze({
+  UNSAFE_CHARACTER: 'unsafe_character',
+  NON_PORTABLE_CHARACTER: 'non_portable_character',
+  ONLY_DOTS_OR_SPACES: 'only_dots_or_spaces'
+});
+
+const ONLY_DOTS_OR_SPACES = /^[\s.]+$/;
+
+/**
+ * What stops `name` from being stored as a file name, or null when nothing
+ * does. Length and emptiness are the storing runtime's own limits.
+ *
+ * @param {string} name
+ * @returns {string|null} One of FILENAME_PROBLEMS, or null
+ */
+export function storableFilenameProblem(name) {
+  if (UNSAFE_FILENAME_CHARACTERS.test(name)) return FILENAME_PROBLEMS.UNSAFE_CHARACTER;
+  if (NON_PORTABLE_FILENAME_CHARACTERS.test(name)) return FILENAME_PROBLEMS.NON_PORTABLE_CHARACTER;
+  if (ONLY_DOTS_OR_SPACES.test(name)) return FILENAME_PROBLEMS.ONLY_DOTS_OR_SPACES;
+  return null;
+}
+
+/**
+ * A name as it is saved to a device: every unsafe character replaced by `_`.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function toSavedFilename(name) {
+  return name.replace(new RegExp(UNSAFE_FILENAME_CHARACTERS.source, 'gu'), '_');
+}
+
+/** The one name a download is saved under when its file has no name. */
+export const SAVED_FILENAME_FALLBACK = 'download';
+
+/**
+ * The name a download is saved under: the file's own name by the saved-name
+ * rule (toSavedFilename), or SAVED_FILENAME_FALLBACK when it has none.
+ *
+ * @param {string|null|undefined} name
+ * @returns {string}
+ */
+export function savedFilename(name) {
+  return typeof name === 'string' && name !== '' ? toSavedFilename(name) : SAVED_FILENAME_FALLBACK;
+}
+
+/**
+ * The saved-name rule as the source of a classic browser script, for a page
+ * that cannot import an ES module (the x.sv reveal page): it declares
+ * `savedFilename` and everything it reads at the script's top level, built
+ * from the functions and constants above, so the page runs this rule, not a
+ * copy. A new module-scope binding the rule reads must be added here.
+ */
+export const SAVED_FILENAME_SCRIPT = [
+  `var UNSAFE_FILENAME_CHARACTERS = ${UNSAFE_FILENAME_CHARACTERS};`,
+  `var SAVED_FILENAME_FALLBACK = ${JSON.stringify(SAVED_FILENAME_FALLBACK)};`,
+  toSavedFilename,
+  savedFilename
+].join('\n');
+
+/**
+ * A storable name derived from text nobody chose as a file name (a note's
+ * title, a device's file name): every unsafe or non-portable character
+ * replaced by `_`. It can still be only dots or spaces, which a caller that
+ * derives a name must refuse or replace itself.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function toStorableFilename(text) {
+  return toSavedFilename(text).replace(new RegExp(NON_PORTABLE_FILENAME_CHARACTERS.source, 'g'), '_');
+}
+
+/** The longest name an ingot stores, in UTF-16 code units. */
+export const INGOT_NAME_MAX = 255;
+
+/**
+ * Two-part extensions that mark a SparkVault document, by the editor that
+ * opens it. A name's extension is the whole marker, so a numbered or
+ * shortened copy still opens in its editor ("Plan (2).note.html", never
+ * "Plan.note (2).html"); the console and the mobile app classify a document by
+ * these lists (./ingot-kind.js).
+ */
+export const WHITEBOARD_MARKER_EXTENSIONS = Object.freeze(['.whiteboard.svg', '.whiteboard.png']);
+export const NOTE_MARKER_EXTENSIONS = Object.freeze(['.note.html', '.note.htm']);
+
+/** Every SparkVault document marker. */
+export const DOCUMENT_MARKER_EXTENSIONS = Object.freeze([...WHITEBOARD_MARKER_EXTENSIONS, ...NOTE_MARKER_EXTENSIONS]);
+
+/**
+ * A name's stem and extension: "report.pdf" is { stem: "report", extension:
+ * ".pdf" }, "Plan.note.html" is { stem: "Plan", extension: ".note.html" }, and
+ * a leading dot is part of the stem.
+ *
+ * @param {string} name
+ * @returns {{ stem: string, extension: string }}
+ */
+export function splitExtension(name) {
+  const lowerName = name.toLowerCase();
+  const marker = DOCUMENT_MARKER_EXTENSIONS.find(
+    (candidate) => lowerName.endsWith(candidate) && lowerName.length > candidate.length
+  );
+  const dot = marker ? name.length - marker.length : name.lastIndexOf('.');
+  return dot > 0
+    ? { stem: name.slice(0, dot), extension: name.slice(dot) }
+    : { stem: name, extension: '' };
+}
+
+/**
+ * The longest prefix of `text` within `maxLength` UTF-16 units that splits no
+ * character.
+ *
+ * @param {string} text
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function truncateToLength(text, maxLength) {
+  let truncated = '';
+  for (const character of text) {
+    if (truncated.length + character.length > maxLength) break;
+    truncated += character;
+  }
+  return truncated;
+}
+
+/**
+ * `name` shortened to at most `maxLength` UTF-16 units, keeping its extension:
+ * the stem gives way, and a name whose extension leaves no room for a stem is
+ * shortened as a whole.
+ *
+ * @param {string} name
+ * @param {number} [maxLength=INGOT_NAME_MAX]
+ * @returns {string}
+ */
+export function fitName(name, maxLength = INGOT_NAME_MAX) {
+  if (name.length <= maxLength) return name;
+  const { stem, extension } = splitExtension(name);
+  return extension.length < maxLength
+    ? `${truncateToLength(stem, maxLength - extension.length)}${extension}`
+    : truncateToLength(name, maxLength);
+}