@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/src/app-sdk/upload-publication.js

@@ -0,0 +1,102 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/upload-publication.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The upload publication contract between Forge and Core's activation.
+ *
+ * Forge stamps UPLOAD_PUBLICATION_PROTOCOL on every upload session it creates
+ * and on the final state it hands Core's activation (POST
+ * /v1/vaults/:vault_id/ingots/:ingot_id/activate); activation refuses any
+ * other version. The two services deploy separately, so a change to what
+ * either side sends or expects moves this number: a session or a finalize
+ * from the other side's contract then fails closed ("restart the upload")
+ * instead of publishing under a contract the other side does not hold.
+ *
+ * Version 2: an upload's own metadata (content type, original file name,
+ * uploader, content HMAC) travels on its upload token and its session, and
+ * activation publishes it from the session; the final state Forge sends
+ * carries only the storage facts Forge owns.
+ *
+ * Isomorphic: no Node imports.
+ */
+
+export const UPLOAD_PUBLICATION_PROTOCOL = 2;
+
+/**
+ * An upload's id as both services spell it: `tus_` and the 32 lowercase hex
+ * digits of 16 random bytes. An encrypt token that names one (`upload_id`)
+ * was staged by Core under it, and Forge keys the upload's session, its chunk
+ * prefix and its VAK wrapping by it, so Core finds and settles the upload by
+ * the session's id.
+ */
+export const UPLOAD_ID_PATTERN = /^tus_[0-9a-f]{32}$/;
+
+/**
+ * How much of an ISTK names a transfer's charge on the usage ledger: enough to
+ * be unique to the token, never the whole bearer credential.
+ */
+export const TRANSFER_REFERENCE_ISTK_CHARS = 24;
+
+/**
+ * The ledger reference of an upload's transfer charge,
+ * `forge_ingot_transfer_upload_<first 24 ISTK chars>`: every charge of one
+ * upload carries it — Core's activation, Core's charge of an upload that never
+ * publishes, Forge's cancel — so whichever lands first is the upload's one
+ * ledger row and the others are duplicates.
+ *
+ * @param {string} istk - The upload's ISTK, as its session carries it
+ * @returns {string}
+ * @throws {TypeError} When the ISTK is not a string of at least
+ *   TRANSFER_REFERENCE_ISTK_CHARS characters
+ */
+export function uploadTransferReference(istk) {
+  if (typeof istk !== 'string' || istk.length < TRANSFER_REFERENCE_ISTK_CHARS) {
+    throw new TypeError(
+      `An upload's transfer reference is named from its ISTK, a string of at least ${TRANSFER_REFERENCE_ISTK_CHARS} characters`
+    );
+  }
+  return `forge_ingot_transfer_upload_${istk.slice(0, TRANSFER_REFERENCE_ISTK_CHARS)}`;
+}
+
+/**
+ * The codes Core's activation refuses an upload with, which Forge's refusal
+ * map reads (the status is Core's):
+ * - UPLOAD_CONTRACT_MISMATCH (409): a finalize or session from another
+ *   publication contract than Core's, a mixed deployment that converges — the
+ *   upload is kept and its finalize tried again.
+ * - UPLOAD_PROTOCOL_RETIRED (410): a session from a contract Core no longer
+ *   publishes, which never can be.
+ * - UPLOAD_SUPERSEDED (410): a session a later staging of its ingot
+ *   superseded, which never can be.
+ * - UPLOAD_POOL_FULL (402): an upload the owner's storage pool cannot take at
+ *   publication, which is final.
+ */
+export const UPLOAD_REFUSAL_CODES = Object.freeze({
+  UPLOAD_CONTRACT_MISMATCH: 'UPLOAD_CONTRACT_MISMATCH',
+  UPLOAD_PROTOCOL_RETIRED: 'UPLOAD_PROTOCOL_RETIRED',
+  UPLOAD_SUPERSEDED: 'UPLOAD_SUPERSEDED',
+  UPLOAD_POOL_FULL: 'UPLOAD_POOL_FULL'
+});
+
+/**
+ * The refusals of Core's that a new upload of the same file cannot remedy:
+ * the owner's storage pool cannot take it (UPLOAD_POOL_FULL), or a later
+ * upload of its ingot replaced it (UPLOAD_SUPERSEDED). Any other code Core
+ * ends an upload with ends its session alone, which a new upload starts
+ * over. Every client reads a terminal answer's code by it
+ * (transfer-retry.js): one of these is a refusal it reports in Core's words,
+ * any other a gone session.
+ */
+export const UPLOAD_FINAL_REFUSAL_CODES = Object.freeze([
+  UPLOAD_REFUSAL_CODES.UPLOAD_POOL_FULL,
+  UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED
+]);
+
+/**
+ * The response header that names the code Core refused an upload with for
+ * good: Forge sends it on every terminal answer to a tus request, a HEAD's
+ * (which has no body) included, so a client tells an upload the owner's pool
+ * cannot take from one a later upload superseded without reading a body.
+ */
+export const UPLOAD_REFUSAL_HEADER = 'X-Upload-Refusal';

