@shuttle.technology/authorization 0.0.0-stage → 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/deviceKey.d.ts

@@ -0,0 +1,13 @@
+export interface DeviceKey {
+    /** Non-extractable ECDH P-256 private key handle. */
+    readonly privateKey: CryptoKey;
+    /** 33-byte compressed public key, 66 lowercase hexadecimal characters. */
+    readonly publicKeyHex: string;
+}
+/** generateDeviceKey creates one device key pair with a non-extractable private key. */
+export declare function generateDeviceKey(subtle?: SubtleCrypto): Promise<DeviceKey>;
+/**
+ * devicePublicKeyHex returns the compressed SEC1 encoding of a P-256 public
+ * key: the parity prefix 02 or 03 followed by the 32-byte X coordinate.
+ */
+export declare function devicePublicKeyHex(publicKey: CryptoKey, subtle?: SubtleCrypto): Promise<string>;

package/dist/deviceKey.js

@@ -0,0 +1,28 @@
+// Device key (source §1.10): the P-256 key pair the own-wallet system seals a
+// wallet's device share to. The private key is generated non-extractable and
+// never leaves the device; only its compressed public key is sent, as the
+// recipient key of a wallet.create operation. This module performs no
+// persistence and no network request: the application keeps the returned
+// private key handle and the sealed device share it later receives in platform
+// storage that can hold a non-extractable key, such as IndexedDB.
+import { ClientFlowError } from "./auth.js";
+/** generateDeviceKey creates one device key pair with a non-extractable private key. */
+export async function generateDeviceKey(subtle = globalThis.crypto.subtle) {
+    const pair = await subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, false, ["deriveBits"]);
+    if (pair.privateKey.extractable)
+        throw new ClientFlowError("device_key_unavailable");
+    return { privateKey: pair.privateKey, publicKeyHex: await devicePublicKeyHex(pair.publicKey, subtle) };
+}
+/**
+ * devicePublicKeyHex returns the compressed SEC1 encoding of a P-256 public
+ * key: the parity prefix 02 or 03 followed by the 32-byte X coordinate.
+ */
+export async function devicePublicKeyHex(publicKey, subtle = globalThis.crypto.subtle) {
+    const raw = new Uint8Array(await subtle.exportKey("raw", publicKey));
+    if (raw.length !== 65 || raw[0] !== 0x04)
+        throw new ClientFlowError("device_key_unavailable");
+    const compressed = new Uint8Array(33);
+    compressed[0] = 0x02 | (raw[64] & 0x01);
+    compressed.set(raw.subarray(1, 33), 1);
+    return Array.from(compressed, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

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/deviceShare.d.ts

@@ -0,0 +1,9 @@
+import type { DeviceSharePackage } from "./walletOperations.ts";
+export { DeviceShareAlgorithm } from "./deviceShareEnvelope.ts";
+/**
+ * resealDeviceShare opens the device share with the device key and seals it,
+ * under its own unchanged context, to the enclave's transport key for one
+ * send. The plaintext share exists only inside this call. The transport key
+ * is taken as given: this function cannot tell an enclave's key from any other.
+ */
+export declare function resealDeviceShare(deviceKey: CryptoKey, sealed: DeviceSharePackage, enclavePublicKeyHex: string, crypto?: Crypto): Promise<DeviceSharePackage>;

package/dist/deviceShare.js

@@ -0,0 +1,24 @@
+// Device share (source §1.10): the one of a wallet's three key shares that only
+// the user's device can open. The own-wallet system seals it to the device key
+// when the wallet is created. To sign, the device opens it and seals it again
+// to the enclave's transport key, so the enclave can combine it with its own
+// share. This module is the whole of what an application needs for that, and
+// it never hands the plaintext share to its caller. It performs no persistence
+// and no network request.
+import { openDeviceShare, sealDeviceShare } from "./deviceShareEnvelope.js";
+export { DeviceShareAlgorithm } from "./deviceShareEnvelope.js";
+/**
+ * resealDeviceShare opens the device share with the device key and seals it,
+ * under its own unchanged context, to the enclave's transport key for one
+ * send. The plaintext share exists only inside this call. The transport key
+ * is taken as given: this function cannot tell an enclave's key from any other.
+ */
+export async function resealDeviceShare(deviceKey, sealed, enclavePublicKeyHex, crypto = globalThis.crypto) {
+    const share = await openDeviceShare(deviceKey, sealed, crypto.subtle);
+    try {
+        return await sealDeviceShare(share, enclavePublicKeyHex, sealed.encryptionContext, crypto);
+    }
+    finally {
+        share.fill(0);
+    }
+}

package/dist/deviceShareEnvelope.d.ts

@@ -0,0 +1,13 @@
+import { type Bytes } from "./aesGcmSiv.ts";
+import type { DeviceSharePackage } from "./walletOperations.ts";
+export declare const DeviceShareAlgorithm = "p256-ecdh-hkdf-sha256-aes256-gcm-siv-v1";
+/**
+ * uncompressedPoint returns the 65-byte form WebCrypto imports, from the
+ * 33-byte compressed or the 65-byte uncompressed SEC1 encoding of a point of
+ * P-256. Anything that is not a point of the curve is refused here.
+ */
+export declare function uncompressedPoint(encoded: Uint8Array): Bytes;
+/** openDeviceShare returns the plaintext share; the caller clears it after use. */
+export declare function openDeviceShare(privateKey: CryptoKey, sealed: DeviceSharePackage, subtle?: SubtleCrypto): Promise<Bytes>;
+/** sealDeviceShare seals a share to a recipient's P-256 key under the given context. */
+export declare function sealDeviceShare(share: Uint8Array, recipientPublicKeyHex: string, contextHex: string, crypto?: Crypto): Promise<DeviceSharePackage>;

package/dist/deviceShareEnvelope.js

@@ -0,0 +1,139 @@
+// The device share envelope, in the own-wallet system's format byte for byte
+// (enclave device_crypto at Wallet source 9160f84): ECDH over P-256 with an
+// ephemeral key, HKDF-SHA-256 with the encryption context as salt and the info
+// "novasol:device-share:v1", AES-256-GCM-SIV with the same context as
+// associated data. openDeviceShare returns the plaintext share, so this module
+// is not a package entry point: applications use deviceShare.ts, which never
+// lets the plaintext out.
+import { ClientFlowError } from "./auth.js";
+import { aes256GcmSivOpen, aes256GcmSivSeal } from "./aesGcmSiv.js";
+export const DeviceShareAlgorithm = "p256-ecdh-hkdf-sha256-aes256-gcm-siv-v1";
+const INFO = new TextEncoder().encode("novasol:device-share:v1");
+const TAG_BYTES = 16;
+// What an opener accepts, so a sealer never produces what cannot be opened.
+const MAX_CIPHERTEXT_BYTES = 4096;
+const MAX_CONTEXT_BYTES = 512;
+// The P-256 field prime and curve constant b; a is -3.
+const P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn;
+const B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+function fault() { throw new ClientFlowError("device_share_unavailable"); }
+function fromHex(value, minimum, maximum) {
+    if (typeof value !== "string" || value.length % 2 !== 0 || !/^[0-9a-f]*$/.test(value) || value.length < 2 * minimum || value.length > 2 * maximum)
+        fault();
+    const out = new Uint8Array(value.length / 2);
+    for (let index = 0; index < out.length; index++)
+        out[index] = Number.parseInt(value.slice(2 * index, 2 * index + 2), 16);
+    return out;
+}
+function toHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+// power and curveSquare work on public coordinates only, never on a secret.
+function power(base, exponent) {
+    let result = 1n;
+    for (let value = base % P, rest = exponent; rest > 0n; rest >>= 1n, value = (value * value) % P)
+        if (rest & 1n)
+            result = (result * value) % P;
+    return result;
+}
+function curveSquare(x) { return (power(x, 3n) + P - ((3n * x) % P) + B) % P; }
+function bigEndian(bytes) {
+    let value = 0n;
+    for (const byte of bytes)
+        value = (value << 8n) | BigInt(byte);
+    return value;
+}
+/**
+ * uncompressedPoint returns the 65-byte form WebCrypto imports, from the
+ * 33-byte compressed or the 65-byte uncompressed SEC1 encoding of a point of
+ * P-256. Anything that is not a point of the curve is refused here.
+ */
+export function uncompressedPoint(encoded) {
+    if (encoded.length === 65 && encoded[0] === 0x04) {
+        const x = bigEndian(encoded.subarray(1, 33));
+        const y = bigEndian(encoded.subarray(33));
+        if (x >= P || y >= P || (y * y) % P !== curveSquare(x))
+            fault();
+        return new Uint8Array(encoded);
+    }
+    if (encoded.length !== 33 || (encoded[0] !== 0x02 && encoded[0] !== 0x03))
+        fault();
+    const x = bigEndian(encoded.subarray(1));
+    if (x >= P)
+        fault();
+    const square = curveSquare(x);
+    let y = power(square, (P + 1n) / 4n);
+    if ((y * y) % P !== square)
+        fault();
+    if (Number(y & 1n) !== (encoded[0] & 1))
+        y = P - y;
+    const out = new Uint8Array(65);
+    out[0] = 0x04;
+    out.set(encoded.subarray(1), 1);
+    for (let index = 0; index < 32; index++)
+        out[64 - index] = Number((y >> BigInt(8 * index)) & 0xffn);
+    return out;
+}
+function compressedPoint(uncompressed) {
+    if (uncompressed.length !== 65 || uncompressed[0] !== 0x04)
+        fault();
+    const out = new Uint8Array(33);
+    out[0] = 0x02 | (uncompressed[64] & 0x01);
+    out.set(uncompressed.subarray(1, 33), 1);
+    return out;
+}
+/** The envelope key: the ECDH shared X coordinate through HKDF-SHA-256, salted with the context. */
+async function envelopeKey(subtle, privateKey, peer, context) {
+    const point = uncompressedPoint(peer);
+    let shared;
+    try {
+        const publicKey = await subtle.importKey("raw", point, { name: "ECDH", namedCurve: "P-256" }, false, []);
+        shared = new Uint8Array(await subtle.deriveBits({ name: "ECDH", public: publicKey }, privateKey, 256));
+        const material = await subtle.importKey("raw", shared, "HKDF", false, ["deriveBits"]);
+        return new Uint8Array(await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: context, info: INFO }, material, 256));
+    }
+    catch {
+        // One answer for every refusal, whatever the platform's own error was.
+        return fault();
+    }
+    finally {
+        shared?.fill(0);
+    }
+}
+/** openDeviceShare returns the plaintext share; the caller clears it after use. */
+export async function openDeviceShare(privateKey, sealed, subtle = globalThis.crypto.subtle) {
+    if (sealed.encryptionAlgorithm !== DeviceShareAlgorithm)
+        fault();
+    const context = fromHex(sealed.encryptionContext, 1, MAX_CONTEXT_BYTES);
+    const ciphertext = fromHex(sealed.ciphertext, TAG_BYTES + 1, MAX_CIPHERTEXT_BYTES);
+    const nonce = fromHex(sealed.nonce, 12, 12);
+    const key = await envelopeKey(subtle, privateKey, fromHex(sealed.ephemeralPublicKey, 33, 65), context);
+    try {
+        return await aes256GcmSivOpen(subtle, key, nonce, ciphertext, context);
+    }
+    catch {
+        return fault();
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/** sealDeviceShare seals a share to a recipient's P-256 key under the given context. */
+export async function sealDeviceShare(share, recipientPublicKeyHex, contextHex, crypto = globalThis.crypto) {
+    if (share.length === 0 || share.length > MAX_CIPHERTEXT_BYTES - TAG_BYTES)
+        fault();
+    const subtle = crypto.subtle;
+    const context = fromHex(contextHex, 1, MAX_CONTEXT_BYTES);
+    const recipient = fromHex(recipientPublicKeyHex, 33, 65);
+    const ephemeral = await subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, false, ["deriveBits"]);
+    const key = await envelopeKey(subtle, ephemeral.privateKey, recipient, context);
+    try {
+        const nonce = crypto.getRandomValues(new Uint8Array(12));
+        const ciphertext = await aes256GcmSivSeal(subtle, key, nonce, share, context);
+        const ephemeralPublic = compressedPoint(new Uint8Array(await subtle.exportKey("raw", ephemeral.publicKey)));
+        return { ciphertext: toHex(ciphertext), nonce: toHex(nonce), ephemeralPublicKey: toHex(ephemeralPublic), encryptionAlgorithm: DeviceShareAlgorithm, encryptionContext: contextHex };
+    }
+    finally {
+        key.fill(0);
+    }
+}

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>;
+}