@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/linkedWallets.js

@@ -0,0 +1,436 @@
+// HTTP-only account links and explicit linked streams.register. Provider tokens
+// are arguments of individual writes; this facade never retains them.
+//
+// The account's session authorizes what is done with a linked wallet: its
+// registration for tracking (register() comes back authorized and
+// executeRegistration() follows at once), and a send from it (send() and
+// replaceSend() come back authorized, prepare() has the transfer prepared and
+// shown, executeSend() sends it on the owner's confirm). No passkey is asked
+// for either (owner decisions of 8 and 14 October 2026); a passkey still
+// confirms creating a wallet.
+import { ClientFlowError, canonicalDecimal, integer, opaqueId, record, rfc3339UTC, unexpiredRFC3339 } from './auth.js';
+import { parseWalletEventPage } from './streams.js';
+export { resumeCursor } from './streams.js';
+import { parseOperationEnvelope } from './slice4.js';
+import { linkedEventsPath, linkedRegistrationsPath, parseLinkedRegistrationOperationEnvelope, parseLinkedRegistrationResult, parseLinkedStreamsRegistrationList, validateLinkedRegistrationCreate } from './linkedRegistrations.js';
+export { linkedEventsPath, linkedRegistrationsPath, parseLinkedRegistrationOperation, parseLinkedRegistrationOperationEnvelope, parseLinkedRegistrationResult, parseLinkedStreamsRegistrationList, validateLinkedRegistrationCreate } from './linkedRegistrations.js';
+import { linkedSignalsPath, readLinkedWalletSignals } from './linkedWalletSignals.js';
+export { linkedSignalsPath, readLinkedWalletSignals, MaxSignalWallets } from './linkedWalletSignals.js';
+import { parseTransferStatus, transferStatusPath } from './transferStatus.js';
+import { parseLinkedWalletBalances } from './balances.js';
+export { parseLinkedWalletBalances } from './balances.js';
+import { parseSendPage, sendsPath } from './sends.js';
+export { eventOfTransaction, parseSendPage, sendEvents, sendsPath } from './sends.js';
+export { parseTransferStatus, transferFinal, transferStatusPath, TransferStates } from './transferStatus.js';
+import { parseWalletLimits, walletLimitsCreate } from './walletLimits.js';
+export { WalletLimitRefusals, isWalletLimitRefusal, MaxLimitCeilings, MaxLimitRecipients } from './walletLimits.js';
+import { DebitPermissions } from './debitPermissions.js';
+export { DebitPermissions, MaxDebitAssets, MaxDebitRecipients } from './debitPermissions.js';
+import { b64, fault, hex, network, publicKey, requestID, requestUUID, safeRevision, text, token, uuid } from './linkedChecks.js';
+import { linkedSendAsset, parseUserWalletOperationEnvelope, replaceAction, transferComment } from './walletOperations.js';
+export class LinkedWallets {
+    #transport;
+    constructor(transport) { this.#transport = transport; }
+    async challenge(cognitoAccessToken, credentialId, signal) {
+        token(cognitoAccessToken);
+        requestID(credentialId);
+        const { payload } = await this.#transport.write('/v1/wallet-connections/challenges', 'POST', { cognito_access_token: cognitoAccessToken, passkey_credential_id: credentialId }, signal);
+        const challenge = parseWalletLinkChallenge(payload, this.#transport.now());
+        if (challenge.publicKey.allowCredentials[0].id !== credentialId)
+            fault();
+        return challenge;
+    }
+    async connect(challengeId, cognitoAccessToken, assertion, signal) {
+        requestUUID(challengeId);
+        token(cognitoAccessToken);
+        validateWalletLinkAssertion(assertion);
+        const encoded = JSON.stringify(assertion);
+        if (new TextEncoder().encode(encoded).length > 65536)
+            throw new ClientFlowError('invalid_linked_wallet_request');
+        return parseWalletConnection((await this.#transport.write('/v1/wallet-connections', 'POST', { challenge_id: challengeId, cognito_access_token: cognitoAccessToken, response: encoded }, signal)).payload);
+    }
+    async connection(connectionId, signal) {
+        requestUUID(connectionId);
+        const connection = parseWalletConnection(await this.#transport.get(`/v1/wallet-connections/${connectionId}`, signal));
+        if (connection.id !== connectionId)
+            fault();
+        return connection;
+    }
+    async sync(connectionId, cognitoAccessToken, signal) {
+        requestUUID(connectionId);
+        token(cognitoAccessToken);
+        const connection = parseWalletConnection((await this.#transport.write(`/v1/wallet-connections/${connectionId}/sync`, 'POST', { cognito_access_token: cognitoAccessToken }, signal)).payload);
+        if (connection.id !== connectionId)
+            fault();
+        return connection;
+    }
+    /**
+     * refresh binds the account to the Wallet identity the provider owns for it
+     * and synchronizes its public wallet inventory. It carries no Wallet token
+     * and no body; repeating it converges on the same connection. Call it after
+     * a wallet was created so the wallet appears in list().
+     */
+    async refresh(signal) {
+        const connection = parseWalletConnection((await this.#transport.write('/v1/wallet-connections/brokered', 'POST', undefined, signal)).payload);
+        if (connection.state !== 'connected')
+            fault();
+        return connection;
+    }
+    async disconnect(connectionId, signal) {
+        requestUUID(connectionId);
+        const connection = parseWalletConnection((await this.#transport.write(`/v1/wallet-connections/${connectionId}`, 'DELETE', undefined, signal)).payload);
+        if (connection.id !== connectionId || connection.state !== 'revoked')
+            fault();
+        return connection;
+    }
+    async list(signal) {
+        return parseLinkedWalletList(await this.#transport.get('/v1/linked-wallets', signal));
+    }
+    async wallet(linkedWalletId, signal) {
+        requestUUID(linkedWalletId);
+        const root = record(await this.#transport.get(`/v1/linked-wallets/${linkedWalletId}`, signal), ['request_id', 'wallet']);
+        if (!opaqueId(root.request_id))
+            fault();
+        const wallet = parseLinkedWallet(root.wallet);
+        if (wallet.id !== linkedWalletId)
+            fault();
+        return { requestId: root.request_id, wallet };
+    }
+    /** Every metadata page is fresh; restart at the beginning to discover earlier insertions. */
+    async registrations(linkedWalletId, options = {}) {
+        const path = linkedRegistrationsPath(linkedWalletId, options);
+        const page = parseLinkedStreamsRegistrationList(await this.#transport.get(path, options.signal), linkedWalletId);
+        if (page.items.length > (options.limit ?? 50) || (options.afterRegistrationId !== undefined && page.items.some(item => item.registrationId <= options.afterRegistrationId)))
+            fault();
+        return page;
+    }
+    /**
+     * One page of the linked wallet's retained events as wallet events 3.0:
+     * what came in, what went out and what else happened, each with kind,
+     * status and revision, those of the kinds eventTypes names. Continuations
+     * are sealed opaque cursors.
+     */
+    async events(linkedWalletId, options = {}) {
+        return parseWalletEventPage(await this.#transport.get(linkedEventsPath(linkedWalletId, options), options.signal));
+    }
+    /**
+     * Opens one signal stream for these linked wallets and reads it to its end.
+     * onOpen says the stream is live: read every wallet once then. onWallets
+     * names wallets with new events: read them with events(). The promise
+     * resolves with the reason the stream ended; a stream lives no longer than
+     * an access token, so the caller opens the next one. It rejects with the
+     * server's refusal, with the abort reason, or when the connection fails;
+     * keep an ordinary timed read for those times.
+     */
+    async signals(linkedWalletIds, handlers) {
+        const body = await this.#transport.stream(linkedSignalsPath(linkedWalletIds), handlers.signal);
+        return readLinkedWalletSignals(body, linkedWalletIds, handlers);
+    }
+    async createRegistration(create, idempotencyKey, signal) {
+        validateLinkedRegistrationCreate(create, this.#transport.accountId());
+        requestID(idempotencyKey);
+        const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
+        const operation = parseLinkedRegistrationOperationEnvelope(payload).operation;
+        if (operation.ownerId !== accountId || operation.linkedWalletId !== create.linked_wallet_id)
+            fault();
+        return operation;
+    }
+    /**
+     * Starts tracking a linked wallet on one network. An EVM wallet has one
+     * address on every EVM network, so it is registered on each of them with its
+     * own call. activityTypes names the kinds of activity events asked for beside
+     * deposits; omitted or empty means deposits only, and Streams refuses a kind
+     * the network does not have. The operation comes back authorized;
+     * executeRegistration() with its version dispatches it.
+     */
+    register(input, idempotencyKey, signal) {
+        record(input, ['linkedWalletId', 'network'], ['assets', 'activityTypes']);
+        const create = { kind: 'streams.register', owner_type: 'account', owner_id: this.#transport.accountId(), linked_wallet_id: input.linkedWalletId, payload: { network: input.network } };
+        if (input.assets !== undefined)
+            create.payload.assets = input.assets;
+        // An empty selection means deposits only and is not sent; any other value is checked with the whole request.
+        if (input.activityTypes !== undefined && !(Array.isArray(input.activityTypes) && input.activityTypes.length === 0))
+            create.payload.activity_types = input.activityTypes;
+        return this.createRegistration(create, idempotencyKey, signal);
+    }
+    async operation(operationId, signal) {
+        requestID(operationId);
+        const operation = parseLinkedRegistrationOperationEnvelope(await this.#transport.get(`/v1/operations/${operationId}`, signal)).operation;
+        if (operation.id !== operationId)
+            fault();
+        return operation;
+    }
+    async executeRegistration(operationId, version, idempotencyKey, signal) {
+        requestID(operationId);
+        requestID(idempotencyKey);
+        if (!canonicalDecimal(version))
+            throw new ClientFlowError('invalid_execute_request');
+        const operation = parseLinkedRegistrationOperationEnvelope((await this.#transport.write(`/v1/operations/${operationId}/execute`, 'POST', undefined, signal, idempotencyKey, version)).payload).operation;
+        if (operation.id !== operationId)
+            fault();
+        return operation;
+    }
+    async registrationResult(operationId, signal) {
+        requestID(operationId);
+        return parseLinkedRegistrationResult(await this.#transport.get(`/v1/operations/${operationId}/result`, signal), operationId);
+    }
+    /**
+     * Starts a send from a linked wallet. The account's session authorizes it:
+     * the operation comes back authorized (authorizationBasis
+     * session_authorized), with no passkey and no confirmation window. Then
+     * prepare() has the own-wallet system prepare the transfer and name its
+     * fee; show the owner what was prepared and, on their confirm,
+     * executeSend() with the device share.
+     */
+    async send(input, idempotencyKey, signal) {
+        const declared = record(input, ['linkedWalletId', 'network', 'asset', 'recipient', 'amountRaw'], ['comment']);
+        requestID(idempotencyKey);
+        if (!uuid(declared.linkedWalletId) || !network(declared.network) || !linkedSendAsset(declared.asset) || typeof declared.recipient !== 'string' || !/^[\x21-\x7e]{1,256}$/.test(declared.recipient) ||
+            !canonicalDecimal(declared.amountRaw) || declared.amountRaw === '0' || declared.amountRaw.length > 78 ||
+            // Only a TON transfer carries a comment.
+            (declared.comment !== undefined && (!transferComment(declared.comment) || !declared.network.startsWith('ton:'))))
+            throw new ClientFlowError('invalid_operation_create');
+        const sent = { network: declared.network, asset: declared.asset, recipient: declared.recipient, amount_raw: declared.amountRaw };
+        if (declared.comment !== undefined)
+            sent.comment = declared.comment;
+        const create = { kind: 'wallet.send', owner_type: 'account', owner_id: this.#transport.accountId(), linked_wallet_id: declared.linkedWalletId, payload: sent };
+        const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
+        const operation = parseUserWalletOperationEnvelope(payload).operation;
+        const shown = operation.display;
+        if (operation.kind !== 'wallet.send' || operation.ownerId !== accountId || operation.linkedWallet?.linkedWalletId !== declared.linkedWalletId ||
+            shown.asset !== declared.asset || shown.comment !== declared.comment)
+            fault();
+        return operation;
+    }
+    /**
+     * Replaces a send the own-wallet system broadcast on an EVM network and the
+     * network has not included: "speed_up" sends the same transfer again with a
+     * higher fee, "cancel" sends nothing to the wallet's own address in its
+     * place. The answer is a send of its own, authorized by the session like
+     * send(): prepare() has the own-wallet system prepare the replacement (it
+     * may answer that the transfer no longer waits), show it with its new fee,
+     * and on the owner's confirm executeSend(). Whichever of the two
+     * transactions the network includes, the other fails; read
+     * transferStatus() of both.
+     */
+    async replaceSend(input, idempotencyKey, signal) {
+        const declared = record(input, ['linkedWalletId', 'operationId', 'action']);
+        requestID(idempotencyKey);
+        if (!uuid(declared.linkedWalletId) || !opaqueId(declared.operationId) || !replaceAction(declared.action))
+            throw new ClientFlowError('invalid_operation_create');
+        const create = { kind: 'wallet.send', owner_type: 'account', owner_id: this.#transport.accountId(), linked_wallet_id: declared.linkedWalletId,
+            payload: { action: declared.action, replaces_operation_id: declared.operationId } };
+        const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
+        const operation = parseUserWalletOperationEnvelope(payload).operation;
+        const shown = operation.display;
+        if (operation.kind !== 'wallet.send' || operation.ownerId !== accountId || operation.linkedWallet?.linkedWalletId !== declared.linkedWalletId ||
+            shown.replacesOperationId !== declared.operationId || shown.replaceAction !== declared.action)
+            fault();
+        return operation;
+    }
+    /**
+     * What the wallet holds on each of its networks: the coin and the tokens
+     * the stand names there, in minimal units with their decimals. The provider
+     * reads its own stand's nodes. A network whose node gave no amount is in
+     * the answer with its status and without amounts; it fails nothing.
+     */
+    async balances(linkedWalletId, signal) {
+        requestUUID(linkedWalletId);
+        return parseLinkedWalletBalances(await this.#transport.get(`/v1/linked-wallets/${linkedWalletId}/balances`, signal), linkedWalletId);
+    }
+    /**
+     * Has the own-wallet system prepare the transfer of a send or replacement
+     * the session authorized, and returns the send with what was prepared:
+     * display.preparedSummary, the sending address and the fee estimate. Show
+     * them to the owner; executeSend() sends exactly that transfer. The
+     * transfer is prepared once: calling again returns the same prepared send
+     * and asks the own-wallet system nothing. A prepared send expires within
+     * 150 seconds; one that expired is sent again from send(). The request
+     * carries no body, idempotency key or version.
+     */
+    async prepare(operationId, signal) {
+        requestID(operationId);
+        const operation = parseUserWalletOperationEnvelope((await this.#transport.write(`/v1/operations/${operationId}/prepare`, 'POST', undefined, signal)).payload).operation;
+        if (operation.id !== operationId || operation.kind !== 'wallet.send' || operation.linkedWallet === undefined)
+            fault();
+        return operation;
+    }
+    /** The key the device seals its share to, read right before executeSend(). */
+    async transportKey(linkedWalletId, signal) {
+        requestUUID(linkedWalletId);
+        const r = record(await this.#transport.get(`/v1/linked-wallets/${linkedWalletId}/transport-key`, signal), ['request_id', 'public_key', 'encryption_algorithm']);
+        if (!opaqueId(r.request_id) || typeof r.public_key !== 'string' || !/^(0[23][0-9a-f]{64}|04[0-9a-f]{128})$/.test(r.public_key) || typeof r.encryption_algorithm !== 'string' || !/^[a-z0-9_-]{1,128}$/.test(r.encryption_algorithm))
+            fault();
+        return { requestId: r.request_id, publicKey: r.public_key, encryptionAlgorithm: r.encryption_algorithm };
+    }
+    /**
+     * Executes a prepared send, on the owner's confirm, with the device share
+     * resealed for the own-wallet system. Without deviceShare the SDK supplies
+     * the share it keeps (deviceShareFor()), recovered first with one passkey
+     * confirmation when this browser holds none; an app that keeps its own share
+     * passes it resealed (resealDeviceShare). The provider cannot open the share.
+     * A send never prepared is refused with VERSION_CONFLICT, an expired one
+     * with OPERATION_EXPIRED.
+     */
+    async executeSend(operationId, version, idempotencyKey, deviceShare, signal) {
+        requestID(operationId);
+        requestID(idempotencyKey);
+        if (!canonicalDecimal(version))
+            throw new ClientFlowError('invalid_execute_request');
+        if (deviceShare === undefined) {
+            const linkedWalletId = parseUserWalletOperationEnvelope(await this.#transport.get(`/v1/operations/${operationId}`, signal)).operation.linkedWallet?.linkedWalletId;
+            if (linkedWalletId === undefined)
+                throw new ClientFlowError('invalid_execute_request');
+            deviceShare = await this.deviceShareFor(linkedWalletId, signal);
+        }
+        const share = record(deviceShare, ['ciphertext', 'nonce', 'ephemeralPublicKey', 'encryptionAlgorithm', 'encryptionContext']);
+        if (![share.ciphertext, share.nonce, share.ephemeralPublicKey, share.encryptionContext].every(hex) || typeof share.encryptionAlgorithm !== 'string')
+            throw new ClientFlowError('invalid_execute_request');
+        const body = { device_share: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeral_public_key: share.ephemeralPublicKey, encryption_algorithm: share.encryptionAlgorithm, encryption_context: share.encryptionContext } };
+        const operation = parseUserWalletOperationEnvelope((await this.#transport.write(`/v1/operations/${operationId}/execute`, 'POST', body, signal, idempotencyKey, version)).payload).operation;
+        if (operation.id !== operationId)
+            fault();
+        return operation;
+    }
+    /**
+     * The device share the SDK keeps for this wallet, resealed to the
+     * own-wallet system's transport key read right before: what executeSend()
+     * sends and what a Mode C request is signed with (signLinkedMediatedRequest).
+     * A browser that holds no share of the wallet (another domain, cleared site
+     * data, another browser or device) recovers it first: the person confirms
+     * once with the passkey on the provider's page, and the share the wallet had
+     * elsewhere stops working. Two tabs never recover the same wallet at once.
+     */
+    async deviceShareFor(linkedWalletId, signal) {
+        return this.#sealedTo(linkedWalletId, async () => (await this.transportKey(linkedWalletId, signal)).publicKey, signal);
+    }
+    /** The kept share, recovered first when this browser holds none (with recover false: refused), resealed to the key read right before. */
+    async #sealedTo(linkedWalletId, publicKey, signal, recover = true) {
+        const devices = this.#devices();
+        const { wallet } = await this.wallet(linkedWalletId, signal);
+        if (recover)
+            await devices.ensure(wallet, this.#serverKey(linkedWalletId, signal), { signal });
+        else if (!(await devices.has(wallet, this.#serverKey(linkedWalletId, signal))))
+            throw new ClientFlowError('device_share_unavailable');
+        return devices.sealedFor(wallet, await publicKey());
+    }
+    /**
+     * The device key of the wallet's latest creation or recovery the provider
+     * made, as 33-byte compressed hex; absent when it knows none. A share kept
+     * here that is sealed to another key was replaced by a recovery elsewhere.
+     */
+    async deviceKey(linkedWalletId, signal) {
+        requestUUID(linkedWalletId);
+        const r = record(await this.#transport.get(`/v1/linked-wallets/${linkedWalletId}/device-key`, signal), ['request_id'], ['device_public_key']);
+        if (!opaqueId(r.request_id) || (r.device_public_key !== undefined && (typeof r.device_public_key !== 'string' || !/^0[23][0-9a-f]{64}$/.test(r.device_public_key))))
+            fault();
+        return r.device_public_key === undefined ? { requestId: r.request_id } : { requestId: r.request_id, devicePublicKey: r.device_public_key };
+    }
+    /** Whether this browser holds a current device share of the wallet; without one the next send recovers it with the passkey. */
+    async hasDeviceShare(linkedWalletId, signal) {
+        const devices = this.#devices();
+        return devices.has((await this.wallet(linkedWalletId, signal)).wallet, this.#serverKey(linkedWalletId, signal));
+    }
+    /**
+     * Recovers the wallet's device share onto this browser when it holds no
+     * current one, as deviceShareFor() would, for an app that does it ahead of a
+     * transfer; force recovers even then. credentialId names the passkey that
+     * confirms it, by default the account's newest. Answers whether a recovery
+     * ran. Optional: sends recover by themselves.
+     */
+    async recoverDevice(linkedWalletId, options = {}) {
+        const devices = this.#devices();
+        return devices.ensure((await this.wallet(linkedWalletId, options.signal)).wallet, this.#serverKey(linkedWalletId, options.signal), options);
+    }
+    #serverKey(linkedWalletId, signal) {
+        return async () => (await this.deviceKey(linkedWalletId, signal)).devicePublicKey;
+    }
+    #devices() {
+        if (!this.#transport.devices)
+            throw new ClientFlowError('device_share_unavailable');
+        return this.#transport.devices;
+    }
+    /**
+     * What became of the transfer a send prepared: on its way, confirmed by the
+     * network, or failed and why. The send's operation succeeds when the
+     * own-wallet system accepted the transfer; this is what the network did
+     * with it. Read it until final is true. Before the send was prepared
+     * there is no transfer and the read is refused with NOT_FOUND.
+     */
+    async transferStatus(operationId, signal) {
+        return parseTransferStatus(await this.#transport.get(transferStatusPath(operationId), signal), operationId);
+    }
+    /**
+     * One page of the account's send history, newest first: every wallet.send
+     * the account can read, with its transaction hash and the recorded final
+     * fate of its transfer. A send with a hash and no transfer has not been
+     * reported final yet: read transferStatus() for it, which records the fate.
+     * The cursor carries the first page's limit.
+     */
+    async sends(options) {
+        const { path, signal } = sendsPath(options);
+        return parseSendPage(await this.#transport.get(path, signal));
+    }
+    /** The limits every send from the wallet obeys, read with the session (walletLimits.ts). Revision "0": never set. */
+    async limits(linkedWalletId, signal) {
+        requestUUID(linkedWalletId);
+        return parseWalletLimits(await this.#transport.get(`/v1/linked-wallets/${linkedWalletId}/limits`, signal), linkedWalletId);
+    }
+    /**
+     * Asks to replace the wallet's limits as a whole; empty ceilings and recipients remove them all. The operation
+     * awaits the owner's passkey: the client's challengeOperation(), completeOperationConfirmation() and
+     * executeOperation() apply it. A send the limits refuse answers one of WalletLimitRefusals.
+     */
+    async setLimits(linkedWalletId, limits, idempotencyKey, signal) {
+        const create = walletLimitsCreate(this.#transport.accountId(), linkedWalletId, limits);
+        requestID(idempotencyKey);
+        const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
+        const operation = parseOperationEnvelope(payload).operation;
+        if (operation.display.kind !== 'wallet_limits.set' || operation.ownerId !== accountId || operation.display.linkedWalletId !== linkedWalletId)
+            fault();
+        return operation;
+    }
+    /** The permissions the account lets services debit its linked wallets by, without the device (debitPermissions.ts). */
+    debitPermissions() { return new DebitPermissions(this.#transport, (linkedWalletId, keeperKey, signal, recover) => this.#sealedTo(linkedWalletId, async () => keeperKey, signal, recover)); }
+}
+export function parseWalletConnection(payload) {
+    const r = record(payload, ['request_id', 'id', 'connector_id', 'state', 'created_at', 'last_synced_at'], ['revoked_at']);
+    if (!opaqueId(r.request_id) || !uuid(r.id) || !opaqueId(r.connector_id) || !['connected', 'revoked', 'reauth_required'].includes(r.state) || !rfc3339UTC(r.created_at) || !rfc3339UTC(r.last_synced_at) || (r.state === 'revoked') !== (r.revoked_at !== undefined) || (r.revoked_at !== undefined && !rfc3339UTC(r.revoked_at)))
+        fault();
+    const out = { requestId: r.request_id, id: r.id, connectorId: r.connector_id, state: r.state, createdAt: r.created_at, lastSyncedAt: r.last_synced_at };
+    if (r.revoked_at !== undefined)
+        out.revokedAt = r.revoked_at;
+    return Object.freeze(out);
+}
+export function parseLinkedWallet(payload) {
+    const r = record(payload, ['id', 'connection_id', 'external_wallet_id', 'external_key_id', 'network', 'address', 'algorithm', 'public_key', 'binding_revision', 'status', 'observed_at']);
+    if (![r.id, r.connection_id, r.external_wallet_id, r.external_key_id].every(uuid) || !text(r.network, 64) || !text(r.address, 256) || !safeRevision(r.binding_revision) || !['active', 'inactive'].includes(r.status) || !rfc3339UTC(r.observed_at) || !publicKey(r.algorithm, r.public_key))
+        fault();
+    return Object.freeze({ id: r.id, connectionId: r.connection_id, externalWalletId: r.external_wallet_id, externalKeyId: r.external_key_id, network: r.network, address: r.address, algorithm: r.algorithm, publicKey: r.public_key, bindingRevision: r.binding_revision, status: r.status, observedAt: r.observed_at });
+}
+export function parseLinkedWalletList(payload) {
+    const r = record(payload, ['request_id', 'items']);
+    if (!opaqueId(r.request_id) || !Array.isArray(r.items) || r.items.length > 1000)
+        fault();
+    const items = r.items.map(parseLinkedWallet);
+    if (items.some(w => w.status !== 'active') || new Set(items.map(w => w.id)).size !== items.length)
+        fault();
+    return { requestId: r.request_id, items: Object.freeze(items) };
+}
+export function parseWalletLinkChallenge(payload, now) {
+    const r = record(payload, ['request_id', 'challenge_id', 'expires_at', 'public_key']);
+    const p = record(r.public_key, ['allow_credentials', 'challenge', 'rp_id', 'timeout_ms', 'user_verification']);
+    if (!opaqueId(r.request_id) || !uuid(r.challenge_id) || !unexpiredRFC3339(r.expires_at, now) || !b64(p.challenge) || !text(p.rp_id, 253) || !integer(p.timeout_ms) || p.timeout_ms < 1 || p.timeout_ms > 300000 || p.user_verification !== 'required' || !Array.isArray(p.allow_credentials) || p.allow_credentials.length !== 1)
+        fault();
+    const c = record(p.allow_credentials[0], ['id', 'type']);
+    if (c.type !== 'public-key' || !b64(c.id))
+        fault();
+    return { requestId: r.request_id, challengeId: r.challenge_id, expiresAt: r.expires_at, publicKey: { challenge: p.challenge, rpId: p.rp_id, timeoutMs: p.timeout_ms, userVerification: 'required', allowCredentials: [{ id: c.id, type: 'public-key' }] } };
+}
+export function validateWalletLinkAssertion(value) {
+    const r = record(value, ['id', 'rawId', 'type', 'response']);
+    const p = record(r.response, ['clientDataJSON', 'authenticatorData', 'signature', 'userHandle']);
+    if (r.type !== 'public-key' || !b64(r.id) || r.rawId !== r.id || ![p.clientDataJSON, p.authenticatorData, p.signature].every(b64) || (p.userHandle !== '' && !b64(p.userHandle)))
+        throw new ClientFlowError('invalid_linked_wallet_request');
+    return value;
+}

package/dist/me.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One wallet of the account: "wallet" is a wallet the provider created,
+ * "linked_wallet" one its owner connected, and walletId is an identifier of
+ * that kind. A listed linked wallet is active; an own wallet is active or
+ * disabled.
+ */
+export interface MeWallet {
+    walletId: string;
+    kind: "wallet" | "linked_wallet";
+    network: string;
+    address: string;
+    state: "active" | "disabled";
+}
+export interface MeProjection {
+    requestId: string;
+    account: {
+        accountId: string;
+        version: string;
+        setupRequired: boolean;
+    };
+    sessionId: string;
+    serverTime: number;
+    /** Every wallet of the account, own then linked, at most 1000 of each kind. */
+    wallets: MeWallet[];
+}
+/** parseMeProjection reads exactly one `/v1/me` answer. */
+export declare function parseMeProjection(payload: unknown): MeProjection;

package/dist/me.js

@@ -0,0 +1,30 @@
+/**
+ * The live `/v1/me` projection: the current account, the session, the server
+ * time and every wallet of the account. It is read as strictly as every
+ * other answer: an unknown member, a missing one or a value outside its
+ * closed form refuses the whole answer.
+ */
+import { ClientFlowError, canonicalDecimal, integer, opaqueId, record } from "./auth.js";
+/** The most wallets of one kind an account lists; the answer holds two kinds. */
+const maxWalletsPerKind = 1000;
+/** parseMeProjection reads exactly one `/v1/me` answer. */
+export function parseMeProjection(payload) {
+    const root = record(payload, ["request_id", "account", "session_id", "server_time", "wallets"]);
+    const account = record(root.account, ["account_id", "version", "setup_required"]);
+    if (!opaqueId(root.request_id) || !opaqueId(account.account_id) || !canonicalDecimal(account.version) || typeof account.setup_required !== "boolean" || !opaqueId(root.session_id) || !integer(root.server_time) ||
+        !Array.isArray(root.wallets) || root.wallets.length > 2 * maxWalletsPerKind) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const wallets = root.wallets.map((value) => {
+        const item = record(value, ["wallet_id", "kind", "network", "address", "state"]);
+        if (!opaqueId(item.wallet_id) || (item.kind !== "wallet" && item.kind !== "linked_wallet") || typeof item.network !== "string" || item.network === "" ||
+            typeof item.address !== "string" || item.address === "" || item.address.length > 256 || (item.state !== "active" && item.state !== "disabled")) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        return { walletId: item.wallet_id, kind: item.kind, network: item.network, address: item.address, state: item.state };
+    });
+    if (wallets.filter((wallet) => wallet.kind === "wallet").length > maxWalletsPerKind || wallets.filter((wallet) => wallet.kind === "linked_wallet").length > maxWalletsPerKind) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return { requestId: root.request_id, account: { accountId: account.account_id, version: account.version, setupRequired: account.setup_required }, sessionId: root.session_id, serverTime: root.server_time, wallets };
+}

package/dist/mediatedOperation.d.ts

@@ -0,0 +1,27 @@
+import { type MediatedLinkedSendDisplay } from "./linkedSendDisplay.ts";
+import type { UserWalletOperation } from "./walletOperations.ts";
+export type { MediatedLinkedSendDisplay } from "./linkedSendDisplay.ts";
+/** The display of a Mode C transfer from a wallet bound in the provider: the network coin only. */
+export interface MediatedSendDisplay {
+    kind: "wallet.send";
+    ownerId: string;
+    requesterId: string;
+    walletId: string;
+    network: string;
+    asset: "native";
+    recipient: string;
+    amountRaw: string;
+    maxFeeRaw: string;
+    preparedSummary?: string;
+}
+/** A Mode C transfer past its material retention: its identity only; a linked wallet stays named by the operation's linkedWallet. */
+export interface MediatedPurgedDisplay {
+    kind: "wallet.send";
+    materialPurged: true;
+    ownerId: string;
+    requesterId: string;
+    walletId?: string;
+}
+export type MediatedDisplay = MediatedSendDisplay | MediatedLinkedSendDisplay | MediatedPurgedDisplay;
+/** parseMediatedOperation reads exactly the mediated status of one Mode C send. */
+export declare function parseMediatedOperation(payload: unknown): UserWalletOperation;

package/dist/mediatedOperation.js

@@ -0,0 +1,68 @@
+// The status of a Mode C send as its owner reads it: a transfer a service
+// forwarded on the person's signed request (authorization basis
+// user_request_signed), from a wallet bound in the provider or from the
+// person's linked wallet. The provider projects it as the mediated status on
+// every route, the owner's GET of the operation and the account's send
+// history included: it freezes no result recipient, and a linked transfer
+// names its wallet by binding_source, connection_id, linked_wallet_id and
+// binding_revision instead of wallet_id.
+import { ClientFlowError, canonicalDecimal, deadlineAfter, isNextAction, opaqueId, record, rfc3339UTC } from "./auth.js";
+import { bindingRevision, lowerUUID, rawQuantity, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+import { parseMediatedLinkedSendDisplay } from "./linkedSendDisplay.js";
+const states = ["authorized", "dispatching", "outcome_unknown", "succeeded", "failed", "denied", "canceled", "expired"];
+const ownNetwork = /^[A-Za-z0-9_.-]{1,64}$/;
+const digest = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+const fault = () => { throw new ClientFlowError("invalid_server_response"); };
+/** parseMediatedOperation reads exactly the mediated status of one Mode C send. */
+export function parseMediatedOperation(payload) {
+    const r = record(payload, ["authorization_basis", "created_at", "display", "effect_state", "expires_at", "id", "kind", "next_action", "operation_fingerprint", "owner_id", "owner_type",
+        "request_fingerprint", "requester_id", "state", "version"], ["result_kind", "wallet_id", "binding_source", "connection_id", "linked_wallet_id", "binding_revision"]);
+    if (r.authorization_basis !== "user_request_signed" || r.kind !== "wallet.send" || r.owner_type !== "account" || !opaqueId(r.id) || !canonicalDecimal(r.version) ||
+        !opaqueId(r.owner_id) || !opaqueId(r.requester_id) || typeof r.state !== "string" || !states.includes(r.state) || !["no_effect", "possible", "known"].includes(r.effect_state) ||
+        !digest(r.request_fingerprint) || !digest(r.operation_fingerprint) || !rfc3339UTC(r.created_at) || !rfc3339UTC(r.expires_at) || !deadlineAfter(r.created_at, r.expires_at) ||
+        !isNextAction(r.next_action) || (r.result_kind !== undefined && r.result_kind !== "transfer_receipt"))
+        fault();
+    // A linked transfer is named by all of its linked identity and never beside a wallet_id.
+    const linked = r.binding_source !== undefined;
+    if (linked ? (r.binding_source !== "linked_wallet" || r.wallet_id !== undefined || !lowerUUID(r.connection_id) || !lowerUUID(r.linked_wallet_id) || !bindingRevision(r.binding_revision))
+        : (!opaqueId(r.wallet_id) || r.connection_id !== undefined || r.linked_wallet_id !== undefined || r.binding_revision !== undefined))
+        fault();
+    const display = mediatedDisplay(r.display, r, linked);
+    const operation = {
+        id: r.id, version: r.version, kind: "wallet.send", state: r.state, effectState: r.effect_state,
+        authorizationBasis: "user_request_signed", ownerType: "account", ownerId: r.owner_id, requesterId: r.requester_id,
+        requestFingerprint: r.request_fingerprint, operationFingerprint: r.operation_fingerprint, display,
+        createdAt: r.created_at, expiresAt: r.expires_at, nextAction: r.next_action,
+    };
+    if (linked)
+        operation.linkedWallet = { connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision };
+    else
+        operation.walletId = r.wallet_id;
+    if (r.result_kind !== undefined)
+        operation.resultKind = "transfer_receipt";
+    return operation;
+}
+function mediatedDisplay(value, r, linked) {
+    if (value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "material_purged")) {
+        const d = record(value, ["kind", "material_purged", "owner_id", "requester_id"], [linked ? "linked_wallet_id" : "wallet_id"]);
+        const own = linked ? d.linked_wallet_id === r.linked_wallet_id : d.wallet_id === r.wallet_id;
+        if (d.kind !== "wallet.send" || d.material_purged !== true || d.owner_id !== r.owner_id || d.requester_id !== r.requester_id || !own)
+            fault();
+        const purged = { kind: "wallet.send", materialPurged: true, ownerId: d.owner_id, requesterId: d.requester_id };
+        if (!linked)
+            purged.walletId = d.wallet_id;
+        return purged;
+    }
+    if (linked) {
+        const d = parseMediatedLinkedSendDisplay(value);
+        if (d.ownerId !== r.owner_id || d.requesterId !== r.requester_id || d.linkedWalletId !== r.linked_wallet_id || d.connectionId !== r.connection_id || d.bindingRevision !== r.binding_revision)
+            fault();
+        return d;
+    }
+    const d = record(value, ["amount_raw", "asset", "kind", "max_fee_raw", "network", "owner_id", "recipient", "requester_id", "wallet_id"], ["prepared_summary"]);
+    if (d.kind !== "wallet.send" || d.asset !== "native" || !rawQuantity(d.amount_raw, true) || !rawQuantity(d.max_fee_raw, false) || typeof d.network !== "string" || !ownNetwork.test(d.network) ||
+        typeof d.recipient !== "string" || !walletRecipient.test(d.recipient) || d.owner_id !== r.owner_id || d.requester_id !== r.requester_id || d.wallet_id !== r.wallet_id)
+        fault();
+    return { kind: "wallet.send", ownerId: d.owner_id, requesterId: d.requester_id, walletId: d.wallet_id, network: d.network, asset: "native",
+        recipient: d.recipient, amountRaw: d.amount_raw, maxFeeRaw: d.max_fee_raw, ...summaryOf(d.prepared_summary) };
+}