@x1id/resolve 0.19.2 → 0.21.0

package/README.md

@@ -620,6 +620,86 @@ of this zero-dependency package). Use the MCP server's `prepare_x402_payment`
 > `confirmed` gets a `402 "payment not yet confirmed; finalize it and retry"`.
 > Poll the signature to `finalized` before the retry.
 
+## Sign in with Solana
+
+Sign a user in with any [Wallet Standard](https://github.com/wallet-standard/wallet-standard)
+wallet that implements `solana:signIn` (SIWS), against the hosted X1ID Connect
+API. You get back a Bearer session proving **wallet control**; the wallet's
+primary `@handle`, if it has one, comes along as metadata.
+
+```ts
+import { signInWithSolana, SiwsError } from "@x1id/resolve";
+
+try {
+  const session = await signInWithSolana({
+    wallet,                 // a Wallet Standard wallet object (e.g. from getWallets().get())
+    apiKey: "x1id_…",       // your integrator key from developers.x1id.io
+    // domain defaults to location.host. It must be on your deployment's SIWS allowlist.
+    statement: "Sign in to Example.",
+  });
+  // session.token (send as `Authorization: Bearer …`), session.address, session.handle
+} catch (e) {
+  if (e instanceof SiwsError) {
+    // e.code: "wallet-unsupported" | "user-rejected" | "domain-not-allowed"
+    //       | "nonce-expired" | "invalid-params" | "wallet-timeout" | "wallet-error" | "network" | "api-error"
+  }
+}
+```
+
+### With fallbacks: `signInWithWallet`
+
+Some wallets lack `solana:signIn` or implement it badly, and a Ledger refuses
+message signing. `signInWithWallet` takes the same arguments and tries, in the
+developers.x1id.io order:
+
+1. SIWS (`solana:signIn`);
+2. a signed, **never-sent** memo transaction (`solana:signTransaction`) whose
+   only instruction is an SPL-Memo carrying the server's
+   `x1id-verify:<audience>:<nonce>`;
+3. `solana:signMessage` over the server's
+   `x1id-connect:v2:wallet-control:<audience>:<address>:<nonce>`.
+
+```ts
+import { signInWithWallet, X1ID_MAINNET_SIGNIN_FEE_PAYER } from "@x1id/resolve";
+
+const { method, ...session } = await signInWithWallet({
+  wallet,
+  apiKey: "x1id_…",
+  rpcUrl: "https://rpc.mainnet.x1.xyz",           // optional: recent blockhash for the memo tx
+  signinFeePayer: X1ID_MAINNET_SIGNIN_FEE_PAYER,   // optional: no-fee layout (api.x1id.io mainnet)
+});
+```
+
+A user rejection or a wallet timeout stops the chain, so the user is never
+prompted twice after saying no. The audience (your key id) is part of every
+signed string, and the SDK signs the server's strings verbatim. It refuses to
+sign a memo or challenge that is not bound to an audience. Without
+`signinFeePayer` the user is the memo transaction's fee payer, which every
+deployment accepts. The transaction is never sent either way. Outside a
+browser, pass `domain` or set `methods: ["memo-tx", "sign-message"]`.
+
+The steps are also exported on their own, for wallets you drive yourself:
+
+| function | does |
+|---|---|
+| `requestSignInChallenge({ apiKey, wallet, apiBase? })` | `POST /v1/auth/challenge {wallet, mode:"signin"}` → `{ nonce, expires_at, … }` |
+| `buildSignInInput({ domain?, address, nonce, statement?, uri?, issuedAt? })` | the `solana:signIn` input: domain, address, statement, uri, version `"1"`, nonce, issuedAt |
+| `verifySolanaSignIn({ apiKey, nonce, signedMessage, signature, apiBase? })` | `POST /v1/auth/verify-signin` (signed bytes as base64, signature as base58) → session |
+| `buildSignInMessageText(input)` | the SIWS message text a wallet renders from that input |
+| `requestConnectChallenge({ apiKey, wallet, mode? })` | challenge for `"signin"`, `"tx"` (adds `memo`), or signMessage (no mode) |
+| `buildSignInMemoTransaction({ user, memo, blockhash?, feePayer? })` | the unsigned memo-only legacy transaction (no web3.js) |
+| `verifySignInTransaction({ apiKey, nonce, signedTransaction })` | `POST /v1/auth/verify-tx` |
+| `verifySignInMessage({ apiKey, nonce, signature, signer })` | `POST /v1/auth/verify` |
+
+The server checks that line 1 is `<domain> wants you to sign in with your Solana account:`
+with an allowed domain, that line 2 is the challenged wallet, that a `Nonce:` line
+carries the single-use challenge nonce, and the ed25519 signature (raw bytes or
+the SIMD-0048 off-chain envelope). A nonce is single-use and expires, so on
+`nonce-expired` call `signInWithSolana` again.
+
+This is the hosted-session flow. For a server-less proof your own backend
+verifies, see `signInWithX1ID` in [SIGNIN.md](./SIGNIN.md).
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:

package/dist/connect.d.ts

@@ -13,7 +13,7 @@
  *
  * So this flow proves wallet control a different, robust way: the wallet signs a
  * throwaway MEMO TRANSACTION — one SPL-Memo instruction carrying
- * `x1id-verify:<nonce>`, fee-paid by the wallet, never broadcast. The hosted
+ * `x1id-verify:<audience>:<nonce>`, fee-paid by the wallet, never broadcast. The hosted
  * `POST /v1/auth/verify-tx` endpoint deserializes the signed artifact, asserts
  * it is EXACTLY that memo (no disguised transfer/approval), that the fee payer
  * is the wallet, that the memo binds our single-use nonce, and verifies the
@@ -33,13 +33,19 @@
  * free of a hard web3 dependency and tests can supply a fake.
  */
 /** Memo prefix the verify-tx proof binds to. The signed memo instruction's
- *  UTF-8 data MUST be EXACTLY `x1id-verify:<nonce>` — the server rejects any
- *  other data, which is what kills replay of an unrelated signed transaction. */
+ *  UTF-8 data MUST be EXACTLY `x1id-verify:<audience>:<nonce>` — the server
+ *  rejects any other data, which is what kills replay of an unrelated signed
+ *  transaction. The AUDIENCE (your API key id, or developers.x1id.io for the
+ *  Developer Portal) is returned by the challenge as `audience` and binds the
+ *  signature to the application it was made for (R3-L2P-1); the hosted API no
+ *  longer accepts the unbound `x1id-verify:<nonce>`. */
 export declare const VERIFY_TX_MEMO_PREFIX: "x1id-verify:";
 /** Canonical SPL Memo program id — the program the challenge memo rides on. */
 export declare const MEMO_PROGRAM_ID: "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
-/** The exact memo string for a given challenge nonce. */
-export declare function verifyTxMemo(nonce: string): string;
+/** The exact memo string for a challenge nonce and its audience. Without an
+ *  audience this is the legacy unbound form, which the current hosted API
+ *  REJECTS — always pass the challenge's `audience` (or use its `memo`). */
+export declare function verifyTxMemo(nonce: string, audience?: string): string;
 /** The slice of a web3.js `PublicKey` used here. */
 export interface PublicKeyInstance {
     toBytes(): Uint8Array;
@@ -87,10 +93,14 @@ export declare const PLACEHOLDER_BLOCKHASH: "11111111111111111111111111111111";
 export interface BuildVerifyTxChallengeParams {
     /** The single-use nonce from the tx-mode challenge. */
     readonly nonce: string;
-    /** The memo the server returned (`x1id-verify:<nonce>`). Optional — derived
-     *  from `nonce` when omitted; when supplied it MUST equal that, or the build
+    /** The memo the server returned (`x1id-verify:<audience>:<nonce>`) —
+     *  RECOMMENDED: pass it verbatim. When omitted it is derived from `nonce` +
+     *  `audience`. When supplied it MUST be an `x1id-verify:` memo for THIS
+     *  nonce (and, if `audience` is given, for that audience), or the build
      *  throws (catches a client that paired the wrong nonce/memo). */
     readonly memo?: string;
+    /** The challenge's `audience` (R3-L2P-1). */
+    readonly audience?: string;
     /** The signing wallet, base58 — becomes the fee payer AND the memo signer. */
     readonly feePayer: string;
     /** A recent blockhash. Defaults to {@link PLACEHOLDER_BLOCKHASH} (the tx is
@@ -101,7 +111,7 @@ export interface BuildVerifyTxChallengeParams {
  * Build the memo-only challenge transaction the wallet signs for verify-tx.
  *
  * The result is a legacy `Transaction` with EXACTLY one instruction: an SPL-Memo
- * instruction whose data is the UTF-8 bytes of `x1id-verify:<nonce>`, with the
+ * instruction whose data is the UTF-8 bytes of `x1id-verify:<audience>:<nonce>`, with the
  * fee payer listed as a required signer on that instruction. Nothing else — no
  * transfer, no compute-budget, no durable nonce — so the signed artifact can
  * only ever be a sign-in proof, never a disguised value-moving transaction. The
@@ -136,6 +146,8 @@ export interface ConnectSession {
 export interface TxChallenge {
     readonly nonce: string;
     readonly memo: string;
+    /** The audience the memo names (R3-L2P-1); absent from older deployments. */
+    readonly audience?: string;
     readonly handle: string | null;
     readonly expires_at: number;
 }

package/dist/connect.js

@@ -13,7 +13,7 @@
  *
  * So this flow proves wallet control a different, robust way: the wallet signs a
  * throwaway MEMO TRANSACTION — one SPL-Memo instruction carrying
- * `x1id-verify:<nonce>`, fee-paid by the wallet, never broadcast. The hosted
+ * `x1id-verify:<audience>:<nonce>`, fee-paid by the wallet, never broadcast. The hosted
  * `POST /v1/auth/verify-tx` endpoint deserializes the signed artifact, asserts
  * it is EXACTLY that memo (no disguised transfer/approval), that the fee payer
  * is the wallet, that the memo binds our single-use nonce, and verifies the
@@ -33,14 +33,26 @@
  * free of a hard web3 dependency and tests can supply a fake.
  */
 /** Memo prefix the verify-tx proof binds to. The signed memo instruction's
- *  UTF-8 data MUST be EXACTLY `x1id-verify:<nonce>` — the server rejects any
- *  other data, which is what kills replay of an unrelated signed transaction. */
+ *  UTF-8 data MUST be EXACTLY `x1id-verify:<audience>:<nonce>` — the server
+ *  rejects any other data, which is what kills replay of an unrelated signed
+ *  transaction. The AUDIENCE (your API key id, or developers.x1id.io for the
+ *  Developer Portal) is returned by the challenge as `audience` and binds the
+ *  signature to the application it was made for (R3-L2P-1); the hosted API no
+ *  longer accepts the unbound `x1id-verify:<nonce>`. */
 export const VERIFY_TX_MEMO_PREFIX = "x1id-verify:";
 /** Canonical SPL Memo program id — the program the challenge memo rides on. */
 export const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
-/** The exact memo string for a given challenge nonce. */
-export function verifyTxMemo(nonce) {
-    return VERIFY_TX_MEMO_PREFIX + nonce;
+/** An audience: a key id (16 base64url chars) or a bare DNS name. */
+const AUDIENCE_RE = /^[A-Za-z0-9._-]{1,253}$/;
+/** The exact memo string for a challenge nonce and its audience. Without an
+ *  audience this is the legacy unbound form, which the current hosted API
+ *  REJECTS — always pass the challenge's `audience` (or use its `memo`). */
+export function verifyTxMemo(nonce, audience) {
+    if (audience === undefined)
+        return VERIFY_TX_MEMO_PREFIX + nonce;
+    if (!AUDIENCE_RE.test(audience))
+        throw new Error(`invalid audience "${audience}"`);
+    return `${VERIFY_TX_MEMO_PREFIX}${audience}:${nonce}`;
 }
 /** 32 zero-bytes in base58 — a structurally valid blockhash. The transaction is
  *  NEVER broadcast, so a placeholder blockhash is fine; a wallet that insists on
@@ -50,7 +62,7 @@ export const PLACEHOLDER_BLOCKHASH = "11111111111111111111111111111111";
  * Build the memo-only challenge transaction the wallet signs for verify-tx.
  *
  * The result is a legacy `Transaction` with EXACTLY one instruction: an SPL-Memo
- * instruction whose data is the UTF-8 bytes of `x1id-verify:<nonce>`, with the
+ * instruction whose data is the UTF-8 bytes of `x1id-verify:<audience>:<nonce>`, with the
  * fee payer listed as a required signer on that instruction. Nothing else — no
  * transfer, no compute-budget, no durable nonce — so the signed artifact can
  * only ever be a sign-in proof, never a disguised value-moving transaction. The
@@ -62,9 +74,20 @@ export function buildVerifyTxChallenge(web3, params) {
         throw new Error("nonce is required");
     if (typeof feePayer !== "string" || feePayer.length === 0)
         throw new Error("feePayer is required");
-    const memo = params.memo ?? verifyTxMemo(nonce);
-    if (memo !== verifyTxMemo(nonce)) {
-        throw new Error(`memo must be exactly "${verifyTxMemo(nonce)}" for this nonce`);
+    const memo = params.memo ?? verifyTxMemo(nonce, params.audience);
+    if (params.audience !== undefined) {
+        const want = verifyTxMemo(nonce, params.audience);
+        if (memo !== want)
+            throw new Error(`memo must be exactly "${want}" for this nonce`);
+    }
+    else {
+        // No audience given: accept the server's audience-bound memo for this
+        // nonce, or the legacy unbound form (older deployments).
+        const rest = memo.startsWith(VERIFY_TX_MEMO_PREFIX) ? memo.slice(VERIFY_TX_MEMO_PREFIX.length) : null;
+        const aud = rest !== null && rest.endsWith(`:${nonce}`) ? rest.slice(0, -(nonce.length + 1)) : null;
+        if (rest !== nonce && !(aud !== null && AUDIENCE_RE.test(aud))) {
+            throw new Error(`memo must be "${VERIFY_TX_MEMO_PREFIX}<audience>:${nonce}" for this nonce`);
+        }
     }
     const payer = new web3.PublicKey(feePayer);
     const memoProgram = new web3.PublicKey(MEMO_PROGRAM_ID);
@@ -169,6 +192,7 @@ export async function signinWithTx(cfg, params) {
     const tx = buildVerifyTxChallenge(params.web3, {
         nonce: challenge.nonce,
         memo: challenge.memo,
+        ...(typeof challenge.audience === "string" ? { audience: challenge.audience } : {}),
         feePayer: params.wallet,
         ...(params.blockhash !== undefined ? { blockhash: params.blockhash } : {}),
     });

package/dist/index.d.ts

@@ -55,6 +55,7 @@ export * from "./pnftTransfer.js";
 export * from "./payment.js";
 export * from "./signin.js";
 export * from "./connect.js";
+export * from "./siws.js";
 export * from "./domainProof.js";
 export { scopedTldCandidate, namespaceIsActive, makeScopedHandleDeriver, type ScopedCandidate, type ScopedHandleDeriver, } from "./scoped.js";
 import { type Chain, type Resolved } from "./types.js";

package/dist/index.js

@@ -62,6 +62,7 @@ export * from "./pnftTransfer.js";
 export * from "./payment.js";
 export * from "./signin.js";
 export * from "./connect.js";
+export * from "./siws.js";
 export * from "./domainProof.js";
 // Named (not `export *`): `NAMESPACE_MAX_LEN` is already exported by
 // adminMarket.js, and two `export *` sharing a name would make it ambiguous

package/dist/siws.d.ts

@@ -0,0 +1,310 @@
+/**
+ * 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 { type ConnectSession } from "./connect.js";
+/**
+ * - `wallet-unsupported` — the wallet does not implement `solana:signIn` (or,
+ *   for `signInWithWallet`, none of signIn / signTransaction / signMessage).
+ * - `user-rejected` — the user declined in the wallet.
+ * - `domain-not-allowed` — dev-api rejected the domain named in the message
+ *   (it is not on the deployment's SIWS allowlist).
+ * - `nonce-expired` — the challenge expired, was already used, or is unknown;
+ *   request a fresh one and retry.
+ * - `invalid-params` — bad input (missing apiKey/domain, injection in a field).
+ * - `wallet-timeout` — the wallet never answered.
+ * - `wallet-error` — the wallet failed or returned an unusable result.
+ * - `network` — the request did not complete (no fetch, timeout, non-JSON).
+ * - `api-error` — any other dev-api error; see `serverCode` / `status`.
+ */
+export type SiwsErrorCode = "wallet-unsupported" | "user-rejected" | "domain-not-allowed" | "nonce-expired" | "invalid-params" | "wallet-timeout" | "wallet-error" | "network" | "api-error";
+export declare class SiwsError extends Error {
+    readonly code: SiwsErrorCode;
+    /** dev-api's own error code (e.g. `CHALLENGE_EXPIRED`), when it sent one. */
+    readonly serverCode?: string | undefined;
+    /** HTTP status, when the error came from a response. */
+    readonly status?: number | undefined;
+    constructor(code: SiwsErrorCode, message: string, 
+    /** dev-api's own error code (e.g. `CHALLENGE_EXPIRED`), when it sent one. */
+    serverCode?: string | undefined, 
+    /** HTTP status, when the error came from a response. */
+    status?: number | undefined);
+}
+/** Map a dev-api error response onto a {@link SiwsErrorCode}. */
+export declare function siwsErrorCodeFor(serverCode: string | undefined, message: string | undefined): SiwsErrorCode;
+/** `solana:signIn` input (Phantom's SIWS spec / @solana/wallet-standard-features). */
+export interface SolanaSignInInput {
+    readonly domain?: string;
+    readonly address?: string;
+    readonly statement?: string;
+    readonly uri?: string;
+    readonly version?: string;
+    readonly chainId?: string;
+    readonly nonce?: string;
+    readonly issuedAt?: string;
+    readonly expirationTime?: string;
+    readonly notBefore?: string;
+    readonly requestId?: string;
+    readonly resources?: readonly string[];
+}
+export interface WalletStandardAccount {
+    readonly address: string;
+    readonly publicKey?: Uint8Array;
+}
+export interface SolanaSignInOutput {
+    readonly account: WalletStandardAccount;
+    readonly signedMessage: Uint8Array;
+    readonly signature: Uint8Array;
+    readonly signatureType?: string;
+}
+/** The slice of a Wallet Standard wallet this module uses. */
+export interface SignInCapableWallet {
+    readonly name?: string;
+    readonly accounts?: readonly WalletStandardAccount[];
+    readonly features: Record<string, unknown>;
+}
+/** True if `wallet` implements `solana:signIn`. */
+export declare function walletSupportsSignIn(wallet: SignInCapableWallet | null | undefined): boolean;
+/** The SIWS message line-1 suffix dev-api's verifier matches on. */
+export declare const SIWS_HEADER_SUFFIX: " wants you to sign in with your Solana account:";
+/** Default statement shown in the wallet. */
+export declare const DEFAULT_SIWS_STATEMENT: "Sign in with your wallet. This does not send a transaction.";
+export interface BuildSignInInputParams {
+    /** The host the user is signing in to (e.g. `app.example.com`). Must be on
+     *  your deployment's SIWS allowlist. Defaults to `globalThis.location.host`. */
+    readonly domain?: string;
+    /** The wallet address (base58) the challenge was issued for. */
+    readonly address: string;
+    /** The challenge nonce from {@link requestSignInChallenge}. */
+    readonly nonce: string;
+    /** Human-readable statement the wallet displays. Defaults to
+     *  {@link DEFAULT_SIWS_STATEMENT}; pass `""` to omit it. */
+    readonly statement?: string;
+    /** Defaults to `globalThis.location.origin`, else `https://<domain>`. */
+    readonly uri?: string;
+    /** ISO-8601; defaults to now. */
+    readonly issuedAt?: string;
+}
+/**
+ * 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 declare function buildSignInInput(params: BuildSignInInputParams): SolanaSignInInput;
+/**
+ * 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 declare function buildSignInMessageText(input: SolanaSignInInput & {
+    domain: string;
+    address: string;
+}): string;
+export interface SiwsApiConfig {
+    /** Your X1ID integrator API key (sent as `x-api-key`). */
+    readonly apiKey: string;
+    /** API origin. Defaults to `https://api.x1id.io`; a trailing `/v1` is tolerated. */
+    readonly apiBase?: string;
+    /** Inject a `fetch` (tests, non-global-fetch runtimes). */
+    readonly fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms (default 15_000). */
+    readonly timeoutMs?: number;
+}
+/** `POST /v1/auth/challenge` response for a `mode: "signin"` wallet challenge. */
+export interface SignInChallengeResponse {
+    readonly nonce: string;
+    readonly handle: string | null;
+    /** The exact string to sign for the signMessage path
+     *  (`x1id-connect:v2:wallet-control:<audience>:<address>:<nonce>`). */
+    readonly challenge: string;
+    /** The audience the signed bytes name (R3-L2P-1): your API key id, or the
+     *  portal's domain for the portal key. Absent from a pre-#608 API. */
+    readonly audience?: string;
+    /** Tx mode only: the exact memo (`x1id-verify:<audience>:<nonce>`). */
+    readonly memo?: string;
+    readonly signature_encoding: string;
+    readonly expires_at: number;
+    readonly proves: string;
+    readonly disclaimer: string;
+}
+/** Body of `POST /v1/auth/verify-signin`. */
+export interface VerifySignInBody {
+    readonly nonce: string;
+    /** base64 of the EXACT bytes the wallet signed. */
+    readonly signedMessage: string;
+    /** base58 of the 64-byte ed25519 signature. */
+    readonly signature: string;
+}
+/** `POST /v1/auth/challenge {wallet, mode: "signin"}` — a single-use nonce. */
+export declare function requestSignInChallenge(params: SiwsApiConfig & {
+    readonly wallet: string;
+}): Promise<SignInChallengeResponse>;
+/**
+ * `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 declare function requestConnectChallenge(params: SiwsApiConfig & {
+    readonly wallet: string;
+    readonly mode?: "signin" | "tx";
+}): Promise<SignInChallengeResponse>;
+/**
+ * `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 declare function verifySolanaSignIn(params: SiwsApiConfig & {
+    readonly nonce: string;
+    readonly signedMessage: Uint8Array | string;
+    readonly signature: Uint8Array | string;
+}): Promise<ConnectSession>;
+/** `POST /v1/auth/verify-tx` with the fully signed memo transaction (base64). */
+export declare function verifySignInTransaction(params: SiwsApiConfig & {
+    readonly nonce: string;
+    readonly signedTransaction: Uint8Array | string;
+}): Promise<ConnectSession>;
+/** `POST /v1/auth/verify` with a signMessage signature over the challenge
+ *  string (signature base58, `signer` = the wallet address). */
+export declare function verifySignInMessage(params: SiwsApiConfig & {
+    readonly nonce: string;
+    readonly signature: Uint8Array | string;
+    readonly signer: string;
+}): Promise<ConnectSession>;
+/** 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 declare const X1ID_MAINNET_SIGNIN_FEE_PAYER: "9kFEzXbNBJLTsvZwrTAcpxr6iLRqHPyu9yp8K4m2YwC3";
+export interface BuildSignInMemoTransactionParams {
+    /** The signing wallet (base58). */
+    readonly user: string;
+    /** The memo, verbatim from the challenge (`x1id-verify:<audience>:<nonce>`). */
+    readonly memo: string;
+    /** A recent blockhash; defaults to the all-ones placeholder (never sent). */
+    readonly blockhash?: string;
+    /** Display-only fee payer for dev-api's no-fee layout (user = signer index 1).
+     *  Null/omitted = the user pays and signs alone (always accepted). */
+    readonly feePayer?: string | null;
+}
+/**
+ * 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 declare function buildSignInMemoTransaction(params: BuildSignInMemoTransactionParams): Uint8Array;
+export interface SignInWithSolanaParams extends SiwsApiConfig {
+    /** A Wallet Standard wallet implementing `solana:signIn`. */
+    readonly wallet: SignInCapableWallet;
+    /** The account to sign in with. Defaults to the wallet's first account
+     *  (connecting via `standard:connect` first if it has none). */
+    readonly account?: WalletStandardAccount;
+    /** Defaults to `globalThis.location.host`. */
+    readonly domain?: string;
+    readonly statement?: string;
+    readonly uri?: string;
+    /** How long to wait for the wallet, ms (default 60_000). */
+    readonly signTimeoutMs?: number;
+}
+/**
+ * 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 declare function signInWithSolana(params: SignInWithSolanaParams): Promise<ConnectSession>;
+export type SignInMethod = "siws" | "memo-tx" | "sign-message";
+export interface SignInWithWalletParams extends SignInWithSolanaParams {
+    /** Paths to try, in order. Default: all three, SIWS → memo tx → signMessage
+     *  (the developers.x1id.io order). */
+    readonly methods?: readonly SignInMethod[];
+    /** Memo path: display-only fee payer for dev-api's no-fee layout. Must equal
+     *  the deployment's CONNECT_SIGNIN_FEE_PAYER (on api.x1id.io mainnet:
+     *  {@link X1ID_MAINNET_SIGNIN_FEE_PAYER}). Default null: the user is the fee
+     *  payer (accepted by every deployment; the tx is never sent either way). */
+    readonly signinFeePayer?: string | null;
+    /** Memo path: an RPC to fetch a recent blockhash from (wallets simulate the
+     *  transaction before signing, and some refuse a stale one). */
+    readonly rpcUrl?: string;
+    /** Memo path: a blockhash to use as-is (overrides `rpcUrl`). Default: the
+     *  all-ones placeholder. */
+    readonly blockhash?: string;
+    /** Called before each path is tried (for UI copy / telemetry). */
+    readonly onAttempt?: (method: SignInMethod) => void;
+}
+/** A session plus the path that produced it. */
+export type WalletSignInResult = ConnectSession & {
+    readonly method: SignInMethod;
+};
+/**
+ * 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 declare function signInWithWallet(params: SignInWithWalletParams): Promise<WalletSignInResult>;

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/voucher.d.ts

@@ -22,8 +22,8 @@
  *   escrows the mint price (a snapshot of the live price) into
  *   `["voucher", name]` and reserves the voucher slot. `recipient` bound ⇒ the
  *   claim registers the handle to that wallet no matter who submits; `null` ⇒
- *   open-code (the claimer owns it) and `claimSecretHash` (= `sha256(secret)`)
- *   is REQUIRED (M72) — the claimer must present the matching `secret`. An optional integrator referrer (the same trailing accounts as
+ *   a bound recipient (audit S6 — open/recipient-less vouchers were removed as
+ *   front-runnable; `claimSecretHash` is vestigial and rejected). An optional integrator referrer (the same trailing accounts as
  *   `register`, from `integrator.ts`) is snapshotted so the claim can split
  *   the escrow. `expiresAt` must be strictly in the future.
  * - `claim_voucher(name)` registers the handle, drawing the fee from the

package/dist/voucher.js

@@ -22,8 +22,8 @@
  *   escrows the mint price (a snapshot of the live price) into
  *   `["voucher", name]` and reserves the voucher slot. `recipient` bound ⇒ the
  *   claim registers the handle to that wallet no matter who submits; `null` ⇒
- *   open-code (the claimer owns it) and `claimSecretHash` (= `sha256(secret)`)
- *   is REQUIRED (M72) — the claimer must present the matching `secret`. An optional integrator referrer (the same trailing accounts as
+ *   a bound recipient (audit S6 — open/recipient-less vouchers were removed as
+ *   front-runnable; `claimSecretHash` is vestigial and rejected). An optional integrator referrer (the same trailing accounts as
  *   `register`, from `integrator.ts`) is snapshotted so the claim can split
  *   the escrow. `expiresAt` must be strictly in the future.
  * - `claim_voucher(name)` registers the handle, drawing the fee from the
@@ -171,8 +171,19 @@ export function decodePrepaidVoucher(data) {
 export function buildCreateVoucherIx(p) {
     const name = encString(p.name);
     const recipient = p.recipient ?? null;
+    // Audit S6: the program now REFUSES a recipient-less voucher (the claim tx
+    // reveals the secret in cleartext, so an open voucher is front-runnable —
+    // error 6106 VoucherMustBeBound). `claimSecretHash` is NO LONGER a second
+    // factor: with a recipient mandatory the program stores None and ignores any
+    // hash. Throw on both so no integrator believes either still works.
+    if (recipient === null) {
+        throw new Error("a voucher must bind its recipient (open secret-code vouchers are front-runnable and were disabled on-chain)");
+    }
+    if (p.claimSecretHash != null) {
+        throw new Error("claimSecretHash is removed — vouchers are recipient-bound and carry no claim secret (the program ignores it)");
+    }
     const recBytes = recipient === null ? Uint8Array.from([0]) : Uint8Array.from([1, ...toBytes32(recipient, "recipient")]);
-    const hashBytes = encOption32(p.claimSecretHash ?? null);
+    const hashBytes = encOption32(null); // S6: always None (a supplied hash throws above)
     const data = new Uint8Array(8 + name.length + 1 + recBytes.length + 8 + hashBytes.length);
     let o = 0;
     data.set(CREATE_VOUCHER_DISCRIMINATOR, o);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.19.2",
+  "version": "0.21.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",