@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/aesGcmSiv.d.ts

@@ -0,0 +1,14 @@
+/** Bytes WebCrypto accepts: a view over its own, unshared buffer. */
+export type Bytes = Uint8Array<ArrayBuffer>;
+/** polyval over whole 16-byte blocks. */
+export declare function polyval(key: Uint8Array, blocks: Uint8Array): Bytes;
+/**
+ * counterBlock is the GCM-SIV counter for one keystream block: the tag with
+ * its top bit set, counting in its first 32 bits, little-endian, wrapping
+ * inside those 32 bits.
+ */
+export declare function counterBlock(tag: Uint8Array, index: number): Bytes;
+/** seal returns ciphertext followed by the 16-byte tag. */
+export declare function aes256GcmSivSeal(subtle: SubtleCrypto, key: Bytes, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<Bytes>;
+/** open returns the plaintext, or throws when the tag does not match. */
+export declare function aes256GcmSivOpen(subtle: SubtleCrypto, key: Bytes, nonce: Uint8Array, sealed: Uint8Array, aad: Uint8Array): Promise<Bytes>;

package/dist/aesGcmSiv.js

@@ -0,0 +1,160 @@
+// AES-256-GCM-SIV (RFC 8452). The own-wallet system seals a device share with
+// it, and WebCrypto does not offer it, so the mode is built here from the one
+// primitive WebCrypto does offer: the AES block function, reached through
+// AES-CTR over a single zero block. Inputs are a few dozen bytes, so every
+// block is one WebCrypto call and POLYVAL runs on BigInt.
+import { ClientFlowError } from "./auth.js";
+const KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const BLOCK = 16;
+// x^128 + x^127 + x^126 + x^121 + 1, the POLYVAL field polynomial.
+const POLYNOMIAL = (1n << 128n) | (1n << 127n) | (1n << 126n) | (1n << 121n) | 1n;
+async function importBlockKey(subtle, raw) {
+    return subtle.importKey("raw", raw, { name: "AES-CTR" }, false, ["encrypt"]);
+}
+/** One AES block encryption: the first CTR keystream block for this counter. */
+async function encryptBlock(subtle, key, block) {
+    return new Uint8Array(await subtle.encrypt({ name: "AES-CTR", counter: block, length: 64 }, key, new Uint8Array(BLOCK)));
+}
+function fieldElement(bytes) {
+    let value = 0n;
+    for (let index = BLOCK - 1; index >= 0; index--)
+        value = (value << 8n) | BigInt(bytes[index]);
+    return value;
+}
+function fieldBytes(value) {
+    const out = new Uint8Array(BLOCK);
+    for (let index = 0; index < BLOCK; index++)
+        out[index] = Number((value >> BigInt(8 * index)) & 0xffn);
+    return out;
+}
+/** dot(a, b) = a * b * x^-128 in the POLYVAL field. */
+function dot(a, b) {
+    let product = 0n;
+    for (let bit = 0n; bit < 128n; bit++)
+        if ((b >> bit) & 1n)
+            product ^= a << bit;
+    for (let bit = 0n; bit < 128n; bit++)
+        if ((product >> bit) & 1n)
+            product ^= POLYNOMIAL << bit;
+    return product >> 128n;
+}
+/** polyval over whole 16-byte blocks. */
+export function polyval(key, blocks) {
+    if (key.length !== BLOCK || blocks.length % BLOCK !== 0)
+        throw new ClientFlowError("device_share_unavailable");
+    const h = fieldElement(key);
+    let state = 0n;
+    for (let offset = 0; offset < blocks.length; offset += BLOCK)
+        state = dot(state ^ fieldElement(blocks.subarray(offset, offset + BLOCK)), h);
+    return fieldBytes(state);
+}
+async function deriveRecordKeys(subtle, key, nonce) {
+    const generating = await importBlockKey(subtle, key);
+    const part = async (counter) => {
+        const block = new Uint8Array(BLOCK);
+        block[0] = counter;
+        block.set(nonce, 4);
+        return (await encryptBlock(subtle, generating, block)).subarray(0, 8);
+    };
+    const authentication = new Uint8Array(16);
+    const encryption = new Uint8Array(KEY_BYTES);
+    try {
+        authentication.set(await part(0), 0);
+        authentication.set(await part(1), 8);
+        for (let index = 0; index < 4; index++)
+            encryption.set(await part(2 + index), 8 * index);
+        return { authentication, encryption: await importBlockKey(subtle, encryption) };
+    }
+    catch (error) {
+        authentication.fill(0);
+        throw error;
+    }
+    finally {
+        encryption.fill(0);
+    }
+}
+function padded(length) { return Math.ceil(length / BLOCK) * BLOCK; }
+async function computeTag(subtle, keys, nonce, plaintext, aad) {
+    const input = new Uint8Array(padded(aad.length) + padded(plaintext.length) + BLOCK);
+    input.set(aad, 0);
+    input.set(plaintext, padded(aad.length));
+    const lengths = new DataView(input.buffer, input.length - BLOCK, BLOCK);
+    lengths.setBigUint64(0, BigInt(aad.length) * 8n, true);
+    lengths.setBigUint64(8, BigInt(plaintext.length) * 8n, true);
+    const digest = polyval(keys.authentication, input);
+    input.fill(0);
+    for (let index = 0; index < NONCE_BYTES; index++)
+        digest[index] ^= nonce[index];
+    digest[15] &= 0x7f;
+    return encryptBlock(subtle, keys.encryption, digest);
+}
+/**
+ * counterBlock is the GCM-SIV counter for one keystream block: the tag with
+ * its top bit set, counting in its first 32 bits, little-endian, wrapping
+ * inside those 32 bits.
+ */
+export function counterBlock(tag, index) {
+    const counter = new Uint8Array(tag);
+    counter[15] |= 0x80;
+    const view = new DataView(counter.buffer);
+    view.setUint32(0, (view.getUint32(0, true) + index) >>> 0, true);
+    return counter;
+}
+async function applyKeystream(subtle, key, tag, data) {
+    const out = new Uint8Array(data.length);
+    for (let offset = 0, index = 0; offset < data.length; offset += BLOCK, index++) {
+        const stream = await encryptBlock(subtle, key, counterBlock(tag, index));
+        for (let byte = 0; byte < BLOCK && offset + byte < data.length; byte++)
+            out[offset + byte] = data[offset + byte] ^ stream[byte];
+        stream.fill(0);
+    }
+    return out;
+}
+function checked(key, nonce) {
+    if (key.length !== KEY_BYTES || nonce.length !== NONCE_BYTES)
+        throw new ClientFlowError("device_share_unavailable");
+}
+/** seal returns ciphertext followed by the 16-byte tag. */
+export async function aes256GcmSivSeal(subtle, key, nonce, plaintext, aad) {
+    checked(key, nonce);
+    const keys = await deriveRecordKeys(subtle, key, nonce);
+    try {
+        const tag = await computeTag(subtle, keys, nonce, plaintext, aad);
+        const out = new Uint8Array(plaintext.length + TAG_BYTES);
+        out.set(await applyKeystream(subtle, keys.encryption, tag, plaintext), 0);
+        out.set(tag, plaintext.length);
+        return out;
+    }
+    finally {
+        keys.authentication.fill(0);
+    }
+}
+/** open returns the plaintext, or throws when the tag does not match. */
+export async function aes256GcmSivOpen(subtle, key, nonce, sealed, aad) {
+    checked(key, nonce);
+    if (sealed.length < TAG_BYTES)
+        throw new ClientFlowError("device_share_unavailable");
+    const keys = await deriveRecordKeys(subtle, key, nonce);
+    const tag = sealed.subarray(sealed.length - TAG_BYTES);
+    let plaintext;
+    let opened = false;
+    try {
+        plaintext = await applyKeystream(subtle, keys.encryption, tag, sealed.subarray(0, sealed.length - TAG_BYTES));
+        const expected = await computeTag(subtle, keys, nonce, plaintext, aad);
+        let difference = 0;
+        for (let index = 0; index < TAG_BYTES; index++)
+            difference |= expected[index] ^ tag[index];
+        if (difference !== 0)
+            throw new ClientFlowError("device_share_unavailable");
+        opened = true;
+        return plaintext;
+    }
+    finally {
+        // The plaintext leaves this function only when its tag was verified.
+        if (!opened)
+            plaintext?.fill(0);
+        keys.authentication.fill(0);
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,68 @@
+export declare const identityMethods: readonly ["google", "apple", "telegram", "passkey"];
+export type IdentityMethod = (typeof identityMethods)[number];
+export type AuthIntent = "signup" | "login";
+export type ClientChannel = "web" | "mobile";
+export type NextAction = "none" | "reauthenticate" | "start_signup" | "start_login" | "use_passkey" | "sign_user_request" | "refresh_resource" | "retry_same_request" | "wait_for_result" | "lookup_operation" | "resync_streams";
+export declare class ClientFlowError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare class AuthorizationError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly nextAction: NextAction;
+    readonly requestId: string;
+    readonly operationId?: string;
+    readonly window?: {
+        earliestCursor: string;
+        latestCursor: string;
+    };
+    readonly status: number;
+    constructor(input: {
+        code: string;
+        retryable: boolean;
+        nextAction: NextAction;
+        requestId: string;
+        operationId?: string;
+        window?: {
+            earliestCursor: string;
+            latestCursor: string;
+        };
+        status: number;
+    });
+}
+export declare function parseAuthorizationError(payload: unknown, status: number): AuthorizationError;
+type ErrorExpectation = {
+    status: number;
+    retryable: boolean;
+    nextAction: NextAction;
+};
+declare const errorCatalog: Readonly<Record<string, ErrorExpectation>>;
+export type AuthorizationErrorCode = keyof typeof errorCatalog;
+export declare function isAuthorizationErrorCode(value: unknown): value is AuthorizationErrorCode;
+export declare function newHandoffBinding(crypto: Crypto): Promise<{
+    state: string;
+    verifier: string;
+    challenge: string;
+}>;
+export declare function base64url(bytes: Uint8Array): string;
+export declare function opaqueId(value: unknown): value is string;
+export declare function canonicalDecimal(value: unknown): value is string;
+export declare function integer(value: unknown): value is number;
+/**
+ * rfc3339Millis accepts only a UTC RFC 3339 date-time string as source §2.2
+ * requires for resource timestamps: four-digit year, two-digit components, the
+ * literal T and Z, an optional 1-9 digit fraction and no other offset form. It
+ * returns epoch milliseconds, or undefined for anything else. Integer
+ * NumericDate seconds (JWT claims, the Mode C request-grant result and
+ * /v1/me server_time) are validated with `integer`, never here.
+ */
+export declare function rfc3339Millis(value: unknown): number | undefined;
+export declare function rfc3339UTC(value: unknown): value is string;
+/** deadlineAfter requires an accepted resource deadline strictly after `created`. */
+export declare function deadlineAfter(created: string, expires: string): boolean;
+/** unexpiredRFC3339 requires a resource deadline strictly after `nowMs`. */
+export declare function unexpiredRFC3339(value: unknown, nowMs: number): value is string;
+export declare function record(value: unknown, required: readonly string[], optional?: readonly string[]): Record<string, unknown>;
+export declare function isNextAction(value: unknown): value is NextAction;
+export {};

package/dist/auth.js

@@ -0,0 +1,215 @@
+export const identityMethods = ["google", "apple", "telegram", "passkey"];
+export class ClientFlowError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "ClientFlowError";
+        this.code = code;
+    }
+}
+export class AuthorizationError extends Error {
+    code;
+    retryable;
+    nextAction;
+    requestId;
+    operationId;
+    window;
+    status;
+    constructor(input) {
+        super(input.code);
+        this.name = "AuthorizationError";
+        this.code = input.code;
+        this.retryable = input.retryable;
+        this.nextAction = input.nextAction;
+        this.requestId = input.requestId;
+        this.operationId = input.operationId;
+        this.window = input.window;
+        this.status = input.status;
+    }
+}
+export function parseAuthorizationError(payload, status) {
+    const outer = record(payload, ["error"]);
+    const error = record(outer.error, ["code", "retryable", "next_action", "request_id"], ["operation_id", "window"]);
+    if (typeof error.code !== "string" || typeof error.retryable !== "boolean" || !isNextAction(error.next_action) || !opaqueId(error.request_id)) {
+        throw new ClientFlowError("invalid_error_response");
+    }
+    if (error.operation_id !== undefined && !opaqueId(error.operation_id)) {
+        throw new ClientFlowError("invalid_error_response");
+    }
+    const expected = errorCatalog[error.code];
+    const possibleCommit = possibleCommitCodes.has(error.code) && error.operation_id !== undefined && error.retryable === false && error.next_action === "lookup_operation";
+    if (!expected || expected.status !== status || (!possibleCommit && (error.retryable !== expected.retryable || error.next_action !== expected.nextAction))) {
+        throw new ClientFlowError("invalid_error_response");
+    }
+    if (error.operation_id !== undefined && !possibleCommit && !operationIdCodes.has(error.code)) {
+        throw new ClientFlowError("invalid_error_response");
+    }
+    if (error.code === "RESULT_NOT_READY" && error.operation_id === undefined)
+        throw new ClientFlowError("invalid_error_response");
+    let window;
+    if (error.code === "RESYNC_REQUIRED") {
+        if (error.window === undefined)
+            throw new ClientFlowError("invalid_error_response");
+        let raw;
+        try {
+            raw = record(error.window, ["earliest_cursor", "latest_cursor"]);
+        }
+        catch {
+            throw new ClientFlowError("invalid_error_response");
+        }
+        if (!opaqueCursor(raw.earliest_cursor) || !opaqueCursor(raw.latest_cursor))
+            throw new ClientFlowError("invalid_error_response");
+        window = { earliestCursor: raw.earliest_cursor, latestCursor: raw.latest_cursor };
+    }
+    else if (error.window !== undefined) {
+        throw new ClientFlowError("invalid_error_response");
+    }
+    return new AuthorizationError({
+        code: error.code,
+        retryable: error.retryable,
+        nextAction: error.next_action,
+        requestId: error.request_id,
+        operationId: error.operation_id,
+        window,
+        status,
+    });
+}
+const errorCatalog = Object.freeze({
+    INVALID_REQUEST: { status: 400, retryable: false, nextAction: "none" },
+    REGISTRATION_SCOPE_SELECTION_REQUIRED: { status: 409, retryable: false, nextAction: "none" },
+    CURSOR_INVALID: { status: 400, retryable: false, nextAction: "none" },
+    UNSUPPORTED_VERSION: { status: 400, retryable: false, nextAction: "none" },
+    UNAUTHORIZED: { status: 401, retryable: false, nextAction: "reauthenticate" },
+    SCOPE_DENIED: { status: 403, retryable: false, nextAction: "none" },
+    ORIGIN_NOT_ALLOWED: { status: 403, retryable: false, nextAction: "none" },
+    LIMIT_PER_TRANSFER_EXCEEDED: { status: 403, retryable: false, nextAction: "none" },
+    LIMIT_DAILY_EXCEEDED: { status: 403, retryable: false, nextAction: "none" },
+    RECIPIENT_NOT_ALLOWED: { status: 403, retryable: false, nextAction: "none" },
+    CONFIRMATION_METHOD_UNAVAILABLE: { status: 403, retryable: false, nextAction: "use_passkey" },
+    USER_PROOF_REQUIRED: { status: 403, retryable: false, nextAction: "sign_user_request" },
+    USER_PROOF_INVALID: { status: 403, retryable: false, nextAction: "sign_user_request" },
+    REQUEST_GRANT_INVALID: { status: 403, retryable: false, nextAction: "use_passkey" },
+    NOT_FOUND: { status: 404, retryable: false, nextAction: "none" },
+    IDENTITY_NOT_REGISTERED: { status: 409, retryable: false, nextAction: "start_signup" },
+    IDENTITY_ALREADY_REGISTERED: { status: 409, retryable: false, nextAction: "start_login" },
+    IDENTITY_ALREADY_LINKED: { status: 409, retryable: false, nextAction: "none" },
+    ACCOUNT_REFERENCE_UNBOUND: { status: 409, retryable: false, nextAction: "none" },
+    LAST_FACTOR: { status: 409, retryable: false, nextAction: "none" },
+    CONFIRMATION_REPLAYED: { status: 409, retryable: false, nextAction: "none" },
+    CANNOT_CANCEL: { status: 409, retryable: false, nextAction: "none" },
+    VERSION_CONFLICT: { status: 409, retryable: false, nextAction: "refresh_resource" },
+    AUTHORIZATION_STALE: { status: 409, retryable: false, nextAction: "refresh_resource" },
+    IDEMPOTENCY_CONFLICT: { status: 409, retryable: false, nextAction: "lookup_operation" },
+    USER_PROOF_REPLAYED: { status: 409, retryable: false, nextAction: "lookup_operation" },
+    OPERATION_NOT_AUTHORIZED: { status: 409, retryable: false, nextAction: "use_passkey" },
+    RESULT_NOT_READY: { status: 409, retryable: true, nextAction: "wait_for_result" },
+    TRANSFER_IN_FLIGHT: { status: 409, retryable: true, nextAction: "retry_same_request" },
+    ATTEMPT_EXPIRED: { status: 410, retryable: false, nextAction: "reauthenticate" },
+    OPERATION_EXPIRED: { status: 410, retryable: false, nextAction: "none" },
+    RESULT_EXPIRED: { status: 410, retryable: false, nextAction: "none" },
+    RESYNC_REQUIRED: { status: 410, retryable: false, nextAction: "resync_streams" },
+    USER_PROOF_EXPIRED: { status: 410, retryable: false, nextAction: "sign_user_request" },
+    CAPABILITY_UNAVAILABLE: { status: 422, retryable: false, nextAction: "none" },
+    RECOVERY_UNAVAILABLE: { status: 422, retryable: false, nextAction: "none" },
+    PAYLOAD_NOT_SUPPORTED: { status: 422, retryable: false, nextAction: "none" },
+    RATE_LIMITED: { status: 429, retryable: true, nextAction: "retry_same_request" },
+    DEPENDENCY_UNAVAILABLE: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    NETWORK_FEE_TOO_HIGH: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    TENANT_AUTH_UNAVAILABLE: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    AUDIT_UNAVAILABLE: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    ADAPTER_INTEGRITY_CONFLICT: { status: 503, retryable: false, nextAction: "none" },
+    INTERNAL_ERROR: { status: 500, retryable: true, nextAction: "retry_same_request" },
+});
+export function isAuthorizationErrorCode(value) {
+    return typeof value === "string" && Object.prototype.hasOwnProperty.call(errorCatalog, value);
+}
+const possibleCommitCodes = new Set(["DEPENDENCY_UNAVAILABLE", "TENANT_AUTH_UNAVAILABLE", "AUDIT_UNAVAILABLE", "INTERNAL_ERROR"]);
+const operationIdCodes = new Set(["IDEMPOTENCY_CONFLICT", "USER_PROOF_REPLAYED", "RESULT_NOT_READY", "OPERATION_EXPIRED", "RESULT_EXPIRED", "OPERATION_NOT_AUTHORIZED", "ADAPTER_INTEGRITY_CONFLICT"]);
+function opaqueCursor(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export async function newHandoffBinding(crypto) {
+    const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
+    const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+    const challenge = base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+    return { state, verifier, challenge };
+}
+export function base64url(bytes) {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    let result = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const value = (bytes[index] << 16) | ((bytes[index + 1] ?? 0) << 8) | (bytes[index + 2] ?? 0);
+        result += alphabet[(value >>> 18) & 63] + alphabet[(value >>> 12) & 63];
+        if (index + 1 < bytes.length)
+            result += alphabet[(value >>> 6) & 63];
+        if (index + 2 < bytes.length)
+            result += alphabet[value & 63];
+    }
+    return result;
+}
+export function opaqueId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+export function canonicalDecimal(value) {
+    return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
+}
+export function integer(value) {
+    return typeof value === "number" && Number.isSafeInteger(value);
+}
+const utcDateTime = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,9})?Z$/;
+/**
+ * rfc3339Millis accepts only a UTC RFC 3339 date-time string as source §2.2
+ * requires for resource timestamps: four-digit year, two-digit components, the
+ * literal T and Z, an optional 1-9 digit fraction and no other offset form. It
+ * returns epoch milliseconds, or undefined for anything else. Integer
+ * NumericDate seconds (JWT claims, the Mode C request-grant result and
+ * /v1/me server_time) are validated with `integer`, never here.
+ */
+export function rfc3339Millis(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const parts = utcDateTime.exec(value);
+    if (!parts)
+        return undefined;
+    const [year, month, day, hour, minute, second] = parts.slice(1, 7).map(Number);
+    const seconds = Date.UTC(year, month - 1, day, hour, minute, second);
+    if (!Number.isSafeInteger(seconds))
+        return undefined;
+    const calendar = new Date(seconds);
+    if (calendar.getUTCFullYear() !== year || calendar.getUTCMonth() + 1 !== month || calendar.getUTCDate() !== day ||
+        calendar.getUTCHours() !== hour || calendar.getUTCMinutes() !== minute || calendar.getUTCSeconds() !== second) {
+        return undefined;
+    }
+    const fraction = parts[7];
+    return fraction === undefined ? seconds : seconds + Number(fraction.slice(1, 4).padEnd(3, "0"));
+}
+export function rfc3339UTC(value) {
+    return rfc3339Millis(value) !== undefined;
+}
+/** deadlineAfter requires an accepted resource deadline strictly after `created`. */
+export function deadlineAfter(created, expires) {
+    const from = rfc3339Millis(created);
+    const until = rfc3339Millis(expires);
+    return from !== undefined && until !== undefined && until > from;
+}
+/** unexpiredRFC3339 requires a resource deadline strictly after `nowMs`. */
+export function unexpiredRFC3339(value, nowMs) {
+    const until = rfc3339Millis(value);
+    return until !== undefined && until > nowMs;
+}
+export function record(value, required, optional = []) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new ClientFlowError("invalid_server_response");
+    const result = value;
+    const allowed = new Set([...required, ...optional]);
+    if (required.some((key) => !(key in result)) || Object.keys(result).some((key) => !allowed.has(key))) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return result;
+}
+export function isNextAction(value) {
+    return typeof value === "string" && [
+        "none", "reauthenticate", "start_signup", "start_login", "use_passkey", "sign_user_request",
+        "refresh_resource", "retry_same_request", "wait_for_result", "lookup_operation", "resync_streams",
+    ].includes(value);
+}

