@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/walletOperations.d.ts

@@ -0,0 +1,209 @@
+import { type NextAction } from "./auth.ts";
+import { type DisplayCommon } from "./walletDisplayParts.ts";
+import { type LinkedRecoverCreate, type LinkedRecoverDisplay } from "./linkedRecovery.ts";
+import { type WalletCreateGrant, type WalletCreateGrantOutcome, type WalletCreateGrantWire } from "./walletCreateGrant.ts";
+import { type ConsentDebitOutcome, type DebitTerms } from "./consentDebit.ts";
+import { type LinkedSendDisplay, type LinkedWalletIdentity } from "./linkedSendDisplay.ts";
+import { type MediatedDisplay, type MediatedPurgedDisplay } from "./mediatedOperation.ts";
+export { LinkedSendAssets, MaxTransferCommentBytes, ReplaceActions, linkedSendAsset, replaceAction, transferComment } from "./linkedSendDisplay.ts";
+export type { LinkedSendAsset, LinkedSendDisplay, LinkedWalletIdentity, ReplaceAction } from "./linkedSendDisplay.ts";
+export type { LinkedRecoverCreate, LinkedRecoverDisplay } from "./linkedRecovery.ts";
+export type { MediatedDisplay, MediatedLinkedSendDisplay, MediatedPurgedDisplay, MediatedSendDisplay } from "./mediatedOperation.ts";
+export type UserWalletOperationKind = "wallet.create" | "wallet.sign" | "wallet.send" | "wallet.export" | "wallet.recover";
+export type WalletResultKind = "signature" | "transfer_receipt" | "wallet_created" | "device_share_recovered";
+export type UserWalletState = "awaiting_confirmation" | "authorized" | "dispatching" | "outcome_unknown" | "succeeded" | "failed" | "denied" | "canceled" | "expired";
+export type UserWalletEffectState = "no_effect" | "possible" | "known";
+/**
+ * session_authorized: the account's live session authorized the operation
+ * with no passkey. A send from a linked wallet, plain or a replacement, is
+ * authorized so (owner decision, 14 October 2026), as is the registration of
+ * a linked wallet for tracking; every other wallet operation is confirmed
+ * with a passkey (user_confirmed). user_request_signed: a service forwarded
+ * the send on the person's signed request (Mode C); its display is a
+ * MediatedDisplay, with no result recipient.
+ */
+export type UserWalletAuthorizationBasis = "" | "user_confirmed" | "session_authorized" | "user_request_signed";
+/**
+ * A wallet operation's result goes to its owner account only, so no create
+ * body names a result recipient: the device share of a created, exported or
+ * recovered wallet reaches this device alone, and the server refuses a
+ * service named as the recipient with INVALID_REQUEST.
+ */
+type UserWalletCommon = {
+    owner_type: "account";
+    owner_id: string;
+};
+/**
+ * UserWalletOperationCreate is the closed request body of source §2.2: the
+ * top-level wallet ID is required for every kind except wallet.create, and
+ * each payload carries exactly its kind's fields.
+ */
+export type UserWalletOperationCreate = (UserWalletCommon & {
+    kind: "wallet.create";
+    payload: {
+        network: string;
+        recipient_public_key: string;
+    };
+    grant?: WalletCreateGrantWire;
+}) | (UserWalletCommon & {
+    kind: "wallet.sign";
+    wallet_id: string;
+    payload: {
+        network: string;
+        message_base64url: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.send";
+    wallet_id: string;
+    payload: {
+        network: string;
+        asset: "native";
+        recipient: string;
+        amount_raw: string;
+        max_fee_raw: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.export";
+    wallet_id: string;
+    payload: {
+        recipient_public_key: string;
+    };
+}) | (UserWalletCommon & {
+    kind: "wallet.recover";
+    wallet_id: string;
+    payload: {
+        expected_generation: string;
+        recipient_public_key: string;
+    };
+}) | LinkedRecoverCreate;
+/** UserWalletPurgedDisplay is the safe identity left after material retention expires. */
+export type UserWalletPurgedDisplay = DisplayCommon & {
+    kind: UserWalletOperationKind;
+    materialPurged: true;
+};
+/**
+ * UserWalletDisplay is the safe display of the frozen material. A purged
+ * record keeps its identity and reports materialPurged instead of inventing
+ * material; it never carries signing output or custody material. Narrow with
+ * `walletMaterialPurged` before reading any per-kind material field.
+ */
+export type UserWalletDisplay = UserWalletPurgedDisplay | (DisplayCommon & {
+    kind: "wallet.create";
+    network: string;
+    recipientPublicKey: string;
+    preparedSummary?: string;
+    grant?: WalletCreateGrant;
+    debit?: DebitTerms;
+}) | (DisplayCommon & {
+    kind: "wallet.sign";
+    network: string;
+    messageBase64url: string;
+    preparedSummary?: string;
+}) | (DisplayCommon & {
+    kind: "wallet.send";
+    network: string;
+    asset: string;
+    recipient: string;
+    amountRaw: string;
+    maxFeeRaw: string;
+    preparedSummary?: string;
+}) | LinkedSendDisplay | (DisplayCommon & {
+    kind: "wallet.export";
+    recipientPublicKey: string;
+    preparedSummary?: string;
+}) | (DisplayCommon & {
+    kind: "wallet.recover";
+    recipientPublicKey: string;
+    expectedGeneration: string;
+    preparedSummary?: string;
+}) | LinkedRecoverDisplay | MediatedDisplay;
+/** walletMaterialPurged separates the purged display from every material display. */
+export declare function walletMaterialPurged(display: UserWalletDisplay): display is UserWalletPurgedDisplay | MediatedPurgedDisplay;
+export interface UserWalletOperation {
+    id: string;
+    version: string;
+    kind: UserWalletOperationKind;
+    state: UserWalletState;
+    effectState: UserWalletEffectState;
+    authorizationBasis: UserWalletAuthorizationBasis;
+    ownerType: "account";
+    ownerId: string;
+    requesterId: string;
+    walletId?: string;
+    /** Present exactly when the operation names a linked wallet instead of walletId. */
+    linkedWallet?: LinkedWalletIdentity;
+    requestFingerprint: string;
+    operationFingerprint: string;
+    display: UserWalletDisplay;
+    /** UTC RFC 3339 date-time string (source §2.2), not NumericDate seconds. */
+    createdAt: string;
+    /** UTC RFC 3339 date-time string (source §2.2), not NumericDate seconds. */
+    expiresAt: string;
+    confirmationLocation?: string;
+    resultKind?: WalletResultKind;
+    nextAction: NextAction;
+}
+/** CreatedWallet is the public identity of a wallet the own-wallet system created. */
+export interface CreatedWallet {
+    walletId: string;
+    keyId: string;
+    network: string;
+    address: string;
+    algorithm: string;
+    publicKey: string;
+}
+/**
+ * DeviceSharePackage is the device share exactly as the own-wallet system
+ * sealed it to the recipient key frozen in the operation. The provider never
+ * opens it; only the holder of the matching device private key can. Every
+ * binary member is lowercase hexadecimal.
+ */
+export interface DeviceSharePackage {
+    ciphertext: string;
+    nonce: string;
+    ephemeralPublicKey: string;
+    encryptionAlgorithm: string;
+    encryptionContext: string;
+}
+export interface WalletResult {
+    requestId: string;
+    result: {
+        operationId: string;
+        kind: WalletResultKind;
+        receiptId: string;
+        outputBase64url?: string;
+        /** Present exactly for a wallet_created result. */
+        wallet?: CreatedWallet;
+        /** Present exactly for a wallet_created and a device_share_recovered result. */
+        deviceShare?: DeviceSharePackage;
+        /** Present exactly for a device_share_recovered result: the linked wallet whose share was recovered. */
+        linkedWalletId?: string;
+        /** Present for a wallet_created result whose creation named a grant (walletCreateGrant.ts). */
+        grant?: WalletCreateGrantOutcome;
+        /** Present when the grant's service holds wallet:debit:user: the debit permission the creation's passkey also created (consentDebit.ts). */
+        debit?: ConsentDebitOutcome;
+    };
+}
+/** MaxWalletMessageBytes is the decoded wallet.sign payload bound of source §2.8. */
+export declare const MaxWalletMessageBytes = 4096;
+/**
+ * validateUserWalletCreate rejects every locally detectable fault before any
+ * request leaves the client: a foreign owner, a wallet ID present or absent
+ * against its kind, a non-compressed recipient key, a noncanonical or
+ * out-of-range quantity, a non-native asset, and a sign message outside
+ * 1..4096 decoded bytes. It returns the exact value it was given so the
+ * caller sends the same closed body it validated.
+ */
+export declare function validateUserWalletCreate(value: UserWalletOperationCreate, expectedOwnerId: string): UserWalletOperationCreate;
+export declare function parseUserWalletOperationEnvelope(payload: unknown): {
+    requestId: string;
+    operation: UserWalletOperation;
+};
+export declare function parseUserWalletOperation(payload: unknown): UserWalletOperation;
+/**
+ * parseWalletResult accepts the protected wallet output of source §2.2:
+ * output_base64url is present for a signature and forbidden for a transfer
+ * receipt. A wallet_created result is its own closed shape: the created
+ * wallet and its sealed device share, with no output member.
+ */
+export declare function parseWalletResult(payload: unknown, expectedOperationId: string): WalletResult;

package/dist/walletOperations.js

@@ -0,0 +1,317 @@
+// Mode B user wallet operations (AUTH-009-A03, source §1.3). Closed types,
+// client-side validation of the five wallet payloads, and strict parsers for
+// the safe status projection and the protected wallet result. These helpers
+// compose the same /v1 operation routes as the local operations; they add no
+// authority. Local faults raise ClientFlowError; server denials stay
+// AuthorizationError and are produced by the caller's transport.
+import { ClientFlowError, canonicalDecimal, deadlineAfter, isNextAction, opaqueId, record, rfc3339UTC, } from "./auth.js";
+import { bindingRevision, displayCommon, lowerHexBytes, lowerUUID, rawQuantity, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+import { parseLinkedRecoverDisplay, parseRecoveredShareResult, validLinkedRecoverCreate } from "./linkedRecovery.js";
+import { parseWalletCreateGrant, parseWalletCreateGrantOutcome, validWalletCreateGrant } from "./walletCreateGrant.js";
+import { parseConsentDebitOutcome, parseDebitTerms } from "./consentDebit.js";
+import { parseLinkedSendDisplay } from "./linkedSendDisplay.js";
+import { parseMediatedOperation } from "./mediatedOperation.js";
+export { LinkedSendAssets, MaxTransferCommentBytes, ReplaceActions, linkedSendAsset, replaceAction, transferComment } from "./linkedSendDisplay.js";
+/** walletMaterialPurged separates the purged display from every material display. */
+export function walletMaterialPurged(display) {
+    return "materialPurged" in display;
+}
+/** MaxWalletMessageBytes is the decoded wallet.sign payload bound of source §2.8. */
+export const MaxWalletMessageBytes = 4096;
+const maxWalletGeneration = (1n << 64n) - 1n;
+const compressedP256Key = /^(02|03)[0-9a-f]{64}$/;
+const walletNetwork = /^[A-Za-z0-9_.-]{1,64}$/;
+const base64urlValue = /^[A-Za-z0-9_-]+$/;
+/**
+ * validateUserWalletCreate rejects every locally detectable fault before any
+ * request leaves the client: a foreign owner, a wallet ID present or absent
+ * against its kind, a non-compressed recipient key, a noncanonical or
+ * out-of-range quantity, a non-native asset, and a sign message outside
+ * 1..4096 decoded bytes. It returns the exact value it was given so the
+ * caller sends the same closed body it validated.
+ */
+export function validateUserWalletCreate(value, expectedOwnerId) {
+    const common = record(value, ["kind", "owner_type", "owner_id", "payload"], ["wallet_id", "linked_wallet_id", "grant"]);
+    // A grant is named beside a creation alone.
+    if (common.owner_type !== "account" || !opaqueId(common.owner_id) || common.owner_id !== expectedOwnerId ||
+        (common.grant !== undefined && (common.kind !== "wallet.create" || !validWalletCreateGrant(common.grant)))) {
+        throw new ClientFlowError("invalid_operation_create");
+    }
+    // A linked wallet is named by a recovery of its device share alone (linkedRecovery.ts).
+    if (common.linked_wallet_id !== undefined) {
+        if (!validLinkedRecoverCreate(common))
+            throw new ClientFlowError("invalid_operation_create");
+        return value;
+    }
+    const walletRequired = common.kind !== "wallet.create";
+    if (walletRequired !== opaqueId(common.wallet_id))
+        throw new ClientFlowError("invalid_operation_create");
+    switch (common.kind) {
+        case "wallet.create": {
+            const payload = record(common.payload, ["network", "recipient_public_key"]);
+            if (!network(payload.network) || !recipientPublicKey(payload.recipient_public_key))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "wallet.sign": {
+            const payload = record(common.payload, ["network", "message_base64url"]);
+            if (!network(payload.network) || !boundedMessage(payload.message_base64url))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "wallet.send": {
+            const payload = record(common.payload, ["network", "asset", "recipient", "amount_raw", "max_fee_raw"]);
+            if (!network(payload.network) || payload.asset !== "native" || typeof payload.recipient !== "string" || !walletRecipient.test(payload.recipient) ||
+                !rawQuantity(payload.amount_raw, true) || !rawQuantity(payload.max_fee_raw, false)) {
+                throw new ClientFlowError("invalid_operation_create");
+            }
+            break;
+        }
+        case "wallet.export": {
+            const payload = record(common.payload, ["recipient_public_key"]);
+            if (!recipientPublicKey(payload.recipient_public_key))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        case "wallet.recover": {
+            const payload = record(common.payload, ["expected_generation", "recipient_public_key"]);
+            if (!recipientPublicKey(payload.recipient_public_key) || !walletGeneration(payload.expected_generation))
+                throw new ClientFlowError("invalid_operation_create");
+            break;
+        }
+        default:
+            throw new ClientFlowError("invalid_operation_create");
+    }
+    return value;
+}
+export function parseUserWalletOperationEnvelope(payload) {
+    const root = record(payload, ["request_id", "operation"]);
+    if (!opaqueId(root.request_id))
+        throw new ClientFlowError("invalid_server_response");
+    return { requestId: root.request_id, operation: parseUserWalletOperation(root.operation) };
+}
+export function parseUserWalletOperation(payload) {
+    // A Mode C send is read in the mediated projection the provider serves for it.
+    if (payload !== null && typeof payload === "object" && payload.authorization_basis === "user_request_signed")
+        return parseMediatedOperation(payload);
+    const root = record(payload, [
+        "id", "version", "kind", "state", "effect_state", "authorization_basis", "owner_type", "owner_id", "requester_id",
+        "request_fingerprint", "operation_fingerprint", "display", "created_at", "expires_at", "next_action",
+    ], ["wallet_id", "confirmation_location", "result_kind", "binding_source", "connection_id", "linked_wallet_id", "binding_revision"]);
+    if (!opaqueId(root.id) || !canonicalDecimal(root.version) || !userWalletKind(root.kind) || !userWalletState(root.state) ||
+        !userWalletEffectState(root.effect_state) || !userWalletBasis(root.authorization_basis) ||
+        root.owner_type !== "account" || !opaqueId(root.owner_id) || !opaqueId(root.requester_id) ||
+        (root.wallet_id !== undefined && !opaqueId(root.wallet_id)) || !lowerHexDigest(root.request_fingerprint) ||
+        !lowerHexDigest(root.operation_fingerprint) || !rfc3339UTC(root.created_at) || !rfc3339UTC(root.expires_at) ||
+        !deadlineAfter(root.created_at, root.expires_at) || (root.confirmation_location !== undefined && !httpsURL(root.confirmation_location)) ||
+        (root.result_kind !== undefined && !walletResultKind(root.result_kind)) || !isNextAction(root.next_action)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    // A linked wallet is named by all three of its members, only for a send or
+    // the recovery of its device share, never beside an own wallet; only a send
+    // is authorized by the session alone.
+    const linked = root.binding_source !== undefined;
+    if (linked && (root.binding_source !== "linked_wallet" || (root.kind !== "wallet.send" && root.kind !== "wallet.recover") || root.wallet_id !== undefined ||
+        !lowerUUID(root.connection_id) || !lowerUUID(root.linked_wallet_id) || !bindingRevision(root.binding_revision) ||
+        (root.kind === "wallet.recover" && root.authorization_basis === "session_authorized"))) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if (!linked && (root.connection_id !== undefined || root.linked_wallet_id !== undefined || root.binding_revision !== undefined || root.authorization_basis === "session_authorized")) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const display = linked && !purgedDisplay(root.display) ? (root.kind === "wallet.recover" ? parseLinkedRecoverDisplay(root.display) : parseLinkedSendDisplay(root.display)) : parseUserWalletDisplay(root.display, root.kind);
+    if (display.ownerId !== root.owner_id || display.requesterId !== root.requester_id || display.walletId !== root.wallet_id) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if ("linkedWalletId" in display && (display.linkedWalletId !== root.linked_wallet_id || display.connectionId !== root.connection_id || display.bindingRevision !== root.binding_revision)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const operation = {
+        id: root.id,
+        version: root.version,
+        kind: root.kind,
+        state: root.state,
+        effectState: root.effect_state,
+        authorizationBasis: root.authorization_basis,
+        ownerType: root.owner_type,
+        ownerId: root.owner_id,
+        requesterId: root.requester_id,
+        requestFingerprint: root.request_fingerprint,
+        operationFingerprint: root.operation_fingerprint,
+        display,
+        createdAt: root.created_at,
+        expiresAt: root.expires_at,
+        nextAction: root.next_action,
+    };
+    if (root.wallet_id !== undefined)
+        operation.walletId = root.wallet_id;
+    if (linked)
+        operation.linkedWallet = { connectionId: root.connection_id, linkedWalletId: root.linked_wallet_id, bindingRevision: root.binding_revision };
+    if (root.confirmation_location !== undefined)
+        operation.confirmationLocation = root.confirmation_location;
+    if (root.result_kind !== undefined)
+        operation.resultKind = root.result_kind;
+    return operation;
+}
+/**
+ * parseWalletResult accepts the protected wallet output of source §2.2:
+ * output_base64url is present for a signature and forbidden for a transfer
+ * receipt. A wallet_created result is its own closed shape: the created
+ * wallet and its sealed device share, with no output member.
+ */
+export function parseWalletResult(payload, expectedOperationId) {
+    const root = record(payload, ["request_id", "result"]);
+    const resultKind = root.result !== null && typeof root.result === "object" ? root.result.kind : undefined;
+    if (resultKind === "wallet_created")
+        return parseCreatedWalletResult(root.request_id, root.result, expectedOperationId);
+    if (resultKind === "device_share_recovered")
+        return parseRecoveredShareResult(root.request_id, root.result, expectedOperationId);
+    const result = record(root.result, ["operation_id", "kind", "receipt_id"], ["output_base64url"]);
+    if (!opaqueId(root.request_id) || !opaqueId(result.operation_id) || result.operation_id !== expectedOperationId ||
+        !walletResultKind(result.kind) || result.kind === "wallet_created" || result.kind === "device_share_recovered" || !opaqueId(result.receipt_id)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    if (result.kind === "signature") {
+        if (typeof result.output_base64url !== "string" || !base64urlValue.test(result.output_base64url))
+            throw new ClientFlowError("invalid_server_response");
+        return { requestId: root.request_id, result: { operationId: result.operation_id, kind: result.kind, receiptId: result.receipt_id, outputBase64url: result.output_base64url } };
+    }
+    if (result.output_base64url !== undefined)
+        throw new ClientFlowError("invalid_server_response");
+    return { requestId: root.request_id, result: { operationId: result.operation_id, kind: result.kind, receiptId: result.receipt_id } };
+}
+function parseCreatedWalletResult(requestId, value, expectedOperationId) {
+    const result = record(value, ["operation_id", "kind", "receipt_id", "wallet", "device_share"], ["grant", "debit"]);
+    const wallet = record(result.wallet, ["wallet_id", "key_id", "network", "address", "algorithm", "public_key"]);
+    const share = record(result.device_share, ["ciphertext", "nonce", "ephemeral_public_key", "encryption_algorithm", "encryption_context"]);
+    // The receipt of a creation is the created wallet ID; a result naming two
+    // different wallets is not one creation.
+    if (!opaqueId(requestId) || result.operation_id !== expectedOperationId || !lowerUUID(wallet.wallet_id) || result.receipt_id !== wallet.wallet_id ||
+        !lowerUUID(wallet.key_id) || typeof wallet.network !== "string" || !/^[a-z0-9_.-]{1,64}$/.test(wallet.network) ||
+        typeof wallet.address !== "string" || !walletRecipient.test(wallet.address) || !algorithmName(wallet.algorithm) || !lowerHexBytes(wallet.public_key) ||
+        !lowerHexBytes(share.ciphertext) || !lowerHexBytes(share.nonce) || !lowerHexBytes(share.ephemeral_public_key) ||
+        !algorithmName(share.encryption_algorithm) || !lowerHexBytes(share.encryption_context)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return {
+        requestId,
+        result: {
+            operationId: expectedOperationId, kind: "wallet_created", receiptId: wallet.wallet_id,
+            wallet: { walletId: wallet.wallet_id, keyId: wallet.key_id, network: wallet.network, address: wallet.address, algorithm: wallet.algorithm, publicKey: wallet.public_key },
+            deviceShare: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeralPublicKey: share.ephemeral_public_key, encryptionAlgorithm: share.encryption_algorithm, encryptionContext: share.encryption_context },
+            ...(result.grant === undefined ? {} : { grant: parseWalletCreateGrantOutcome(result.grant) }),
+            ...(result.debit === undefined ? {} : { debit: parseConsentDebitOutcome(result.debit) }),
+        },
+    };
+}
+function purgedDisplay(value) {
+    return value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "material_purged");
+}
+function parseUserWalletDisplay(value, kind) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new ClientFlowError("invalid_server_response");
+    if (Object.prototype.hasOwnProperty.call(value, "material_purged")) {
+        const purged = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "material_purged"], ["wallet_id"]);
+        if (purged.kind !== kind || purged.material_purged !== true)
+            throw new ClientFlowError("invalid_server_response");
+        return { ...displayCommon(purged), kind, materialPurged: true };
+    }
+    switch (kind) {
+        case "wallet.create": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "recipient_public_key"], ["wallet_id", "prepared_summary", "grant", "debit"]);
+            if (display.kind !== kind || !network(display.network) || !recipientPublicKey(display.recipient_public_key))
+                throw new ClientFlowError("invalid_server_response");
+            return { ...displayCommon(display), kind, network: display.network, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary),
+                ...(display.grant === undefined ? {} : { grant: parseWalletCreateGrant(display.grant) }), ...(display.debit === undefined ? {} : { debit: parseDebitTerms(display.debit) }) };
+        }
+        case "wallet.sign": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "message_base64url"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !network(display.network) || !boundedMessage(display.message_base64url))
+                throw new ClientFlowError("invalid_server_response");
+            return { ...displayCommon(display), kind, network: display.network, messageBase64url: display.message_base64url, ...summaryOf(display.prepared_summary) };
+        }
+        case "wallet.send": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "asset", "recipient", "amount_raw", "max_fee_raw"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !network(display.network) || display.asset !== "native" || typeof display.recipient !== "string" ||
+                !walletRecipient.test(display.recipient) || !rawQuantity(display.amount_raw, true) || !rawQuantity(display.max_fee_raw, false)) {
+                throw new ClientFlowError("invalid_server_response");
+            }
+            return {
+                ...displayCommon(display), kind, network: display.network, asset: display.asset, recipient: display.recipient,
+                amountRaw: display.amount_raw, maxFeeRaw: display.max_fee_raw, ...summaryOf(display.prepared_summary),
+            };
+        }
+        case "wallet.export": {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "recipient_public_key"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== kind || !recipientPublicKey(display.recipient_public_key))
+                throw new ClientFlowError("invalid_server_response");
+            return { ...displayCommon(display), kind, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary) };
+        }
+        default: {
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "recipient_public_key", "expected_generation"], ["wallet_id", "prepared_summary"]);
+            if (display.kind !== "wallet.recover" || !recipientPublicKey(display.recipient_public_key) || !walletGeneration(display.expected_generation)) {
+                throw new ClientFlowError("invalid_server_response");
+            }
+            return {
+                ...displayCommon(display), kind: "wallet.recover", recipientPublicKey: display.recipient_public_key,
+                expectedGeneration: display.expected_generation, ...summaryOf(display.prepared_summary),
+            };
+        }
+    }
+}
+function network(value) {
+    return typeof value === "string" && walletNetwork.test(value);
+}
+function recipientPublicKey(value) {
+    return typeof value === "string" && compressedP256Key.test(value);
+}
+/**
+ * boundedMessage accepts unpadded base64url whose decoded length is 1..4096
+ * bytes. A base64url group of exactly one residual character encodes no byte,
+ * so that length is rejected outright.
+ */
+function boundedMessage(value) {
+    if (typeof value !== "string" || !base64urlValue.test(value) || value.length % 4 === 1)
+        return false;
+    const decoded = Math.floor((value.length * 3) / 4);
+    return decoded >= 1 && decoded <= MaxWalletMessageBytes;
+}
+function walletGeneration(value) {
+    if (!canonicalDecimal(value))
+        return false;
+    const generation = BigInt(value);
+    return generation > 0n && generation <= maxWalletGeneration;
+}
+function userWalletKind(value) {
+    return value === "wallet.create" || value === "wallet.sign" || value === "wallet.send" || value === "wallet.export" || value === "wallet.recover";
+}
+function walletResultKind(value) {
+    return value === "signature" || value === "transfer_receipt" || value === "wallet_created" || value === "device_share_recovered";
+}
+function algorithmName(value) {
+    return typeof value === "string" && /^[a-z0-9_-]{1,128}$/.test(value);
+}
+function userWalletState(value) {
+    return value === "awaiting_confirmation" || value === "authorized" || value === "dispatching" || value === "outcome_unknown" ||
+        value === "succeeded" || value === "failed" || value === "denied" || value === "canceled" || value === "expired";
+}
+function userWalletEffectState(value) {
+    return value === "no_effect" || value === "possible" || value === "known";
+}
+function userWalletBasis(value) {
+    return value === "" || value === "user_confirmed" || value === "session_authorized";
+}
+function lowerHexDigest(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+function httpsURL(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/webRenewal.d.ts

@@ -0,0 +1,92 @@
+import type { FetchLike } from "./client.ts";
+/** The code of the typed error that asks the application to start the top-level restore. */
+export declare const webRenewalRequiresNavigation = "web_renewal_requires_navigation";
+interface WebSessionTarget {
+    authorizationOrigin: string;
+    clientId: string;
+    /** The name the tabs of one application take turns under. */
+    lockName: string;
+    signal?: AbortSignal;
+    /** Throws once the renewal or restore was superseded; asked under the lock right before each step that asks the provider. */
+    current?: () => void;
+}
+export interface WebRenewalRequest extends WebSessionTarget {
+    fetch: FetchLike;
+    /** The session's CSRF token, held in memory only; without one the renewal starts from the cookie. */
+    csrfToken: string | undefined;
+}
+export interface WebRestoreRequest extends WebSessionTarget {
+    redirectUri: string;
+    crypto: Crypto;
+    /** The host's top-level launcher; it answers the registered redirect the restore came back to. */
+    launch: (url: string, signal?: AbortSignal) => Promise<string | void>;
+    /** POST /v1/auth/restore with this body, answering the session payload. */
+    exchange: (body: string) => Promise<unknown>;
+}
+/**
+ * The tabs of one application share the cookie, and the provider ends a
+ * session whose refresh value it is shown twice. Every renewal and every
+ * restore therefore runs under one Web Lock per client: each sends the value
+ * the previous one left. A restore holds it until the host's launcher
+ * settles or the restore's signal aborts it; the host gets the same signal
+ * and closes its window, so no abandoned navigation rotates the value later.
+ * A sign-in's exchange, which sets the cookie too, goes out under the same
+ * lock (client.ts), so a renewal's late answer never follows a newer
+ * sign-in's.
+ */
+export declare function underRenewalLock<T>(target: WebSessionTarget & {
+    whenWaiting?: () => void;
+}, work: () => Promise<T>): Promise<T>;
+/**
+ * renewWebSession is the background call: POST /v1/auth/renew with the cookie
+ * (credentials: "include"). A page that holds the session's CSRF token sends
+ * it; a page that holds none (a reload, a new tab), or whose token a renewal
+ * or restore in another tab replaced, renews from the cookie alone with the
+ * fixed X-Authorization-Renew header and gets a new token. It answers the
+ * session payload.
+ */
+export declare function renewWebSession(request: WebRenewalRequest): Promise<unknown>;
+/**
+ * staleCsrfRefusal is the answer a web lifecycle call gets when a renewal or
+ * restore in another tab replaced the session's CSRF token since this page
+ * last renewed.
+ */
+export declare function staleCsrfRefusal(error: unknown): boolean;
+/**
+ * revokeWithCurrentCredentials is logout's way past a CSRF token another tab
+ * replaced. Under the tabs' lock, held until the revocation answers, it
+ * renews from the cookie alone and revokes with the tokens that answer, but
+ * only when they belong to the session the logout was asked for: a cookie
+ * another sign-in replaced is left alone and the revocation is not confirmed.
+ */
+export declare function revokeWithCurrentCredentials(request: Omit<WebRenewalRequest, "csrfToken"> & {
+    sessionId: string;
+    whenWaiting?: () => void;
+}, revoke: (accessToken: string, csrfToken: string) => Promise<unknown>): Promise<unknown>;
+/** revokedAnswer says a logout answer confirms the revocation. */
+export declare function revokedAnswer(payload: unknown): boolean;
+/**
+ * revokeUnclaimedSession ends the session of a sign-in answer this page does
+ * not install, because a logout or a newer sign-in overtook it while it was
+ * asked for. The answer set the cookie, so without it a reload would take up
+ * a session nobody holds, one the person may have logged out of. The
+ * provider clears the cookie only while it holds that session. A CSRF token
+ * another tab replaced meanwhile (it renewed that session from the cookie) is
+ * followed by the logout's recovery: one renewal from the cookie under the
+ * tabs' lock, checked against the answer's session, and the revocation with
+ * its tokens. It answers true only for a confirmed revocation of exactly that
+ * session; a cookie that holds another session is left alone and answers
+ * false, as does any refusal or failure. whenWaiting is told when the
+ * recovery has to wait for the lock (a restore may hold it while its window
+ * is open): the revocation goes on, but nobody needs to wait for its verdict.
+ */
+export declare function revokeUnclaimedSession(request: Omit<WebRenewalRequest, "csrfToken"> & {
+    whenWaiting?: () => void;
+}, payload: unknown, revoke: (accessToken: string, csrfToken: string) => Promise<unknown>): Promise<boolean>;
+/**
+ * restoreWebSession is the top-level restore: a fresh state and S256 verifier
+ * in memory, the provider restore URL through the host's launcher, and the
+ * one-use handoff of the redirect it returns exchanged for the session.
+ */
+export declare function restoreWebSession(request: WebRestoreRequest): Promise<unknown>;
+export {};