@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/deviceKey.d.ts

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

package/dist/deviceKey.js

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

package/dist/deviceShare.d.ts

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

package/dist/deviceShare.js

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

package/dist/deviceShareEnvelope.d.ts

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

package/dist/deviceShareEnvelope.js

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

package/dist/linkedChecks.d.ts

@@ -0,0 +1,17 @@
+import type { ResultRecipient } from './slice4.ts';
+export declare function fault(): never;
+export declare function requestID(v: unknown): void;
+export declare function requestUUID(v: unknown): void;
+export declare function token(v: unknown): void;
+export declare function uuid(v: unknown): v is string;
+export declare function safeRevision(v: unknown): v is string;
+export declare function text(v: unknown, max: number): v is string;
+export declare function hex(v: unknown): v is string;
+export declare function b64(v: unknown): v is string;
+export declare function digest(v: unknown): v is string;
+export declare function publicKey(a: unknown, v: unknown): boolean;
+export declare function network(v: unknown): v is string;
+export declare function assets(v: unknown): v is string[];
+export declare function activityTypes(v: unknown): v is string[];
+export declare function recipient(v: unknown): ResultRecipient;
+export declare function https(v: unknown): boolean;

package/dist/linkedChecks.js

@@ -0,0 +1,31 @@
+// The small checks the linked-wallet modules share: identifiers, revisions,
+// networks, assets and the error a request or an answer fails with. They
+// moved out of linkedWallets.ts when that file reached the repository line
+// target.
+import { ClientFlowError, canonicalDecimal, opaqueId, record } from './auth.js';
+import { MaxStreamsActivityTypes } from './streams.js';
+export function fault() { throw new ClientFlowError('invalid_server_response'); }
+export function requestID(v) { if (!opaqueId(v))
+    throw new ClientFlowError('invalid_linked_wallet_request'); }
+export function requestUUID(v) { if (!uuid(v))
+    throw new ClientFlowError('invalid_linked_wallet_request'); }
+export function token(v) { if (!text(v, 8192))
+    throw new ClientFlowError('invalid_linked_wallet_request'); }
+export function uuid(v) { return typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(v); }
+export function safeRevision(v) { return canonicalDecimal(v) && v.length <= 16 && v !== '0' && BigInt(v) <= BigInt(Number.MAX_SAFE_INTEGER); }
+export function text(v, max) { return typeof v === 'string' && v.length > 0 && new TextEncoder().encode(v).length <= max && v.trim() === v && !/[\x00-\x1f\x7f]/.test(v); }
+export function hex(v) { return typeof v === 'string' && v.length > 0 && v.length <= 2048 && /^([0-9a-f]{2})+$/.test(v); }
+export function b64(v) { return typeof v === 'string' && /^[A-Za-z0-9_-]+$/.test(v); }
+export function digest(v) { return typeof v === 'string' && /^[0-9a-f]{64}$/.test(v); }
+export function publicKey(a, v) { return typeof v === 'string' && (a === 'ed25519' ? /^[a-f0-9]{64}$/.test(v) : a === 'secp256k1' && /^(02|03)[a-f0-9]{64}$|^04[a-f0-9]{128}$/.test(v)); }
+export function network(v) { return typeof v === 'string' && /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/.test(v); }
+export function assets(v) { return Array.isArray(v) && v.length <= 32 && new Set(v).size === v.length && v.every(a => typeof a === 'string' && /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}\/[-a-z0-9]{3,8}:[-.%a-zA-Z0-9]{1,128}(\/[-.%a-zA-Z0-9]{1,78})?$/.test(a)); }
+export function activityTypes(v) { return Array.isArray(v) && v.length <= MaxStreamsActivityTypes && new Set(v).size === v.length && v.every(t => typeof t === 'string' && t.length <= 64 && /^[a-z][a-z0-9]*(?:[._][a-z0-9]+)*$/.test(t)); }
+export function recipient(v) { const r = record(v, ['type', 'id']); if (!['account', 'service'].includes(r.type) || !opaqueId(r.id))
+    fault(); return { type: r.type, id: r.id }; }
+export function https(v) { try {
+    return typeof v === 'string' && new URL(v).protocol === 'https:';
+}
+catch {
+    return false;
+} }

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