package/dist/balances.d.ts

@@ -0,0 +1,31 @@
+/** ok: the node gave every amount. partial: some. unavailable: none. */
+export type NetworkBalanceStatus = 'ok' | 'partial' | 'unavailable';
+/**
+ * One asset of a network. amountRaw is in the asset's minimal units and is
+ * absent when the node did not give it: an unread amount is never zero.
+ * contract is the token's contract on the network, its mint on Solana and its
+ * master on TON; the network's own coin has none.
+ */
+export interface AssetBalance {
+    readonly asset: 'native' | 'usdt' | 'usdc';
+    readonly decimals: number;
+    readonly contract?: string;
+    readonly amountRaw?: string;
+}
+/** One network of the wallet: its own coin first, then its tokens. The assets are named even when no amount could be read. */
+export interface NetworkBalances {
+    readonly network: string;
+    readonly status: NetworkBalanceStatus;
+    readonly balances: readonly AssetBalance[];
+}
+/** An EVM wallet has one network entry for each EVM network of the stand; any other wallet one, or none where the stand has no node for its network. */
+export interface LinkedWalletBalances {
+    readonly requestId: string;
+    readonly linkedWalletId: string;
+    readonly address: string;
+    /** When the provider finished reading the nodes. */
+    readonly observedAt: string;
+    readonly networks: readonly NetworkBalances[];
+}
+/** Parses the closed balances answer of the wallet that was asked about. */
+export declare function parseLinkedWalletBalances(payload: unknown, expectedLinkedWalletId: string): LinkedWalletBalances;

