@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/dist/encoding.js

@@ -1,5 +1,39 @@
-const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-const BASE64_LOOKUP = new Map(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) {
+    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) {
+    const bytes = decodeBase64url(value);
+    if (bytes === null) {
+        throw new SparkVaultValidationError('Invalid base64url input');
+    }
+    return bytes;
+}
 export function utf8ToBytes(value) {
     const bytes = [];
     for (let i = 0; i < value.length; i++) {
@@ -26,98 +60,70 @@ export function utf8ToBytes(value) {
     }
     return new Uint8Array(bytes);
 }
-export function base64EncodeUtf8(value) {
-    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) {
     let output = '';
-    let i = 0;
-    while (i < bytes.length) {
-        const byte1 = bytes[i++];
-        if (byte1 < 0x80) {
-            output += String.fromCharCode(byte1);
+    let index = 0;
+    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;
+        let codePoint;
+        let lower = 0x80;
+        let upper = 0xbf;
+        if (lead >= 0xc2 && lead <= 0xdf) {
+            continuations = 1;
+            codePoint = lead & 0x1f;
         }
-        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;
+        else if (lead >= 0xe0 && lead <= 0xef) {
+            continuations = 2;
+            codePoint = lead & 0x0f;
+            if (lead === 0xe0)
+                lower = 0xa0;
+            if (lead === 0xed)
+                upper = 0x9f;
         }
-        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));
+        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');
+        }
+        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);
+        }
+        output += String.fromCodePoint(codePoint);
     }
     return output;
 }
-export function base64UrlToBytes(value) {
-    return base64ToBytes(value);
+export function base64EncodeUtf8(value) {
+    return bytesToBase64(utf8ToBytes(value));
 }
 export function base64UrlToUtf8(value) {
     return bytesToUtf8(base64UrlToBytes(value));
 }
-export function bytesToBase64(bytes) {
-    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) {
-    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;
-}
 //# sourceMappingURL=encoding.js.map

package/dist/encoding.js.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"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"}

package/dist/entropy.d.ts

@@ -1,18 +1,39 @@
 import type { MobileHttpClient } from './http.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 declare class MobileEntropyClient {
     private readonly http;
     constructor(http: MobileHttpClient);
+    generate(options: GenerateEntropyOptions & {
+        format: 'bytes';
+    }): Promise<EntropyResponse<number[]>>;
+    generate(options: GenerateEntropyOptions & {
+        format?: Exclude<EntropyFormat, 'bytes'>;
+    }): Promise<EntropyResponse<string>>;
     generate(options: GenerateEntropyOptions): Promise<EntropyResponse>;
     generateBytes(bytes: number): Promise<Uint8Array>;
-    private validateByteCount;
+    /**
+     * 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
+     */
+    drawFirstParty(bytes: number): Promise<Uint8Array>;
 }

package/dist/entropy.js

@@ -1,35 +1,82 @@
-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 { apiPath } from './request-path.js';
 export class MobileEntropyClient {
     constructor(http) {
         this.http = http;
     }
     async generate(options) {
-        this.validateByteCount(options.bytes);
-        const response = await this.http.post('/entropy/generate', {
+        const format = options.format ?? 'base64';
+        validateEntropyRequest(options.bytes, format);
+        const response = await this.http.post(apiPath `/entropy/generate`, {
             num_bytes: options.bytes,
-            format: options.format ?? 'base64',
+            format,
         });
         return response.data;
     }
     async generateBytes(bytes) {
         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);
     }
-    validateByteCount(bytes) {
-        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) {
+        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(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, bytes) {
+    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, format) {
+    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,
+        });
     }
 }
 //# sourceMappingURL=entropy.js.map

package/dist/entropy.js.map

