@sparkvault/sdk-mobile 6.0.2 → 7.0.0

package/src/app-sdk/transient.js

@@ -0,0 +1,30 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/transient.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * Whether sending the SAME request again can succeed, read from its HTTP
+ * status: the one retry rule every client and every provider adapter applies.
+ *
+ * A retry rule restated beside every client drifts, and the copy that drifted
+ * decides whether a deliverable message is retried or abandoned, or whether a
+ * download is tried again. Each caller keeps its provider's own extras on top of
+ * this rule (a success body, a dead-token reason, a vendor error name).
+ *
+ * Browser-safe and import-free: sdk-js bundles it and sdk-mobile mirrors it.
+ */
+
+/**
+ * Is this HTTP status one a retry of the same request can turn into a success?
+ *
+ * RFC 9110: 408 means the server never received the whole request, 429 that it
+ * throttled it, and a 5xx that it failed; every other status is the server's
+ * verdict on this exact request. A caller that got no response at all (a network
+ * error, a timeout) has no status to pass and decides that case itself.
+ *
+ * @param {number} status
+ * @returns {boolean}
+ */
+export function isTransientHttpStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}

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,
@@ -68,6 +54,11 @@ export interface SparkVaultMobileConfig {
    */
   backgroundUploader?: MobileBackgroundUploader;
   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[];
 }
 
@@ -141,8 +132,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,
     });
@@ -165,10 +158,10 @@ export function resolveMobileConfig(config: SparkVaultMobileConfig): ResolvedMob
     backgroundTransfer: config.backgroundTransfer,
     backgroundUploader: config.backgroundUploader,
     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[]>>,
+];

package/src/entropy.ts

@@ -1,18 +1,34 @@
-import { base64ToBytes } from './encoding.js';
+import { base64ToBytes } from './app-sdk/encoding.js';
+import { ENTROPY_FORMATS, MAX_DRAW_BYTES, isEntropyFormat, maxBytesFor } from './app-sdk/entropy-contract.js';
 import { SparkVaultMobileError, SparkVaultValidationError } from './errors.js';
 import type { MobileHttpClient } from './http.js';
+import { apiPath } from './request-path.js';
 
-export type EntropyFormat = 'hex' | 'base64' | 'bytes' | 'uuid';
+/** An output format the entropy endpoint serves (the platform's entropy contract). */
+export type EntropyFormat =
+  | 'hex'
+  | 'base64'
+  | 'base64url'
+  | 'alphanumeric'
+  | 'alphanumeric-mixed'
+  | 'password'
+  | 'numeric'
+  | 'uuid'
+  | 'bytes';
 
 export interface GenerateEntropyOptions {
+  /** Number of random bytes: 1–1024, or 1–512 for alphanumeric, alphanumeric-mixed and password. */
   bytes: number;
+  /** Output format. Defaults to base64. */
   format?: EntropyFormat;
 }
 
-export interface EntropyResponse {
-  value: string;
+/** The endpoint's answer: `value` is a number array for the `bytes` format and a string for every other. */
+export interface EntropyResponse<Value extends string | number[] = string | number[]> {
+  value: Value;
   num_bytes: number;
   format?: EntropyFormat;
+  reference_id?: string;
 }
 
 export class MobileEntropyClient {
@@ -22,35 +38,85 @@ export class MobileEntropyClient {
     this.http = http;
   }
 
+  generate(options: GenerateEntropyOptions & { format: 'bytes' }): Promise<EntropyResponse<number[]>>;
+  generate(options: GenerateEntropyOptions & { format?: Exclude<EntropyFormat, 'bytes'> }): Promise<EntropyResponse<string>>;
+  generate(options: GenerateEntropyOptions): Promise<EntropyResponse>;
   async generate(options: GenerateEntropyOptions): Promise<EntropyResponse> {
-    this.validateByteCount(options.bytes);
-    const response = await this.http.post<EntropyResponse>('/entropy/generate', {
+    const format = options.format ?? 'base64';
+    validateEntropyRequest(options.bytes, format);
+    const response = await this.http.post<EntropyResponse>(apiPath`/entropy/generate`, {
       num_bytes: options.bytes,
-      format: options.format ?? 'base64',
+      format,
     });
     return response.data;
   }
 
   async generateBytes(bytes: number): Promise<Uint8Array> {
     const response = await this.generate({ bytes, format: 'base64' });
-    if (typeof response.value !== 'string' || response.value.length === 0) {
-      throw new SparkVaultMobileError('Entropy endpoint returned no value');
-    }
-
-    const entropy = base64ToBytes(response.value);
-    if (entropy.length !== bytes) {
-      throw new SparkVaultMobileError(`Entropy length mismatch: expected ${bytes}, got ${entropy.length}`);
-    }
-
-    return entropy;
+    return drawnBytes(response.value, bytes);
   }
 
-  private validateByteCount(bytes: number): void {
-    if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024) {
-      throw new SparkVaultValidationError('Entropy byte count must be an integer from 1 to 1024', {
+  /**
+   * Random bytes for the signed-in client's own working values (a key's id, a
+   * secret's server share), from POST /v1/entropy/first-party: answered to an
+   * interactive SparkVault session only, never plan- or bandwidth-gated and
+   * never recorded as the account's usage. Values an integration asks for come
+   * from `generate` / `generateBytes`.
+   *
+   * @param bytes - 1 to the entropy contract's ceiling (MAX_DRAW_BYTES)
+   * @returns exactly `bytes` bytes
+   */
+  async drawFirstParty(bytes: number): Promise<Uint8Array> {
+    if (!Number.isInteger(bytes) || bytes < 1 || bytes > MAX_DRAW_BYTES) {
+      throw new SparkVaultValidationError(`Entropy byte count must be an integer from 1 to ${MAX_DRAW_BYTES}`, {
         field: 'bytes',
         received: bytes,
       });
     }
+    const response = await this.http.post<{ value: unknown; num_bytes: number }>(apiPath`/entropy/first-party`, {
+      num_bytes: bytes,
+    });
+    return drawnBytes(response.data.value, bytes);
+  }
+}
+
+/**
+ * The bytes a draw answered as base64, refused unless they are exactly the
+ * bytes asked for, so a malformed answer fails the operation that asked for it.
+ */
+function drawnBytes(value: unknown, bytes: number): Uint8Array {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new SparkVaultMobileError('Entropy endpoint returned no value');
+  }
+
+  const entropy = base64ToBytes(value);
+  if (entropy === null) {
+    throw new SparkVaultMobileError('Entropy endpoint returned a value that is not base64');
+  }
+  if (entropy.length !== bytes) {
+    throw new SparkVaultMobileError(`Entropy length mismatch: expected ${bytes}, got ${entropy.length}`);
+  }
+
+  return entropy;
+}
+
+/**
+ * Refuse a request the endpoint would refuse, before it is sent: the format must
+ * be one the endpoint serves, and the byte count an integer from 1 to that
+ * format's ceiling.
+ */
+function validateEntropyRequest(bytes: number, format: EntropyFormat): void {
+  if (!isEntropyFormat(format)) {
+    throw new SparkVaultValidationError(`Entropy format must be one of: ${ENTROPY_FORMATS.join(', ')}`, {
+      field: 'format',
+      received: format,
+    });
+  }
+  const max = maxBytesFor(format);
+  if (!Number.isInteger(bytes) || bytes < 1 || bytes > max) {
+    throw new SparkVaultValidationError(`Entropy byte count must be an integer from 1 to ${max} for the ${format} format`, {
+      field: 'bytes',
+      received: bytes,
+    });
   }
 }