@x1id/resolve 0.23.0 → 0.44.0

package/dist/messaging.js

@@ -0,0 +1,979 @@
+/**
+ * X1ID Messaging — end-to-end encrypted messages between @names
+ * (docs/specs/x1id-messaging.md, OpenProject #8873: Msg 1 + Msg 2).
+ *
+ * What this module gives an integrator:
+ *
+ * - **Keys from a wallet signature.** {@link messagingKeyDerivationMessage} is
+ *   the fixed, domain-separated text a wallet signs; {@link deriveMessagingKeyPair}
+ *   turns that signature into an X25519 keypair (HKDF-SHA256). The user never
+ *   manages a separate secret: the same wallet signing the same message gives
+ *   the same key on every device. Same pattern as Shield's key derivation
+ *   (app/src/lib/shield/keys.ts), including the "sign twice, both must match"
+ *   determinism check ({@link signaturesMatch}).
+ * - **The on-chain key record.** The public key is published by the name's
+ *   owner as the text record {@link MSG_KEY_TEXT_KEY} (`x1.msg.key`), value
+ *   `x1msg1;k=<x25519 pubkey, base64url>;w=<inbox wallet>;i=<key index>` —
+ *   {@link encodeMessagingKeyRecord} / {@link parseMessagingKeyRecord}.
+ *   Rotation = derive with the next index and overwrite the record.
+ * - **The trust rule** ({@link judgeMessagingKey}, pure) and the chain read
+ *   that applies it ({@link resolveMessagingKey}): a key is honoured only if
+ *   the record was written AFTER the current holder's ownership epoch and its
+ *   inbox wallet is the current authority, or a record delegate granted after
+ *   that epoch. A key left behind by a previous owner is never used.
+ * - **Envelopes.** {@link sealMessage} encrypts (X25519 + HKDF-SHA256 +
+ *   XChaCha20-Poly1305, fresh ephemeral key per recipient, padded to a length
+ *   bucket) for ONE X1 network ({@link MessagingNetwork}: the network byte is
+ *   in the authenticated header and the signed digest, so a message can't be
+ *   replayed across mainnet/testnet); the sender's WALLET signs the envelope digest
+ *   ({@link envelopeSigningMessage}); {@link attachSignature} completes it;
+ *   {@link parseEnvelope} / {@link verifyEnvelopeSignature} check it without
+ *   decrypting (what the relay does); {@link openMessage} verifies and decrypts.
+ * - **Optional on-chain proof of sending**, paid by the SENDER:
+ *   {@link buildMessageProofMemoIx} — an SPL Memo `x1msg1:<digest hex>` signed
+ *   by the sender's wallet.
+ *
+ * # Dependencies — why this module is a separate entry point
+ *
+ * The rest of `@x1id/resolve` is dependency-free. Messaging needs X25519,
+ * XChaCha20-Poly1305, HKDF and strict Ed25519 verification, and hand-rolling
+ * any of those is not acceptable. It uses the audited, pure-TypeScript @noble
+ * libraries (`@noble/curves`, `@noble/ciphers`, `@noble/hashes`; @solana/web3.js
+ * itself depends on curves + hashes, and the X1ID app already ships curves).
+ * It is published as the `@x1id/resolve/messaging` subpath and is NOT
+ * re-exported from the package root, so importing the resolver never loads
+ * them.
+ *
+ * Nothing here talks to the relay or signs anything: wallet signatures come in
+ * as bytes, and the relay is plain HTTP (spec §6).
+ */
+import { x25519, ed25519 } from "@noble/curves/ed25519";
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha2";
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { makeAccountReader, nftHolder, parseHandleAccount } from "./accounts.js";
+import { decodeRecordDelegate, RECORD_DELEGATE_SEED } from "./delegate.js";
+import { decodeTextRecord, hashTextKey, TEXT_RECORD_SEED, TEXT_VALUE_MAX_LEN } from "./textRecords.js";
+import { ResolveError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** The text-record key a name publishes its messaging key under. */
+export const MSG_KEY_TEXT_KEY = "x1.msg.key";
+/** Version tag that starts every v1 key-record value. */
+export const MSG_KEY_RECORD_VERSION = "x1msg1";
+/** Highest key index accepted (rotation counter). */
+export const MSG_MAX_KEY_INDEX = 65535;
+/** The header's network byte (offset 4) per network. 0 (the pre-network
+ *  "reserved flags" value) and anything else are refused. */
+export const MSG_NETWORK_BYTE = Object.freeze({ mainnet: 1, testnet: 2 });
+/** Is `v` a {@link MessagingNetwork}? */
+export function isMessagingNetwork(v) {
+    return v === "mainnet" || v === "testnet";
+}
+function networkFromByte(b) {
+    return b === MSG_NETWORK_BYTE.mainnet ? "mainnet" : b === MSG_NETWORK_BYTE.testnet ? "testnet" : null;
+}
+/** Envelope magic + version: ASCII "X1M" then 0x01. */
+export const MSG_ENVELOPE_MAGIC = Uint8Array.from([0x58, 0x31, 0x4d, 0x01]);
+/** Plaintext is padded up to the smallest of these sizes that fits, so the
+ *  ciphertext reveals only which bucket the message falls in. */
+export const MSG_PAD_BUCKETS = Object.freeze([256, 1024, 4096, 16384]);
+/** Padded-plaintext framing: u32 length + 1 content-type byte. */
+const PAD_OVERHEAD = 5;
+/** Longest message text, UTF-8 bytes. */
+export const MSG_MAX_TEXT_BYTES = 16384 - PAD_OVERHEAD;
+/** Content type byte: UTF-8 plain text (the only one in v1). */
+export const MSG_CONTENT_TEXT = 1;
+/** Fixed header: magic(4) network(1) sender(32) recipient(32) createdAt(8) id(16) stanzaCount(1). */
+const FIXED_HEADER_LEN = 4 + 1 + 32 + 32 + 8 + 16 + 1; // 94
+/** One recipient stanza: key(32) ephemeral(32) wrapped content key(32 + 16 tag). */
+const STANZA_LEN = 32 + 32 + 48;
+const NONCE_LEN = 24;
+const TAG_LEN = 16;
+const SIG_LEN = 64;
+/** Trailer kind byte: the wallet signed {@link envelopeSigningMessage}. */
+const SIG_KIND_MESSAGE = 0;
+/** Trailer kind byte: the wallet signed {@link envelopeSigningTransaction}. */
+const SIG_KIND_TX = 1;
+/** Largest signed-transaction message a transaction-kind trailer may carry. */
+const MAX_TX_MESSAGE = 600;
+/** Largest valid envelope, bytes (two stanzas, largest bucket, tx trailer). */
+export const MSG_MAX_ENVELOPE_BYTES = FIXED_HEADER_LEN + 2 * STANZA_LEN + NONCE_LEN + 4 + 16384 + TAG_LEN + 1 + SIG_LEN + 2 + MAX_TX_MESSAGE;
+/** SPL Memo v2 — the program the optional proof of sending rides on. */
+export const MSG_MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+/** Prefix of the proof-of-sending memo: `x1msg1:<64 hex digest>`. */
+export const MSG_PROOF_MEMO_PREFIX = "x1msg1:";
+const TE = new TextEncoder();
+const HKDF_SALT_KEY = TE.encode("x1id-msg/v1/key-derivation");
+const HKDF_INFO_WRAP = TE.encode("x1id-msg/v1/wrap");
+/** A typed failure from this module. `code` is stable; `message` is for people. */
+export class MessagingError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MessagingError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new MessagingError("bad-input", `${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new MessagingError("bad-input", `${what} must be exactly 32 bytes`);
+    return v;
+}
+function concatBytes(...parts) {
+    let n = 0;
+    for (const p of parts)
+        n += p.length;
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+function isAllZero(b) {
+    let d = 0;
+    for (let i = 0; i < b.length; i++)
+        d |= b[i];
+    return d === 0;
+}
+/** Lowercase hex. */
+export function toHex(b) {
+    let s = "";
+    for (let i = 0; i < b.length; i++)
+        s += b[i].toString(16).padStart(2, "0");
+    return s;
+}
+function fromHex(s) {
+    if (!/^(?:[0-9a-f]{2})*$/.test(s))
+        return null;
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+const B64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/** RFC 4648 §5 base64url, no padding. */
+export function base64urlEncode(b) {
+    let s = "";
+    let i = 0;
+    for (; i + 2 < b.length; i += 3) {
+        const n = (b[i] << 16) | (b[i + 1] << 8) | b[i + 2];
+        s += B64URL[n >> 18] + B64URL[(n >> 12) & 63] + B64URL[(n >> 6) & 63] + B64URL[n & 63];
+    }
+    const rest = b.length - i;
+    if (rest === 1) {
+        const n = b[i] << 16;
+        s += B64URL[n >> 18] + B64URL[(n >> 12) & 63];
+    }
+    else if (rest === 2) {
+        const n = (b[i] << 16) | (b[i + 1] << 8);
+        s += B64URL[n >> 18] + B64URL[(n >> 12) & 63] + B64URL[(n >> 6) & 63];
+    }
+    return s;
+}
+/** Strict base64url decode (no padding, canonical trailing bits), or null. */
+export function base64urlDecode(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s) || s.length % 4 === 1)
+        return null;
+    const out = new Uint8Array(Math.floor((s.length * 3) / 4));
+    let o = 0;
+    let acc = 0;
+    let bits = 0;
+    for (let i = 0; i < s.length; i++) {
+        acc = (acc << 6) | B64URL.indexOf(s[i]);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[o++] = (acc >> bits) & 0xff;
+        }
+    }
+    // Non-canonical encodings (stray low bits) are refused, so every byte
+    // string has exactly one accepted spelling.
+    if (bits > 0 && (acc & ((1 << bits) - 1)) !== 0)
+        return null;
+    return out;
+}
+const defaultRandom = (n) => {
+    const b = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(b);
+    return b;
+};
+// ---------------------------------------------------------------------------
+// Keys from a wallet signature
+// ---------------------------------------------------------------------------
+function checkIndex(index) {
+    if (!Number.isInteger(index) || index < 0 || index > MSG_MAX_KEY_INDEX) {
+        throw new MessagingError("bad-input", `key index must be an integer 0..=${MSG_MAX_KEY_INDEX}`);
+    }
+}
+/**
+ * The exact text a wallet signs to derive its messaging key. Fixed and
+ * domain-separated (it names X1ID Messaging, the wallet and the key index, so
+ * a signature made for anything else — a sign-in, another app, another index —
+ * never yields this key). Plain printable ASCII + newlines so every wallet
+ * shows it as text.
+ *
+ * The signature IS the secret: anyone who obtains it can derive the key and
+ * read the wallet's messages. The text says so, and apps must never send or
+ * store it (the X1ID app keeps it in memory only, like Shield).
+ */
+export function messagingKeyDerivationMessage(wallet, index = 0) {
+    checkIndex(index);
+    const w = encodeBase58(toBytes32(wallet, "wallet"));
+    return TE.encode("X1ID Messaging key v1\n\n" +
+        "Signing this creates your private X1ID messaging key. Anyone who has this " +
+        "signature can read your messages, so only sign it in an app you trust with them.\n\n" +
+        `Wallet: ${w}\n` +
+        `Key index: ${index}`);
+}
+/**
+ * Derive the X25519 keypair from the wallet's 64-byte signature over
+ * {@link messagingKeyDerivationMessage}`(wallet, index)`:
+ *
+ *     secret = HKDF-SHA256(ikm = signature, salt = "x1id-msg/v1/key-derivation",
+ *                          info = "x25519|<wallet>|<index>", L = 32)
+ *
+ * (X25519 clamps the scalar itself.) Only deterministic wallets give a stable
+ * key — have the wallet sign twice on set-up and require
+ * {@link signaturesMatch}, exactly as Shield does.
+ */
+export function deriveMessagingKeyPair(signature, wallet, index = 0) {
+    checkIndex(index);
+    if (!(signature instanceof Uint8Array) || signature.length !== SIG_LEN) {
+        throw new MessagingError("bad-input", "signature must be 64 bytes");
+    }
+    if (isAllZero(signature))
+        throw new MessagingError("bad-input", "signature is all zero");
+    const w = encodeBase58(toBytes32(wallet, "wallet"));
+    const secretKey = hkdf(sha256, signature, HKDF_SALT_KEY, TE.encode(`x25519|${w}|${index}`), 32);
+    return { wallet: w, index, publicKey: x25519.getPublicKey(secretKey), secretKey };
+}
+/** Constant-time equality of two signatures — the determinism check. */
+export function signaturesMatch(a, b) {
+    return a.length === SIG_LEN && bytesEqual(a, b);
+}
+/** The record value, ASCII: `x1msg1;k=<base64url pubkey>;w=<wallet>;i=<index>`. */
+export function encodeMessagingKeyRecord(r) {
+    if (!(r.publicKey instanceof Uint8Array) || r.publicKey.length !== 32) {
+        throw new MessagingError("bad-input", "publicKey must be 32 bytes");
+    }
+    if (isAllZero(r.publicKey))
+        throw new MessagingError("bad-input", "publicKey is all zero");
+    checkIndex(r.index);
+    const w = encodeBase58(toBytes32(r.wallet, "wallet"));
+    const s = `${MSG_KEY_RECORD_VERSION};k=${base64urlEncode(r.publicKey)};w=${w};i=${r.index}`;
+    if (s.length > TEXT_VALUE_MAX_LEN)
+        throw new MessagingError("bad-input", "record value too long");
+    return s;
+}
+/** {@link encodeMessagingKeyRecord} as the raw bytes a text-record ix takes. */
+export function encodeMessagingKeyRecordBytes(r) {
+    return TE.encode(encodeMessagingKeyRecord(r));
+}
+const RECORD_RE = /^x1msg1;k=([A-Za-z0-9_-]{43});w=([1-9A-HJ-NP-Za-km-z]{32,44});i=(0|[1-9][0-9]{0,4})$/;
+/**
+ * Parse a record value strictly: exactly the v1 shape, canonical base64url, a
+ * real 32-byte wallet, a non-zero key. Anything else (another version, extra
+ * fields, padding, whitespace) is null — a reader must then treat the name as
+ * having no usable key.
+ */
+export function parseMessagingKeyRecord(value) {
+    let s;
+    if (typeof value === "string")
+        s = value;
+    else {
+        try {
+            s = new TextDecoder("utf-8", { fatal: true }).decode(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    const m = RECORD_RE.exec(s);
+    if (!m)
+        return null;
+    const publicKey = base64urlDecode(m[1]);
+    if (!publicKey || publicKey.length !== 32 || isAllZero(publicKey))
+        return null;
+    const walletBytes = decodeBase58_32(m[2]);
+    if (!walletBytes)
+        return null;
+    const wallet = encodeBase58(walletBytes);
+    if (wallet !== m[2])
+        return null; // canonical spelling only
+    const index = Number(m[3]);
+    if (index > MSG_MAX_KEY_INDEX)
+        return null;
+    return { version: 1, publicKey, wallet, index };
+}
+/**
+ * The ownership epoch a messaging key must post-date:
+ * `max(registered_at, holder_epoch)` — the last native register/sale/transfer
+ * or native pNFT sale (docs/record-trust.md, attestation.ts).
+ */
+export function messagingOwnershipEpoch(h) {
+    return h.registeredAt > h.holderEpoch ? h.registeredAt : h.holderEpoch;
+}
+/**
+ * THE trust rule (spec §3). A name's messaging key is honoured only when ALL of:
+ *
+ * 1. the record exists and parses as a v1 key;
+ * 2. `updated_at >= max(registered_at, holder_epoch)` — it was written in the
+ *    CURRENT holder's ownership epoch — and `updated_at >= records_cleared_at`;
+ * 3. its inbox wallet `w` is the name's current authority (owner / NFT holder),
+ *    OR the current record delegate whose `delegated_at >= max(registered_at,
+ *    holder_epoch)` (the holder authorised that delegate after their epoch).
+ *
+ * Rule 3 also catches what the epochs cannot: a bearer-NFT trade on an
+ * outside marketplace bumps no epoch, but the old holder's key names the old
+ * holder's wallet, which is no longer the authority, so it stops counting.
+ * Pure; no I/O.
+ */
+export function judgeMessagingKey(input) {
+    if (!input.record)
+        return { ok: false, reason: "no-record" };
+    const key = parseMessagingKeyRecord(input.record.value);
+    if (!key)
+        return { ok: false, reason: "malformed" };
+    const epoch = messagingOwnershipEpoch(input.handle);
+    if (input.record.updatedAt < epoch || input.record.updatedAt < input.handle.recordsClearedAt) {
+        return { ok: false, reason: "stale", key };
+    }
+    if (key.wallet === input.authority)
+        return { ok: true, key, basis: "authority" };
+    if (input.delegate && input.delegate.delegate === key.wallet) {
+        if (input.delegate.delegatedAt >= epoch)
+            return { ok: true, key, basis: "delegate" };
+        return { ok: false, reason: "delegate-stale", key };
+    }
+    return { ok: false, reason: "wallet-not-authorized", key };
+}
+function b58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+/**
+ * Read `@name`'s messaging key from chain and judge it with
+ * {@link judgeMessagingKey}. Bare `@handles` only (like Shield). Throws a
+ * `ResolveError` for an invalid or unregistered name; a name without a usable
+ * key is a normal result (`verdict.ok === false`), not an error.
+ */
+export async function resolveMessagingKey(name, config) {
+    const reader = makeAccountReader(config.rpcUrl, config.fetchImpl);
+    const programBytes = toBytes32(config.handleProgramId, "handleProgramId");
+    const programB58 = encodeBase58(programBytes);
+    const canonical = config.wasm.normalizeHandle(name.trim().replace(/^@/, ""));
+    if (!canonical)
+        throw new ResolveError("invalid-handle", `"${name}" is not a valid handle`, name);
+    const derived = config.wasm.deriveHandleAccount(canonical, programBytes);
+    if (!derived)
+        throw new ResolveError("invalid-handle", `"${name}" is not a valid handle`, name);
+    const handleAccount = encodeBase58(derived);
+    const info = await reader.accountInfo(handleAccount);
+    if (!info || info.owner !== programB58)
+        throw new ResolveError("not-found", `@${canonical} is not registered`, name);
+    const handle = parseHandleAccount(info.data);
+    if (!handle)
+        throw new ResolveError("rpc-error", `@${canonical} returned a malformed account`, name);
+    const authority = handle.nftMint === null
+        ? encodeBase58(handle.owner)
+        : (await nftHolder(reader, config.wasm, canonical, handle.nftMint, name)).address;
+    const recordAccount = await config.find([TE.encode(TEXT_RECORD_SEED), derived, await hashTextKey(MSG_KEY_TEXT_KEY)], programB58);
+    const delegateAccount = await config.find([TE.encode(RECORD_DELEGATE_SEED), derived], programB58);
+    const [recInfo, delInfo] = await Promise.all([reader.accountInfo(recordAccount), reader.accountInfo(delegateAccount)]);
+    // An account under any other program is not ours — treat as absent.
+    const recOk = recInfo && recInfo.owner === programB58 ? recInfo : null;
+    const rec = recOk ? decodeTextRecord(recOk.data, recordAccount, handle.registeredAt, handle.recordsClearedAt, handle.holderEpoch) : null;
+    const del = delInfo && delInfo.owner === programB58 ? decodeRecordDelegate(delInfo.data) : null;
+    const record = rec && rec.handle === handleAccount && rec.key === MSG_KEY_TEXT_KEY
+        ? { value: rec.value, updatedAt: rec.updatedAt }
+        : null;
+    const verdict = recOk && !record
+        ? { ok: false, reason: "malformed" }
+        : judgeMessagingKey({
+            record,
+            handle,
+            authority,
+            delegate: del && del.handle === handleAccount ? del : null,
+        });
+    return { name: canonical, handleAccount, authority, recordAccount, recordExists: recOk !== null, verdict };
+}
+// ---------------------------------------------------------------------------
+// Padding
+// ---------------------------------------------------------------------------
+/** The padded size for `textBytes` bytes of text. */
+export function paddedLength(textBytes) {
+    const need = textBytes + PAD_OVERHEAD;
+    for (const b of MSG_PAD_BUCKETS)
+        if (need <= b)
+            return b;
+    throw new MessagingError("too-long", `message is too long (max ${MSG_MAX_TEXT_BYTES} bytes)`);
+}
+function pad(text) {
+    const body = TE.encode(text);
+    const out = new Uint8Array(paddedLength(body.length));
+    new DataView(out.buffer).setUint32(0, body.length + 1, true);
+    out[4] = MSG_CONTENT_TEXT;
+    out.set(body, 5);
+    return out;
+}
+function unpad(p) {
+    if (!MSG_PAD_BUCKETS.includes(p.length))
+        throw new MessagingError("malformed", "bad padded length");
+    const n = new DataView(p.buffer, p.byteOffset, p.byteLength).getUint32(0, true);
+    if (n < 1 || 4 + n > p.length)
+        throw new MessagingError("malformed", "bad content length");
+    if (p[4] !== MSG_CONTENT_TEXT)
+        throw new MessagingError("malformed", "unknown content type");
+    if (!isAllZero(p.subarray(4 + n)))
+        throw new MessagingError("malformed", "non-zero padding");
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(p.subarray(5, 4 + n));
+    }
+    catch {
+        throw new MessagingError("malformed", "message text is not UTF-8");
+    }
+}
+function wrapKeys(shared, ephemeral, key) {
+    if (isAllZero(shared))
+        throw new MessagingError("bad-input", "invalid (low-order) public key");
+    const okm = hkdf(sha256, shared, concatBytes(ephemeral, key), HKDF_INFO_WRAP, 32 + NONCE_LEN);
+    return { k: okm.subarray(0, 32), n: okm.subarray(32) };
+}
+function x25519Shared(secret, pub) {
+    try {
+        return x25519.getSharedSecret(secret, pub);
+    }
+    catch {
+        throw new MessagingError("bad-input", "invalid public key");
+    }
+}
+/**
+ * The text the sender's wallet signs for an envelope: the X1 network and the
+ * envelope's sha256 fingerprint under a fixed, domain-separated heading
+ * (printable ASCII). The digest already covers the network byte; naming it in
+ * the text also shows the user which network they are sending on.
+ */
+export function envelopeSigningMessage(digest, network) {
+    if (digest.length !== 32)
+        throw new MessagingError("bad-input", "digest must be 32 bytes");
+    if (!isMessagingNetwork(network))
+        throw new MessagingError("bad-input", "network must be mainnet or testnet");
+    return TE.encode(`X1ID Messaging: send a message\n\nNetwork: X1 ${network}\nFingerprint: ${toHex(digest)}`);
+}
+/**
+ * Encrypt `text` to the recipient (and optionally the sender's own key).
+ *
+ * Per message: a random 32-byte content key encrypts the padded text with
+ * XChaCha20-Poly1305 (random 24-byte nonce; AAD = every header byte before
+ * the ciphertext, so network, sender, recipient, time, id and stanzas are all
+ * authenticated). Per stanza: a FRESH ephemeral X25519 key, ECDH with the
+ * stanza's key, HKDF-SHA256 (salt = ephemeral ‖ key) → wrap key + nonce, and
+ * the content key sealed under them (AAD = the fixed header ‖ the stanza key).
+ *
+ * Returns the unsigned envelope: have the sender's wallet sign
+ * `signingMessage`, then {@link attachSignature}.
+ */
+export function sealMessage(p) {
+    const rand = p.random ?? defaultRandom;
+    if (!isMessagingNetwork(p.network))
+        throw new MessagingError("bad-input", "network must be mainnet or testnet");
+    const sender = toBytes32(p.sender, "sender");
+    const recipient = toBytes32(p.recipient, "recipient");
+    const keys = [p.recipientKey];
+    if (p.senderKey !== undefined)
+        keys.push(p.senderKey);
+    for (const k of keys) {
+        if (!(k instanceof Uint8Array) || k.length !== 32 || isAllZero(k)) {
+            throw new MessagingError("bad-input", "keys must be 32-byte X25519 public keys");
+        }
+    }
+    if (keys.length === 2 && bytesEqual(keys[0], keys[1]))
+        keys.pop(); // messaging yourself
+    const createdAtMs = p.createdAtMs ?? Date.now();
+    if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0)
+        throw new MessagingError("bad-input", "bad createdAtMs");
+    const fixed = new Uint8Array(FIXED_HEADER_LEN);
+    fixed.set(MSG_ENVELOPE_MAGIC, 0);
+    fixed[4] = MSG_NETWORK_BYTE[p.network];
+    fixed.set(sender, 5);
+    fixed.set(recipient, 37);
+    new DataView(fixed.buffer).setBigUint64(69, BigInt(createdAtMs), true);
+    const id = rand(16);
+    fixed.set(id, 77);
+    fixed[93] = keys.length;
+    const cek = rand(32);
+    const stanzas = [];
+    for (const key of keys) {
+        const ephSecret = rand(32);
+        const eph = x25519.getPublicKey(ephSecret);
+        const w = wrapKeys(x25519Shared(ephSecret, key), eph, key);
+        const wrapped = xchacha20poly1305(w.k, w.n, concatBytes(fixed, key)).encrypt(cek);
+        stanzas.push(concatBytes(key, eph, wrapped));
+        ephSecret.fill(0);
+    }
+    const nonce = rand(NONCE_LEN);
+    const aad = concatBytes(fixed, ...stanzas, nonce);
+    const ct = xchacha20poly1305(cek, nonce, aad).encrypt(pad(p.text));
+    cek.fill(0);
+    const len = new Uint8Array(4);
+    new DataView(len.buffer).setUint32(0, ct.length, true);
+    const body = concatBytes(aad, len, ct);
+    const digest = sha256(body);
+    return { body, digest, signingMessage: envelopeSigningMessage(digest, p.network), messageId: toHex(id) };
+}
+function finishEnvelope(env) {
+    const parsed = parseEnvelope(env);
+    if (!parsed || !verifyEnvelopeSignature(parsed)) {
+        throw new MessagingError("bad-signature", "the wallet's signature does not verify for the sender");
+    }
+    return env;
+}
+/**
+ * Complete an envelope with the sender wallet's `signMessage` signature over
+ * `signingMessage` (raw, or SIMD-0048-wrapped — both verify). Checks it
+ * before returning, so a wallet that signed the wrong thing (or whose message
+ * signatures don't verify on X1) fails HERE, not at the recipient — fall back
+ * to {@link envelopeSigningTransaction} + {@link attachTransactionSignature}.
+ */
+export function attachSignature(unsigned, signature) {
+    if (!(signature instanceof Uint8Array) || signature.length !== SIG_LEN) {
+        throw new MessagingError("bad-input", "signature must be 64 bytes");
+    }
+    return finishEnvelope(concatBytes(unsigned.body, Uint8Array.of(SIG_KIND_MESSAGE), signature));
+}
+/**
+ * Complete an envelope with a TRANSACTION signature: for wallets that can sign
+ * transactions but not (verifiable) messages — the same reason X1ID sign-in
+ * has `/v1/auth/verify-tx`. `signedTx` is the wire transaction the wallet
+ * returned from signing {@link envelopeSigningTransaction} (never broadcast).
+ * Only the message bytes and the fee payer's signature are kept.
+ */
+export function attachTransactionSignature(unsigned, signedTx) {
+    const split = splitSignedTransaction(signedTx);
+    if (!split)
+        throw new MessagingError("bad-input", "not a signed transaction");
+    if (split.message.length > MAX_TX_MESSAGE)
+        throw new MessagingError("bad-input", "signed transaction too large");
+    const len = new Uint8Array(2);
+    new DataView(len.buffer).setUint16(0, split.message.length, true);
+    return finishEnvelope(concatBytes(unsigned.body, Uint8Array.of(SIG_KIND_TX), split.signature, len, split.message));
+}
+/** Structural parse — the relay's check. Null for anything malformed. */
+export function parseEnvelope(env) {
+    if (!(env instanceof Uint8Array) || env.length < FIXED_HEADER_LEN + STANZA_LEN + NONCE_LEN + 4 + TAG_LEN + 1 + SIG_LEN) {
+        return null;
+    }
+    if (env.length > MSG_MAX_ENVELOPE_BYTES)
+        return null;
+    for (let i = 0; i < 4; i++)
+        if (env[i] !== MSG_ENVELOPE_MAGIC[i])
+            return null;
+    const network = networkFromByte(env[4]);
+    if (!network)
+        return null;
+    const dv = new DataView(env.buffer, env.byteOffset, env.byteLength);
+    const createdAt = dv.getBigUint64(69, true);
+    if (createdAt > BigInt(Number.MAX_SAFE_INTEGER))
+        return null;
+    const count = env[93];
+    if (count < 1 || count > 2)
+        return null;
+    let o = FIXED_HEADER_LEN;
+    const stanzas = [];
+    for (let i = 0; i < count; i++) {
+        if (o + STANZA_LEN > env.length)
+            return null;
+        stanzas.push({
+            key: env.slice(o, o + 32),
+            ephemeral: env.slice(o + 32, o + 64),
+            wrapped: env.slice(o + 64, o + STANZA_LEN),
+        });
+        o += STANZA_LEN;
+    }
+    if (count === 2 && bytesEqual(stanzas[0].key, stanzas[1].key))
+        return null;
+    o += NONCE_LEN;
+    if (o + 4 > env.length)
+        return null;
+    const ctLen = dv.getUint32(o, true);
+    o += 4;
+    if (!MSG_PAD_BUCKETS.includes(ctLen - TAG_LEN))
+        return null;
+    const bodyEnd = o + ctLen;
+    if (bodyEnd + 1 + SIG_LEN > env.length)
+        return null;
+    const kind = env[bodyEnd];
+    const signature = env.slice(bodyEnd + 1, bodyEnd + 1 + SIG_LEN);
+    let signedTxMessage = null;
+    if (kind === SIG_KIND_MESSAGE) {
+        if (bodyEnd + 1 + SIG_LEN !== env.length)
+            return null;
+    }
+    else if (kind === SIG_KIND_TX) {
+        const at = bodyEnd + 1 + SIG_LEN;
+        if (at + 2 > env.length)
+            return null;
+        const n = dv.getUint16(at, true);
+        if (n < 1 || n > MAX_TX_MESSAGE || at + 2 + n !== env.length)
+            return null;
+        signedTxMessage = env.slice(at + 2);
+    }
+    else {
+        return null;
+    }
+    const body = env.slice(0, bodyEnd);
+    return {
+        network,
+        sender: encodeBase58(env.slice(5, 37)),
+        recipient: encodeBase58(env.slice(37, 69)),
+        createdAtMs: Number(createdAt),
+        messageId: toHex(env.slice(77, 93)),
+        stanzas,
+        body,
+        digest: sha256(body),
+        signatureKind: kind === SIG_KIND_TX ? "transaction" : "message",
+        signature,
+        signedTxMessage,
+        size: env.length,
+    };
+}
+// ---------------------------------------------------------------------------
+// Transaction-signature mode (wallets whose message signatures don't verify)
+// ---------------------------------------------------------------------------
+const COMPUTE_BUDGET_PROGRAM_ID = "ComputeBudget111111111111111111111111111111";
+/** The memo a transaction-mode sender signs: `x1msg1-sig:<digest hex>`. */
+export function envelopeSigningMemo(digest) {
+    if (digest.length !== 32)
+        throw new MessagingError("bad-input", "digest must be 32 bytes");
+    return `x1msg1-sig:${toHex(digest)}`;
+}
+function compactU16(n) {
+    const out = [];
+    let v = n;
+    for (;;) {
+        const b = v & 0x7f;
+        v >>= 7;
+        if (v === 0) {
+            out.push(b);
+            return out;
+        }
+        out.push(b | 0x80);
+    }
+}
+function readCompactU16(b, at) {
+    let v = 0;
+    for (let i = 0; i < 3; i++) {
+        if (at + i >= b.length)
+            return null;
+        const x = b[at + i];
+        v |= (x & 0x7f) << (7 * i);
+        if ((x & 0x80) === 0)
+            return [v, at + i + 1];
+    }
+    return null;
+}
+/**
+ * The unsigned wire transaction a transaction-mode sender's wallet signs (and
+ * must NOT broadcast): a legacy message, fee payer = sender, ONE SPL Memo
+ * instruction carrying {@link envelopeSigningMemo}. Its "recent blockhash" is
+ * the envelope digest itself — never a real blockhash, so the signed artifact
+ * can never land on chain and cost the sender a fee, whoever holds it.
+ */
+export function envelopeSigningTransaction(sender, digest) {
+    const payer = toBytes32(sender, "sender");
+    if (digest.length !== 32)
+        throw new MessagingError("bad-input", "digest must be 32 bytes");
+    const memoProgram = toBytes32(MSG_MEMO_PROGRAM_ID, "memo program");
+    const data = TE.encode(envelopeSigningMemo(digest));
+    const msg = Uint8Array.from([
+        1, 0, 1, // 1 signer, 0 read-only signed, 1 read-only unsigned (the memo program)
+        ...compactU16(2), ...payer, ...memoProgram,
+        ...digest,
+        ...compactU16(1), 1, ...compactU16(0), ...compactU16(data.length), ...data,
+    ]);
+    return concatBytes(Uint8Array.from(compactU16(1)), new Uint8Array(SIG_LEN), msg);
+}
+/** Split a signed wire transaction into its message and the FIRST (fee
+ *  payer's) signature, or null. */
+export function splitSignedTransaction(tx) {
+    const sc = readCompactU16(tx, 0);
+    if (!sc || sc[0] < 1)
+        return null;
+    const msgAt = sc[1] + sc[0] * SIG_LEN;
+    if (msgAt >= tx.length)
+        return null;
+    return { signature: tx.slice(sc[1], sc[1] + SIG_LEN), message: tx.slice(msgAt) };
+}
+/**
+ * Strictly check a transaction MESSAGE as a signature over `digest` by
+ * `sender`, and verify the signature. Accepted: legacy or v0 without address
+ * lookups; exactly one required signer, the fee payer = `sender`; exactly one
+ * SPL Memo instruction whose data is {@link envelopeSigningMemo}`(digest)`;
+ * nothing else except ComputeBudget instructions (some wallets add a priority
+ * fee before signing). Any blockhash (it is never broadcast).
+ */
+export function verifyTransactionSignature(sender, digest, message, signature) {
+    try {
+        const pub = toBytes32(sender, "sender");
+        const senderB58 = encodeBase58(pub);
+        let at = 0;
+        const versioned = (message[0] & 0x80) !== 0;
+        if (versioned) {
+            if ((message[0] & 0x7f) !== 0)
+                return false; // v0 only
+            at = 1;
+        }
+        if (at + 3 > message.length)
+            return false;
+        if (message[at] !== 1)
+            return false; // exactly one required signature
+        at += 3;
+        const kc = readCompactU16(message, at);
+        if (!kc || kc[0] < 2)
+            return false;
+        at = kc[1];
+        const keys = [];
+        for (let i = 0; i < kc[0]; i++) {
+            if (at + 32 > message.length)
+                return false;
+            keys.push(encodeBase58(message.subarray(at, at + 32)));
+            at += 32;
+        }
+        if (keys[0] !== senderB58)
+            return false;
+        at += 32; // blockhash
+        const ic = readCompactU16(message, at);
+        if (!ic)
+            return false;
+        at = ic[1];
+        const want = TE.encode(envelopeSigningMemo(digest));
+        let memos = 0;
+        for (let i = 0; i < ic[0]; i++) {
+            if (at >= message.length)
+                return false;
+            const prog = keys[message[at]];
+            at += 1;
+            const ac = readCompactU16(message, at);
+            if (!ac)
+                return false;
+            for (let j = 0; j < ac[0]; j++)
+                if ((message[ac[1] + j] ?? 255) >= keys.length)
+                    return false;
+            at = ac[1] + ac[0];
+            const dl = readCompactU16(message, at);
+            if (!dl)
+                return false;
+            if (dl[1] + dl[0] > message.length)
+                return false;
+            const data = message.subarray(dl[1], dl[1] + dl[0]);
+            at = dl[1] + dl[0];
+            if (prog === MSG_MEMO_PROGRAM_ID) {
+                if (!bytesEqual(data, want))
+                    return false;
+                memos++;
+            }
+            else if (prog !== COMPUTE_BUDGET_PROGRAM_ID) {
+                return false;
+            }
+        }
+        if (memos !== 1)
+            return false;
+        if (versioned) {
+            const lc = readCompactU16(message, at);
+            if (!lc || lc[0] !== 0)
+                return false; // no address-table lookups
+            at = lc[1];
+        }
+        if (at !== message.length)
+            return false;
+        return ed25519.verify(signature, message, pub, { zip215: false });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Solana off-chain message envelope (SIMD-0048, v0) some wallets wrap a
+ * `signMessage` payload in before signing: 0xff "solana offchain", version 0,
+ * a zero application domain, `format`, one signer, u16 length, the message.
+ * Same bytes as the X1ID app's unlock check.
+ */
+export function solanaOffchainEnvelope(message, signer, format) {
+    if (message.length > 0xffff)
+        throw new MessagingError("bad-input", "message too long for an off-chain envelope");
+    const out = new Uint8Array(1 + 15 + 1 + 32 + 1 + 1 + 32 + 2 + message.length);
+    let o = 0;
+    out[o++] = 0xff;
+    out.set(TE.encode("solana offchain"), o);
+    o += 15;
+    out[o++] = 0; // version
+    o += 32; // application domain: zero
+    out[o++] = format;
+    out[o++] = 1; // signer count
+    out.set(signer, o);
+    o += 32;
+    out[o++] = message.length & 0xff;
+    out[o++] = (message.length >> 8) & 0xff;
+    out.set(message, o);
+    return out;
+}
+/**
+ * Verify a wallet's ed25519 signature over `message` — over the raw bytes, or
+ * over the SIMD-0048 envelope some wallets sign instead. Strict RFC 8032
+ * (non-canonical encodings and small-order keys refused). Returns which form
+ * verified, or null.
+ */
+export function verifyWalletSignature(wallet, message, signature) {
+    let pub;
+    try {
+        pub = toBytes32(wallet, "wallet");
+    }
+    catch {
+        return null;
+    }
+    if (!(signature instanceof Uint8Array) || signature.length !== SIG_LEN)
+        return null;
+    const ok = (m) => {
+        try {
+            return ed25519.verify(signature, m, pub, { zip215: false });
+        }
+        catch {
+            return false;
+        }
+    };
+    if (ok(message))
+        return "raw";
+    for (const fmt of [0, 1, 2]) {
+        if (message.length <= 0xffff && ok(solanaOffchainEnvelope(message, pub, fmt)))
+            return `offchain-v0-fmt${fmt}`;
+    }
+    return null;
+}
+/** Does the envelope's signature verify for its sender? Returns the mode, or
+ *  null. This is what the relay checks before storing anything. */
+export function verifyEnvelopeSignature(p) {
+    if (p.signatureKind === "transaction") {
+        return p.signedTxMessage && verifyTransactionSignature(p.sender, p.digest, p.signedTxMessage, p.signature)
+            ? "transaction"
+            : null;
+    }
+    return verifyWalletSignature(p.sender, envelopeSigningMessage(p.digest, p.network), p.signature);
+}
+/**
+ * Is the envelope addressed to exactly this (trusted) key record: its
+ * recipient wallet is the record's inbox wallet `w` AND its recipient stanza
+ * (always the first) is for the record's key `k`? What the relay checks on
+ * send against the recipient's on-chain key (spec §6.3). Pure.
+ */
+export function envelopeMatchesKey(p, key) {
+    const first = p.stanzas[0];
+    return p.recipient === key.wallet && first !== undefined && bytesEqual(first.key, key.publicKey);
+}
+/**
+ * Verify the sender's signature, then decrypt with `keys` (the reader's
+ * keypair; either side of the conversation). Throws {@link MessagingError}:
+ * `malformed`, `wrong-network`, `bad-signature`, `not-for-this-key`,
+ * `decrypt-failed`.
+ */
+export function openMessage(env, keys, opts = {}) {
+    const p = parseEnvelope(env);
+    if (!p)
+        throw new MessagingError("malformed", "not a valid X1ID message envelope");
+    if (opts.network !== undefined && p.network !== opts.network) {
+        throw new MessagingError("wrong-network", `this message was sent on X1 ${p.network}, not ${opts.network}`);
+    }
+    const mode = verifyEnvelopeSignature(p);
+    if (!mode)
+        throw new MessagingError("bad-signature", "the sender's wallet signature does not verify");
+    const idx = p.stanzas.findIndex((s) => bytesEqual(s.key, keys.publicKey));
+    if (idx < 0)
+        throw new MessagingError("not-for-this-key", "this message was not encrypted to your key");
+    const st = p.stanzas[idx];
+    const fixed = p.body.subarray(0, FIXED_HEADER_LEN);
+    let cek;
+    let padded;
+    try {
+        const w = wrapKeys(x25519Shared(keys.secretKey, st.ephemeral), st.ephemeral, st.key);
+        cek = xchacha20poly1305(w.k, w.n, concatBytes(fixed, st.key)).decrypt(st.wrapped);
+        const nonceAt = FIXED_HEADER_LEN + p.stanzas.length * STANZA_LEN;
+        const aad = p.body.subarray(0, nonceAt + NONCE_LEN);
+        const ct = p.body.subarray(nonceAt + NONCE_LEN + 4);
+        padded = xchacha20poly1305(cek, p.body.slice(nonceAt, nonceAt + NONCE_LEN), aad).decrypt(ct);
+    }
+    catch {
+        throw new MessagingError("decrypt-failed", "the message could not be decrypted with this key");
+    }
+    cek.fill(0);
+    // The recipient stanza is always first; the second is the sender's copy.
+    return {
+        network: p.network,
+        sender: p.sender,
+        recipient: p.recipient,
+        createdAtMs: p.createdAtMs,
+        messageId: p.messageId,
+        text: unpad(padded),
+        digest: toHex(p.digest),
+        signatureMode: mode,
+        asSender: idx === 1,
+    };
+}
+/** Envelope bytes → the relay's wire string (base64url). */
+export function encodeEnvelope(env) {
+    return base64urlEncode(env);
+}
+/** The relay's wire string → envelope bytes, or null. */
+export function decodeEnvelope(s) {
+    return base64urlDecode(s);
+}
+// ---------------------------------------------------------------------------
+// Optional on-chain proof of sending (sender-paid)
+// ---------------------------------------------------------------------------
+/** The proof memo for an envelope digest: `x1msg1:<64 hex>` (71 bytes). */
+export function messageProofMemo(digest) {
+    if (digest.length !== 32)
+        throw new MessagingError("bad-input", "digest must be 32 bytes");
+    return MSG_PROOF_MEMO_PREFIX + toHex(digest);
+}
+/** Parse a proof memo back to its digest, or null. */
+export function parseMessageProofMemo(memo) {
+    if (!memo.startsWith(MSG_PROOF_MEMO_PREFIX))
+        return null;
+    const hex = memo.slice(MSG_PROOF_MEMO_PREFIX.length);
+    if (hex.length !== 64)
+        return null;
+    return fromHex(hex);
+}
+/**
+ * The SPL Memo instruction that records "this wallet sent the message with
+ * this digest" on chain. The SENDER signs and pays the fee (X1ID pays nothing
+ * and never sees the transaction). The sender is listed as a signer of the
+ * memo itself, so the proof is attributable even if someone else paid.
+ */
+export function buildMessageProofMemoIx(p) {
+    return {
+        programId: MSG_MEMO_PROGRAM_ID,
+        keys: [{ pubkey: b58(p.sender, "sender"), isSigner: true, isWritable: false }],
+        data: TE.encode(messageProofMemo(p.digest)),
+    };
+}