@x1id/resolve 0.22.0 → 0.43.0

package/dist/loginButton.js

@@ -0,0 +1,207 @@
+/**
+ * The "Sign in with X1ID" button — framework-free (no React), for the OIDC
+ * flow in ./oidc.ts. Two forms:
+ *
+ * ```ts
+ * // 1. A function that returns a <button> (append it anywhere):
+ * const client = createX1idOidcClient({ clientId: "x1c_…", redirectUri: "https://app.example/callback" });
+ * document.querySelector("#login")!.append(createX1idLoginButton({ client }));
+ *
+ * // 2. A custom element (register once, then use markup):
+ * defineX1idLoginButton();
+ * // <x1id-login-button client-id="x1c_…" redirect-uri="https://app.example/callback"></x1id-login-button>
+ * ```
+ *
+ * Nothing touches the DOM at import time (safe to import on a server, and
+ * tree-shaken away if unused). Accessible by construction: a native
+ * `<button type="button">` (keyboard + focus for free), a visible
+ * `:focus-visible` ring, `aria-busy` while the redirect starts, the mark is
+ * decorative (`alt=""`), light/dark follow `prefers-color-scheme` unless forced,
+ * Windows high-contrast (`forced-colors`) and `prefers-reduced-motion` are
+ * honored. Styles go in a constructable stylesheet where supported (not
+ * blocked by a strict `style-src` CSP), else one `<style>` element.
+ *
+ * Brand: the label is "Sign in with X1ID" — X1ID is one word, uppercase. Don't
+ * recolor or redraw the mark.
+ */
+import { X1ID_LOGO_DATA_URI } from "./logo.js";
+import { beginX1idLogin, createX1idOidcClient, } from "./oidc.js";
+export const X1ID_LOGIN_LABEL = "Sign in with X1ID";
+export const X1ID_LOGIN_BUTTON_TAG = "x1id-login-button";
+const STYLE_ID = "x1id-login-style";
+export const X1ID_LOGIN_BUTTON_CSS = `
+:host{display:inline-block}
+:host([hidden]){display:none}
+.x1id-login{display:inline-flex;align-items:center;justify-content:center;gap:.6em;
+  box-sizing:border-box;min-height:44px;margin:0;padding:.6em 1.1em;
+  font:inherit;font-size:1rem;font-weight:600;line-height:1.2;letter-spacing:0;
+  cursor:pointer;border-radius:8px;border:1px solid rgba(15,20,32,.16);
+  background:#fff;color:#0f1420;-webkit-font-smoothing:antialiased;
+  transition:background-color .12s ease,border-color .12s ease}
+.x1id-login:hover{background:#f6f8fb;border-color:rgba(15,20,32,.28)}
+.x1id-login:active{background:#eef1f6}
+.x1id-login:focus-visible{outline:2px solid #0a84ff;outline-offset:2px}
+.x1id-login:disabled{opacity:.55;cursor:default}
+.x1id-login[aria-busy="true"]{cursor:progress}
+.x1id-login-logo{width:20px;height:20px;border-radius:5px;flex:0 0 auto;display:block}
+.x1id-login-label{white-space:nowrap}
+.x1id-login--dark{background:#161b26;color:#f3f6fb;border-color:rgba(255,255,255,.16)}
+.x1id-login--dark:hover{background:#1d2431;border-color:rgba(255,255,255,.28)}
+.x1id-login--dark:active{background:#131822}
+@media (prefers-color-scheme:dark){
+  .x1id-login:not(.x1id-login--light){background:#161b26;color:#f3f6fb;border-color:rgba(255,255,255,.16)}
+  .x1id-login:not(.x1id-login--light):hover{background:#1d2431;border-color:rgba(255,255,255,.28)}
+  .x1id-login:not(.x1id-login--light):active{background:#131822}
+}
+@media (prefers-reduced-motion:reduce){.x1id-login{transition:none}}
+@media (forced-colors:active){.x1id-login{border-color:ButtonText}.x1id-login:focus-visible{outline-color:Highlight}}
+`;
+/** Add the button CSS once to a document or shadow root. */
+function adoptStyles(root, doc) {
+    const Sheet = globalThis.CSSStyleSheet;
+    if (Sheet && Array.isArray(root.adoptedStyleSheets) && "replaceSync" in Sheet.prototype) {
+        const marked = root.adoptedStyleSheets.some((s) => s.__x1idLogin);
+        if (marked)
+            return;
+        const sheet = new Sheet();
+        sheet.replaceSync(X1ID_LOGIN_BUTTON_CSS);
+        sheet.__x1idLogin = true;
+        root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+        return;
+    }
+    const host = "head" in root ? (root.head ?? root.documentElement) : root;
+    if (!host)
+        return;
+    if ("getElementById" in root && root.getElementById(STYLE_ID))
+        return;
+    const el = doc.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = X1ID_LOGIN_BUTTON_CSS;
+    host.appendChild(el);
+}
+function buildButton(doc, opts) {
+    const text = opts.label ?? X1ID_LOGIN_LABEL;
+    const btn = doc.createElement("button");
+    btn.type = "button";
+    btn.className = "x1id-login" + (opts.theme === "light" ? " x1id-login--light" : opts.theme === "dark" ? " x1id-login--dark" : "");
+    if (opts.disabled)
+        btn.disabled = true;
+    const logo = doc.createElement("img");
+    logo.className = "x1id-login-logo";
+    logo.src = X1ID_LOGO_DATA_URI;
+    logo.width = 20;
+    logo.height = 20;
+    logo.alt = ""; // decorative: the label names the button
+    logo.setAttribute("aria-hidden", "true");
+    const label = doc.createElement("span");
+    label.className = "x1id-login-label";
+    label.textContent = text;
+    btn.append(logo, label);
+    btn.addEventListener("click", (ev) => {
+        if (btn.disabled || btn.getAttribute("aria-busy") === "true")
+            return;
+        const run = opts.onClick
+            ? () => opts.onClick(ev)
+            : opts.client
+                ? () => beginX1idLogin(opts.client, opts.authorization ?? {}).then(() => undefined)
+                : null;
+        if (!run)
+            return;
+        btn.setAttribute("aria-busy", "true");
+        btn.disabled = true;
+        Promise.resolve()
+            .then(run)
+            .catch((err) => {
+            btn.disabled = !!opts.disabled;
+            btn.removeAttribute("aria-busy");
+            (opts.onError ?? ((e) => console.error("[x1id] Sign in with X1ID failed", e)))(err);
+        });
+        // On success the page navigates away; the button stays busy until then.
+    });
+    return btn;
+}
+/**
+ * Build a "Sign in with X1ID" `<button>`. Pass `client` (click → redirect to
+ * auth.x1id.io) or your own `onClick`. Injects its stylesheet once.
+ */
+export function createX1idLoginButton(opts = {}) {
+    const doc = opts.document ?? globalThis.document;
+    if (!doc)
+        throw new Error("createX1idLoginButton needs a DOM (call it in the browser)");
+    adoptStyles(doc, doc);
+    return buildButton(doc, opts);
+}
+/** The custom element's attributes → client config (pure; exported for tests). */
+export function loginButtonAttributes(get) {
+    const clientId = get("client-id");
+    const redirectUri = get("redirect-uri");
+    const issuer = get("issuer");
+    const scope = get("scope");
+    const prompt = get("prompt");
+    const t = get("theme");
+    const config = clientId && redirectUri ? { clientId, redirectUri, ...(issuer ? { issuer } : {}), ...(scope ? { scope } : {}) } : null;
+    return {
+        config,
+        authorization: prompt ? { prompt } : {},
+        theme: t === "light" || t === "dark" ? t : "auto",
+        label: get("label") ?? undefined,
+    };
+}
+/**
+ * Register `<x1id-login-button>` (idempotent). Attributes: `client-id`,
+ * `redirect-uri` (required unless you set `el.client`), `issuer`, `scope`,
+ * `prompt`, `theme` (auto|light|dark), `label`, `disabled`. A failure to start
+ * dispatches a bubbling `x1id-error` CustomEvent (`detail` = the error).
+ */
+export function defineX1idLoginButton(tagName = X1ID_LOGIN_BUTTON_TAG) {
+    const g = globalThis;
+    if (!g.customElements || !g.HTMLElement)
+        throw new Error("defineX1idLoginButton needs a browser with custom elements");
+    if (g.customElements.get(tagName))
+        return;
+    class X1idLoginButtonElement extends g.HTMLElement {
+        static get observedAttributes() {
+            return ["client-id", "redirect-uri", "issuer", "scope", "prompt", "theme", "label", "disabled"];
+        }
+        /** Set a client programmatically instead of the attributes. */
+        client = null;
+        cached = null;
+        connectedCallback() {
+            this.render();
+        }
+        attributeChangedCallback() {
+            if (this.isConnected)
+                this.render();
+        }
+        resolveClient(config) {
+            if (this.client)
+                return this.client;
+            if (!config)
+                throw new Error(`<${tagName}> needs client-id and redirect-uri attributes (or el.client)`);
+            const key = JSON.stringify(config);
+            if (this.cached?.key !== key)
+                this.cached = { key, client: createX1idOidcClient(config) };
+            return this.cached.client;
+        }
+        render() {
+            const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+            const a = loginButtonAttributes((n) => this.getAttribute(n));
+            adoptStyles(root, this.ownerDocument);
+            const btn = buildButton(this.ownerDocument, {
+                theme: a.theme,
+                ...(a.label !== undefined ? { label: a.label } : {}),
+                disabled: this.hasAttribute("disabled"),
+                onClick: () => beginX1idLogin(this.resolveClient(a.config), a.authorization).then(() => undefined),
+                onError: (err) => {
+                    this.dispatchEvent(new CustomEvent("x1id-error", { detail: err, bubbles: true, composed: true }));
+                },
+            });
+            btn.setAttribute("part", "button");
+            for (const n of Array.from(root.childNodes))
+                if (!(n instanceof HTMLStyleElement))
+                    n.remove();
+            root.appendChild(btn);
+        }
+    }
+    g.customElements.define(tagName, X1idLoginButtonElement);
+}

