@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/linkedWallets.js

@@ -0,0 +1,471 @@
+// 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, deadlineAfter, integer, isNextAction, opaqueId, record, rfc3339UTC, unexpiredRFC3339 } from './auth.js';
+import { appendEventTypes, parseWalletEventPage, MaxStreamsActivityTypes, MaxStreamsCursorLength, MaxStreamsPageLimit } from './streams.js';
+export { resumeCursor } from './streams.js';
+import { parseOperationEnvelope } from './slice4.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 { activityTypes, assets, b64, digest, fault, hex, https, network, publicKey, recipient, 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', 'resultRecipient']);
+        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;
+        if (input.resultRecipient !== undefined)
+            create.result_recipient = input.resultRecipient;
+        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', 'resultRecipient']);
+        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 };
+        if (declared.resultRecipient !== undefined)
+            create.result_recipient = recipient(declared.resultRecipient);
+        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'], ['resultRecipient']);
+        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 } };
+        if (declared.resultRecipient !== undefined)
+            create.result_recipient = recipient(declared.resultRecipient);
+        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 (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);
+        const share = record(deviceShare, ['ciphertext', 'nonce', 'ephemeralPublicKey', 'encryptionAlgorithm', 'encryptionContext']);
+        if (!canonicalDecimal(version) || ![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;
+    }
+    /**
+     * 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;
+    }
+}
+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;
+}
+export function validateLinkedRegistrationCreate(value, ownerId) {
+    const r = record(value, ['kind', 'owner_type', 'owner_id', 'linked_wallet_id', 'payload'], ['result_recipient']);
+    const p = record(r.payload, ['network'], ['assets', 'activity_types']);
+    if (r.kind !== 'streams.register' || r.owner_type !== 'account' || !opaqueId(r.owner_id) || r.owner_id !== ownerId || !uuid(r.linked_wallet_id) || !network(p.network) || (p.assets !== undefined && !assets(p.assets)) || (p.activity_types !== undefined && !activityTypes(p.activity_types)))
+        throw new ClientFlowError('invalid_operation_create');
+    if (r.result_recipient !== undefined)
+        recipient(r.result_recipient);
+    return value;
+}
+export function parseLinkedRegistrationOperationEnvelope(payload) {
+    const r = record(payload, ['request_id', 'operation']);
+    if (!opaqueId(r.request_id))
+        fault();
+    return { requestId: r.request_id, operation: parseLinkedRegistrationOperation(r.operation) };
+}
+export function parseLinkedRegistrationOperation(payload) {
+    const r = record(payload, ['id', 'version', 'kind', 'state', 'effect_state', 'authorization_basis', 'owner_type', 'owner_id', 'requester_id', 'binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'request_fingerprint', 'operation_fingerprint', 'display', 'created_at', 'expires_at', 'next_action'], ['confirmation_location']);
+    if (!opaqueId(r.id) || !canonicalDecimal(r.version) || r.kind !== 'streams.register' || r.owner_type !== 'account' || !opaqueId(r.owner_id) || !opaqueId(r.requester_id) || r.binding_source !== 'linked_wallet' || !uuid(r.connection_id) || !uuid(r.linked_wallet_id) || !safeRevision(r.binding_revision) || !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) || !['awaiting_confirmation', 'authorized', 'dispatching', 'outcome_unknown', 'succeeded', 'failed', 'denied', 'canceled', 'expired'].includes(r.state) || !['no_effect', 'possible', 'known'].includes(r.effect_state) || !['', 'user_confirmed', 'session_authorized'].includes(r.authorization_basis) || (r.confirmation_location !== undefined && !https(r.confirmation_location)))
+        fault();
+    const purged = typeof r.display === 'object' && r.display !== null && 'material_purged' in r.display;
+    const d = record(r.display, ['kind', 'owner_id', 'requester_id', 'result_recipient', ...(purged ? ['material_purged'] : ['binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'assets', 'network', 'address', 'streams_mapping_id', 'streams_mapping_version', 'target_customer_id', 'target_project_id', 'target_environment_id'])]);
+    if (d.kind !== r.kind || d.owner_id !== r.owner_id || d.requester_id !== r.requester_id)
+        fault();
+    const common = { kind: 'streams.register', ownerId: r.owner_id, requesterId: r.requester_id, resultRecipient: recipient(d.result_recipient) };
+    let display;
+    if (purged) {
+        if (d.material_purged !== true)
+            fault();
+        display = { ...common, materialPurged: true };
+    }
+    else {
+        if (d.binding_source !== r.binding_source || d.connection_id !== r.connection_id || d.linked_wallet_id !== r.linked_wallet_id || d.binding_revision !== r.binding_revision || !assets(d.assets) || !network(d.network) || !text(d.address, 256) || !safeRevision(d.streams_mapping_version) || ![d.streams_mapping_id, d.target_customer_id, d.target_project_id, d.target_environment_id].every(opaqueId))
+            fault();
+        display = { ...common, bindingSource: 'linked_wallet', connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision, assets: Object.freeze([...d.assets]), network: d.network, address: d.address, streamsMappingId: d.streams_mapping_id, streamsMappingVersion: d.streams_mapping_version, targetCustomerId: d.target_customer_id, targetProjectId: d.target_project_id, targetEnvironmentId: d.target_environment_id };
+    }
+    const operation = { id: r.id, version: r.version, kind: 'streams.register', state: r.state, effectState: r.effect_state, authorizationBasis: r.authorization_basis, ownerType: 'account', ownerId: r.owner_id, requesterId: r.requester_id, bindingSource: 'linked_wallet', connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision, requestFingerprint: r.request_fingerprint, operationFingerprint: r.operation_fingerprint, display, createdAt: r.created_at, expiresAt: r.expires_at, nextAction: r.next_action };
+    if (r.confirmation_location !== undefined)
+        operation.confirmationLocation = r.confirmation_location;
+    return operation;
+}
+export function parseLinkedRegistrationResult(payload, operationId) {
+    const r = record(payload, ['request_id', 'result']);
+    const v = record(r.result, ['kind', 'operation_id', 'binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'source_registration_id', 'registration_digest', 'receipt_id']);
+    if (!opaqueId(r.request_id) || !opaqueId(v.operation_id) || v.operation_id !== operationId || v.kind !== 'streams_registration' || v.binding_source !== 'linked_wallet' || !uuid(v.connection_id) || !uuid(v.linked_wallet_id) || !safeRevision(v.binding_revision) || !text(v.source_registration_id, 128) || !text(v.receipt_id, 128) || !digest(v.registration_digest))
+        fault();
+    return { requestId: r.request_id, result: { kind: 'streams_registration', operationId: v.operation_id, bindingSource: 'linked_wallet', connectionId: v.connection_id, linkedWalletId: v.linked_wallet_id, bindingRevision: v.binding_revision, sourceRegistrationId: v.source_registration_id, registrationDigest: v.registration_digest, receiptId: v.receipt_id } };
+}
+export function linkedRegistrationsPath(linkedWalletId, options = {}) {
+    requestUUID(linkedWalletId);
+    const declared = record(options, [], ['afterRegistrationId', 'limit', 'signal']);
+    const query = new URLSearchParams();
+    if (declared.afterRegistrationId !== undefined) {
+        requestUUID(declared.afterRegistrationId);
+        query.set('after_registration_id', declared.afterRegistrationId);
+    }
+    readLimit(query, declared.limit);
+    return linkedReadPath(linkedWalletId, 'registrations', query);
+}
+export function linkedEventsPath(linkedWalletId, options = {}) {
+    requestUUID(linkedWalletId);
+    const declared = record(options, [], ['registrationId', 'cursor', 'limit', 'eventTypes', 'signal']);
+    const query = new URLSearchParams();
+    if (declared.registrationId !== undefined) {
+        requestUUID(declared.registrationId);
+        query.set('registration_id', declared.registrationId);
+    }
+    if (declared.cursor !== undefined) {
+        if (typeof declared.cursor !== 'string' || declared.cursor.length < 1 || declared.cursor.length > MaxStreamsCursorLength)
+            throw new ClientFlowError('invalid_streams_request');
+        query.set('cursor', declared.cursor);
+    }
+    readLimit(query, declared.limit);
+    appendEventTypes(query, declared.eventTypes);
+    return linkedReadPath(linkedWalletId, 'events', query);
+}
+export function parseLinkedStreamsRegistrationList(payload, linkedWalletId) {
+    const root = record(payload, ['items', 'has_more'], ['next_after_registration_id']);
+    if (!Array.isArray(root.items) || root.items.length > MaxStreamsPageLimit || typeof root.has_more !== 'boolean' || root.has_more !== Object.hasOwn(root, 'next_after_registration_id'))
+        fault();
+    const items = root.items.map(item => parseLinkedStreamsRegistration(item, linkedWalletId));
+    if (items.some((item, index) => index > 0 && items[index - 1].registrationId >= item.registrationId))
+        fault();
+    if (root.has_more && (!uuid(root.next_after_registration_id) || items.length === 0 || root.next_after_registration_id !== items.at(-1).registrationId))
+        fault();
+    const page = { items: Object.freeze(items), hasMore: root.has_more };
+    return Object.freeze(root.has_more ? { ...page, nextAfterRegistrationId: root.next_after_registration_id } : page);
+}
+function parseLinkedStreamsRegistration(payload, linkedWalletId) {
+    const r = record(payload, ['registration_id', 'binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'source_registration_id', 'network', 'address', 'assets', 'status', 'effective_from', 'revision', 'source_version']);
+    if (!uuid(r.registration_id) || r.binding_source !== 'linked_wallet' || !uuid(r.connection_id) || !uuid(r.linked_wallet_id) || r.linked_wallet_id !== linkedWalletId || !safeRevision(r.binding_revision) || !opaqueId(r.source_registration_id) || !network(r.network) || typeof r.address !== 'string' || !/^[A-Za-z0-9_:-]{1,256}$/.test(r.address) || !assets(r.assets) || !['pending', 'active'].includes(r.status) || typeof r.effective_from !== 'string' || new TextEncoder().encode(r.effective_from).length < 1 || new TextEncoder().encode(r.effective_from).length > 256 || !integer(r.revision) || r.revision < 1 || typeof r.source_version !== 'string' || !/^[0-9]+\.[0-9]+$/.test(r.source_version))
+        fault();
+    return Object.freeze({ registrationId: r.registration_id, bindingSource: 'linked_wallet', connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision, sourceRegistrationId: r.source_registration_id, network: r.network, address: r.address, assets: Object.freeze([...r.assets]), status: r.status, effectiveFrom: r.effective_from, revision: r.revision, sourceVersion: r.source_version });
+}
+function linkedReadPath(id, kind, query) {
+    const path = `/v1/linked-wallets/${id}/${kind}`;
+    return query.size === 0 ? path : `${path}?${query.toString()}`;
+}
+function readLimit(query, value) {
+    if (value === undefined)
+        return;
+    if (!integer(value) || value < 1 || value > MaxStreamsPageLimit)
+        throw new ClientFlowError('invalid_streams_request');
+    query.set('limit', String(value));
+}

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