package/dist/balances.js

@@ -0,0 +1,44 @@
+// What a linked wallet holds: on each network its key has an address on, the
+// network's own coin and the tokens the stand names there. The provider reads
+// the amounts from the stand's own nodes, so the application hands a wallet's
+// address to no node operator.
+import { ClientFlowError, canonicalDecimal, integer, opaqueId, record, rfc3339UTC } from './auth.js';
+const statuses = ['ok', 'partial', 'unavailable'];
+const assets = ['native', 'usdt', 'usdc'];
+/** Parses the closed balances answer of the wallet that was asked about. */
+export function parseLinkedWalletBalances(payload, expectedLinkedWalletId) {
+    const root = record(payload, ['request_id', 'linked_wallet_id', 'address', 'observed_at', 'networks']);
+    if (!opaqueId(root.request_id) || root.linked_wallet_id !== expectedLinkedWalletId || typeof root.address !== 'string' || !/^[\x21-\x7e]{1,256}$/.test(root.address) ||
+        !rfc3339UTC(root.observed_at) || !Array.isArray(root.networks))
+        fault();
+    const networks = root.networks.map(parseNetwork);
+    if (new Set(networks.map((network) => network.network)).size !== networks.length)
+        fault();
+    return Object.freeze({ requestId: root.request_id, linkedWalletId: expectedLinkedWalletId, address: root.address, observedAt: root.observed_at, networks: Object.freeze(networks) });
+}
+function parseNetwork(payload) {
+    const n = record(payload, ['network', 'status', 'balances']);
+    if (typeof n.network !== 'string' || !/^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/.test(n.network) || typeof n.status !== 'string' || !statuses.includes(n.status) || !Array.isArray(n.balances) || n.balances.length === 0)
+        fault();
+    const balances = n.balances.map(parseAsset);
+    const read = balances.filter((balance) => balance.amountRaw !== undefined).length;
+    // The coin comes first and once, no asset twice, and the status says what was read.
+    if (balances[0].asset !== 'native' || new Set(balances.map((balance) => balance.asset)).size !== balances.length ||
+        n.status !== (read === balances.length ? 'ok' : read === 0 ? 'unavailable' : 'partial'))
+        fault();
+    return Object.freeze({ network: n.network, status: n.status, balances: Object.freeze(balances) });
+}
+function parseAsset(payload) {
+    const a = record(payload, ['asset', 'decimals'], ['contract', 'amount_raw']);
+    if (typeof a.asset !== 'string' || !assets.includes(a.asset) || !integer(a.decimals) || a.decimals < 0 || a.decimals > 30 ||
+        (a.asset === 'native') !== (a.contract === undefined) || (a.contract !== undefined && (typeof a.contract !== 'string' || !/^[\x21-\x7e]{1,128}$/.test(a.contract))) ||
+        (a.amount_raw !== undefined && (!canonicalDecimal(a.amount_raw) || a.amount_raw.length > 78)))
+        fault();
+    const out = { asset: a.asset, decimals: a.decimals };
+    if (a.contract !== undefined)
+        out.contract = a.contract;
+    if (a.amount_raw !== undefined)
+        out.amountRaw = a.amount_raw;
+    return Object.freeze(out);
+}
+function fault() { throw new ClientFlowError('invalid_server_response'); }

