@x1id/resolve 0.19.1 → 0.21.0

package/dist/siws.js

@@ -0,0 +1,607 @@
+/**
+ * Sign In With Solana (SIWS, the Wallet Standard `solana:signIn` feature)
+ * against the hosted X1ID Connect API (`POST /v1/auth/challenge` +
+ * `POST /v1/auth/verify-signin`).
+ *
+ * # Why SIWS
+ *
+ * `solana:signIn` lets the WALLET build and display a structured sign-in
+ * message (domain, address, statement, nonce, ...) instead of an opaque blob.
+ * It is also the most reliable wallet-control proof on X1 in practice:
+ * Backpack's injected script hijacks OTHER wallets' `signMessage` but not
+ * `signIn`. This is the same path developers.x1id.io uses
+ * (portal/src/lib/wallet/standardWallet.ts) — the input fields here mirror it.
+ *
+ * # Flow
+ *
+ *   1. `requestSignInChallenge` — `POST /v1/auth/challenge {wallet, mode:"signin"}`
+ *      returns a single-use `nonce` bound to your API key and the wallet.
+ *   2. `buildSignInInput` — the `solana:signIn` input naming YOUR domain, the
+ *      wallet address and that nonce.
+ *   3. the wallet signs the SIWS message it renders from that input.
+ *   4. `verifySolanaSignIn` — `POST /v1/auth/verify-signin` with the exact
+ *      signed bytes (base64) and the 64-byte signature (base58). dev-api checks
+ *      line 1 (`<domain> wants you to sign in with your Solana account:`, domain
+ *      on its allowlist), line 2 (the challenged wallet), a `Nonce: <nonce>`
+ *      line, and the ed25519 signature (raw bytes or the SIMD-0048 v0
+ *      off-chain envelope). It returns a Bearer {@link ConnectSession}.
+ *
+ * `signInWithSolana` does all four. Framework-agnostic: it takes any Wallet
+ * Standard wallet object, with no wallet-adapter or web3.js dependency.
+ *
+ * # Fallbacks: `signInWithWallet`
+ *
+ * Not every wallet implements `solana:signIn`, and some implement it badly.
+ * `signInWithWallet` tries, in the same order as developers.x1id.io
+ * (portal/src/lib/wallet/standardWallet.ts `proveForPortalSession`):
+ *
+ *   1. SIWS (`solana:signIn` → `/v1/auth/verify-signin`);
+ *   2. a signed, NEVER-SENT memo transaction (`solana:signTransaction` →
+ *      `/v1/auth/verify-tx`) whose only instruction is an SPL-Memo carrying the
+ *      server's audience-bound `x1id-verify:<audience>:<nonce>` verbatim. With
+ *      `signinFeePayer` set it uses dev-api's no-fee layout (display-only fee
+ *      payer at signer index 0, the user at index 1); otherwise the user is the
+ *      fee payer. Works for Ledger, which refuses message signing;
+ *   3. `solana:signMessage` over the server's v2 challenge string
+ *      (`x1id-connect:v2:wallet-control:<audience>:<address>:<nonce>`) →
+ *      `/v1/auth/verify`.
+ *
+ * A user rejection or a wallet timeout stops the chain (the user said no; a
+ * second prompt would be hostile). Any other failure moves to the next path.
+ * Challenge strings and memos are always signed exactly as the server issued
+ * them, never rebuilt here (R3-L2P-1 audience binding).
+ *
+ * The session proves WALLET CONTROL (source `"wallet"`); the wallet's primary
+ * `@handle`, if any, is reported as metadata and re-resolved on every
+ * `GET /v1/auth/session`.
+ *
+ * Not to be confused with {@link import("./signin.js").signInWithX1ID}: that is
+ * the server-less, relying-party-verified `@handle` proof. This module talks to
+ * the hosted API and gets a session back.
+ */
+import { decodeBase58, encodeBase58 } from "./base58.js";
+import { DEFAULT_CONNECT_BASE_URL, MEMO_PROGRAM_ID, PLACEHOLDER_BLOCKHASH, VERIFY_TX_MEMO_PREFIX, } from "./connect.js";
+export class SiwsError extends Error {
+    code;
+    serverCode;
+    status;
+    constructor(code, message, 
+    /** dev-api's own error code (e.g. `CHALLENGE_EXPIRED`), when it sent one. */
+    serverCode, 
+    /** HTTP status, when the error came from a response. */
+    status) {
+        super(message);
+        this.code = code;
+        this.serverCode = serverCode;
+        this.status = status;
+        this.name = "SiwsError";
+    }
+}
+/** Map a dev-api error response onto a {@link SiwsErrorCode}. */
+export function siwsErrorCodeFor(serverCode, message) {
+    const c = (serverCode ?? "").toUpperCase();
+    if (c === "CHALLENGE_EXPIRED" || c === "CHALLENGE_NOT_FOUND")
+        return "nonce-expired";
+    // dev-api reports a disallowed domain as CONTROL_PROOF_INVALID with
+    // `... which is not allowed here` (or, for a portal key, `... not this
+    // application's domain`); a dedicated code (any *DOMAIN* code) is accepted
+    // too so a future, more specific server code maps the same way.
+    if (c.includes("DOMAIN"))
+        return "domain-not-allowed";
+    if (c === "CONTROL_PROOF_INVALID" && /not allowed|not this application's domain/i.test(message ?? "")) {
+        return "domain-not-allowed";
+    }
+    if (c === "REQUEST_FAILED" || c === "BAD_RESPONSE" || c === "NO_FETCH")
+        return "network";
+    return "api-error";
+}
+/** True if `wallet` implements `solana:signIn`. */
+export function walletSupportsSignIn(wallet) {
+    const f = wallet?.features?.["solana:signIn"];
+    return typeof f?.signIn === "function";
+}
+// -----------------------------------------------------------------------------
+// Message input
+// -----------------------------------------------------------------------------
+/** The SIWS message line-1 suffix dev-api's verifier matches on. */
+export const SIWS_HEADER_SUFFIX = " wants you to sign in with your Solana account:";
+/** Default statement shown in the wallet. */
+export const DEFAULT_SIWS_STATEMENT = "Sign in with your wallet. This does not send a transaction.";
+// Any control char (incl. CR/LF) would let a field inject extra SIWS lines.
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+function locationField(k) {
+    const loc = globalThis.location;
+    const v = loc?.[k];
+    return typeof v === "string" && v ? v : undefined;
+}
+/**
+ * Build the Wallet Standard `solana:signIn` input for an X1ID challenge —
+ * exactly the fields developers.x1id.io sends: domain, address, statement, uri,
+ * version `"1"`, nonce, issuedAt.
+ */
+export function buildSignInInput(params) {
+    const domain = params.domain ?? locationField("host");
+    if (!domain) {
+        throw new SiwsError("invalid-params", "`domain` is required outside a browser (no globalThis.location.host)");
+    }
+    if (CONTROL_RE.test(domain) || /\s/.test(domain)) {
+        throw new SiwsError("invalid-params", "`domain` must be a bare host (no whitespace or control characters)");
+    }
+    if (!params.address || CONTROL_RE.test(params.address))
+        throw new SiwsError("invalid-params", "`address` is required");
+    if (!/^[0-9A-Za-z]{1,64}$/.test(params.nonce ?? "")) {
+        throw new SiwsError("invalid-params", "`nonce` must be the alphanumeric nonce from the challenge");
+    }
+    const statement = params.statement ?? DEFAULT_SIWS_STATEMENT;
+    if (CONTROL_RE.test(statement)) {
+        throw new SiwsError("invalid-params", "`statement` must be a single line (no control characters)");
+    }
+    const uri = params.uri ?? locationField("origin") ?? `https://${domain}`;
+    if (CONTROL_RE.test(uri))
+        throw new SiwsError("invalid-params", "`uri` must not contain control characters");
+    const issuedAt = params.issuedAt ?? new Date().toISOString();
+    if (CONTROL_RE.test(issuedAt))
+        throw new SiwsError("invalid-params", "`issuedAt` must not contain control characters");
+    return {
+        domain,
+        address: params.address,
+        ...(statement ? { statement } : {}),
+        uri,
+        version: "1",
+        nonce: params.nonce,
+        issuedAt,
+    };
+}
+/**
+ * Render a `solana:signIn` input as SIWS message text, per the SIWS spec
+ * (identical to `createSignInMessageText` in @solana/wallet-standard-util).
+ * Wallets render this themselves; it is exported for tests, previews, and
+ * server-side expectations.
+ */
+export function buildSignInMessageText(input) {
+    let message = `${input.domain}${SIWS_HEADER_SUFFIX}\n`;
+    message += input.address;
+    if (input.statement)
+        message += `\n\n${input.statement}`;
+    const fields = [];
+    if (input.uri)
+        fields.push(`URI: ${input.uri}`);
+    if (input.version)
+        fields.push(`Version: ${input.version}`);
+    if (input.chainId)
+        fields.push(`Chain ID: ${input.chainId}`);
+    if (input.nonce)
+        fields.push(`Nonce: ${input.nonce}`);
+    if (input.issuedAt)
+        fields.push(`Issued At: ${input.issuedAt}`);
+    if (input.expirationTime)
+        fields.push(`Expiration Time: ${input.expirationTime}`);
+    if (input.notBefore)
+        fields.push(`Not Before: ${input.notBefore}`);
+    if (input.requestId)
+        fields.push(`Request ID: ${input.requestId}`);
+    if (input.resources) {
+        fields.push("Resources:");
+        for (const r of input.resources)
+            fields.push(`- ${r}`);
+    }
+    if (fields.length)
+        message += `\n\n${fields.join("\n")}`;
+    return message;
+}
+function apiBaseOf(cfg) {
+    return (cfg.apiBase ?? DEFAULT_CONNECT_BASE_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+async function postJson(cfg, path, body) {
+    if (!cfg.apiKey)
+        throw new SiwsError("invalid-params", "an X1ID apiKey is required");
+    const doFetch = cfg.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function")
+        throw new SiwsError("network", "no fetch available; pass fetchImpl");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), cfg.timeoutMs ?? 15_000);
+    let res;
+    try {
+        res = await doFetch(`${apiBaseOf(cfg)}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-api-key": cfg.apiKey },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        throw new SiwsError("network", `request to ${path} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        throw new SiwsError("network", `${path} returned non-JSON (HTTP ${res.status})`, undefined, res.status);
+    }
+    if (!res.ok) {
+        const b = (parsed ?? {});
+        const serverCode = typeof b.code === "string" ? b.code : undefined;
+        const message = typeof b.message === "string" ? b.message : `${path} returned HTTP ${res.status}`;
+        throw new SiwsError(siwsErrorCodeFor(serverCode, message), message, serverCode, res.status);
+    }
+    return parsed;
+}
+/** `POST /v1/auth/challenge {wallet, mode: "signin"}` — a single-use nonce. */
+export async function requestSignInChallenge(params) {
+    return requestConnectChallenge({ ...params, mode: "signin" });
+}
+/**
+ * `POST /v1/auth/challenge {wallet, mode?}` for any wallet-proof mode:
+ * `"signin"` (SIWS), `"tx"` (memo transaction; the response carries `memo`),
+ * or omitted (signMessage over `challenge`).
+ */
+export async function requestConnectChallenge(params) {
+    if (!params.wallet)
+        throw new SiwsError("invalid-params", "`wallet` (base58 address) is required");
+    const r = await postJson(params, "/v1/auth/challenge", {
+        wallet: params.wallet,
+        ...(params.mode ? { mode: params.mode } : {}),
+    });
+    if (!r || typeof r.nonce !== "string" || !r.nonce || typeof r.challenge !== "string") {
+        throw new SiwsError("api-error", "challenge response carried no nonce/challenge");
+    }
+    return r;
+}
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(bin);
+}
+function toBytes(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (ArrayBuffer.isView(v))
+        return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+    if (Array.isArray(v) && v.every((b) => Number.isInteger(b) && b >= 0 && b < 256))
+        return Uint8Array.from(v);
+    return null;
+}
+/**
+ * `POST /v1/auth/verify-signin` — the raw verify call. Accepts the wallet's
+ * byte outputs and encodes them as dev-api expects (signedMessage base64,
+ * signature base58), or pre-encoded strings passed through as-is.
+ */
+export async function verifySolanaSignIn(params) {
+    const signedMessage = typeof params.signedMessage === "string" ? params.signedMessage : bytesToBase64(params.signedMessage);
+    let signature;
+    if (typeof params.signature === "string") {
+        signature = params.signature;
+    }
+    else {
+        if (params.signature.length !== 64) {
+            throw new SiwsError("wallet-error", `expected a 64-byte ed25519 signature, got ${params.signature.length} bytes`);
+        }
+        signature = encodeBase58(params.signature);
+    }
+    const body = { nonce: params.nonce, signedMessage, signature };
+    return postJson(params, "/v1/auth/verify-signin", body);
+}
+// -----------------------------------------------------------------------------
+// One call
+// -----------------------------------------------------------------------------
+/** `POST /v1/auth/verify-tx` with the fully signed memo transaction (base64). */
+export async function verifySignInTransaction(params) {
+    const signedTransaction = typeof params.signedTransaction === "string" ? params.signedTransaction : bytesToBase64(params.signedTransaction);
+    return postJson(params, "/v1/auth/verify-tx", { nonce: params.nonce, signedTransaction });
+}
+/** `POST /v1/auth/verify` with a signMessage signature over the challenge
+ *  string (signature base58, `signer` = the wallet address). */
+export async function verifySignInMessage(params) {
+    let signature;
+    if (typeof params.signature === "string") {
+        signature = params.signature;
+    }
+    else {
+        if (params.signature.length !== 64) {
+            throw new SiwsError("wallet-error", `expected a 64-byte ed25519 signature, got ${params.signature.length} bytes`);
+        }
+        signature = encodeBase58(params.signature);
+    }
+    return postJson(params, "/v1/auth/verify", { nonce: params.nonce, signature, signer: params.signer });
+}
+// -----------------------------------------------------------------------------
+// Memo transaction (no web3.js)
+// -----------------------------------------------------------------------------
+/** X1ID's display-only sign-in fee payer on X1 MAINNET (System-owned, tiny
+ *  balance so wallet simulations pass; it never signs and the tx is never
+ *  sent). Pass it as `signinFeePayer` only against a deployment whose
+ *  `CONNECT_SIGNIN_FEE_PAYER` is this address (api.x1id.io on mainnet). */
+export const X1ID_MAINNET_SIGNIN_FEE_PAYER = "9kFEzXbNBJLTsvZwrTAcpxr6iLRqHPyu9yp8K4m2YwC3";
+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);
+    }
+}
+/**
+ * The unsigned, serialized LEGACY memo-only transaction the wallet signs for
+ * `/v1/auth/verify-tx`: exactly one SPL-Memo instruction carrying `memo`, with
+ * the user as the memo's signer. Byte-identical to the portal's
+ * `buildMemoTx` (portal/src/lib/wallet/memoTx.ts). It is never broadcast.
+ */
+export function buildSignInMemoTransaction(params) {
+    const u = decodeBase58(params.user, 32);
+    const m = decodeBase58(MEMO_PROGRAM_ID, 32);
+    const bh = decodeBase58(params.blockhash ?? PLACEHOLDER_BLOCKHASH, 32);
+    const p = params.feePayer ? decodeBase58(params.feePayer, 32) : null;
+    if (!u)
+        throw new SiwsError("invalid-params", "`user` must be a base58 32-byte address");
+    if (!m || !bh)
+        throw new SiwsError("invalid-params", "`blockhash` must be base58 of 32 bytes");
+    if (params.feePayer && !p)
+        throw new SiwsError("invalid-params", "`feePayer` must be a base58 32-byte address");
+    const data = new TextEncoder().encode(params.memo);
+    const msg = p
+        ? [
+            // 2 signers (payer, user), 1 readonly signed (user), 1 readonly unsigned (memo program)
+            2, 1, 1,
+            ...compactU16(3), ...p, ...u, ...m,
+            ...bh,
+            ...compactU16(1), 2, ...compactU16(1), 1, ...compactU16(data.length), ...data,
+        ]
+        : [
+            1, 0, 1,
+            ...compactU16(2), ...u, ...m,
+            ...bh,
+            ...compactU16(1), 1, ...compactU16(1), 0, ...compactU16(data.length), ...data,
+        ];
+    const sigCount = p ? 2 : 1;
+    return new Uint8Array([...compactU16(sigCount), ...new Uint8Array(64 * sigCount), ...msg]);
+}
+async function latestBlockhash(rpcUrl, doFetch) {
+    let bh;
+    try {
+        const res = await doFetch(rpcUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getLatestBlockhash", params: [{ commitment: "confirmed" }] }),
+        });
+        bh = (await res.json())?.result?.value?.blockhash;
+    }
+    catch (e) {
+        throw new SiwsError("network", `could not fetch a recent blockhash: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (typeof bh !== "string")
+        throw new SiwsError("network", "the RPC returned no blockhash");
+    return bh;
+}
+function isUserRejection(e) {
+    const err = e;
+    const m = `${(err && (err.message || err.reason || err.name)) ?? ""}`;
+    return err?.code === 4001 || /reject|denied|cancel/i.test(m);
+}
+/** The extension's background worker was asleep/unreachable (not a reject). */
+function isExtensionUnreachable(e) {
+    const msg = String(e?.message ?? e ?? "");
+    return /unexpected error|receiving end does not exist|could not establish connection|extension context|disconnected port/i.test(msg);
+}
+function withTimeout(p, ms) {
+    let t;
+    return Promise.race([
+        p.finally(() => clearTimeout(t)),
+        new Promise((_, rej) => {
+            t = setTimeout(() => rej(new SiwsError("wallet-timeout", "the wallet did not respond")), ms);
+        }),
+    ]);
+}
+function walletFailure(e, what) {
+    if (e instanceof SiwsError)
+        return e;
+    if (isUserRejection(e))
+        return new SiwsError("user-rejected", "the request was rejected in the wallet");
+    const msg = e?.message;
+    const err = new SiwsError("wallet-error", `${what}: ${typeof msg === "string" && msg ? msg : String(e)}`);
+    if (isExtensionUnreachable(e))
+        err.unreachable = true;
+    return err;
+}
+/** Stop the fallback chain: the user said no, or the wallet is gone. */
+function isFinal(e) {
+    return e.code === "user-rejected" || e.code === "wallet-timeout" || e.unreachable === true;
+}
+async function resolveAccount(wallet, account, timeoutMs) {
+    let acct = account ?? wallet.accounts?.[0];
+    if (acct)
+        return acct;
+    const connectFeat = wallet.features["standard:connect"];
+    if (typeof connectFeat?.connect !== "function") {
+        throw new SiwsError("wallet-error", "the wallet has no connected account and no standard:connect");
+    }
+    try {
+        const out = await withTimeout(connectFeat.connect(), timeoutMs);
+        acct = out?.accounts?.[0] ?? wallet.accounts?.[0];
+    }
+    catch (e) {
+        throw walletFailure(e, "wallet connect failed");
+    }
+    if (!acct)
+        throw new SiwsError("wallet-error", "the wallet connected without an account");
+    return acct;
+}
+function sigBytes(v) {
+    const o = v;
+    const b = toBytes(v) ?? (o && typeof o === "object" ? toBytes(o.signature) : null);
+    return b && b.length === 64 ? b : null;
+}
+// --- path 1: SIWS ------------------------------------------------------------
+async function proveWithSignIn(params, account, timeoutMs) {
+    const signInFeat = params.wallet.features["solana:signIn"];
+    const address = account.address;
+    // Validate domain/statement/uri BEFORE spending a challenge.
+    const input = buildSignInInput({
+        address,
+        nonce: "0",
+        ...(params.domain !== undefined ? { domain: params.domain } : {}),
+        ...(params.statement !== undefined ? { statement: params.statement } : {}),
+        ...(params.uri !== undefined ? { uri: params.uri } : {}),
+    });
+    const challenge = await requestSignInChallenge({ ...params, wallet: address });
+    let out;
+    try {
+        [out] = await withTimeout(signInFeat.signIn({ ...input, nonce: challenge.nonce }), timeoutMs);
+    }
+    catch (e) {
+        throw walletFailure(e, "solana:signIn failed");
+    }
+    const signed = toBytes(out?.signedMessage);
+    const sig = toBytes(out?.signature);
+    if (!out || !signed || !sig)
+        throw new SiwsError("wallet-error", "the wallet returned no sign-in signature");
+    if (sig.length !== 64)
+        throw new SiwsError("wallet-error", `the wallet returned a ${sig.length}-byte signature; expected 64`);
+    if (out.account?.address && out.account.address !== address) {
+        throw new SiwsError("wallet-error", "the wallet signed in with a different account than the challenge was issued for");
+    }
+    return verifySolanaSignIn({ ...params, nonce: challenge.nonce, signedMessage: signed, signature: sig });
+}
+/** True if `memo` is a verify-tx memo for this nonce that the client may sign:
+ *  the audience-bound `x1id-verify:<audience>:<nonce>` (matching `audience`
+ *  when the server sent one), or the v2 wallet-control challenge for this
+ *  wallet + nonce (dev-api's accepted alternative when no memo is returned). */
+function acceptableMemo(memo, ch, address) {
+    if (ch.audience !== undefined && memo === `${VERIFY_TX_MEMO_PREFIX}${ch.audience}:${ch.nonce}`)
+        return true;
+    if (ch.audience === undefined && memo.startsWith(VERIFY_TX_MEMO_PREFIX) && memo.endsWith(`:${ch.nonce}`))
+        return true;
+    return isV2WalletControl(memo, address, ch.nonce, ch.audience);
+}
+function isV2WalletControl(s, address, nonce, audience) {
+    if (audience !== undefined)
+        return s === `x1id-connect:v2:wallet-control:${audience}:${address}:${nonce}`;
+    return s.startsWith("x1id-connect:v2:wallet-control:") && s.endsWith(`:${address}:${nonce}`);
+}
+async function proveWithMemoTx(params, account, timeoutMs) {
+    const txFeat = params.wallet.features["solana:signTransaction"];
+    const address = account.address;
+    const ch = await requestConnectChallenge({ ...params, wallet: address, mode: "tx" });
+    // Signed verbatim — never rebuilt locally (R3-L2P-1).
+    const memo = ch.memo ?? ch.challenge;
+    if (!acceptableMemo(memo, ch, address)) {
+        throw new SiwsError("api-error", "the challenge memo is not an audience-bound sign-in memo for this nonce; refusing to sign it");
+    }
+    const doFetch = params.fetchImpl ?? globalThis.fetch;
+    const blockhash = params.blockhash ?? (params.rpcUrl ? await latestBlockhash(params.rpcUrl, doFetch) : PLACEHOLDER_BLOCKHASH);
+    const tx = buildSignInMemoTransaction({ user: address, memo, blockhash, feePayer: params.signinFeePayer ?? null });
+    let signed;
+    try {
+        const [out] = await withTimeout(txFeat.signTransaction({ account, transaction: tx }), timeoutMs);
+        signed = toBytes(out?.signedTransaction);
+    }
+    catch (e) {
+        throw walletFailure(e, "solana:signTransaction failed");
+    }
+    if (!signed)
+        throw new SiwsError("wallet-error", "the wallet returned no signed transaction");
+    return verifySignInTransaction({ ...params, nonce: ch.nonce, signedTransaction: signed });
+}
+async function proveWithSignMessage(params, account, timeoutMs) {
+    const msgFeat = params.wallet.features["solana:signMessage"];
+    const address = account.address;
+    const ch = await requestConnectChallenge({ ...params, wallet: address });
+    // A wallet with a primary @handle gets a handle-control challenge
+    // (`x1id-connect:v2:handle-control:<audience>:…`); both are v2 and
+    // audience-bound. Refuse anything else (an unbound v1 string).
+    const s = ch.challenge;
+    const okShape = isV2WalletControl(s, address, ch.nonce, ch.audience) ||
+        (s.startsWith(`x1id-connect:v2:handle-control:${ch.audience ?? ""}`) && s.endsWith(`:${ch.nonce}`));
+    if (!okShape) {
+        throw new SiwsError("api-error", "the challenge is not an audience-bound v2 Connect challenge; refusing to sign it");
+    }
+    let sig;
+    try {
+        const [out] = await withTimeout(msgFeat.signMessage({ account, message: new TextEncoder().encode(s) }), timeoutMs);
+        sig = sigBytes(out?.signature);
+    }
+    catch (e) {
+        throw walletFailure(e, "solana:signMessage failed");
+    }
+    if (!sig)
+        throw new SiwsError("wallet-error", "the wallet did not return a 64-byte ed25519 signature");
+    return verifySignInMessage({ ...params, nonce: ch.nonce, signature: sig, signer: address });
+}
+// -----------------------------------------------------------------------------
+// One call
+// -----------------------------------------------------------------------------
+/**
+ * Sign in with a Wallet Standard wallet via `solana:signIn` ONLY and return the
+ * X1ID Connect session. Throws {@link SiwsError} (`wallet-unsupported` when the
+ * wallet lacks `solana:signIn`). For automatic fallbacks use
+ * {@link signInWithWallet}.
+ *
+ * ```ts
+ * const session = await signInWithSolana({ wallet, apiKey: "x1id_..." });
+ * // session.token → `Authorization: Bearer …`; session.address; session.handle
+ * ```
+ */
+export async function signInWithSolana(params) {
+    const { wallet } = params;
+    if (!walletSupportsSignIn(wallet)) {
+        throw new SiwsError("wallet-unsupported", `${wallet?.name ?? "this wallet"} does not support Sign In With Solana (solana:signIn)`);
+    }
+    const timeoutMs = params.signTimeoutMs ?? 60_000;
+    const account = await resolveAccount(wallet, params.account, timeoutMs);
+    return proveWithSignIn(params, account, timeoutMs);
+}
+/**
+ * Sign in with any Wallet Standard wallet, falling back across the three
+ * wallet-control proofs the hosted API accepts: SIWS → never-sent memo
+ * transaction → signMessage (see the module docs). A user rejection or a
+ * wallet timeout stops immediately; otherwise the LAST path's error is thrown
+ * if every path fails. `wallet-unsupported` when the wallet implements none of
+ * `solana:signIn`, `solana:signTransaction`, `solana:signMessage`.
+ */
+export async function signInWithWallet(params) {
+    const { wallet } = params;
+    const features = wallet?.features ?? {};
+    const has = (k, fn) => typeof features[k]?.[fn] === "function";
+    const available = {
+        siws: has("solana:signIn", "signIn"),
+        "memo-tx": has("solana:signTransaction", "signTransaction"),
+        "sign-message": has("solana:signMessage", "signMessage"),
+    };
+    const order = (params.methods ?? ["siws", "memo-tx", "sign-message"]).filter((m) => available[m]);
+    if (order.length === 0) {
+        throw new SiwsError("wallet-unsupported", `${wallet?.name ?? "this wallet"} supports none of solana:signIn, solana:signTransaction, solana:signMessage`);
+    }
+    const timeoutMs = params.signTimeoutMs ?? 60_000;
+    const account = await resolveAccount(wallet, params.account, timeoutMs);
+    let last;
+    for (const method of order) {
+        params.onAttempt?.(method);
+        try {
+            const session = method === "siws"
+                ? await proveWithSignIn(params, account, timeoutMs)
+                : method === "memo-tx"
+                    ? await proveWithMemoTx(params, account, timeoutMs)
+                    : await proveWithSignMessage(params, account, timeoutMs);
+            return { ...session, method };
+        }
+        catch (e) {
+            const err = e instanceof SiwsError ? e : walletFailure(e, `${method} failed`);
+            // Bad caller input (e.g. no domain outside a browser) is not a wallet
+            // problem — surface it rather than silently degrading.
+            if (isFinal(err) || err.code === "invalid-params")
+                throw err;
+            last = err;
+        }
+    }
+    throw last ?? new SiwsError("wallet-error", "sign-in failed");
+}

package/dist/subname.js

@@ -173,6 +173,12 @@ export function buildCreateSubnameIx(p) {
     if (labelBytes.length === 0 || labelBytes.length > SUBNAME_LABEL_MAX_LEN) {
         throw new Error(`label must be 1..=${SUBNAME_LABEL_MAX_LEN} bytes`);
     }
+    // W171: a subname label follows handle-label grammar — a label like
+    // "Bad Label" (space, uppercase) otherwise builds and is only rejected on
+    // chain. Lowercase a-z / 0-9 with interior single hyphens only.
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(p.label) || p.label.includes("--")) {
+        throw new Error("label must be lowercase a-z, 0-9 and interior single hyphens only (no spaces, uppercase, or leading/trailing/double hyphen)");
+    }
     const encLabel = encVec(labelBytes);
     const data = new Uint8Array(8 + encLabel.length);
     data.set(CREATE_SUBNAME_DISCRIMINATOR, 0);

package/dist/textRecords.js

@@ -297,6 +297,13 @@ function checkKey(key) {
     if (bytes.length === 0 || bytes.length > TEXT_KEY_MAX_LEN) {
         throw new Error(`key must be 1..=${TEXT_KEY_MAX_LEN} bytes of UTF-8`);
     }
+    // W171: reject keys with spaces / control chars / non-ASCII — a key like
+    // "BAD KEY!" otherwise builds and only fails loosely downstream. Record keys
+    // are dotted identifiers (e.g. "agent.manifest", "com.twitter"): visible
+    // ASCII, no whitespace.
+    if (!/^[\x21-\x7e]+$/.test(key)) {
+        throw new Error('key must be visible ASCII with no spaces (e.g. "agent.manifest")');
+    }
     return bytes;
 }
 function checkValue(value) {

package/dist/transfer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `transfer` — hand an UNTOKENIZED handle to a new owner (a direct gift /
+ * reassignment of `handle.owner`). This is the plain-handle counterpart to a
+ * tokenized handle's pNFT transfer: a tokenized handle's ownership IS its NFT,
+ * so the program REFUSES `transfer` on one (`HandleIsTokenized`) — move the
+ * pNFT instead (see `pnftTransfer.ts`).
+ *
+ * Signed by the handle's CURRENT owner (`has_one = owner` on-chain). The
+ * program also refuses the move if the handle is locked (`require_unlocked`)
+ * or a live auction on it still has bids. It is NOT gated by the registry
+ * pause, so a treasury gift can be made even while registration is paused.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no web3.js.
+ * PDAs are NOT derived here (see delegate.ts's module docs); derive
+ * `["handle", name]` and `["auction", handle]` with your runtime's canonical
+ * `findProgramAddress` and pass them in.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** Anchor instruction discriminator: `sha256("global:transfer")[0..8]`. */
+export declare const TRANSFER_DISCRIMINATOR: Uint8Array;
+export interface TransferParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's CURRENT owner — must equal `handle.owner` on-chain. Signer. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` (or scoped `["handle", label, name]`) PDA. Must be
+     *  UNTOKENIZED; a tokenized handle is moved by transferring its pNFT. */
+    readonly handle: AddressLike;
+    /** The `["auction", handle]` PDA — read-only; the program reads it only to
+     *  refuse a transfer while a live auction still has bids. Pass the derived
+     *  address even if no auction account exists there. */
+    readonly auction: AddressLike;
+    /** The address to hand the handle to. */
+    readonly newOwner: AddressLike;
+    /** Scoped (under-TLD) handles only: the account(s) `verify_handle_pda` needs
+     *  to re-derive `["handle", label, name]`. Omit for a bare `@handle`. */
+    readonly remainingAccounts?: readonly AddressLike[];
+}
+/**
+ * Build `transfer(new_owner)`. The data is the 8-byte discriminator followed by
+ * the 32-byte new owner; the accounts are `owner` (signer), `handle` (writable)
+ * and the read-only `["auction", handle]` PDA, plus any scoped-TLD
+ * remaining-accounts. Returns an UNSIGNED instruction — sign with `owner`.
+ */
+export declare function buildTransferIx(p: TransferParams): BuiltInstruction;