@sparkvault/sdk-mobile 6.0.2 → 7.0.0

package/src/app-sdk/forge-url.js

@@ -0,0 +1,224 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/forge-url.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Forge transfer URLs: the one reading of the URL Core issues for an ingot
+ * transfer, `https://forge.sparkvault.com/{encrypt|decrypt}?istk=…`, and of the
+ * session URL a tus upload continues at, whether just created or kept (resumed,
+ * probed or terminated).
+ *
+ * The URL carries the ISTK, a bearer credential for one transfer, and an upload
+ * sends the plaintext after it, so every client reads the URL here before a
+ * byte or the credential leaves: the Node tus client (forge-tus), both SDKs
+ * (sdk-js bundles this module; sdk-mobile carries a generated copy), the
+ * console, the Slack app, the HubSpot record tab and the Salesforce record
+ * panel (each a generated copy). Core builds the URL with `forgeTransferUrl`.
+ *
+ * Both readings are string rules over the one shape Core and Forge write, not
+ * a URL parser: a React Native host need not provide a WHATWG `URL` (React
+ * Native's own resolves relative references and serializes query strings
+ * differently), and a shape this strict leaves nothing for a parser to
+ * normalize, so a transfer goes to exactly the host and path that was checked.
+ *
+ * Dependency-free and free of runtime globals.
+ */
+
+import { SPARKVAULT_FORGE_HOST } from './platform-domains.js';
+
+/** Why a transfer URL was refused; each caller raises its own error for the reason. */
+export const FORGE_URL_REFUSAL = Object.freeze({
+  /** Not a string, or not an absolute URL written in printable ASCII. */
+  INVALID: 'invalid_url',
+  /** Not https: the credential and the bytes would cross the network in the clear. */
+  NOT_HTTPS: 'not_https',
+  /** Userinfo, a port or a fragment, none of which Core ever issues. */
+  UNSAFE_PARTS: 'unsafe_parts',
+  /** A host the caller does not send transfers to, or one that is not a DNS name. */
+  HOST: 'host_not_allowed',
+  /** A path other than the transfer operation's own. */
+  OPERATION: 'wrong_operation',
+  /** No ISTK, more than one, or one that is not base64url. */
+  ISTK: 'bad_istk',
+});
+
+/** An ISTK is base64url; its length is Core's to choose, so it is not pinned. */
+const ISTK_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/** A tus session Forge opens under its endpoint (`tus_<hex>`): one segment, no dot segment or escape. */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/** Printable ASCII with no space: every character a transfer URL is written in. */
+const URL_TEXT = /^[\x21-\x7e]+$/;
+
+/** An absolute URL cut at its delimiters: scheme, authority, path, query, fragment. */
+const ABSOLUTE_URL = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)([^?#]*)(?:\?([^#]*))?(#.*)?$/;
+
+/** A DNS name: letter-digit-hyphen labels joined by dots (compared lowercased). */
+const HOSTNAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+
+/**
+ * Forge's own host, the one a platform-issued transfer URL names.
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isForgeHost(hostname) {
+  return hostname === SPARKVAULT_FORGE_HOST;
+}
+
+/**
+ * The URL Core issues for a transfer: Forge's operation endpoint carrying the
+ * ISTK.
+ *
+ * @param {'encrypt'|'decrypt'} operation
+ * @param {string} istk
+ * @returns {string}
+ */
+export function forgeTransferUrl(operation, istk) {
+  return `https://${SPARKVAULT_FORGE_HOST}/${operation}?istk=${encodeURIComponent(istk)}`;
+}
+
+/**
+ * Read a Core-issued transfer URL. It must be written in printable ASCII, be
+ * https, carry no userinfo, port or fragment, name an allowed host, have the
+ * operation as its whole path, and carry exactly one base64url `istk`. Other
+ * query parameters (a preview URL's `disposition=inline`) ride along; the query
+ * is read the way a form encodes one (`+` is a space, escapes are decoded).
+ *
+ * A download fetches the URL it read as it was written; an upload is created
+ * at `endpoint` with the ISTK in a header.
+ *
+ * @param {unknown} value
+ * @param {Object} options
+ * @param {'encrypt'|'decrypt'} options.operation - The transfer the URL must name
+ * @param {(hostname: string) => boolean} [options.isAllowedHost] - Forge's own
+ *   host by default; a published SDK passes its configured allowlist. It is
+ *   handed the lowercased host name.
+ * @returns {{ ok: true, origin: string, endpoint: string, istk: string } | { ok: false, reason: string }}
+ *   `origin` is the scheme and host; `endpoint` is where a tus upload is created.
+ */
+export function readForgeTransferUrl(value, { operation, isAllowedHost = isForgeHost }) {
+  const url = readHttpsUrl(value);
+  if (!url.ok) return url;
+  if (!isAllowedHost(url.hostname)) return refused(FORGE_URL_REFUSAL.HOST);
+  if (url.path !== `/${operation}`) return refused(FORGE_URL_REFUSAL.OPERATION);
+  const istks = queryValues(url.query, 'istk');
+  if (istks.length !== 1 || !ISTK_PATTERN.test(istks[0])) return refused(FORGE_URL_REFUSAL.ISTK);
+  const origin = `https://${url.hostname}`;
+  return { ok: true, origin, endpoint: `${origin}/${operation}`, istk: istks[0] };
+}
+
+/**
+ * Whether a value is exactly the URL Core issues for a transfer
+ * (`forgeTransferUrl`), with nothing added or re-spelled. A client deployed
+ * with Core may demand this; a published SDK, which must accept what a newer
+ * Core adds, reads with readForgeTransferUrl.
+ *
+ * @param {unknown} value
+ * @param {'encrypt'|'decrypt'} operation
+ * @returns {boolean}
+ */
+export function isIssuedForgeTransferUrl(value, operation) {
+  const read = readForgeTransferUrl(value, { operation });
+  return read.ok && value === forgeTransferUrl(operation, read.istk);
+}
+
+/**
+ * Place the session a tus create answered with (its `Location`) under the
+ * endpoint the session was created at. Every later request carries the ISTK
+ * and the file's bytes, so the session must be one segment directly under the
+ * endpoint's path on the endpoint's own origin: `<endpoint path>/<session>` as
+ * Forge sends it, or the same with the endpoint's origin written in front.
+ *
+ * @param {unknown} location
+ * @param {string} endpoint - An `endpoint` readForgeTransferUrl returned
+ * @returns {string|null} The session URL, or null when the answer points anywhere else
+ */
+export function resolveForgeSessionUrl(location, endpoint) {
+  const base = readHttpsUrl(endpoint);
+  if (!base.ok || base.query !== undefined || typeof location !== 'string' || !URL_TEXT.test(location)) {
+    return null;
+  }
+  const origin = `https://${base.hostname}`;
+  let path = null;
+  if (location.startsWith(`${origin}/`)) {
+    path = location.slice(origin.length);
+  } else if (location.startsWith('/') && !location.startsWith('//')) {
+    path = location;
+  }
+  if (path === null || !path.startsWith(`${base.path}/`)) return null;
+  const session = path.slice(base.path.length + 1);
+  return SESSION_ID_PATTERN.test(session) ? `${origin}${base.path}/${session}` : null;
+}
+
+/**
+ * Read a tus session URL a client kept to resume an upload: a session Forge
+ * opened directly under the operation's endpoint on an allowed host, exactly
+ * as resolveForgeSessionUrl placed it when the session was created. A resumed
+ * session receives the ISTK and the file's bytes, so it is held to the rule a
+ * created one was.
+ *
+ * @param {unknown} value
+ * @param {Object} options
+ * @param {'encrypt'|'decrypt'} options.operation - The transfer the session belongs to
+ * @param {(hostname: string) => boolean} [options.isAllowedHost] - As for readForgeTransferUrl
+ * @returns {{ ok: true, url: string } | { ok: false, reason: string }}
+ */
+export function readForgeSessionUrl(value, { operation, isAllowedHost = isForgeHost }) {
+  const url = readHttpsUrl(value);
+  if (!url.ok) return url;
+  if (!isAllowedHost(url.hostname)) return refused(FORGE_URL_REFUSAL.HOST);
+  const session = resolveForgeSessionUrl(value, `https://${url.hostname}/${operation}`);
+  return session === null ? refused(FORGE_URL_REFUSAL.OPERATION) : { ok: true, url: session };
+}
+
+/**
+ * Cut an https URL into its host name, path and query by string rules alone.
+ * @param {unknown} value
+ * @returns {{ ok: true, hostname: string, path: string, query: string|undefined } | { ok: false, reason: string }}
+ */
+function readHttpsUrl(value) {
+  if (typeof value !== 'string' || !URL_TEXT.test(value)) return refused(FORGE_URL_REFUSAL.INVALID);
+  const parts = ABSOLUTE_URL.exec(value);
+  if (!parts) return refused(FORGE_URL_REFUSAL.INVALID);
+  const [, scheme, authority, path, query, fragment] = parts;
+  if (scheme.toLowerCase() !== 'https') return refused(FORGE_URL_REFUSAL.NOT_HTTPS);
+  if (authority.includes('@') || /:[0-9]*$/.test(authority) || fragment !== undefined) {
+    return refused(FORGE_URL_REFUSAL.UNSAFE_PARTS);
+  }
+  const hostname = authority.toLowerCase();
+  if (!HOSTNAME.test(hostname)) return refused(FORGE_URL_REFUSAL.HOST);
+  return { ok: true, hostname, path, query };
+}
+
+/**
+ * Every value of one query parameter, names and values read as a form encodes
+ * them: `+` is a space and escapes are decoded (text that is not a valid
+ * escape sequence stays as written).
+ * @param {string|undefined} query
+ * @param {string} name
+ * @returns {string[]}
+ */
+function queryValues(query, name) {
+  const values = [];
+  for (const pair of (query ?? '').split('&')) {
+    if (!pair) continue;
+    const equals = pair.indexOf('=');
+    const key = formDecode(equals === -1 ? pair : pair.slice(0, equals));
+    if (key === name) values.push(equals === -1 ? '' : formDecode(pair.slice(equals + 1)));
+  }
+  return values;
+}
+
+function formDecode(text) {
+  const spaced = text.replace(/\+/g, ' ');
+  try {
+    return decodeURIComponent(spaced);
+  } catch {
+    return spaced;
+  }
+}
+
+function refused(reason) {
+  return { ok: false, reason };
+}

package/src/app-sdk/ids.js

@@ -0,0 +1,71 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/ids.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * SparkVault resource ids: the one grammar every surface reads an id by before
+ * the id names a request path or a stored file.
+ *
+ * Core mints an id as its kind's prefix, an underscore and a body: the hex of a
+ * UUIDv7 (apps/api lib/utils.js buildPrefixedIdFromBytes), or a hex digest for
+ * an invitation and an inbox notification. The grammar admits the kind's
+ * prefix, '_' and a body of the path-safe alphabet [A-Za-z0-9_-], 128
+ * characters in all, so an id that passes is exactly one request-path segment
+ * and one file-name component: it can never name a parent path, carry a
+ * separator or a dot-segment, or read as an id of another kind.
+ *
+ * - `isResourceIdOf(kind, value)`: an id of that kind.
+ * - `isResourceId(value)`: an id of any kind, for a check that takes several.
+ *
+ * Browser-safe and import-free: sdk-js bundles it, sdk-mobile mirrors it, and
+ * the apps, the console and the mobile app import it.
+ */
+
+/** The prefix Core mints each resource kind's id with. */
+export const RESOURCE_ID_PREFIXES = Object.freeze({
+  account: 'acc',
+  folder: 'fld',
+  ingot: 'ing',
+  invite: 'inv',
+  notification: 'ntf',
+  spark: 'spk',
+  user: 'usr',
+  vault: 'vlt'
+});
+
+/** The longest id, prefix included. */
+export const RESOURCE_ID_MAX_LENGTH = 128;
+
+const ID_BODY = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Whether a value is an id of the given kind.
+ *
+ * @param {string} kind - A key of RESOURCE_ID_PREFIXES
+ * @param {unknown} value
+ * @returns {boolean}
+ * @throws {TypeError} for a kind the grammar does not name: a misspelled kind
+ *   would otherwise refuse every id without saying why
+ */
+export function isResourceIdOf(kind, value) {
+  if (!Object.hasOwn(RESOURCE_ID_PREFIXES, kind)) {
+    throw new TypeError(`No resource kind '${kind}'`);
+  }
+  const prefix = `${RESOURCE_ID_PREFIXES[kind]}_`;
+  return typeof value === 'string'
+    && value.length <= RESOURCE_ID_MAX_LENGTH
+    && value.startsWith(prefix)
+    && ID_BODY.test(value.slice(prefix.length));
+}
+
+const KINDS = Object.freeze(Object.keys(RESOURCE_ID_PREFIXES));
+
+/**
+ * Whether a value is an id of any kind.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isResourceId(value) {
+  return KINDS.some((kind) => isResourceIdOf(kind, value));
+}

package/src/app-sdk/ingot-access-log.js

@@ -0,0 +1,51 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/ingot-access-log.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Ingot access logs: which of an ingot's audit events are accesses, and how one
+ * audit entry reads as an access. Both SDKs read
+ * GET /v1/vaults/{vault_id}/ingots/{ingot_id}/audit-logs through it: sdk-js
+ * bundles this module, and sdk-mobile (which publishes standalone) carries a
+ * build-time copy pinned byte-for-byte by its drift test.
+ *
+ * An entry arrives in the server's public audit shape (AuditLogRepository
+ * toPublicFormat, annotated by the audit-log controller's actor resolution):
+ * `timestamp`, `event_type`, `actor_id`, `actor_type`, `actor_display`,
+ * `ip_address`, `user_agent`, `metadata` (null while encrypted), `encrypted`,
+ * `vault_id` and `ingot_id`.
+ */
+
+/**
+ * The ingot audit events that are accesses, and what each one is: Core records
+ * an access to a file as the download that delivered it, a SparkLink open of
+ * the file included.
+ */
+const ACCESS_ACTIONS = new Map([
+  ['ingot_downloaded', 'download'],
+]);
+
+/** The event types an access-log request asks the server for. */
+export const INGOT_ACCESS_EVENT_TYPES = Object.freeze([...ACCESS_ACTIONS.keys()]);
+
+/**
+ * One audit entry as an access. The actor reads as the server resolved it (a
+ * member's email, an API key's name), else as the identity a SparkLink visitor
+ * gave (kept in the entry's metadata), else as the raw actor id.
+ *
+ * @param {{ timestamp: number, event_type: string, actor_id?: string | null, actor_display?: string,
+ *   ip_address?: string | null, user_agent?: string | null, metadata?: { identity?: string | null } | null }} entry
+ * @returns {{ timestamp: number, action: 'download', identity: string, ip_address: string,
+ *   user_agent: string } | null} null for an event that is not an access
+ */
+export function readIngotAccess(entry) {
+  const action = ACCESS_ACTIONS.get(entry.event_type);
+  if (action === undefined) return null;
+  return {
+    timestamp: entry.timestamp,
+    action,
+    identity: entry.actor_display || entry.metadata?.identity || entry.actor_id || 'Unknown',
+    ip_address: entry.ip_address ?? '',
+    user_agent: entry.user_agent ?? '',
+  };
+}

package/src/app-sdk/phone.js

@@ -0,0 +1,139 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/phone.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Phone numbers a person types: how one reads as E.164, and whether a typed
+ * identifier is a phone number at all. Pure, with no imports, so a browser or
+ * an SDK bundle can carry it: Core reads and checks every phone it is given
+ * with it, the console imports it, sdk-js bundles it, and sdk-mobile carries a
+ * build-time copy pinned byte-for-byte by its drift test.
+ *
+ * A '+' ahead of the digits DECLARES the country code, so every digit is kept
+ * exactly as given: ten digits after a '+' are a foreign number (+47 Norway,
+ * +45 Denmark, +65 Singapore, +354 Iceland …), and reading them as a NANP number
+ * would hand an OTP or a bearer link to whoever holds the matching North
+ * American line. Only input WITHOUT a '+' may take the NANP shorthand: exactly
+ * ten digits, or eleven starting with the '1'. Any other bare digit string
+ * declares no country and is refused rather than guessed.
+ *
+ * A typed number holds ASCII digits, at most one '+' ahead of all of them, and
+ * the separators people type: whitespace, parentheses, dots and dashes of any
+ * script, and the invisible formatting marks a contacts app wraps a number in.
+ * The separators and marks are dropped. Anything else is refused, never
+ * dropped: stripping it would fold part of the text into the number and deliver
+ * to someone else's line — a letter or a dial-control character (',' and ';'
+ * pause, '#' and '*' are keypad tones) carries an extension ("x2", ",89"), a
+ * digit of another script ('٧', '７') is a digit the ASCII read would silently
+ * lose, and a '+' after a digit declares nothing.
+ *
+ * An identifier typed where an email address or a phone number is accepted is
+ * a phone number only when it holds phone characters only, led by a digit, '+'
+ * or '(': an email whose local part starts with a digit ("2024user@gmail.com",
+ * "12345678@qq.com") stays an email.
+ */
+
+/** A '+' before any digit: the caller declared the country code. */
+const DECLARED_COUNTRY_CODE = /^\D*\+/;
+
+/** E.164 digits once a country code is declared: 8–15, never a leading 0. */
+const E164_DIGITS = /^[1-9]\d{7,14}$/;
+
+/** A canonical E.164 value. */
+const E164 = /^\+[1-9]\d{7,14}$/;
+
+/** Invisible formatting marks (bidi embeddings, zero-width characters), in any number. */
+const FORMAT_MARKS = /\p{Cf}/gu;
+
+/**
+ * Typed phone text once its formatting marks are dropped: ASCII digits and
+ * separators, with at most one '+', ahead of every digit.
+ */
+const PHONE_TEXT = /^[\s().\p{Pd}]*\+?[\d\s().\p{Pd}]*$/u;
+
+/** How phone text starts where an identifier may be either: a digit, '+' or '('. */
+const PHONE_LEAD = /^[+(\d]/;
+
+/**
+ * @param {string} value
+ * @returns {string} The value without its formatting marks
+ */
+function withoutFormatMarks(value) {
+  return value.replace(FORMAT_MARKS, '');
+}
+
+/**
+ * Read a typed phone number as E.164.
+ *
+ * @param {unknown} raw
+ * @returns {string|null} E.164 with its leading '+', or null when the input
+ *   names no dialable number
+ */
+export function parsePhone(raw) {
+  if (typeof raw !== 'string') return null;
+  const text = withoutFormatMarks(raw);
+  if (!PHONE_TEXT.test(text)) return null;
+  const digits = text.replace(/\D/g, '');
+
+  if (DECLARED_COUNTRY_CODE.test(text)) {
+    return E164_DIGITS.test(digits) ? `+${digits}` : null;
+  }
+  if (digits.length === 10) return `+1${digits}`;
+  if (digits.length === 11 && digits.startsWith('1')) return `+${digits}`;
+  return null;
+}
+
+/**
+ * Whether a value is already a canonical E.164 phone number — exactly the
+ * values parsePhone returns unchanged.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isE164Phone(value) {
+  return typeof value === 'string' && E164.test(value);
+}
+
+/**
+ * Whether an identifier typed where either is accepted is an email address or
+ * a phone number.
+ *
+ * @param {unknown} value
+ * @returns {'email' | 'phone'}
+ */
+export function inferIdentityType(value) {
+  if (typeof value !== 'string') return 'email';
+  const text = withoutFormatMarks(value).trim();
+  return PHONE_LEAD.test(text) && PHONE_TEXT.test(text) ? 'phone' : 'email';
+}
+
+/**
+ * A phone number as a phone field shows it while it is typed: a NANP number as
+ * (XXX) XXX-XXXX; a declared country code, or a digit string that is not a NANP
+ * number, keeps every digit as given, so formatting never turns one destination
+ * into another. Text holding anything but phone characters (a letter, a
+ * dial-control character, a digit of another script) is left as typed, so it
+ * reaches parsePhone and is refused there instead of being dropped from the
+ * field.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function formatPhoneDisplay(value) {
+  const text = withoutFormatMarks(value);
+  if (!PHONE_TEXT.test(text)) return value;
+  const digits = text.replace(/\D/g, '');
+
+  if (DECLARED_COUNTRY_CODE.test(text) && !(digits.startsWith('1') && digits.length === 11)) {
+    return `+${digits}`;
+  }
+  if (digits.length > 11 || (digits.length === 11 && !digits.startsWith('1'))) {
+    return digits;
+  }
+
+  const national = digits.length === 11 ? digits.slice(1) : digits;
+  if (national.length === 0) return '';
+  if (national.length <= 3) return `(${national}`;
+  if (national.length <= 6) return `(${national.slice(0, 3)}) ${national.slice(3)}`;
+  return `(${national.slice(0, 3)}) ${national.slice(3, 6)}-${national.slice(6, 10)}`;
+}

package/src/app-sdk/platform-domains.js

@@ -0,0 +1,99 @@
+// 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
+
+/**
+ * SparkVault-owned domain registry.
+ *
+ * Keep platform domain decisions centralized: CSP, redirect safety, custom
+ * domain reservation, and Identity postMessage trust all depend on the same
+ * ownership boundary.
+ */
+
+export const SPARKVAULT_ROOT_DOMAIN = 'sparkvault.com';
+
+/** The person-facing Identity portal host (auth.sv shell + hosted login). */
+export const SPARKVAULT_AUTH_HOST = 'auth.sv';
+
+/**
+ * The Identity IdP origin's host: it serves the OIDC ceremonies (/authorize,
+ * /token), the SDK sign-in page and the Identity API, issues every Identity
+ * token (`iss` is https://{host}/{account_id}), and holds the hub session
+ * cookie. Core verifies the tokens it issues and the Identity product mints
+ * them, so both name it from here. Never the auth.sv portal host.
+ */
+export const SPARKVAULT_IDENTITY_HOST = 'auth.sparkvault.com';
+
+/** The SparkLinks host: shared Sparks, single-use links and the Messaging recipient pages. */
+export const SPARKVAULT_LINKS_HOST = 'x.sv';
+
+/** The durable file-share and Secure Upload Portal host. */
+export const SPARKVAULT_FILES_HOST = 'files.sv';
+
+export const SPARKVAULT_PLATFORM_SV_HOSTS = Object.freeze([
+  SPARKVAULT_AUTH_HOST,
+  SPARKVAULT_LINKS_HOST,
+  SPARKVAULT_FILES_HOST,
+  'file.sv',
+  'send.sv',
+  'spark.sv',
+  'by.sv',
+  'at.sv',
+  'db.sv'
+]);
+
+/** The SparkVault console. */
+export const SPARKVAULT_APP_HOST = 'app.sparkvault.com';
+
+/** Forge, the streaming encrypt/decrypt service every ingot transfer goes through. */
+export const SPARKVAULT_FORGE_HOST = 'forge.sparkvault.com';
+
+const SPARKVAULT_WEBSOCKET_HOSTS = Object.freeze([
+  'ws.sparkvault.com'
+]);
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The platform's own hosts as patterns over a URL's hostname: the root domain
+ * and its subdomains, and each .sv host exactly (isSparkVaultOwnedHostname).
+ * Both SDKs trust a backend-issued transfer URL on these hosts by default;
+ * their `allowedDownloadHostPatterns` option replaces the list for another
+ * deployment.
+ */
+export const SPARKVAULT_OWNED_HOST_PATTERNS = Object.freeze([
+  new RegExp(`(^|\\.)${escapeRegExp(SPARKVAULT_ROOT_DOMAIN)}$`, 'i'),
+  new RegExp(`^(${SPARKVAULT_PLATFORM_SV_HOSTS.map(escapeRegExp).join('|')})$`, 'i')
+]);
+
+function normalizeHostname(hostname) {
+  if (typeof hostname !== 'string') return '';
+  return hostname.trim().toLowerCase().replace(/\.$/, '');
+}
+
+export function isSparkVaultRootOrSubdomain(hostname) {
+  const normalized = normalizeHostname(hostname);
+  return normalized === SPARKVAULT_ROOT_DOMAIN || normalized.endsWith(`.${SPARKVAULT_ROOT_DOMAIN}`);
+}
+
+export function isSparkVaultPlatformSvHost(hostname) {
+  return SPARKVAULT_PLATFORM_SV_HOSTS.includes(normalizeHostname(hostname));
+}
+
+export function isSparkVaultOwnedHostname(hostname) {
+  return isSparkVaultRootOrSubdomain(hostname) || isSparkVaultPlatformSvHost(hostname);
+}
+
+export function isSparkVaultReservedDomain(hostname) {
+  return isSparkVaultOwnedHostname(hostname);
+}
+
+export function sparkVaultPlatformSvOrigins() {
+  return SPARKVAULT_PLATFORM_SV_HOSTS.map((host) => `https://${host}`);
+}
+
+export function sparkVaultWebSocketOrigins() {
+  return SPARKVAULT_WEBSOCKET_HOSTS.map((host) => `wss://${host}`);
+}

package/src/app-sdk/request-path.js

@@ -0,0 +1,81 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/request-path.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Request paths: the one rule every SDK applies before a caller-supplied value
+ * becomes part of a SparkVault request URL.
+ *
+ * A request carries the caller's credentials (a Bearer token, an API key, a
+ * Vault Access Token), so a value that smuggles '/' or a dot-segment into the
+ * path would re-target that credentialed request at another route. The rules:
+ *
+ * - `encodePathSegment`: every value interpolated into a path is encoded as
+ *   exactly one segment. Percent-encoding keeps '/', '?' and '#' inside the
+ *   segment, and the three values no encoding can keep one segment ('', '.'
+ *   and '..', which URL resolution drops or collapses) are refused.
+ * - `buildRequestPath`: the template loop an SDK's tagged path builder runs,
+ *   so every interpolated value passes `encodePathSegment` by construction.
+ * - `queryString`: the one query encoding, which leaves unset values out.
+ *
+ * A server-issued id is checked for its shape first, by the one resource-id
+ * grammar (ids.js).
+ *
+ * Browser-safe and dependency-free: sdk-js bundles it, and sdk-mobile (which
+ * publishes standalone) carries a build-time copy pinned byte-for-byte by its
+ * drift test. Each SDK wraps it in a typed front door that throws its own
+ * validation error.
+ */
+
+/**
+ * Encode a value as exactly one request-path segment.
+ * @param {unknown} value
+ * @returns {string | null} the encoded segment, or null when the value cannot
+ *   be one segment: not a string, empty, '.', '..', or not well-formed UTF-16
+ *   (a lone surrogate has no percent-encoding).
+ */
+export function encodePathSegment(value) {
+  if (typeof value !== 'string' || value === '' || value === '.' || value === '..') {
+    return null;
+  }
+  try {
+    return encodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Join a tagged template's literals with its values, each value encoded as
+ * exactly one path segment.
+ * @param {readonly string[]} literals
+ * @param {readonly unknown[]} values
+ * @returns {string | null} the path, or null when any value cannot be one
+ *   segment (see `encodePathSegment`).
+ */
+export function buildRequestPath(literals, values) {
+  let path = literals[0];
+  for (let index = 0; index < values.length; index += 1) {
+    const segment = encodePathSegment(values[index]);
+    if (segment === null) return null;
+    path += segment + literals[index + 1];
+  }
+  return path;
+}
+
+/**
+ * Encode query parameters, leaving out every unset value (`undefined`, `null`
+ * or `''`). Other values are sent as their string form, so `0` and `false`
+ * are sent.
+ * @param {Readonly<Record<string, string | number | boolean | null | undefined>> | undefined} params
+ * @returns {string} `?a=1&b=2`, or '' when no value is set.
+ */
+export function queryString(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value === undefined || value === null || value === '') continue;
+    search.append(key, String(value));
+  }
+  const query = search.toString();
+  return query ? `?${query}` : '';
+}