package/src/app-sdk/vat-refusal.js

@@ -0,0 +1,74 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/vat-refusal.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Why Core refused a Vault Access Token (VAT): the `details.reason` every VAT
+ * refusal carries, and the one reading of it clients share.
+ *
+ *   401 VAT_INVALID    no token, or a malformed, unknown or swept one, or one a
+ *                      since-revoked DVAK minted — unseal again
+ *   403 VAT_EXPIRED    the token outlived its TTL — unseal again, retry as-is
+ *   403 VAT_READ_ONLY  a View Only token on a write — no unseal fixes it
+ *
+ * A 403 with no reason is a token for another vault or account, which no
+ * unseal of this vault fixes; a 401 with no reason is the login itself, never
+ * the VAT. Browser-safe: no imports.
+ */
+
+export const VAT_REFUSAL_REASONS = Object.freeze({
+  INVALID: 'VAT_INVALID',
+  EXPIRED: 'VAT_EXPIRED',
+  READ_ONLY: 'VAT_READ_ONLY'
+});
+
+/** The status each refusal is answered with. */
+export const VAT_REFUSAL_STATUS = Object.freeze({
+  [VAT_REFUSAL_REASONS.INVALID]: 401,
+  [VAT_REFUSAL_REASONS.EXPIRED]: 403,
+  [VAT_REFUSAL_REASONS.READ_ONLY]: 403
+});
+
+/**
+ * The VAT refusal a Core error answer names, or null when it is not one.
+ *
+ * @param {{ statusCode?: number, details?: { reason?: string } }} error - An
+ *   error as parsed from a Core response (status plus the body's `details`)
+ * @returns {string|null} One of VAT_REFUSAL_REASONS, or null
+ */
+export function vatRefusalReason(error) {
+  const reason = error?.details?.reason;
+  return typeof reason === 'string' && Object.hasOwn(VAT_REFUSAL_STATUS, reason) &&
+    VAT_REFUSAL_STATUS[reason] === error?.statusCode
+    ? reason
+    : null;
+}
+
+/**
+ * Whether a refusal says the token's vault session is over: an invalid or an
+ * expired token, which only a new unseal replaces, so a client forgets it. A
+ * read-only refusal leaves the session standing (the token still reads), and
+ * so does a refusal that names no VAT reason.
+ *
+ * @param {string|null} reason - What vatRefusalReason returned
+ * @returns {boolean}
+ */
+export function endsVatSession(reason) {
+  return reason === VAT_REFUSAL_REASONS.INVALID || reason === VAT_REFUSAL_REASONS.EXPIRED;
+}
+
+/**
+ * True when Core refused the request's login, not a Vault Access Token it
+ * carried: a 401 bearing Core's session code (AUTHENTICATION_ERROR, the
+ * mapped error's `upstreamCode`) that names no VAT refusal. Its token was
+ * refused, or its account is unavailable (details.reason ACCOUNT_UNAVAILABLE,
+ * ./refusal-reasons.js). A 401 for a credential in the request body (an
+ * unseal key) carries Core's credential code (UNAUTHORIZED) and is not one.
+ *
+ * @param {{ statusCode?: number, upstreamCode?: string|null, details?: { reason?: string } }} error -
+ *   An error as parsed from a Core response (parseApiError)
+ * @returns {boolean}
+ */
+export function isRefusedLogin(error) {
+  return error?.statusCode === 401 && error?.upstreamCode === 'AUTHENTICATION_ERROR' && vatRefusalReason(error) === null;
+}

