@shuttle.technology/authorization 0.1.0 → 0.2.0

package/dist/debitPermissions.js

@@ -0,0 +1,117 @@
+// Card-like debits on the person's side: the permissions an account lets a
+// service debit its linked wallets by, without the device. Reach it with
+// client.linkedWallets().debitPermissions(). A permission and its revocation
+// are local operations the person confirms with a passkey through the
+// client's own challengeOperation() and completeOperationConfirmation().
+// executeDebitPermission() then applies a new permission, handing the
+// wallet's device share to the platform share keeper sealed to the key the
+// keeper made for that operation: the share the SDK keeps (deviceShares.ts),
+// or the one an app that keeps its own passes; a revocation is applied with the client's
+// executeOperation(), without a body. The debits themselves are made by the
+// service's backend with its own key (POST /v1/service/operations).
+import { ClientFlowError, canonicalDecimal, record } from './auth.js';
+import { resealDeviceShare } from './deviceShare.js';
+import { debitPermissionCreate, debitPermissionRevocation, parseDebitPermissionList } from './debitPermissionWire.js';
+import { fault, hex, requestID } from './linkedChecks.js';
+import { parseOperationEnvelope } from './slice4.js';
+export { MaxDebitAssets, MaxDebitRecipients, debitPermissionCreate, debitPermissionRevocation, parseDebitPermissionDisplay, parseDebitPermissionList, parseDebitPermissionRevokeDisplay } from './debitPermissionWire.js';
+export class DebitPermissions {
+    #transport;
+    #kept;
+    constructor(transport, kept) { this.#transport = transport; this.#kept = kept; }
+    /**
+     * Asks to let one service debit one linked wallet within the bounds given. The operation comes back
+     * awaiting the person's passkey; its display says the bounds as the provider keeps them and, when the
+     * keeper does not hold the wallet's device share yet, the key the execute seals it to.
+     */
+    async createDebitPermission(input, idempotencyKey, signal) {
+        const create = debitPermissionCreate(this.#transport.accountId(), input);
+        requestID(idempotencyKey);
+        const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
+        const operation = parseOperationEnvelope(payload).operation;
+        if (operation.display.kind !== 'debit_permission.create' || operation.ownerId !== accountId || operation.display.linkedWalletId !== create.linked_wallet_id ||
+            operation.display.servicePrincipalId !== input.servicePrincipalId)
+            fault();
+        return operation;
+    }
+    /**
+     * Applies a confirmed permission. It reads the operation first: when it is confirmed (authorized, at the
+     * version given) and its display names the share keeper's key, the device share is resealed to that key and sent: without keys the
+     * share the SDK keeps for the wallet (recovered first with one passkey confirmation when this browser holds none), with keys the
+     * app's own (resealDeviceShare). The plaintext share exists only inside that call. Without that key the keeper holds the share already
+     * and nothing is sent. The person's own copy stays where it is, and their sends with it go on as before.
+     */
+    async executeDebitPermission(operationId, version, idempotencyKey, keys, signal) {
+        return this.#execute(operationId, version, idempotencyKey, keys, signal, true);
+    }
+    /**
+     * executeConsentDebitPermission is executeDebitPermission() with the share the SDK keeps, for the permission a
+     * grant's consent created (consentDebit.ts): it never recovers a share, so reading a result never asks for a
+     * passkey; without a current share kept here it refuses with device_share_unavailable and sends nothing.
+     */
+    async executeConsentDebitPermission(operationId, version, idempotencyKey, signal) {
+        return this.#execute(operationId, version, idempotencyKey, undefined, signal, false);
+    }
+    async #execute(operationId, version, idempotencyKey, keys, signal, recover) {
+        requestID(operationId);
+        requestID(idempotencyKey);
+        if (!canonicalDecimal(version))
+            throw new ClientFlowError('invalid_execute_request');
+        const read = parseOperationEnvelope(await this.#transport.get(`/v1/operations/${operationId}`, signal)).operation;
+        if (read.id !== operationId)
+            fault();
+        if (read.display.kind !== 'debit_permission.create')
+            throw new ClientFlowError('invalid_execute_request');
+        let body;
+        const keeperKey = read.display.shareKeeperPublicKey;
+        // The share leaves the device only for a permission the passkey confirmed and that still waits for this
+        // very execute. Any other state (unconfirmed, applied, ended) is executed without it, and the server answers.
+        if (keeperKey !== undefined && read.state === 'authorized') {
+            if (read.version !== version)
+                throw new ClientFlowError('invalid_execute_request');
+            const share = keys === undefined ? await this.#keptFor(read, keeperKey, signal, recover) : await this.#sealedFor(keys, keeperKey);
+            body = { device_share: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeral_public_key: share.ephemeralPublicKey, encryption_algorithm: share.encryptionAlgorithm, encryption_context: share.encryptionContext } };
+        }
+        const operation = parseOperationEnvelope((await this.#transport.write(`/v1/operations/${operationId}/execute`, 'POST', body, signal, idempotencyKey, version)).payload).operation;
+        if (operation.id !== operationId)
+            fault();
+        return operation;
+    }
+    /** The account's permissions in every state, newest first. */
+    async listDebitPermissions(signal) {
+        return parseDebitPermissionList(await this.#transport.get('/v1/debit-permissions', signal));
+    }
+    /**
+     * Asks to end one permission. The operation awaits the person's passkey; executeOperation() applies it,
+     * without a body. A debit not yet executed is refused from then on.
+     */
+    async revokeDebitPermission(debitPermissionId, idempotencyKey, signal) {
+        const create = debitPermissionRevocation(this.#transport.accountId(), debitPermissionId);
+        requestID(idempotencyKey);
+        const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
+        const operation = parseOperationEnvelope(payload).operation;
+        if (operation.display.kind !== 'debit_permission.revoke' || operation.ownerId !== accountId || operation.display.debitPermissionId !== debitPermissionId)
+            fault();
+        return operation;
+    }
+    async #keptFor(read, keeperKey, signal, recover) {
+        if (read.display.kind !== 'debit_permission.create')
+            throw new ClientFlowError('invalid_execute_request');
+        if (!this.#kept)
+            throw new ClientFlowError('device_share_unavailable');
+        return this.#kept(read.display.linkedWalletId, keeperKey, signal, recover);
+    }
+    async #sealedFor(keys, keeperKey) {
+        let declared, share;
+        try {
+            declared = record(keys, ['devicePrivateKey', 'deviceShare']);
+            share = record(declared.deviceShare, ['ciphertext', 'nonce', 'ephemeralPublicKey', 'encryptionAlgorithm', 'encryptionContext']);
+        }
+        catch {
+            throw new ClientFlowError('invalid_execute_request');
+        }
+        if (![share.ciphertext, share.nonce, share.ephemeralPublicKey, share.encryptionContext].every(hex) || typeof share.encryptionAlgorithm !== 'string')
+            throw new ClientFlowError('invalid_execute_request');
+        return resealDeviceShare(declared.devicePrivateKey, keys.deviceShare, keeperKey);
+    }
+}

package/dist/deviceRecovery.d.ts

@@ -0,0 +1,40 @@
+import { type PollOptions } from "./poll.ts";
+import type { DeviceRecoveryOptions, DeviceShareRecord, PendingDeviceShareRecord } from "./deviceShares.ts";
+import type { LinkedWallet } from "./linkedWallets.ts";
+import type { AccountIdentity, ConfirmationChallenge } from "./slice4.ts";
+import type { UserWalletOperation, UserWalletOperationCreate, WalletResult } from "./walletOperations.ts";
+/** The calls of the client the recovery is made of; AuthorizationClient answers them all. */
+export interface RecoveryClient {
+    identities(signal?: AbortSignal): Promise<AccountIdentity[]>;
+    createWalletOperation(create: UserWalletOperationCreate, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    challengeWalletOperation(operationId: string, credentialId: string, signal?: AbortSignal): Promise<ConfirmationChallenge>;
+    completeWalletOperationConfirmation(callbackUri: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    executeWalletOperation(operationId: string, version: string, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    walletOperation(operationId: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    walletOperationResult(operationId: string, signal?: AbortSignal): Promise<WalletResult>;
+}
+/** How long the SDK reads an executed recovery: rounds of at most a minute each, and the poll's own clock and sleep. */
+export interface RecoverySettling {
+    rounds?: number;
+    now?: () => number;
+    sleep?: PollOptions<UserWalletOperation>["sleep"];
+}
+/** newestPasskey is the account's passkey a recovery is confirmed with when the app names none: the one added last. */
+export declare function newestPasskey(identities: readonly AccountIdentity[]): string;
+/**
+ * recoverDeviceShare recovers the device share of one of the account's linked
+ * wallets onto a new device key and answers the record to keep. keepPending
+ * keeps the confirmed recovery before it is executed. Every refusal of the
+ * provider surfaces as its AuthorizationError; what the SDK refuses itself is
+ * a ClientFlowError: device_recovery_requires_passkey,
+ * hosted_callback_unavailable (the host's launcher did not answer the
+ * redirect back), device_recovery_not_confirmed, device_recovery_failed.
+ */
+export declare function recoverDeviceShare(client: RecoveryClient, accountId: string, crypto: Crypto, wallet: LinkedWallet, options: DeviceRecoveryOptions, keepPending: (pending: PendingDeviceShareRecord) => Promise<void>, settling?: RecoverySettling): Promise<DeviceShareRecord>;
+/**
+ * resumeDeviceRecovery takes up a pending recovery where it stopped: executes
+ * it when it was never executed, and reads it to its end. Undefined means it
+ * ended without effect (or is gone past its retention), and a new recovery
+ * may start; one still under way is device_recovery_failed and stays pending.
+ */
+export declare function resumeDeviceRecovery(client: RecoveryClient, crypto: Crypto, wallet: LinkedWallet, pending: PendingDeviceShareRecord, options: DeviceRecoveryOptions, settling?: RecoverySettling): Promise<DeviceShareRecord | undefined>;

package/dist/deviceRecovery.js

@@ -0,0 +1,143 @@
+// The recovery of a linked wallet's device share onto this device (owner
+// decision of 28 October 2026). The wallet's key is three shares, any two of
+// which sign; the own-wallet system rebuilds the device share from the other
+// two and seals it to a new device key made here. The person sees one passkey
+// confirmation on the provider's page, as for creating the wallet: a session
+// alone never yields a device share, since a send needs nothing more than the
+// session and that share. Once it succeeds the share this wallet had on any
+// other device stops working.
+//
+// A confirmed recovery is kept as pending, with its device key, operation and
+// execute key, before it is executed: an answer that is lost or a Wallet that
+// has not said yet leaves it pending, and the next call resumes that same
+// operation instead of starting a second one whose effect a late first one
+// would undo.
+import { AuthorizationError, ClientFlowError, opaqueId } from "./auth.js";
+import { generateDeviceKey } from "./deviceKey.js";
+import { openDeviceShare } from "./deviceShareEnvelope.js";
+import { linkedRecoverCreate } from "./linkedRecovery.js";
+import { pollAuthoritative } from "./poll.js";
+const terminal = new Set(["succeeded", "failed", "denied", "canceled", "expired"]);
+function randomKey(crypto) {
+    return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** newestPasskey is the account's passkey a recovery is confirmed with when the app names none: the one added last. */
+export function newestPasskey(identities) {
+    const passkeys = identities.filter((identity) => identity.method === "passkey" && identity.credentialId !== undefined)
+        .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+    if (passkeys.length === 0)
+        throw new ClientFlowError("device_recovery_requires_passkey");
+    return passkeys[0].credentialId;
+}
+async function settled(client, operation, signal, settling) {
+    let last = operation;
+    for (let round = 0; round < (settling.rounds ?? 5) && !terminal.has(last.state); round++) {
+        const polled = await pollAuthoritative({ read: (stop) => client.walletOperation(operation.id, stop), terminal: (value) => terminal.has(value.state), signal, now: settling.now, sleep: settling.sleep });
+        if (polled.lastKnown)
+            last = polled.lastKnown;
+        if (polled.disposition === "local_canceled")
+            throw signal?.reason ?? new ClientFlowError("device_recovery_failed");
+    }
+    return last;
+}
+/**
+ * finish executes a confirmed recovery with its own execute key, unless it was
+ * executed already, and reads it to its end. It answers the record to keep,
+ * or undefined when the recovery ended without effect; one the Wallet has not
+ * finished is device_recovery_failed and stays pending.
+ */
+async function finish(client, crypto, wallet, pending, operation, signal, settling) {
+    if (operation.state === "authorized")
+        operation = await client.executeWalletOperation(pending.pendingOperationId, operation.version, pending.executeKey, signal);
+    operation = await settled(client, operation, signal, settling);
+    if (operation.state !== "succeeded") {
+        if (terminal.has(operation.state))
+            return undefined;
+        throw new ClientFlowError("device_recovery_failed");
+    }
+    const { result } = await client.walletOperationResult(operation.id, signal);
+    // The recovery names the linked wallet it was admitted for, which a reconnection may since have renamed; the wallet itself is the same.
+    if (result.kind !== "device_share_recovered" || result.linkedWalletId !== (pending.pendingLinkedWalletId ?? wallet.id) || result.receiptId !== wallet.externalWalletId || !result.deviceShare || !opaqueId(result.operationId)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    // Only a share this device can open is kept.
+    (await openDeviceShare(pending.privateKey, result.deviceShare, crypto.subtle)).fill(0);
+    return { walletId: wallet.externalWalletId, privateKey: pending.privateKey, publicKeyHex: pending.publicKeyHex, deviceShare: result.deviceShare };
+}
+/**
+ * recoverDeviceShare recovers the device share of one of the account's linked
+ * wallets onto a new device key and answers the record to keep. keepPending
+ * keeps the confirmed recovery before it is executed. Every refusal of the
+ * provider surfaces as its AuthorizationError; what the SDK refuses itself is
+ * a ClientFlowError: device_recovery_requires_passkey,
+ * hosted_callback_unavailable (the host's launcher did not answer the
+ * redirect back), device_recovery_not_confirmed, device_recovery_failed.
+ */
+export async function recoverDeviceShare(client, accountId, crypto, wallet, options, keepPending, settling = {}) {
+    const { signal } = options;
+    if (options.credentialId !== undefined && !/^[A-Za-z0-9_-]{1,1024}$/.test(options.credentialId))
+        throw new ClientFlowError("invalid_confirmation_request");
+    const credentialId = options.credentialId ?? newestPasskey(await client.identities(signal));
+    const device = await generateDeviceKey(crypto.subtle);
+    let operation = await client.createWalletOperation(linkedRecoverCreate(accountId, wallet.id, device.publicKeyHex), randomKey(crypto), signal);
+    if (operation.kind !== "wallet.recover" || operation.linkedWallet?.linkedWalletId !== wallet.id)
+        throw new ClientFlowError("invalid_server_response");
+    const challenge = await client.challengeWalletOperation(operation.id, credentialId, signal);
+    if (typeof challenge.callbackUri !== "string")
+        throw new ClientFlowError("hosted_callback_unavailable");
+    operation = await client.completeWalletOperationConfirmation(challenge.callbackUri, signal);
+    if (operation.state !== "authorized")
+        throw new ClientFlowError("device_recovery_not_confirmed");
+    const pending = { walletId: wallet.externalWalletId, privateKey: device.privateKey, publicKeyHex: device.publicKeyHex, pendingOperationId: operation.id, executeKey: randomKey(crypto), pendingLinkedWalletId: wallet.id };
+    await keepPending(pending);
+    const kept = await finish(client, crypto, wallet, pending, operation, signal, settling);
+    if (!kept)
+        throw new ClientFlowError("device_recovery_failed");
+    return kept;
+}
+/**
+ * resumeDeviceRecovery takes up a pending recovery where it stopped: executes
+ * it when it was never executed, and reads it to its end. Undefined means it
+ * ended without effect (or is gone past its retention), and a new recovery
+ * may start; one still under way is device_recovery_failed and stays pending.
+ */
+export async function resumeDeviceRecovery(client, crypto, wallet, pending, options, settling = {}) {
+    let operation;
+    try {
+        operation = await client.walletOperation(pending.pendingOperationId, options.signal);
+    }
+    catch (error) {
+        if (error instanceof AuthorizationError && error.code === "NOT_FOUND")
+            return undefined;
+        throw error;
+    }
+    if (operation.kind !== "wallet.recover" || operation.linkedWallet?.linkedWalletId !== (pending.pendingLinkedWalletId ?? wallet.id))
+        throw new ClientFlowError("invalid_server_response");
+    // Never confirmed, it can have no effect, and nobody else may confirm it.
+    if (operation.state === "awaiting_confirmation")
+        return undefined;
+    if (operation.state === "authorized") {
+        // Never claimed: one past its deadline, or one the provider no longer
+        // claims (only the confirming session executes it), can have no effect,
+        // and a new recovery replaces it.
+        if (Date.parse(operation.expiresAt) <= Date.now())
+            return undefined;
+        try {
+            operation = await client.executeWalletOperation(pending.pendingOperationId, operation.version, pending.executeKey, options.signal);
+        }
+        catch (error) {
+            if (error instanceof AuthorizationError && (error.code === "AUTHORIZATION_STALE" || error.code === "OPERATION_EXPIRED"))
+                return undefined;
+            throw error;
+        }
+    }
+    try {
+        return await finish(client, crypto, wallet, pending, operation, options.signal, settling);
+    }
+    catch (error) {
+        // A result past its retention cannot be read: a new recovery replaces it.
+        if (error instanceof AuthorizationError && error.code === "RESULT_EXPIRED")
+            return undefined;
+        throw error;
+    }
+}

package/dist/deviceShares.d.ts

@@ -0,0 +1,91 @@
+import { type DeviceKey } from "./deviceKey.ts";
+import type { LinkedWallet } from "./linkedWallets.ts";
+import type { DeviceSharePackage, WalletResult } from "./walletOperations.ts";
+/**
+ * One wallet's device share as this device keeps it. walletId is the
+ * own-wallet system's wallet ID (a linked wallet's externalWalletId),
+ * publicKeyHex the device key's compressed public key. A record of a
+ * recovery confirmed but not finished carries pendingOperationId and
+ * executeKey and no deviceShare: it is no usable share, and the recovery is
+ * resumed from it.
+ */
+export interface DeviceShareRecord {
+    readonly walletId: string;
+    readonly privateKey: CryptoKey;
+    readonly publicKeyHex?: string;
+    readonly deviceShare?: DeviceSharePackage;
+    readonly pendingOperationId?: string;
+    readonly executeKey?: string;
+    /** The linked wallet the pending recovery was admitted for; a reconnection may since have given the wallet another. */
+    readonly pendingLinkedWalletId?: string;
+}
+/** A recovery confirmed and kept before it is executed. */
+export type PendingDeviceShareRecord = DeviceShareRecord & {
+    publicKeyHex: string;
+    pendingOperationId: string;
+    executeKey: string;
+    deviceShare?: undefined;
+};
+/** Where the records live. load answers undefined for a wallet this device holds no record of. */
+export interface DeviceShareStore {
+    load(walletId: string): Promise<DeviceShareRecord | undefined>;
+    save(record: DeviceShareRecord): Promise<void>;
+}
+/** Options of a recovery: the passkey that confirms it (by default the account's newest) and the caller's signal. */
+export interface DeviceRecoveryOptions {
+    credentialId?: string;
+    signal?: AbortSignal;
+}
+/** The provider's device key of a wallet, undefined when it names none; read again each time it is asked. */
+export type ServerDeviceKey = () => Promise<string | undefined>;
+/** What the linked-wallet facade asks of the keeper (linkedWallets.ts). */
+export interface LinkedDeviceShares {
+    has(wallet: LinkedWallet, serverKey: ServerDeviceKey): Promise<boolean>;
+    /** Makes sure this device holds a usable share of the wallet, recovering it unless one is kept (force: always); answers whether it recovered. */
+    ensure(wallet: LinkedWallet, serverKey: ServerDeviceKey, options?: DeviceRecoveryOptions & {
+        force?: boolean;
+    }): Promise<boolean>;
+    /** The kept share resealed to the own-wallet system's transport key for one transfer. */
+    sealedFor(wallet: LinkedWallet, transportPublicKey: string): Promise<DeviceSharePackage>;
+}
+/**
+ * indexedDBDeviceShareStore keeps the records in the origin's IndexedDB, under
+ * namespace (one per client configuration), so the tabs of this origin share
+ * them and the key handles stay non-extractable.
+ */
+export declare function indexedDBDeviceShareStore(namespace: string, factory?: IDBFactory | undefined): DeviceShareStore;
+/** The store a web client keeps its shares in when the app supplies none: the origin's IndexedDB, where there is one. */
+export declare function defaultDeviceShareStore(channel: "web" | "mobile", namespace: string): DeviceShareStore | undefined;
+/**
+ * DeviceShareKeeper is one client's keeper: the store, the lock its tabs take
+ * turns under, the device keys of the creations it made, and the recovery the
+ * client runs and resumes (deviceRecovery.ts).
+ */
+export declare class DeviceShareKeeper implements LinkedDeviceShares {
+    #private;
+    constructor(input: {
+        store: DeviceShareStore | undefined;
+        crypto: Crypto;
+        lockPrefix: string;
+        lock: <T>(name: string, work: () => Promise<T>) => Promise<T>;
+        recover: (wallet: LinkedWallet, options: DeviceRecoveryOptions, keepPending: (record: PendingDeviceShareRecord) => Promise<void>) => Promise<DeviceShareRecord>;
+        resume: (wallet: LinkedWallet, record: PendingDeviceShareRecord, options: DeviceRecoveryOptions) => Promise<DeviceShareRecord | undefined>;
+    });
+    /** The device key a creation without the app's own key is sealed to; the same one for every call with the same idempotency key, also at once. */
+    creationKey(idempotencyKey: string): Promise<DeviceKey>;
+    /** holdCreation remembers which device key the admitted creation's share will be sealed to. */
+    holdCreation(operationId: string, device: DeviceKey): void;
+    /**
+     * keepCreated keeps the share of a creation this keeper made the key for,
+     * once its result is read, under the wallet's lock. It never replaces a
+     * record of the wallet: one kept already is the creation's own, read before,
+     * or a later recovery's, pending or done, which a late read of the
+     * creation's result must not undo.
+     */
+    keepCreated(operationId: string, result: WalletResult["result"]): Promise<void>;
+    has(wallet: LinkedWallet, serverKey: ServerDeviceKey): Promise<boolean>;
+    ensure(wallet: LinkedWallet, serverKey: ServerDeviceKey, options?: DeviceRecoveryOptions & {
+        force?: boolean;
+    }): Promise<boolean>;
+    sealedFor(wallet: LinkedWallet, transportPublicKey: string): Promise<DeviceSharePackage>;
+}

package/dist/deviceShares.js

@@ -0,0 +1,204 @@
+// The device shares this SDK keeps (owner decision of 28 October 2026): for
+// each wallet whose device key the SDK made, at creation or at a recovery, the
+// non-extractable device key and the wallet's device share sealed to it, in
+// the origin's storage. A browser that holds no usable share of a wallet,
+// after a change of domain, cleared site data, another browser or device, or
+// a recovery on another device that replaced its share, recovers it with one
+// passkey confirmation (deviceRecovery.ts) and then sends as before. The
+// provider names the device key of the wallet's latest creation or recovery;
+// a kept share sealed to another key is stale. The tabs of one browser take
+// turns under one Web Lock per wallet, so two of them never recover the same
+// wallet at once. The plaintext share never leaves resealDeviceShare.
+import { ClientFlowError } from "./auth.js";
+import { generateDeviceKey } from "./deviceKey.js";
+import { resealDeviceShare } from "./deviceShare.js";
+const unavailable = () => new ClientFlowError("device_share_unavailable");
+const DATABASE = "streams-authorization-device-shares";
+const STORE = "shares";
+function pending(record) {
+    return record !== undefined && record.deviceShare === undefined && typeof record.pendingOperationId === "string" && typeof record.executeKey === "string" && typeof record.publicKeyHex === "string";
+}
+function usable(record) {
+    return record !== undefined && record.pendingOperationId === undefined && record.deviceShare !== null && typeof record.deviceShare === "object";
+}
+/** A usable share is current when the provider names no device key, or names the one it is sealed to. */
+function current(record, serverKey) {
+    return usable(record) && (serverKey === undefined || record.publicKeyHex === serverKey);
+}
+/**
+ * indexedDBDeviceShareStore keeps the records in the origin's IndexedDB, under
+ * namespace (one per client configuration), so the tabs of this origin share
+ * them and the key handles stay non-extractable.
+ */
+export function indexedDBDeviceShareStore(namespace, factory = globalThis.indexedDB) {
+    if (!factory || typeof factory.open !== "function")
+        throw unavailable();
+    const key = (walletId) => `${namespace}|${walletId}`;
+    const run = (mode, work) => new Promise((resolve, reject) => {
+        const opened = factory.open(DATABASE, 1);
+        opened.onupgradeneeded = () => { opened.result.createObjectStore(STORE); };
+        opened.onerror = () => reject(unavailable());
+        opened.onsuccess = () => {
+            const database = opened.result;
+            try {
+                const transaction = database.transaction(STORE, mode);
+                const request = work(transaction.objectStore(STORE));
+                transaction.oncomplete = () => { database.close(); resolve(request.result); };
+                transaction.onerror = transaction.onabort = () => { database.close(); reject(unavailable()); };
+            }
+            catch {
+                database.close();
+                reject(unavailable());
+            }
+        };
+    });
+    return {
+        async load(walletId) {
+            const value = await run("readonly", (store) => store.get(key(walletId)));
+            if (value === undefined)
+                return undefined;
+            const record = value;
+            if (record.walletId !== walletId || !(record.privateKey instanceof CryptoKey) || (!usable(record) && !pending(record)))
+                throw unavailable();
+            return record;
+        },
+        async save(record) {
+            const kept = { walletId: record.walletId, privateKey: record.privateKey };
+            if (record.publicKeyHex !== undefined)
+                kept.publicKeyHex = record.publicKeyHex;
+            if (record.deviceShare !== undefined)
+                kept.deviceShare = { ...record.deviceShare };
+            if (record.pendingOperationId !== undefined)
+                Object.assign(kept, { pendingOperationId: record.pendingOperationId, executeKey: record.executeKey });
+            if (record.pendingLinkedWalletId !== undefined)
+                kept.pendingLinkedWalletId = record.pendingLinkedWalletId;
+            await run("readwrite", (store) => store.put(kept, key(record.walletId)));
+        },
+    };
+}
+/** The store a web client keeps its shares in when the app supplies none: the origin's IndexedDB, where there is one. */
+export function defaultDeviceShareStore(channel, namespace) {
+    if (channel !== "web" || typeof globalThis.indexedDB?.open !== "function")
+        return undefined;
+    return indexedDBDeviceShareStore(namespace);
+}
+/**
+ * DeviceShareKeeper is one client's keeper: the store, the lock its tabs take
+ * turns under, the device keys of the creations it made, and the recovery the
+ * client runs and resumes (deviceRecovery.ts).
+ */
+export class DeviceShareKeeper {
+    #store;
+    #crypto;
+    #lock;
+    #lockPrefix;
+    #recover;
+    #resume;
+    /** Device keys of creations, by the creation's idempotency key, so a repeat sends the same request. */
+    #creationKeys = new Map();
+    /** The creation's device key, by operation, until its result is kept. */
+    #creations = new Map();
+    /** Recoveries under way in this client, by wallet. */
+    #flights = new Map();
+    constructor(input) {
+        this.#store = input.store;
+        this.#crypto = input.crypto;
+        this.#lock = input.lock;
+        this.#lockPrefix = input.lockPrefix;
+        this.#recover = input.recover;
+        this.#resume = input.resume;
+    }
+    #required() {
+        if (!this.#store)
+            throw unavailable();
+        return this.#store;
+    }
+    /** The device key a creation without the app's own key is sealed to; the same one for every call with the same idempotency key, also at once. */
+    creationKey(idempotencyKey) {
+        this.#required();
+        let made = this.#creationKeys.get(idempotencyKey);
+        if (!made) {
+            made = generateDeviceKey(this.#crypto.subtle);
+            this.#creationKeys.set(idempotencyKey, made);
+            made.catch(() => this.#creationKeys.delete(idempotencyKey));
+        }
+        return made;
+    }
+    /** holdCreation remembers which device key the admitted creation's share will be sealed to. */
+    holdCreation(operationId, device) { this.#creations.set(operationId, device); }
+    /**
+     * keepCreated keeps the share of a creation this keeper made the key for,
+     * once its result is read, under the wallet's lock. It never replaces a
+     * record of the wallet: one kept already is the creation's own, read before,
+     * or a later recovery's, pending or done, which a late read of the
+     * creation's result must not undo.
+     */
+    async keepCreated(operationId, result) {
+        const device = this.#creations.get(operationId);
+        if (!device || result.kind !== "wallet_created" || !result.wallet || !result.deviceShare)
+            return;
+        const store = this.#required(), walletId = result.wallet.walletId, deviceShare = result.deviceShare;
+        await this.#lock(this.#lockName(walletId), async () => {
+            if ((await store.load(walletId)) === undefined)
+                await store.save({ walletId, privateKey: device.privateKey, publicKeyHex: device.publicKeyHex, deviceShare });
+        });
+        this.#creations.delete(operationId);
+    }
+    #lockName(walletId) { return `${this.#lockPrefix}:device-recovery:${walletId}`; }
+    async has(wallet, serverKey) {
+        const record = await this.#required().load(wallet.externalWalletId);
+        return usable(record) && current(record, await serverKey());
+    }
+    ensure(wallet, serverKey, options = {}) {
+        const store = this.#required();
+        const walletId = wallet.externalWalletId;
+        const force = options.force === true;
+        const running = force ? undefined : this.#flights.get(walletId);
+        if (running)
+            return running;
+        const flight = (async () => {
+            if (!force && current(await store.load(walletId), await serverKey()))
+                return false;
+            // Under the tabs' lock the store and the provider's key are read again:
+            // a tab that waited finds the share the other one recovered, or the
+            // recovery it left pending, and recovers nothing new.
+            return this.#lock(this.#lockName(walletId), async () => {
+                let record = await store.load(walletId);
+                let resumed = false;
+                if (pending(record)) {
+                    record = await this.#resume(wallet, record, options);
+                    if (record) {
+                        await store.save(record);
+                        resumed = true;
+                    }
+                }
+                // A share kept, or resumed just now, is used only while the provider
+                // names its key: a recovery on another device since replaced it.
+                if ((resumed || !force) && current(record, await serverKey()))
+                    return resumed;
+                // One recovery, and one more when another device recovered meanwhile;
+                // then the call gives up rather than chase the other device.
+                for (let attempt = resumed ? 1 : 0; attempt < 2; attempt++) {
+                    const recovered = await this.#recover(wallet, options, (kept) => store.save(kept));
+                    if (recovered.walletId !== walletId)
+                        throw new ClientFlowError("invalid_server_response");
+                    await store.save(recovered);
+                    if (current(recovered, await serverKey()))
+                        return true;
+                }
+                throw new ClientFlowError("device_recovery_failed");
+            });
+        })();
+        if (!force) {
+            this.#flights.set(walletId, flight);
+            void flight.then(() => this.#flights.delete(walletId), () => this.#flights.delete(walletId));
+        }
+        return flight;
+    }
+    async sealedFor(wallet, transportPublicKey) {
+        const record = await this.#required().load(wallet.externalWalletId);
+        if (!usable(record))
+            throw unavailable();
+        return resealDeviceShare(record.privateKey, record.deviceShare, transportPublicKey, this.#crypto);
+    }
+}