@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/linkedRecovery.js

@@ -0,0 +1,49 @@
+// The wire of a linked wallet's device-share recovery (wallet.recover naming
+// linked_wallet_id): the closed create body, the display the person confirms
+// with the passkey, and the result, the device share sealed to the new device
+// key. deviceRecovery.ts runs it; walletOperations.ts reads it among the
+// other wallet operations.
+import { ClientFlowError, opaqueId, record } from "./auth.js";
+import { bindingRevision, displayCommon, lowerHexBytes, lowerUUID, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+const compressedP256Key = /^(02|03)[0-9a-f]{64}$/;
+const linkedNetwork = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/;
+export function linkedRecoverCreate(ownerId, linkedWalletId, recipientPublicKey) {
+    return { kind: "wallet.recover", owner_type: "account", owner_id: ownerId, linked_wallet_id: linkedWalletId, payload: { recipient_public_key: recipientPublicKey } };
+}
+/** validLinkedRecoverCreate checks the members a recovery adds to the common ones validateUserWalletCreate checked. */
+export function validLinkedRecoverCreate(common) {
+    if (common.kind !== "wallet.recover" || common.wallet_id !== undefined || !lowerUUID(common.linked_wallet_id))
+        return false;
+    const payload = common.payload;
+    return payload !== null && typeof payload === "object" && !Array.isArray(payload) && Object.keys(payload).length === 1 &&
+        typeof payload.recipient_public_key === "string" && compressedP256Key.test(payload.recipient_public_key);
+}
+export function parseLinkedRecoverDisplay(value) {
+    const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "binding_source", "connection_id", "linked_wallet_id", "binding_revision", "network", "address", "recipient_public_key"], ["prepared_summary"]);
+    if (display.kind !== "wallet.recover" || display.binding_source !== "linked_wallet" || !lowerUUID(display.connection_id) || !lowerUUID(display.linked_wallet_id) ||
+        !bindingRevision(display.binding_revision) || typeof display.network !== "string" || !linkedNetwork.test(display.network) ||
+        typeof display.address !== "string" || !walletRecipient.test(display.address) || typeof display.recipient_public_key !== "string" || !compressedP256Key.test(display.recipient_public_key)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return {
+        ...displayCommon(display), kind: "wallet.recover", connectionId: display.connection_id, linkedWalletId: display.linked_wallet_id, bindingRevision: display.binding_revision,
+        network: display.network, address: display.address, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary),
+    };
+}
+/** The released result of a recovery: the wallet it is of and its device share, sealed to the new device key. */
+export function parseRecoveredShareResult(requestId, value, expectedOperationId) {
+    const result = record(value, ["kind", "operation_id", "receipt_id", "linked_wallet_id", "device_share"]);
+    const share = record(result.device_share, ["ciphertext", "nonce", "ephemeral_public_key", "encryption_algorithm", "encryption_context"]);
+    if (!opaqueId(requestId) || result.kind !== "device_share_recovered" || result.operation_id !== expectedOperationId || !lowerUUID(result.receipt_id) || !lowerUUID(result.linked_wallet_id) ||
+        !lowerHexBytes(share.ciphertext) || !lowerHexBytes(share.nonce) || !lowerHexBytes(share.ephemeral_public_key) ||
+        typeof share.encryption_algorithm !== "string" || !/^[a-z0-9_-]{1,128}$/.test(share.encryption_algorithm) || !lowerHexBytes(share.encryption_context)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return {
+        requestId,
+        result: {
+            operationId: expectedOperationId, kind: "device_share_recovered", receiptId: result.receipt_id, linkedWalletId: result.linked_wallet_id,
+            deviceShare: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeralPublicKey: share.ephemeral_public_key, encryptionAlgorithm: share.encryption_algorithm, encryptionContext: share.encryption_context },
+        },
+    };
+}

package/dist/linkedRegistrations.d.ts