package/dist/logo.d.ts

@@ -0,0 +1 @@
+export declare const X1ID_LOGO_DATA_URI = "data:image/png;base64,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";

package/dist/logo.js

@@ -0,0 +1,8 @@
+// Brand asset — do not edit by hand. Shared by the widget (widget/src/logo.ts
+// re-exports it) and the "Sign in with X1ID" button (src/loginButton.ts).
+// The official X1ID square logo (app/public/branding/x1id-512-square.png),
+// downscaled to 48px and inlined as a data: URI so the production
+// "Sign in with X1ID" button carries our mark with no external request and
+// nothing for a host page's CSP to block (same philosophy as the inlined WASM).
+// Regenerate from that PNG (48px, base64) if the mark ever changes.
+export const X1ID_LOGO_DATA_URI = "data:image/png;base64,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";

package/dist/messaging.d.ts

@@ -0,0 +1,439 @@
+/**
+ * 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 { type ParsedHandle } from "./accounts.js";
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { PdaFinder } from "./namespacePricing.js";
+import type { WasmResolver } from "./wasm.js";
+/** The text-record key a name publishes its messaging key under. */
+export declare const MSG_KEY_TEXT_KEY = "x1.msg.key";
+/** Version tag that starts every v1 key-record value. */
+export declare const MSG_KEY_RECORD_VERSION = "x1msg1";
+/** Highest key index accepted (rotation counter). */
+export declare const MSG_MAX_KEY_INDEX = 65535;
+/** The X1 network an envelope is bound to. */
+export type MessagingNetwork = "mainnet" | "testnet";
+/** The header's network byte (offset 4) per network. 0 (the pre-network
+ *  "reserved flags" value) and anything else are refused. */
+export declare const MSG_NETWORK_BYTE: Readonly<Record<MessagingNetwork, number>>;
+/** Is `v` a {@link MessagingNetwork}? */
+export declare function isMessagingNetwork(v: unknown): v is MessagingNetwork;
+/** Envelope magic + version: ASCII "X1M" then 0x01. */
+export declare const MSG_ENVELOPE_MAGIC: Uint8Array;
+/** Plaintext is padded up to the smallest of these sizes that fits, so the
+ *  ciphertext reveals only which bucket the message falls in. */
+export declare const MSG_PAD_BUCKETS: readonly number[];
+/** Longest message text, UTF-8 bytes. */
+export declare const MSG_MAX_TEXT_BYTES: number;
+/** Content type byte: UTF-8 plain text (the only one in v1). */
+export declare const MSG_CONTENT_TEXT = 1;
+/** Largest valid envelope, bytes (two stanzas, largest bucket, tx trailer). */
+export declare const MSG_MAX_ENVELOPE_BYTES: number;
+/** SPL Memo v2 — the program the optional proof of sending rides on. */
+export declare const MSG_MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+/** Prefix of the proof-of-sending memo: `x1msg1:<64 hex digest>`. */
+export declare const MSG_PROOF_MEMO_PREFIX = "x1msg1:";
+/** A typed failure from this module. `code` is stable; `message` is for people. */
+export declare class MessagingError extends Error {
+    readonly code: "bad-input" | "malformed" | "bad-signature" | "not-for-this-key" | "decrypt-failed" | "wrong-network" | "too-long";
+    constructor(code: MessagingError["code"], message: string);
+}
+/** Lowercase hex. */
+export declare function toHex(b: Uint8Array): string;
+/** RFC 4648 §5 base64url, no padding. */
+export declare function base64urlEncode(b: Uint8Array): string;
+/** Strict base64url decode (no padding, canonical trailing bits), or null. */
+export declare function base64urlDecode(s: string): Uint8Array | null;
+/** Random bytes source — WebCrypto by default; injectable for test vectors. */
+export type RandomBytes = (n: number) => Uint8Array;
+/**
+ * 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 declare function messagingKeyDerivationMessage(wallet: AddressLike, index?: number): Uint8Array;
+/** A messaging keypair. `secretKey` is the X25519 private scalar — keep it in
+ *  memory only. */
+export interface MessagingKeyPair {
+    readonly wallet: string;
+    readonly index: number;
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+}
+/**
+ * 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 declare function deriveMessagingKeyPair(signature: Uint8Array, wallet: AddressLike, index?: number): MessagingKeyPair;
+/** Constant-time equality of two signatures — the determinism check. */
+export declare function signaturesMatch(a: Uint8Array, b: Uint8Array): boolean;
+/** A parsed `x1.msg.key` record value. */
+export interface MessagingKeyRecord {
+    readonly version: 1;
+    /** X25519 public key. */
+    readonly publicKey: Uint8Array;
+    /** The inbox wallet: the wallet whose signature derived this key, and the
+     *  address the relay delivers to. */
+    readonly wallet: string;
+    /** Derivation index (rotation counter). */
+    readonly index: number;
+}
+/** The record value, ASCII: `x1msg1;k=<base64url pubkey>;w=<wallet>;i=<index>`. */
+export declare function encodeMessagingKeyRecord(r: {
+    publicKey: Uint8Array;
+    wallet: AddressLike;
+    index: number;
+}): string;
+/** {@link encodeMessagingKeyRecord} as the raw bytes a text-record ix takes. */
+export declare function encodeMessagingKeyRecordBytes(r: {
+    publicKey: Uint8Array;
+    wallet: AddressLike;
+    index: number;
+}): Uint8Array;
+/**
+ * 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 declare function parseMessagingKeyRecord(value: string | Uint8Array): MessagingKeyRecord | null;
+/** Everything the trust rule needs, read from chain by the caller. */
+export interface MessagingKeyTrustInput {
+    /** The `x1.msg.key` TextRecord, or null when the account does not exist. */
+    readonly record: {
+        readonly value: Uint8Array;
+        readonly updatedAt: bigint;
+    } | null;
+    /** The handle's epochs (from `parseHandleAccount`). */
+    readonly handle: Pick<ParsedHandle, "registeredAt" | "recordsClearedAt" | "holderEpoch">;
+    /** The name's CURRENT authority: `Handle.owner`, or the NFT holder when
+     *  tokenized. Base58. */
+    readonly authority: string;
+    /** The `["delegate", handle]` RecordDelegate, or null. */
+    readonly delegate: {
+        readonly delegate: string;
+        readonly delegatedAt: bigint;
+    } | null;
+}
+export type MessagingKeyVerdict = {
+    readonly ok: true;
+    readonly key: MessagingKeyRecord;
+    /** Why the inbox wallet may speak for the name. */
+    readonly basis: "authority" | "delegate";
+} | {
+    readonly ok: false;
+    readonly reason: "no-record" | "malformed" | "stale" | "wallet-not-authorized" | "delegate-stale";
+    /** The parsed key when it parsed (for an owner surface: "replace this"). */
+    readonly key?: MessagingKeyRecord;
+};
+/**
+ * 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 declare function messagingOwnershipEpoch(h: Pick<ParsedHandle, "registeredAt" | "holderEpoch">): bigint;
+/**
+ * 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 declare function judgeMessagingKey(input: MessagingKeyTrustInput): MessagingKeyVerdict;
+/** Config for {@link resolveMessagingKey} — the shape Shield's recipient
+ *  resolver takes. */
+export interface MessagingResolveConfig {
+    readonly rpcUrl: string;
+    readonly handleProgramId: AddressLike;
+    readonly wasm: WasmResolver;
+    /** Canonical `find_program_address` (never hand-rolled here). */
+    readonly find: PdaFinder;
+    readonly fetchImpl?: typeof fetch;
+}
+/** What {@link resolveMessagingKey} found. */
+export interface ResolvedMessagingKey {
+    /** Canonical name (no `@`). */
+    readonly name: string;
+    readonly handleAccount: string;
+    /** The name's current authority (owner / NFT holder). */
+    readonly authority: string;
+    /** The `["text", handle, sha256("x1.msg.key")]` account. */
+    readonly recordAccount: string;
+    /** Whether that account exists at all (stale or not) — a set-up flow
+     *  UPDATES an existing account (re-stamping it into the new epoch) and
+     *  CREATES a missing one. */
+    readonly recordExists: boolean;
+    readonly verdict: MessagingKeyVerdict;
+}
+/**
+ * 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 declare function resolveMessagingKey(name: string, config: MessagingResolveConfig): Promise<ResolvedMessagingKey>;
+/** The padded size for `textBytes` bytes of text. */
+export declare function paddedLength(textBytes: number): number;
+/** One recipient stanza: which key it is for, the ephemeral key, the wrapped
+ *  content key. */
+export interface EnvelopeStanza {
+    readonly key: Uint8Array;
+    readonly ephemeral: Uint8Array;
+    readonly wrapped: Uint8Array;
+}
+/** A structurally valid envelope (nothing decrypted). */
+export interface ParsedEnvelope {
+    /** The X1 network the sender sealed it for (authenticated + signed). */
+    readonly network: MessagingNetwork;
+    readonly sender: string;
+    readonly recipient: string;
+    readonly createdAtMs: number;
+    /** 16 random bytes, hex. */
+    readonly messageId: string;
+    readonly stanzas: readonly EnvelopeStanza[];
+    /** The signed bytes (everything but the trailing signature). */
+    readonly body: Uint8Array;
+    /** sha256(body) — the value the sender signs and the proof memo carries. */
+    readonly digest: Uint8Array;
+    /** How the sender's wallet signed (trailer kind byte). */
+    readonly signatureKind: "message" | "transaction";
+    readonly signature: Uint8Array;
+    /** `transaction` kind only: the signed transaction MESSAGE bytes. */
+    readonly signedTxMessage: Uint8Array | null;
+    /** Total length, bytes. */
+    readonly size: number;
+}
+/** An envelope awaiting the sender's wallet signature. */
+export interface UnsignedEnvelope {
+    readonly body: Uint8Array;
+    readonly digest: Uint8Array;
+    /** Exactly what the sender's wallet must `signMessage`. */
+    readonly signingMessage: Uint8Array;
+    readonly messageId: string;
+}
+export interface SealParams {
+    /** The X1 network this message is for. Bound into the header (AEAD
+     *  associated data and the signed digest) and the wallet's signing text, so
+     *  a relay or reader on the other network refuses it. */
+    readonly network: MessagingNetwork;
+    /** The sender's wallet (signs the envelope). */
+    readonly sender: AddressLike;
+    /** The recipient's inbox wallet — the key record's `w`. */
+    readonly recipient: AddressLike;
+    /** The recipient's X25519 key — the key record's `k`. */
+    readonly recipientKey: Uint8Array;
+    /** The sender's own X25519 public key: adds a second stanza so the sender
+     *  can re-read what they sent. Omit for recipient-only. */
+    readonly senderKey?: Uint8Array;
+    readonly text: string;
+    /** Default: now. */
+    readonly createdAtMs?: number;
+    /** Test seam for vectors. Default: WebCrypto. */
+    readonly random?: RandomBytes;
+}
+/**
+ * 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 declare function envelopeSigningMessage(digest: Uint8Array, network: MessagingNetwork): Uint8Array;
+/**
+ * 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 declare function sealMessage(p: SealParams): UnsignedEnvelope;
+/**
+ * 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 declare function attachSignature(unsigned: UnsignedEnvelope, signature: Uint8Array): Uint8Array;
+/**
+ * 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 declare function attachTransactionSignature(unsigned: UnsignedEnvelope, signedTx: Uint8Array): Uint8Array;
+/** Structural parse — the relay's check. Null for anything malformed. */
+export declare function parseEnvelope(env: Uint8Array): ParsedEnvelope | null;
+/** The memo a transaction-mode sender signs: `x1msg1-sig:<digest hex>`. */
+export declare function envelopeSigningMemo(digest: Uint8Array): string;
+/**
+ * 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 declare function envelopeSigningTransaction(sender: AddressLike, digest: Uint8Array): Uint8Array;
+/** Split a signed wire transaction into its message and the FIRST (fee
+ *  payer's) signature, or null. */
+export declare function splitSignedTransaction(tx: Uint8Array): {
+    message: Uint8Array;
+    signature: Uint8Array;
+} | null;
+/**
+ * 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 declare function verifyTransactionSignature(sender: AddressLike, digest: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+/**
+ * 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 declare function solanaOffchainEnvelope(message: Uint8Array, signer: Uint8Array, format: 0 | 1 | 2): Uint8Array;
+export type WalletSignatureMode = "raw" | "offchain-v0-fmt0" | "offchain-v0-fmt1" | "offchain-v0-fmt2";
+/** How an envelope's sender signature verified: a message mode, or
+ *  `transaction` (a signed, never-broadcast memo transaction). */
+export type EnvelopeSignatureMode = WalletSignatureMode | "transaction";
+/**
+ * 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 declare function verifyWalletSignature(wallet: AddressLike, message: Uint8Array, signature: Uint8Array): WalletSignatureMode | 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 declare function verifyEnvelopeSignature(p: ParsedEnvelope): EnvelopeSignatureMode | null;
+/**
+ * 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 declare function envelopeMatchesKey(p: Pick<ParsedEnvelope, "recipient" | "stanzas">, key: Pick<MessagingKeyRecord, "wallet" | "publicKey">): boolean;
+/** A verified, decrypted message. `text` is UNTRUSTED user input: render it
+ *  as plain text, never as HTML/Markdown, never follow links automatically. */
+export interface OpenedMessage {
+    readonly network: MessagingNetwork;
+    readonly sender: string;
+    readonly recipient: string;
+    readonly createdAtMs: number;
+    readonly messageId: string;
+    readonly text: string;
+    /** sha256 of the signed envelope body, hex — the proof-of-sending hash. */
+    readonly digest: string;
+    readonly signatureMode: EnvelopeSignatureMode;
+    /** True when opened with the sender's own key (a "sent" copy). */
+    readonly asSender: boolean;
+}
+/** Options for {@link openMessage}. */
+export interface OpenOptions {
+    /** The network the reader is on. When set, an envelope sealed for the other
+     *  network is refused (`wrong-network`) before anything is decrypted. Apps
+     *  should always pass it. */
+    readonly network?: MessagingNetwork;
+}
+/**
+ * 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 declare function openMessage(env: Uint8Array, keys: Pick<MessagingKeyPair, "publicKey" | "secretKey">, opts?: OpenOptions): OpenedMessage;
+/** Envelope bytes → the relay's wire string (base64url). */
+export declare function encodeEnvelope(env: Uint8Array): string;
+/** The relay's wire string → envelope bytes, or null. */
+export declare function decodeEnvelope(s: string): Uint8Array | null;
+/** The proof memo for an envelope digest: `x1msg1:<64 hex>` (71 bytes). */
+export declare function messageProofMemo(digest: Uint8Array): string;
+/** Parse a proof memo back to its digest, or null. */
+export declare function parseMessageProofMemo(memo: string): Uint8Array | null;
+/**
+ * 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 declare function buildMessageProofMemoIx(p: {
+    sender: AddressLike;
+    digest: Uint8Array;
+}): BuiltInstruction;