@x1id/resolve 0.19.1 → 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/gate.js

@@ -15,6 +15,7 @@
  * attestor-signed `Attestation` account.
  */
 import { fetchAttestations, isHandleVerified, ATTESTATION_KIND_DNS, ATTESTATION_KIND_SOCIAL, ATTESTATION_KIND_X, ATTESTATION_KIND_DISCORD, ATTESTATION_KIND_GITHUB, ATTESTATION_KIND_TELEGRAM, } from "./attestation.js";
+import { ResolveError } from "./types.js";
 /** Named platform kinds, re-exported so callers gate without magic numbers. */
 export const GateKind = {
     dns: ATTESTATION_KIND_DNS,
@@ -29,7 +30,16 @@ export const GateKind = {
 export function attestationsPassGate(attestations, gate) {
     if (gate === "any-verified")
         return isHandleVerified(attestations);
-    const kinds = "kind" in gate ? [gate.kind] : gate.anyOf;
+    // W171: a malformed gate (null, a string other than "any-verified", or an
+    // object with neither `kind` nor `anyOf`) otherwise threw a raw
+    // `TypeError: Cannot use 'in' operator…`. Surface it as a typed ResolveError.
+    if (gate === null || typeof gate !== "object") {
+        throw new ResolveError("invalid-input", 'gate must be "any-verified", { kind } or { anyOf: [...] }', String(gate));
+    }
+    const kinds = "kind" in gate ? [gate.kind] : "anyOf" in gate ? gate.anyOf : null;
+    if (kinds === null) {
+        throw new ResolveError("invalid-input", "gate object needs a `kind` or `anyOf`", JSON.stringify(gate));
+    }
     return attestations.some((a) => !a.stale && !a.holderMismatch && kinds.includes(a.kind));
 }
 /** Fetch a handle's attestations and test the gate in one call. `handleAccount`,

package/dist/index.d.ts

@@ -42,6 +42,7 @@ export * from "./integrator.js";
 export * from "./voucher.js";
 export * from "./agent.js";
 export * from "./register.js";
+export * from "./transfer.js";
 export * from "./adminConfig.js";
 export * from "./lease.js";
 export * from "./accounts.js";
@@ -54,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

@@ -42,6 +42,7 @@ export * from "./integrator.js";
 export * from "./voucher.js";
 export * from "./agent.js";
 export * from "./register.js";
+export * from "./transfer.js";
 export * from "./adminConfig.js";
 export * from "./lease.js";
 // Was previously imported here for internal use only, never re-exported —
@@ -61,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/register.js

@@ -16,6 +16,7 @@
  * field this builder needs (the treasury address every registration pays).
  */
 import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { normalizeHandle } from "./parse.js";
 /** Anchor instruction discriminator: `sha256("global:register")[0..8]`. */
 export const REGISTER_DISCRIMINATOR = Uint8Array.from([
     211, 124, 67, 15, 211, 194, 178, 240,
@@ -73,6 +74,16 @@ export function buildRegisterIx(p) {
     if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
         throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
     }
+    // W171: the Handle PDA is derived from the CANONICAL name, so a non-canonical
+    // name (uppercase, surrounding space, …) builds an instruction the chain
+    // rejects with an opaque ConstraintSeeds (2006). normalizeHandle validates the
+    // grammar (ASCII, length, no leading/trailing/double hyphen, not all-digit)
+    // AND lowercases; require the caller to pass that canonical form so `handle`
+    // and the encoded name agree.
+    const canonical = normalizeHandle(p.name);
+    if (canonical !== p.name) {
+        throw new Error(`name must be the canonical handle "${canonical}" (got "${p.name}") — normalizeHandle() it and derive \`handle\` from the same value`);
+    }
     const nameBytes = new TextEncoder().encode(p.name);
     if (nameBytes.length < 1 || nameBytes.length > 32) {
         throw new Error("name must be 1..=32 bytes (UTF-8)");
@@ -123,6 +134,16 @@ export function buildRegisterReservedIx(p) {
     if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
         throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
     }
+    // W171: the Handle PDA is derived from the CANONICAL name, so a non-canonical
+    // name (uppercase, surrounding space, …) builds an instruction the chain
+    // rejects with an opaque ConstraintSeeds (2006). normalizeHandle validates the
+    // grammar (ASCII, length, no leading/trailing/double hyphen, not all-digit)
+    // AND lowercases; require the caller to pass that canonical form so `handle`
+    // and the encoded name agree.
+    const canonical = normalizeHandle(p.name);
+    if (canonical !== p.name) {
+        throw new Error(`name must be the canonical handle "${canonical}" (got "${p.name}") — normalizeHandle() it and derive \`handle\` from the same value`);
+    }
     const nameBytes = new TextEncoder().encode(p.name);
     if (nameBytes.length < 1 || nameBytes.length > 32) {
         throw new Error("name must be 1..=32 bytes (UTF-8)");
@@ -194,6 +215,16 @@ export function buildRegisterWithFortiIx(p) {
     if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
         throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
     }
+    // W171: the Handle PDA is derived from the CANONICAL name, so a non-canonical
+    // name (uppercase, surrounding space, …) builds an instruction the chain
+    // rejects with an opaque ConstraintSeeds (2006). normalizeHandle validates the
+    // grammar (ASCII, length, no leading/trailing/double hyphen, not all-digit)
+    // AND lowercases; require the caller to pass that canonical form so `handle`
+    // and the encoded name agree.
+    const canonical = normalizeHandle(p.name);
+    if (canonical !== p.name) {
+        throw new Error(`name must be the canonical handle "${canonical}" (got "${p.name}") — normalizeHandle() it and derive \`handle\` from the same value`);
+    }
     const nameBytes = new TextEncoder().encode(p.name);
     if (nameBytes.length < 1 || nameBytes.length > 32) {
         throw new Error("name must be 1..=32 bytes (UTF-8)");