@@ -1 +1 @@
-{"version":3,"file":"entropy.js","sourceRoot":"","sources":["../src/entropy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAgB/E,MAAM,OAAO,mBAAmB;IAG9B,YAAY,IAAsB;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAA+B;QAC5C,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAkB,mBAAmB,EAAE;YAC1E,SAAS,EAAE,OAAO,CAAC,KAAK;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ;SACnC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,KAAa;QAC/B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClE,IAAI,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,KAAK,SAAS,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvG,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,iBAAiB,CAAC,KAAa;QACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI,EAAE,CAAC;YAC1D,MAAM,IAAI,yBAAyB,CAAC,sDAAsD,EAAE;gBAC1F,KAAK,EAAE,OAAO;gBACd,QAAQ,EAAE,KAAK;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"entropy.js","sourceRoot":"","sources":["../src/entropy.ts"],"names":[],"mappings":"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"}

package/dist/entropy.test-d.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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>>,
+    Assert<Equals<Answer<{
+        bytes: number;
+        format: EntropyFormat;
+    }>['value'], string | number[]>>
+];
+export {};

package/dist/entropy.test-d.js

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=entropy.test-d.js.map

package/dist/entropy.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entropy.test-d.js","sourceRoot":"","sources":["../src/entropy.test-d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/errors.d.ts

@@ -50,10 +50,10 @@ export declare class SparkVaultTimeoutError extends SparkVaultMobileError {
     constructor(message?: string);
 }
 /**
- * Thrown when a download is requested against an ingot that is still being
- * processed server-side (status `uploading`/`encrypting`). Transient by
- * nature, but retrying immediately will not help — callers should back off
- * until the ingot becomes active.
+ * Thrown when a download is requested against an ingot whose upload Forge has
+ * not activated yet (status `uploading`). Transient by nature, but retrying
+ * immediately will not help — callers should back off until the ingot becomes
+ * active.
  */
 export declare class IngotNotReadyError extends SparkVaultMobileError {
     /** Server-reported ingot status at the time of the request, when known. */
@@ -64,25 +64,87 @@ export declare class IngotNotReadyError extends SparkVaultMobileError {
         meta?: ApiMeta;
     });
 }