package/src/billing.ts

@@ -1,10 +1,6 @@
 import type { MobileHttpClient } from './http.js';
-import type { IapPlatform, SparkVaultSubscription } from './types.js';
-
-/** Short-lived Stripe Customer Portal URL for managing the subscription on web. */
-export interface PortalSession {
-  portal_url: string;
-}
+import type { IapPlatform, IapValidation, SparkVaultSubscription } from './types.js';
+import { apiPath } from './request-path.js';
 
 export class MobileBillingClient {
   private readonly http: MobileHttpClient;
@@ -14,38 +10,33 @@ export class MobileBillingClient {
   }
 
   /**
-   * Current subscription: plan, licensed vs. used seats, capacity blocks, live
-   * pool usage, and Identity attempts. Drives the subscription / usage view.
+   * Current subscription: billing lifecycle, licensed vs. used seats, capacity
+   * blocks, live pool usage, and Identity attempts. Drives the subscription /
+   * usage view.
    */
   async getSubscription(): Promise<SparkVaultSubscription> {
-    const response = await this.http.get<SparkVaultSubscription>('/billing/subscription');
-    return response.data;
-  }
-
-  /**
-   * Open the Stripe Customer Portal to manage the subscription on web (seat /
-   * block changes that fixed native SKUs cannot carry route here). The caller
-   * loads the returned URL in the WebView.
-   */
-  async createPortalSession(): Promise<PortalSession> {
-    const response = await this.http.post<PortalSession>('/billing/portal');
+    const response = await this.http.get<SparkVaultSubscription>(apiPath`/billing/subscription`);
     return response.data;
   }
 
   /**
-   * Validate a native in-app purchase receipt server-side and apply the
-   * resulting entitlements. Returns the refreshed subscription so the client
-   * can update its plan / usage view immediately after purchase.
+   * Validate a native in-app purchase server-side and apply the entitlements
+   * it buys. `receipt` is the App Store signed transaction (JWS) or the Play
+   * purchase token. Answers whether Core provisioned the purchase; read the
+   * subscription again with getSubscription() to show the change.
    */
   async iapValidate(
     platform: IapPlatform,
     productId: string,
     receipt: string
-  ): Promise<SparkVaultSubscription> {
-    const response = await this.http.post<SparkVaultSubscription>('/billing/iap/validate', {
+  ): Promise<IapValidation> {
+    // Core reads an App Store purchase's signed transaction as `receipt` and a
+    // Play purchase's token as `purchase_token`.
+    const credential = platform === 'android' ? { purchase_token: receipt } : { receipt };
+    const response = await this.http.post<IapValidation>(apiPath`/billing/iap/validate`, {
       platform,
       product_id: productId,
-      receipt,
+      ...credential,
     });
     return response.data;
   }

package/src/config.ts

@@ -1,8 +1,6 @@
 import { SparkVaultValidationError } from './errors.js';
-import {
-  SPARKVAULT_PLATFORM_SV_HOSTS,
-  SPARKVAULT_ROOT_DOMAIN,
-} from './platform-domains.generated.js';
+import { isResourceIdOf } from './app-sdk/ids.js';
+import { SPARKVAULT_IDENTITY_HOST, SPARKVAULT_OWNED_HOST_PATTERNS } from './app-sdk/platform-domains.js';
 import type {
   FetchLike,
   MobileBackgroundTransfer,
@@ -12,22 +10,10 @@ import type {
   SparkVaultLogger,
   TokenStorageAdapter,
 } from './types.js';
+import { apiPath, type ApiPath } from './request-path.js';
 
 const DEFAULT_API_BASE_URL = 'https://api.sparkvault.com/v1';
-const DEFAULT_IDENTITY_BASE_URL = 'https://auth.sparkvault.com';
-
-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[] = [
-  new RegExp(`(^|\\.)${escapeRegExp(SPARKVAULT_ROOT_DOMAIN)}$`, 'i'),
-  new RegExp(`(^|\\.)(${SPARKVAULT_PLATFORM_SV_HOSTS.map(escapeRegExp).join('|')})$`, 'i'),
-  /\.amazonaws\.com$/i,
-  /\.cloudfront\.net$/i,
-];
+const DEFAULT_IDENTITY_BASE_URL = `https://${SPARKVAULT_IDENTITY_HOST}`;
 
 const noopLogger: SparkVaultLogger = {
   debug: () => undefined,
@@ -45,6 +31,11 @@ export interface SparkVaultMobileConfig {
   userAgent?: string;
   timeoutMs?: number;
   fileTransferTimeoutMs?: number;
+  /**
+   * Timeout of a tus create POST and DELETE. A HEAD and the receipt (the
+   * PATCH at the final offset) wait HEAD_AND_RECEIPT_TIMEOUT_MS instead:
+   * Forge answers either only after its own call to Core.
+   */
   tusPostTimeoutMs?: number;
   /** Stall watchdog per tus chunk PATCH: aborts after this long with NO upload progress (not an absolute deadline). */
   tusChunkTimeoutMs?: number;
@@ -67,10 +58,36 @@ export interface SparkVaultMobileConfig {
    * upload, and every upload when this is unset, streams over XHR.
    */
   backgroundUploader?: MobileBackgroundUploader;
+  /**
+   * Whether the device has a network path right now (an app wires it to its
+   * OS network signal). Read when an upload request got no answer: while it
+   * answers false the upload waits for `onOnline` instead of spending its
+   * retries, then asks Forge where the session stands. Only a definite
+   * "offline" should answer false; a path that may come up is online. Given
+   * together with `onOnline`, or not at all.
+   */
+  isOnline?: () => boolean;
+  /**
+   * Subscribe to the network coming back; returns the unsubscribe. The pair
+   * of `isOnline`. A wait it ends is otherwise ended only by the upload's
+   * `abortSignal`.
+   */
+  onOnline?: (listener: () => void) => () => void;
   logger?: Partial<SparkVaultLogger>;
+  /**
+   * Host allowlist for the backend-issued Forge transfer URLs the SDK sends an
+   * ingot's ISTK to (downloads and uploads alike). Defaults to the SparkVault
+   * platform's own hosts; override only when pointing at another deployment.
+   */
   allowedDownloadHostPatterns?: RegExp[];
 }
 
+/** The device's network signal, as the upload's offline wait reads it (`isOnline` with `onOnline`). */
+export interface MobileConnectivity {
+  isOnline(): boolean;
+  onOnline(listener: () => void): () => void;
+}
+
 export interface ResolvedMobileConfig {
   tokenStorage: TokenStorageAdapter;
   apiBaseUrl: string;
@@ -87,10 +104,23 @@ export interface ResolvedMobileConfig {
   fileDownloader?: MobileFileDownloader;
   backgroundTransfer?: MobileBackgroundTransfer;
   backgroundUploader?: MobileBackgroundUploader;
+  connectivity?: MobileConnectivity;
   logger: SparkVaultLogger;
   allowedDownloadHostPatterns: RegExp[];
 }
 
+/** The `isOnline` / `onOnline` pair as one signal, or none: one without the other cannot wait for the network. */
+function resolveConnectivity(config: SparkVaultMobileConfig): MobileConnectivity | undefined {
+  const { isOnline, onOnline } = config;
+  if (isOnline === undefined && onOnline === undefined) return undefined;
+  if (typeof isOnline !== 'function' || typeof onOnline !== 'function') {
+    throw new SparkVaultValidationError('isOnline and onOnline are given together, as functions', {
+      field: typeof isOnline === 'function' ? 'onOnline' : 'isOnline',
+    });
+  }
+  return { isOnline, onOnline };
+}
+
 function normalizeBaseUrl(url: string, field: string): string {
   if (!url || typeof url !== 'string') {
     throw new SparkVaultValidationError(`${field} must be a non-empty string`, { field });
@@ -141,8 +171,10 @@ export function resolveMobileConfig(config: SparkVaultMobileConfig): ResolvedMob
     });
   }
 
-  if (!identityAccountId.startsWith('acc_')) {
-    throw new SparkVaultValidationError('identityAccountId must start with "acc_"', {
+  // The account id names Identity request paths: the platform's one id
+  // grammar keeps it a single path segment.
+  if (!isResourceIdOf('account', identityAccountId)) {
+    throw new SparkVaultValidationError('identityAccountId must be a SparkVault account id (acc_...)', {
       field: 'identityAccountId',
       received: identityAccountId,
     });
@@ -164,11 +196,12 @@ export function resolveMobileConfig(config: SparkVaultMobileConfig): ResolvedMob
     fileDownloader: config.fileDownloader,
     backgroundTransfer: config.backgroundTransfer,
     backgroundUploader: config.backgroundUploader,
+    connectivity: resolveConnectivity(config),
     logger: { ...noopLogger, ...config.logger },
-    allowedDownloadHostPatterns: config.allowedDownloadHostPatterns ?? DEFAULT_ALLOWED_DOWNLOAD_HOST_PATTERNS,
+    allowedDownloadHostPatterns: config.allowedDownloadHostPatterns ?? [...SPARKVAULT_OWNED_HOST_PATTERNS],
   };
 }
 
-export function identityUrl(config: ResolvedMobileConfig, path: string): string {
-  return `${config.identityBaseUrl}/${config.identityAccountId}${path}`;
+export function identityUrl(config: ResolvedMobileConfig, path: ApiPath): string {
+  return `${config.identityBaseUrl}${apiPath`/${config.identityAccountId}`}${path}`;
 }

package/src/encoding.ts

@@ -1,7 +1,48 @@
-const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-const BASE64_LOOKUP = new Map<string, number>(
-  Array.from(BASE64_ALPHABET).map((char, index) => [char, index])
-);
+/**
+ * Base64 and UTF-8 for the mobile SDK.
+ *
+ * The base64 codec is the platform's one copy, mirrored from
+ * `@sparkvault/app-sdk/encoding` into `./app-sdk/encoding.js`; the decoders here
+ * raise this SDK's validation error where that codec refuses a text. UTF-8 is
+ * converted here rather than with TextEncoder/TextDecoder, which the JavaScript
+ * engines of the React Native versions this SDK supports need not provide.
+ * Decoding UTF-8 is fatal: bytes that are not UTF-8 are refused, never read as
+ * invented characters.
+ */
+
+import {
+  base64ToBytes as decodeBase64,
+  base64urlToBytes as decodeBase64url,
+  bytesToBase64,
+  bytesToBase64url,
+} from './app-sdk/encoding.js';
+import { SparkVaultValidationError } from './errors.js';
+
+export { bytesToBase64, bytesToBase64url };
+
+/**
+ * Decode standard base64.
+ * @throws SparkVaultValidationError when the text is not base64
+ */
+export function base64ToBytes(value: string): Uint8Array {
+  const bytes = decodeBase64(value);
+  if (bytes === null) {
+    throw new SparkVaultValidationError('Invalid base64 input');
+  }
+  return bytes;
+}
+
+/**
+ * Decode base64url.
+ * @throws SparkVaultValidationError when the text is not base64url
+ */
+export function base64UrlToBytes(value: string): Uint8Array {
+  const bytes = decodeBase64url(value);
+  if (bytes === null) {
+    throw new SparkVaultValidationError('Invalid base64url input');
+  }
+  return bytes;
+}
 
 export function utf8ToBytes(value: string): Uint8Array {
   const bytes: number[] = [];
@@ -40,121 +81,68 @@ export function utf8ToBytes(value: string): Uint8Array {
   return new Uint8Array(bytes);
 }
 
-export function base64EncodeUtf8(value: string): string {
-  return bytesToBase64(utf8ToBytes(value));
-}
-
+/**
+ * Decode UTF-8 by the WHATWG decoder's rules in fatal mode: a byte that cannot
+ * start a sequence, a sequence cut short, an overlong form, a surrogate or a
+ * code point past U+10FFFF refuses the whole input.
+ * @throws SparkVaultValidationError when the bytes are not UTF-8
+ */
 export function bytesToUtf8(bytes: Uint8Array): string {
   let output = '';
-  let i = 0;
+  let index = 0;
 
-  while (i < bytes.length) {
-    const byte1 = bytes[i++];
-    if (byte1 < 0x80) {
-      output += String.fromCharCode(byte1);
+  while (index < bytes.length) {
+    const lead = bytes[index++];
+    if (lead < 0x80) {
+      output += String.fromCharCode(lead);
       continue;
     }
 
-    if (byte1 >= 0xc0 && byte1 < 0xe0) {
-      const byte2 = bytes[i++];
-      output += String.fromCharCode(((byte1 & 0x1f) << 6) | (byte2 & 0x3f));
-      continue;
+    // The first continuation byte's range is what excludes overlong forms,
+    // surrogates and code points past U+10FFFF.
+    let continuations: number;
+    let codePoint: number;
+    let lower = 0x80;
+    let upper = 0xbf;
+    if (lead >= 0xc2 && lead <= 0xdf) {
+      continuations = 1;
+      codePoint = lead & 0x1f;
+    } else if (lead >= 0xe0 && lead <= 0xef) {
+      continuations = 2;
+      codePoint = lead & 0x0f;
+      if (lead === 0xe0) lower = 0xa0;
+      if (lead === 0xed) upper = 0x9f;
+    } else if (lead >= 0xf0 && lead <= 0xf4) {
+      continuations = 3;
+      codePoint = lead & 0x07;
+      if (lead === 0xf0) lower = 0x90;
+      if (lead === 0xf4) upper = 0x8f;
+    } else {
+      throw new SparkVaultValidationError('Invalid UTF-8 input');
     }
 
-    if (byte1 >= 0xe0 && byte1 < 0xf0) {
-      const byte2 = bytes[i++];
-      const byte3 = bytes[i++];
-      output += String.fromCharCode(
-        ((byte1 & 0x0f) << 12) |
-        ((byte2 & 0x3f) << 6) |
-        (byte3 & 0x3f)
-      );
-      continue;
+    for (let seen = 0; seen < continuations; seen++) {
+      if (index >= bytes.length) {
+        throw new SparkVaultValidationError('Invalid UTF-8 input');
+      }
+      const next = bytes[index++];
+      if (next < lower || next > upper) {
+        throw new SparkVaultValidationError('Invalid UTF-8 input');
+      }
+      lower = 0x80;
+      upper = 0xbf;
+      codePoint = (codePoint << 6) | (next & 0x3f);
     }
-
-    const byte2 = bytes[i++];
-    const byte3 = bytes[i++];
-    const byte4 = bytes[i++];
-    const codePoint = (
-      ((byte1 & 0x07) << 18) |
-      ((byte2 & 0x3f) << 12) |
-      ((byte3 & 0x3f) << 6) |
-      (byte4 & 0x3f)
-    ) - 0x10000;
-    output += String.fromCharCode(
-      0xd800 + (codePoint >> 10),
-      0xdc00 + (codePoint & 0x3ff)
-    );
+    output += String.fromCodePoint(codePoint);
   }
 
   return output;
 }
 
-export function base64UrlToBytes(value: string): Uint8Array {
-  return base64ToBytes(value);
+export function base64EncodeUtf8(value: string): string {
+  return bytesToBase64(utf8ToBytes(value));
 }
 
 export function base64UrlToUtf8(value: string): string {
   return bytesToUtf8(base64UrlToBytes(value));
 }
-
-export function bytesToBase64(bytes: Uint8Array): string {
-  let output = '';
-
-  for (let i = 0; i < bytes.length; i += 3) {
-    const byte1 = bytes[i];
-    const byte2 = bytes[i + 1] ?? 0;
-    const byte3 = bytes[i + 2] ?? 0;
-    const triplet = (byte1 << 16) | (byte2 << 8) | byte3;
-
-    output += BASE64_ALPHABET[(triplet >> 18) & 0x3f];
-    output += BASE64_ALPHABET[(triplet >> 12) & 0x3f];
-    output += i + 1 < bytes.length ? BASE64_ALPHABET[(triplet >> 6) & 0x3f] : '=';
-    output += i + 2 < bytes.length ? BASE64_ALPHABET[triplet & 0x3f] : '=';
-  }
-
-  return output;
-}
-
-export function base64ToBytes(value: string): Uint8Array {
-  const sanitized = value.replace(/\s/g, '').replace(/-/g, '+').replace(/_/g, '/');
-  if (sanitized.length % 4 === 1) {
-    throw new Error('Invalid base64 input');
-  }
-
-  const padded = sanitized.padEnd(Math.ceil(sanitized.length / 4) * 4, '=');
-
-  // 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];
-    const c2 = padded[i + 1];
-    const c3 = padded[i + 2];
-    const c4 = padded[i + 3];
-
-    const v1 = BASE64_LOOKUP.get(c1);
-    const v2 = BASE64_LOOKUP.get(c2);
-    const v3 = c3 === '=' ? 0 : BASE64_LOOKUP.get(c3);
-    const v4 = c4 === '=' ? 0 : BASE64_LOOKUP.get(c4);
-
-    if (v1 === undefined || v2 === undefined || v3 === undefined || v4 === undefined) {
-      throw new Error('Invalid base64 input');
-    }
-
-    const triplet = (v1 << 18) | (v2 << 12) | (v3 << 6) | v4;
-    bytes[outIndex++] = (triplet >> 16) & 0xff;
-    if (c3 !== '=') bytes[outIndex++] = (triplet >> 8) & 0xff;
-    if (c4 !== '=') bytes[outIndex++] = triplet & 0xff;
-  }
-
-  return bytes;
-}

package/src/entropy.test-d.ts

@@ -0,0 +1,47 @@
+/**
+ * Entropy wire-contract assertions — COMPILE-TIME ONLY (see notify.test-d.ts for
+ * why these live in `src` under a `.test-d.ts` name).
+ *
+ * The endpoint answers a `bytes` request with a number array and every other
+ * format with a string, so `generate` is typed per format, and a format known
+ * only as an EntropyFormat resolves to either shape. The format list
+ * itself is pinned to the platform contract at runtime by
+ * tests/app-sdk-mirrors.test.ts.
+ */
+
+import type { EntropyFormat, MobileEntropyClient } from './entropy.js';
+
+/** Fails to compile unless `T` resolves to exactly `true`. */
+type Assert<T extends true> = T;
+
+/** Invariant type equality: `A` and `B` must be the same type, not merely mutually assignable. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+
+/** What `generate` resolves to for a call with `Options`: its first overload that accepts them. */
+type Answer<Options> = MobileEntropyClient['generate'] extends {
+  (options: infer First): infer FirstResult;
+  (options: infer Second): infer SecondResult;
+  (options: infer Third): infer ThirdResult;
+}
+  ? Options extends First
+    ? Awaited<FirstResult>
+    : Options extends Second
+      ? Awaited<SecondResult>
+      : Options extends Third
+        ? Awaited<ThirdResult>
+        : never
+  : never;
+
+export type EntropyWireContract = [
+  Assert<Equals<
+    EntropyFormat,
+    'hex' | 'base64' | 'base64url' | 'alphanumeric' | 'alphanumeric-mixed' | 'password' | 'numeric' | 'uuid' | 'bytes'
+  >>,
+  Assert<Equals<Answer<{ bytes: number; format: 'bytes' }>['value'], number[]>>,
+  Assert<Equals<Answer<{ bytes: number; format: 'password' }>['value'], string>>,
+  Assert<Equals<Answer<{ bytes: number }>['value'], string>>,
+  // A format known only as an EntropyFormat still compiles, answering either shape.
+  Assert<Equals<Answer<{ bytes: number; format: EntropyFormat }>['value'], string | number[]>>,
+];