package/dist/canonicalize.d.ts

@@ -0,0 +1,19 @@
+export type CanonicalValue = string | number | boolean | null | readonly CanonicalValue[] | {
+    readonly [member: string]: CanonicalValue;
+};
+/**
+ * MaxCanonicalDepth bounds nesting. The Mode C request nests one object inside
+ * another and the proof payload is flat, so this bound is far above every
+ * accepted document and exists only to keep a hostile value from recursing.
+ */
+export declare const MaxCanonicalDepth = 8;
+/** canonicalJSON returns the RFC 8785 canonical serialization of value. */
+export declare function canonicalJSON(value: CanonicalValue): string;
+/** canonicalJSONBytes returns the UTF-8 bytes canonicalJSON produces. */
+export declare function canonicalJSONBytes(value: CanonicalValue): Uint8Array<ArrayBuffer>;
+/**
+ * sha256HexLower is the lowercase hexadecimal SHA-256 digest Mode C uses for
+ * `request_hash`. Uppercase hexadecimal is a different value and the server
+ * rejects it, so the alphabet is fixed here.
+ */
+export declare function sha256HexLower(crypto: Crypto, bytes: Uint8Array<ArrayBuffer>): Promise<string>;

package/dist/canonicalize.js

@@ -0,0 +1,107 @@
+// RFC 8785 JSON Canonicalization Scheme (source §2.5). Mode C hashes the
+// normalized OperationCreate and signs the closed proof payload over exactly
+// these bytes, so the client canonicalizes locally and never accepts a
+// server-, backend- or library-supplied serialization of either value.
+//
+// The implementation is deliberately closed rather than general: only the JSON
+// value forms the two Mode C documents contain are accepted, and every other
+// input is a local fault instead of a best-effort approximation. In particular
+// a JSON number is accepted only as a safe integer, because the closed payload
+// carries integer NumericDate seconds and nothing else; a fractional or
+// out-of-range number would otherwise be canonicalized through a rounding rule
+// this package has no requirement to own.
+import { ClientFlowError } from "./auth.js";
+/**
+ * MaxCanonicalDepth bounds nesting. The Mode C request nests one object inside
+ * another and the proof payload is flat, so this bound is far above every
+ * accepted document and exists only to keep a hostile value from recursing.
+ */
+export const MaxCanonicalDepth = 8;
+/** canonicalJSON returns the RFC 8785 canonical serialization of value. */
+export function canonicalJSON(value) {
+    return serialize(value, 0);
+}
+/** canonicalJSONBytes returns the UTF-8 bytes canonicalJSON produces. */
+export function canonicalJSONBytes(value) {
+    return new TextEncoder().encode(canonicalJSON(value));
+}
+/**
+ * sha256HexLower is the lowercase hexadecimal SHA-256 digest Mode C uses for
+ * `request_hash`. Uppercase hexadecimal is a different value and the server
+ * rejects it, so the alphabet is fixed here.
+ */
+export async function sha256HexLower(crypto, bytes) {
+    if (!crypto?.subtle || typeof crypto.subtle.digest !== "function")
+        throw new ClientFlowError("runtime_capability_unavailable");
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    let result = "";
+    for (const octet of digest)
+        result += lowerHex[octet >>> 4] + lowerHex[octet & 15];
+    return result;
+}
+const lowerHex = "0123456789abcdef";
+function serialize(value, depth) {
+    if (depth > MaxCanonicalDepth)
+        throw new ClientFlowError("noncanonical_value");
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            return serializeNumber(value);
+        case "string":
+            return serializeString(value);
+        case "object":
+            break;
+        default:
+            throw new ClientFlowError("noncanonical_value");
+    }
+    if (Array.isArray(value)) {
+        const items = value;
+        return "[" + items.map((item) => serialize(item, depth + 1)).join(",") + "]";
+    }
+    const object = value;
+    const members = Object.keys(object).sort(compareUTF16);
+    const encoded = members.map((member) => {
+        const child = object[member];
+        if (child === undefined)
+            throw new ClientFlowError("noncanonical_value");
+        return serializeString(member) + ":" + serialize(child, depth + 1);
+    });
+    return "{" + encoded.join(",") + "}";
+}
+/**
+ * serializeNumber accepts only a safe integer. RFC 8785 serializes numbers
+ * through the ECMAScript Number-to-String algorithm, which `String` performs
+ * exactly for this range, including -0 as "0".
+ */
+function serializeNumber(value) {
+    if (!Number.isSafeInteger(value))
+        throw new ClientFlowError("noncanonical_value");
+    return String(value);
+}
+/**
+ * serializeString uses the ECMAScript JSON string serialization RFC 8785
+ * §3.2.2.2 requires. A lone surrogate is not valid Unicode text, so it is
+ * refused here instead of being escaped into a document the server would then
+ * canonicalize differently.
+ */
+function serializeString(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit < 0xd800 || unit > 0xdfff)
+            continue;
+        const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+        if (unit >= 0xdc00 || next < 0xdc00 || next > 0xdfff)
+            throw new ClientFlowError("noncanonical_value");
+        index += 1;
+    }
+    return JSON.stringify(value);
+}
+/** compareUTF16 orders member names by UTF-16 code unit as RFC 8785 §3.2.3 requires. */
+function compareUTF16(left, right) {
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
+}