+/** The ingot a create was refused over, as the server read it. */
+export interface IngotNameHolder {
+    ingotId: string;
+    /**
+     * Lifecycle status of the holder: `active` when its upload finished,
+     * `uploading` when it has not (only a `refuse` create is refused over an
+     * unfinished holder; `complete_pending` completes one).
+     */
+    status: string;
+    sizeBytes: number;
+}
+/**
+ * Thrown when a create is refused because an ingot already holds the name in
+ * the target folder (409 `details.reason === 'NAME_HELD'`): with
+ * `onNameConflict: 'complete_pending'` a published holder, with `'refuse'` any
+ * holder. The server decided before writing anything, so the holder is
+ * untouched; `holder` is the row it read, which lets the caller act on it
+ * (send its bytes into its own row by id, adopt it, or try another name)
+ * without a second read.
+ */
+export declare class IngotNameHeldError extends SparkVaultMobileError {
+    readonly holder: IngotNameHolder;
+    constructor(message: string, options: {
+        holder: IngotNameHolder;
+        details?: Record<string, unknown>;
+        meta?: ApiMeta;
+    });
+}
 export declare class TusUploadError extends SparkVaultMobileError {
     readonly cause: Error | null;
     readonly filename: string | null;
     readonly fileSize: number | null;
-    readonly phase: 'create' | 'upload' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
+    /**
+     * Where the upload stopped: `finalize` is after the transfer, when every
+     * byte was on Forge but the ingot was not confirmed published.
+     */
+    readonly phase: 'create' | 'upload' | 'finalize' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
     /**
      * True when Forge no longer has the session (it answered a status
-     * `isSessionGone` recognises: expired or terminated), or the session
-     * cannot carry this file. The persisted session is worthless, so the
-     * caller starts a fresh upload instead of retrying it.
+     * `isSessionGone` recognises, or the expiry it named has passed), or the
+     * session cannot carry this file. The persisted session is worthless, so
+     * the caller starts a fresh upload instead of retrying it.
      */
     readonly sessionLost: boolean;
+    /**
+     * The `Retry-After` of the answer that ended the upload, in ms: the
+     * earliest a next attempt can expect another answer. Null when that answer
+     * named none, or no answer arrived.
+     */
+    readonly retryAfterMs: number | null;
+    /**
+     * True when every byte is on Forge and the session is intact but the ingot
+     * was not confirmed published: the vault did not read it `active` within
+     * the activation poll budget, or Forge was still saving the file at the
+     * upload's idle limit (code `upload_received_publishing`; it finishes
+     * without this device). The caller retries later by resuming the session
+     * it persisted, which asks Forge for the receipt again and sends no bytes.
+     */
+    readonly retryLater: boolean;
+    /**
+     * The code Core ended this upload with, as Forge named it. With code
+     * `upload_refused` a final refusal (`UPLOAD_POOL_FULL`: the account's
+     * storage pool cannot take it; `UPLOAD_SUPERSEDED`: a later upload replaced
+     * it), whose message is Core's own sentence and which no new upload of the
+     * same file remedies; with `sessionLost` any other code (`NOT_FOUND`: the
+     * file the upload was for is gone; `UPLOAD_PROTOCOL_RETIRED`; a 412's),
+     * which a fresh upload starts over from. Null when the answer named none.
+     */
+    readonly coreCode: string | null;
     constructor(message: string, options?: {
         cause?: Error | null;
         httpStatus?: number | null;
+        /** The error's code when it names an outcome of its own; otherwise the HTTP status, or `tus_upload_error`. */
+        code?: string;
         filename?: string | null;
         fileSize?: number | null;
         phase?: TusUploadError['phase'];
         sessionLost?: boolean;
+        retryAfterMs?: number | null;
+        retryLater?: boolean;
+        coreCode?: string | null;
     });
     /**
      * Wrap an error the SDK did not produce (a `fileReader` read, an
@@ -136,32 +198,54 @@ export declare function isNetworkError(err: unknown): boolean;
  * per-upload token minted with the ingot (expired, consumed, or bound to a
  * different session) — not the vault session. Re-unsealing the vault cannot
  * fix it; the caller creates a new upload session (`POST /ingots`) instead.
- * Use `isVatExpiredError` / `isReadOnlyVaultError` to tell the API's VAT
- * rejections apart.
+ * Use `vatRefusalReason` to tell the API's VAT refusals apart.
  */
 export declare function isAuthError(err: unknown): boolean;
 /**
- * True when the API rejected the vault access token because it has expired
- * (`details.reason === 'VAT_EXPIRED'` on a 401 or 403 — an expired VAT
- * answers 403 for its first hour, then 401). Re-unsealing the vault mints a
- * fresh VAT and the same request can be retried as-is.
+ * The reason the API refused the vault access token, or null when the error
+ * is not a VAT refusal:
+ *   - `VAT_INVALID` (401): no, a malformed, unknown or swept token, or one a
+ *     since-revoked DVAK minted — unseal again. Never the login.
+ *   - `VAT_EXPIRED` (403): the token outlived its TTL — unseal again and
+ *     retry the same request as-is.
+ *   - `VAT_READ_ONLY` (403): a View Only token on a write — no unseal fixes it.
+ * A 403 with no reason is a token for another vault or account; a 401 with no
+ * reason is the login itself.
+ */
+export declare function vatRefusalReason(err: unknown): string | null;
+/**
+ * True when the API refused the vault access token because it has expired
+ * (403 `VAT_EXPIRED`). Re-unsealing the vault mints a fresh VAT and the same
+ * request can be retried as-is.
  */
 export declare function isVatExpiredError(err: unknown): err is SparkVaultMobileError;
 /**
- * True when the vault access token is valid but read-only
- * (`details.reason === 'VAT_READ_ONLY'` on a 403): the session was unsealed
- * with a read-only access level, so a write cannot succeed by retrying or by
- * re-unsealing the same way — the caller needs write access to the vault.
+ * True when the vault access token is valid but read-only (403
+ * `VAT_READ_ONLY`): the session was unsealed with a read-only access level, so
+ * a write cannot succeed by retrying or by re-unsealing the same way — the
+ * caller needs write access to the vault.
  */
 export declare function isReadOnlyVaultError(err: unknown): err is SparkVaultMobileError;
+/**
+ * True for the API's 404 not-found answer: the resource it names does not
+ * exist (or is not this caller's to see). The only answer that says a vault,
+ * an ingot or a key's vault is missing; a rate limit, an outage or a refused
+ * session says nothing about it. Never true for a `TusUploadError`: Forge's
+ * 404 is an upload session that is gone, not a missing resource.
+ */
+export declare function isNotFoundError(err: unknown): err is SparkVaultMobileError;
 /** True for a 429 rate-limit response — retry after a cooldown, never immediately. */
 export declare function isRateLimitError(err: unknown): boolean;
 /** Type guard for the still-processing-ingot download failure. */
 export declare function isIngotNotReadyError(err: unknown): err is IngotNotReadyError;
+/** Type guard for a create refused over the same-name ingot holding its name. */
+export declare function isIngotNameHeldError(err: unknown): err is IngotNameHeldError;
 /**
- * True when retrying a failed download can succeed. Validation failures and
- * deterministic 4xx responses always fail the same way again; everything else
- * (connectivity, 5xx, 408, 429) is worth another attempt.
+ * True when retrying a failed download can succeed. A validation failure always
+ * fails the same way again, and an HTTP refusal is retried only when the
+ * platform's retry rule (`isTransientHttpStatus`, mirrored from
+ * `@sparkvault/app-sdk/transient`) calls it transient; every other failure
+ * (connectivity, an answer that could not be read) is worth another attempt.
  */
 export declare function isRetryableDownloadError(err: unknown): boolean;
 /**