@@ -0,0 +1,11 @@
+import type { LinkedEventsOptions, LinkedRegistrationCreate, LinkedRegistrationListOptions, LinkedRegistrationOperation, LinkedRegistrationResult, LinkedStreamsRegistrationList } from './linkedWallets.ts';
+export declare function validateLinkedRegistrationCreate(value: LinkedRegistrationCreate, ownerId: string): LinkedRegistrationCreate;
+export declare function parseLinkedRegistrationOperationEnvelope(payload: unknown): {
+    requestId: string;
+    operation: LinkedRegistrationOperation;
+};
+export declare function parseLinkedRegistrationOperation(payload: unknown): LinkedRegistrationOperation;
+export declare function parseLinkedRegistrationResult(payload: unknown, operationId: string): LinkedRegistrationResult;
+export declare function linkedRegistrationsPath(linkedWalletId: string, options?: LinkedRegistrationListOptions): string;
+export declare function linkedEventsPath(linkedWalletId: string, options?: LinkedEventsOptions): string;
+export declare function parseLinkedStreamsRegistrationList(payload: unknown, linkedWalletId: string): LinkedStreamsRegistrationList;

package/dist/linkedRegistrations.js

@@ -0,0 +1,109 @@
+// The linked-wallet registrations for tracking, as Authorization frames them:
+// the closed create body, the operation and its result, and the paths and
+// pages of a linked wallet's registrations and events. linkedWallets.ts calls
+// them and re-exports them.
+import { ClientFlowError, canonicalDecimal, deadlineAfter, integer, isNextAction, opaqueId, record, rfc3339UTC } from './auth.js';
+import { appendEventTypes, MaxStreamsCursorLength, MaxStreamsPageLimit } from './streams.js';
+import { activityTypes, assets, digest, fault, https, network, recipient, requestUUID, safeRevision, text, uuid } from './linkedChecks.js';
+export function validateLinkedRegistrationCreate(value, ownerId) {
+    const r = record(value, ['kind', 'owner_type', 'owner_id', 'linked_wallet_id', 'payload']);
+    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');
+    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/linkedSendDisplay.d.ts

@@ -0,0 +1,73 @@
+import { type DisplayCommon } from "./walletDisplayParts.ts";
+/**
+ * LinkedWalletIdentity names a wallet created through the provider in the
+ * own-wallet system. It has no walletId: the operation names it by this
+ * identity instead.
+ */
+export interface LinkedWalletIdentity {
+    connectionId: string;
+    linkedWalletId: string;
+    bindingRevision: string;
+}
+/** What a send from a linked wallet may move: the network's own coin, or a token the own-wallet system sends there. */
+export declare const LinkedSendAssets: readonly ["native", "usdt", "usdc"];
+export type LinkedSendAsset = (typeof LinkedSendAssets)[number];
+export declare function linkedSendAsset(value: unknown): value is LinkedSendAsset;
+/**
+ * What replaces a send the network has not included, on an EVM network:
+ * "speed_up" sends the same transfer again with a higher fee, "cancel" sends
+ * nothing to the wallet's own address in its place. Either way at most one of
+ * the two transactions is ever included.
+ */
+export declare const ReplaceActions: readonly ["speed_up", "cancel"];
+export type ReplaceAction = (typeof ReplaceActions)[number];
+export declare function replaceAction(value: unknown): value is ReplaceAction;
+/** The longest comment a transfer carries, in bytes of UTF-8: what one TON comment holds. */
+export declare const MaxTransferCommentBytes = 120;
+/**
+ * transferComment says whether a value is a text a send may carry to its
+ * recipient: 1 to 120 bytes of UTF-8 with no control character, line
+ * separator or character that reorders text. The provider applies the same
+ * rule, and the owner confirms the comment exactly as it is shown.
+ */
+export declare function transferComment(value: unknown): value is string;
+/**
+ * LinkedSendDisplay is what the owner confirms for a send from a linked
+ * wallet. address, preparedSummary and feeEstimate appear once the own-wallet
+ * system prepared the transfer (LinkedWallets.prepare()). feeEstimate is "estimated"
+ * with estimatedFeeRaw, the network fee in minimal units of the network's own
+ * coin, paid on top of the amount; or "unavailable" when that system could
+ * estimate none, which is never a fee of zero. It is an estimate: the
+ * confirmation does not bound the fee.
+ *
+ * A replacement carries replacesOperationId, the send whose transfer it
+ * replaces, and replaceAction. network, asset, recipient and amountRaw are
+ * then what the replacing transaction itself moves: for a cancel nothing
+ * ("0") of the network's own coin to the wallet's own address.
+ *
+ * comment is the text the transfer carries to its recipient, on TON; it is
+ * absent for a send without one.
+ */
+export type LinkedSendDisplay = DisplayCommon & LinkedWalletIdentity & {
+    kind: "wallet.send";
+    network: string;
+    asset: string;
+    recipient: string;
+    amountRaw: string;
+    address?: string;
+    preparedSummary?: string;
+    feeEstimate?: "estimated" | "unavailable";
+    estimatedFeeRaw?: string;
+    replacesOperationId?: string;
+    replaceAction?: ReplaceAction;
+    comment?: string;
+};
+export declare function parseLinkedSendDisplay(value: unknown): LinkedSendDisplay;
+/**
+ * MediatedLinkedSendDisplay is the safe display of a Mode C transfer from a
+ * linked wallet that a service forwarded on the person's signed request. It
+ * freezes no result recipient and is never a replacement.
+ */
+export type MediatedLinkedSendDisplay = Omit<LinkedSendDisplay, "resultRecipient" | "replacesOperationId" | "replaceAction">;
+/** parseMediatedLinkedSendDisplay reads exactly the display of a forwarded linked transfer. */
+export declare function parseMediatedLinkedSendDisplay(value: unknown): MediatedLinkedSendDisplay;

package/dist/linkedSendDisplay.js

@@ -0,0 +1,84 @@
+// The safe display of a send from a linked wallet: a wallet created through
+// the provider that lives in the own-wallet system. The same display serves
+// the replacement of such a send that the network has not included.
+import { ClientFlowError, opaqueId, record } from "./auth.js";
+import { bindingRevision, displayCommon, lowerUUID, rawQuantity, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+const linkedNetwork = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/;
+/** What a send from a linked wallet may move: the network's own coin, or a token the own-wallet system sends there. */
+export const LinkedSendAssets = ["native", "usdt", "usdc"];
+export function linkedSendAsset(value) {
+    return typeof value === "string" && LinkedSendAssets.includes(value);
+}
+/**
+ * What replaces a send the network has not included, on an EVM network:
+ * "speed_up" sends the same transfer again with a higher fee, "cancel" sends
+ * nothing to the wallet's own address in its place. Either way at most one of
+ * the two transactions is ever included.
+ */
+export const ReplaceActions = ["speed_up", "cancel"];
+export function replaceAction(value) {
+    return typeof value === "string" && ReplaceActions.includes(value);
+}
+/** The longest comment a transfer carries, in bytes of UTF-8: what one TON comment holds. */
+export const MaxTransferCommentBytes = 120;
+// Control characters, line and paragraph separators, characters that reorder
+// the text around them, and halves of a character.
+const notInComment = /[\p{Cc}\p{Zl}\p{Zp}\p{Bidi_Control}\p{Cs}]/u;
+const utf8 = new TextEncoder();
+/**
+ * transferComment says whether a value is a text a send may carry to its
+ * recipient: 1 to 120 bytes of UTF-8 with no control character, line
+ * separator or character that reorders text. The provider applies the same
+ * rule, and the owner confirms the comment exactly as it is shown.
+ */
+export function transferComment(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= MaxTransferCommentBytes && !notInComment.test(value) && utf8.encode(value).length <= MaxTransferCommentBytes;
+}
+export function parseLinkedSendDisplay(value) {
+    const display = record(value, [...linkedSendMembers, "result_recipient"], [...linkedSendOptional, "replaces_operation_id", "replace_action"]);
+    const replaces = display.replaces_operation_id !== undefined;
+    if (!linkedSendValid(display, replaces) || replaces !== (display.replace_action !== undefined) || (replaces && (!opaqueId(display.replaces_operation_id) || !replaceAction(display.replace_action))) ||
+        // A replacement carries no comment.
+        (replaces && display.comment !== undefined)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const parsed = { ...displayCommon(display), ...linkedSendParts(display) };
+    if (replaces) {
+        parsed.replacesOperationId = display.replaces_operation_id;
+        parsed.replaceAction = display.replace_action;
+    }
+    return parsed;
+}
+/** parseMediatedLinkedSendDisplay reads exactly the display of a forwarded linked transfer. */
+export function parseMediatedLinkedSendDisplay(value) {
+    const display = record(value, linkedSendMembers, linkedSendOptional);
+    if (!linkedSendValid(display, false) || !opaqueId(display.owner_id) || !opaqueId(display.requester_id))
+        throw new ClientFlowError("invalid_server_response");
+    return { ownerId: display.owner_id, requesterId: display.requester_id, ...linkedSendParts(display) };
+}
+const linkedSendMembers = ["kind", "owner_id", "requester_id", "binding_source", "connection_id", "linked_wallet_id", "binding_revision", "network", "asset", "recipient", "amount_raw"];
+const linkedSendOptional = ["address", "prepared_summary", "fee_estimate", "estimated_fee_raw", "comment"];
+function linkedSendValid(display, replaces) {
+    return display.kind === "wallet.send" && display.binding_source === "linked_wallet" && lowerUUID(display.connection_id) && lowerUUID(display.linked_wallet_id) && bindingRevision(display.binding_revision) &&
+        typeof display.network === "string" && linkedNetwork.test(display.network) && linkedSendAsset(display.asset) && typeof display.recipient === "string" && walletRecipient.test(display.recipient) &&
+        // Only a replacement moves nothing: a cancel, or a cancel sent again.
+        rawQuantity(display.amount_raw, !replaces) && (display.address === undefined || (typeof display.address === "string" && walletRecipient.test(display.address))) &&
+        (display.fee_estimate === undefined || display.fee_estimate === "estimated" || display.fee_estimate === "unavailable") &&
+        (display.fee_estimate === "estimated") === (display.estimated_fee_raw !== undefined) && (display.estimated_fee_raw === undefined || rawQuantity(display.estimated_fee_raw, false)) &&
+        (display.comment === undefined || transferComment(display.comment));
+}
+function linkedSendParts(display) {
+    const parts = {
+        kind: "wallet.send", connectionId: display.connection_id, linkedWalletId: display.linked_wallet_id, bindingRevision: display.binding_revision,
+        network: display.network, asset: display.asset, recipient: display.recipient, amountRaw: display.amount_raw, ...summaryOf(display.prepared_summary),
+    };
+    if (display.address !== undefined)
+        parts.address = display.address;
+    if (display.fee_estimate !== undefined)
+        parts.feeEstimate = display.fee_estimate;
+    if (display.estimated_fee_raw !== undefined)
+        parts.estimatedFeeRaw = display.estimated_fee_raw;
+    if (display.comment !== undefined)
+        parts.comment = display.comment;
+    return parts;
+}

package/dist/linkedWalletSignals.d.ts

@@ -0,0 +1,22 @@
+/** The most linked wallets one stream names. */
+export declare const MaxSignalWallets = 32;
+/** Why a stream ended: its time ran out, the server is restarting, or the connection closed. */
+export type LinkedWalletSignalEnd = 'expired' | 'server_draining' | 'connection_closed';
+export interface LinkedWalletSignalHandlers {
+    /**
+     * The stream is live. Read every wallet once now: whatever happened before
+     * this moment is in that read, whatever happens after it is signalled.
+     * expiresAt is when the server ends the stream, in epoch milliseconds.
+     */
+    onOpen?: (expiresAt: number) => void;
+    /** These linked wallets have new events. Read them now. */
+    onWallets: (linkedWalletIds: readonly string[]) => void;
+    signal?: AbortSignal;
+}
+export declare function linkedSignalsPath(linkedWalletIds: readonly string[]): string;
+/**
+ * Reads one stream to its end and reports what it says. It resolves with the
+ * reason the stream ended and rejects when the answer is not this protocol or
+ * the connection fails. Aborting the signal rejects with the abort reason.
+ */
+export declare function readLinkedWalletSignals(body: ReadableStream<Uint8Array>, linkedWalletIds: readonly string[], handlers: LinkedWalletSignalHandlers): Promise<LinkedWalletSignalEnd>;

package/dist/linkedWalletSignals.js

@@ -0,0 +1,101 @@
+// Live signals for linked wallets. Authorization holds one long-lived answer
+// open and names on it the linked wallets that have new events. A signal
+// carries no event: the wallets it names are read through events(), which
+// authorizes every read. A stream lives no longer than an access token does;
+// when it ends, a new one is opened with the session's current token.
+import { ClientFlowError, record, rfc3339UTC } from './auth.js';
+/** The most linked wallets one stream names. */
+export const MaxSignalWallets = 32;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// One frame is a short line or two; anything longer is not this protocol.
+const maxFrameLength = 4096;
+export function linkedSignalsPath(linkedWalletIds) {
+    if (!Array.isArray(linkedWalletIds) || linkedWalletIds.length < 1 || linkedWalletIds.length > MaxSignalWallets ||
+        new Set(linkedWalletIds).size !== linkedWalletIds.length || linkedWalletIds.some(id => typeof id !== 'string' || !uuidPattern.test(id))) {
+        throw new ClientFlowError('invalid_linked_wallet_request');
+    }
+    const query = new URLSearchParams();
+    for (const id of linkedWalletIds)
+        query.append('linked_wallet_id', id);
+    return `/v1/linked-wallets/signals?${query.toString()}`;
+}
+/**
+ * Reads one stream to its end and reports what it says. It resolves with the
+ * reason the stream ended and rejects when the answer is not this protocol or
+ * the connection fails. Aborting the signal rejects with the abort reason.
+ */
+export async function readLinkedWalletSignals(body, linkedWalletIds, handlers) {
+    const named = new Set(linkedWalletIds);
+    const reader = body.getReader();
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    const signal = handlers.signal;
+    // Aborting ends the read whoever opened the stream: a read in flight then
+    // comes back as done, and the abort reason is what the caller gets.
+    const abort = () => { reader.cancel(signal?.reason).catch(() => undefined); };
+    signal?.addEventListener('abort', abort, { once: true });
+    let pending = '';
+    let open = false;
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                throw signal.reason;
+            const { value, done } = await reader.read();
+            if (signal?.aborted)
+                throw signal.reason;
+            if (done) {
+                if (pending.length > 0)
+                    fault(); // cut inside a frame
+                return 'connection_closed';
+            }
+            try {
+                pending += decoder.decode(value, { stream: true });
+            }
+            catch {
+                fault();
+            }
+            for (let end = pending.indexOf('\n\n'); end >= 0; end = pending.indexOf('\n\n')) {
+                const frame = pending.slice(0, end);
+                pending = pending.slice(end + 2);
+                if (frame.startsWith(':'))
+                    continue; // a comment keeps the connection alive
+                const parsed = /^event: (open|wallets|close)\ndata: (\{[^\n]*\})$/.exec(frame);
+                if (!parsed)
+                    fault();
+                let data;
+                try {
+                    data = JSON.parse(parsed[2]);
+                }
+                catch {
+                    fault();
+                }
+                if (parsed[1] === 'open') {
+                    const root = record(data, ['expires_at']);
+                    if (open || !rfc3339UTC(root.expires_at))
+                        fault();
+                    open = true;
+                    handlers.onOpen?.(Date.parse(root.expires_at));
+                }
+                else if (parsed[1] === 'wallets') {
+                    const root = record(data, ['linked_wallet_ids']);
+                    const ids = root.linked_wallet_ids;
+                    if (!open || !Array.isArray(ids) || ids.length < 1 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== 'string' || !named.has(id)))
+                        fault();
+                    handlers.onWallets(Object.freeze([...ids]));
+                }
+                else {
+                    const root = record(data, ['reason']);
+                    if (root.reason !== 'expired' && root.reason !== 'server_draining')
+                        fault();
+                    return root.reason;
+                }
+            }
+            if (pending.length > maxFrameLength)
+                fault();
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
+        reader.cancel().catch(() => undefined);
+    }
+}
+function fault() { throw new ClientFlowError('invalid_server_response'); }