@x1id/resolve 0.21.0 → 0.23.0

package/dist/x402.d.ts

@@ -21,12 +21,21 @@
  * its own SVM chain, but `@x402/core`'s reference client/facilitator only route
  * the `solana:*` scheme family — so to let ANY standard, unmodified x402 client
  * or wallet pay an x1id agent out of the box, X1 testnet uses the CAIP-30 form
- * keyed on X1's genesis. (Fortiswap's self-hosted X1 facilitator uses the
- * identical id.) An earlier release used a principled `"x1:<full-genesis>"`
+ * keyed on X1's genesis. x1id's X1 rail is standalone and self-verified: the
+ * buyer self-sponsors and broadcasts, and the seller checks the finalized
+ * transaction on chain itself; no external facilitator is involved. An
+ * earlier release used a principled `"x1:<full-genesis>"`
  * extension; it was OSS-incompatible, so this migrated to CAIP-30 —
  * {@link X1_LEGACY_TESTNET_NETWORK} is kept only for reading older manifests.
  * Verified against `getGenesisHash` (full hash
  * `C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho`).
+ *
+ * # HTTP headers (x402 v2 transport)
+ *
+ * api.x1id.io sends the 402 body also as `PAYMENT-REQUIRED` (base64 JSON),
+ * accepts the payment in `PAYMENT-SIGNATURE` (base64 JSON; the v1 name
+ * `X-PAYMENT` still works), and returns `PAYMENT-RESPONSE` plus the v1
+ * `X-PAYMENT-RESPONSE` on success.
  */
 /** X1 testnet's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
  *  genesis hash — so unmodified OSS x402 clients route to it (#8325). */
@@ -72,9 +81,23 @@ export interface X402PaymentRequirements {
          *  no sponsor (see docs/x402.md): this SDK always sets it to the
          *  BUYER's own address (self-sponsored, no facilitator, no custody). */
         readonly feePayer: string;
-        /** UTF-8, <=256 bytes. Lets a seller correlate the on-chain payment to
-         *  an invoice without a unique deposit address per sale. */
-        readonly memo?: string;
+        /** Reference-key mode (api.x1id.io, R3-x402-1): a base58 pubkey derived
+         *  from the request + challenge nonce + payer (see
+         *  {@link deriveX402Reference}). The buyer appends it to the
+         *  TransferChecked instruction as one extra READ-ONLY, NON-SIGNER account.
+         *  Nobody holds a key for it. */
+        readonly reference?: string;
+        /** Hex SHA-256 of the canonical request the challenge was issued for
+         *  ({@link x402RequestHash}). Informational: lets a client confirm it is
+         *  about to pay for the request it will actually send. */
+        readonly requestHash?: string;
+        /** R4-D-1 payer-signed redemption (api.x1id.io): the exact UTF-8 message
+         *  the bound payer signs (ed25519, `signMessage`) to redeem this challenge
+         *  ({@link x402RedeemMessage}). The base58 signature goes in the payment
+         *  payload as `payload.payerSig`. The on-chain payment is public once it
+         *  lands; this signature is what proves the REDEEMER is the payer, so a
+         *  front-runner who copies the transaction signature cannot redeem it. */
+        readonly redeemMessage?: string;
         readonly recentBlockhash?: string;
         readonly lastValidBlockHeight?: string;
     };
@@ -97,6 +120,10 @@ export interface X402PaymentPayload {
     };
 }
 export interface BuildX402RequirementsParams {
+    /** Reference-key mode: the derived reference pubkey + request hash
+     *  ({@link deriveX402Reference}, {@link x402RequestHash}). */
+    readonly reference?: string;
+    readonly requestHash?: string;
     /** The recipient's base58 address. */
     readonly payTo: string;
     /** The SPL/Token-2022 mint's base58 address. */
@@ -114,7 +141,6 @@ export interface BuildX402RequirementsParams {
      *  default. Pass {@link X1_TESTNET_NETWORK} for testnet. */
     readonly network?: string;
     readonly maxTimeoutSeconds?: number;
-    readonly memo?: string;
     readonly recentBlockhash?: string;
     readonly lastValidBlockHeight?: string;
 }
@@ -128,3 +154,41 @@ export declare function buildX402Requirements(p: BuildX402RequirementsParams): X
 /** Parse a 402 response body, returning null if it doesn't look like one
  *  (missing/wrong `x402Version`, `accepts` not an array). Never throws. */
 export declare function parseX402Response(body: unknown): X402PaymentRequiredResponse | null;
+/** Domain-separation tag for the reference preimage. */
+export declare const X402_REFERENCE_DOMAIN = "x1id-x402-ref:v1|api.x1id.io/dev-api";
+/** SHA-256("") in hex — the body hash of a GET/HEAD or empty body. */
+export declare const X402_EMPTY_BODY_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/** Canonicalise a URL path (see the section docs). */
+export declare function canonicalizeX402Path(path: string): string;
+/** Canonicalise a query string (with or without the leading "?"). */
+export declare function canonicalizeX402Query(query: string): string;
+export interface X402RequestInput {
+    /** HTTP method; uppercased. */
+    readonly method: string;
+    /** The request target: a path with optional `?query` and `#fragment`, or an
+     *  absolute URL (scheme + host are dropped). */
+    readonly url: string;
+    /** The exact body bytes (a string is hashed as UTF-8). Ignored for GET/HEAD. */
+    readonly body?: Uint8Array | string | null;
+}
+/** The canonical request string (see the section docs). */
+export declare function canonicalX402Request(req: X402RequestInput): string;
+/** Hex SHA-256 of {@link canonicalX402Request} — `accepts[].extra.requestHash`. */
+export declare function x402RequestHash(req: X402RequestInput): string;
+/** Domain-separation tag for the payer-signed redemption message (R4-D-1). */
+export declare const X402_REDEEM_DOMAIN = "x1id-x402-redeem:v1|api.x1id.io/dev-api";
+/**
+ * R4-D-1: the message the bound payer signs to redeem a challenge — over its
+ * `accepts[].extra.reference`, which is single-use and already bound
+ * (server-side) to the endpoint, the exact request and the payer, so the
+ * signature cannot be replayed onto another challenge. Sent as base58 in
+ * `payload.payerSig`. The 402 also carries it verbatim as
+ * `accepts[].extra.redeemMessage`.
+ */
+export declare function x402RedeemMessage(reference: string): string;
+/** Derive the base58 reference pubkey for a request + challenge nonce + payer. */
+export declare function deriveX402Reference(p: {
+    readonly canonicalRequest: string;
+    readonly nonce: string;
+    readonly payer: string;
+}): string;

package/dist/x402.js

@@ -21,13 +21,24 @@
  * its own SVM chain, but `@x402/core`'s reference client/facilitator only route
  * the `solana:*` scheme family — so to let ANY standard, unmodified x402 client
  * or wallet pay an x1id agent out of the box, X1 testnet uses the CAIP-30 form
- * keyed on X1's genesis. (Fortiswap's self-hosted X1 facilitator uses the
- * identical id.) An earlier release used a principled `"x1:<full-genesis>"`
+ * keyed on X1's genesis. x1id's X1 rail is standalone and self-verified: the
+ * buyer self-sponsors and broadcasts, and the seller checks the finalized
+ * transaction on chain itself; no external facilitator is involved. An
+ * earlier release used a principled `"x1:<full-genesis>"`
  * extension; it was OSS-incompatible, so this migrated to CAIP-30 —
  * {@link X1_LEGACY_TESTNET_NETWORK} is kept only for reading older manifests.
  * Verified against `getGenesisHash` (full hash
  * `C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho`).
+ *
+ * # HTTP headers (x402 v2 transport)
+ *
+ * api.x1id.io sends the 402 body also as `PAYMENT-REQUIRED` (base64 JSON),
+ * accepts the payment in `PAYMENT-SIGNATURE` (base64 JSON; the v1 name
+ * `X-PAYMENT` still works), and returns `PAYMENT-RESPONSE` plus the v1
+ * `X-PAYMENT-RESPONSE` on success.
  */
+import { encodeBase58 } from "./base58.js";
+import { sha256, toHex } from "./sha256.js";
 /** X1 testnet's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
  *  genesis hash — so unmodified OSS x402 clients route to it (#8325). */
 export const X1_TESTNET_NETWORK = "solana:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWw";
@@ -71,12 +82,17 @@ export function buildX402Requirements(p) {
     if (!/^\d+$/.test(p.amount)) {
         throw new Error("amount must be a decimal string of smallest units (e.g. \"1000000\")");
     }
-    if (p.memo !== undefined && new TextEncoder().encode(p.memo).length > 256) {
-        throw new Error("memo must be <=256 UTF-8 bytes");
-    }
     const extra = { feePayer: p.buyer };
-    if (p.memo !== undefined)
-        extra.memo = p.memo;
+    if (p.reference !== undefined) {
+        if (!PUBKEY_RE.test(p.reference))
+            throw new Error("reference must be a base58 address");
+        extra.reference = p.reference;
+    }
+    if (p.requestHash !== undefined) {
+        if (!/^[0-9a-f]{64}$/.test(p.requestHash))
+            throw new Error("requestHash must be 64 lowercase hex chars");
+        extra.requestHash = p.requestHash;
+    }
     if (p.recentBlockhash !== undefined) {
         extra.recentBlockhash = p.recentBlockhash;
     }
@@ -103,3 +119,138 @@ export function parseX402Response(body) {
         return null;
     return { x402Version: X402_VERSION, accepts: b.accepts };
 }
+// ── Request-bound reference keys (api.x1id.io R3-x402-1) ───────────────────────
+//
+// A 402 challenge from api.x1id.io binds the payment to the EXACT request it
+// was issued for. The server derives a `reference` pubkey from the canonical
+// request, the challenge nonce and the payer; the buyer appends it to the
+// TransferChecked instruction as an extra read-only, non-signer account (SPL
+// Token ignores extra accounts for a single-owner transfer), ~6.6k CU per
+// payment. Nobody signs with the reference; it is not a keypair or a PDA, just
+// 32 hash bytes read as an address.
+//
+// Canonical request (one UTF-8 string, "\n"-separated, no trailing newline):
+//
+//   METHOD          uppercased ("GET", "POST")
+//   path            split on "/", each segment percent-decoded then re-encoded
+//                   per RFC 3986 (unreserved A-Z a-z 0-9 - . _ ~ literal, every
+//                   other byte %XX uppercase). No trailing-slash folding, case
+//                   PRESERVED: /v1/resolve/@Alice and /v1/resolve/@alice are
+//                   DIFFERENT requests (both canonicalise "@" to %40).
+//   query           split on "&" (empty parts dropped), each "k=v" split on the
+//                   first "=" ("k" alone == "k="), "+" read as a space, both
+//                   sides percent-decoded then re-encoded as above, sorted by
+//                   (key, value) on the encoded strings, duplicates KEPT, joined
+//                   with "&". "" when there is no query. No fragment.
+//   bodyHash        lowercase hex SHA-256 of the exact body bytes; GET/HEAD or
+//                   no body = SHA-256("") = e3b0c442…b855.
+//
+// Scheme and host are excluded (the domain is fixed by the tag below).
+//
+//   requestHash = hex(SHA-256(canonical))
+//   reference   = base58(SHA-256(utf8(X402_REFERENCE_DOMAIN + "\n" + canonical
+//                                       + "\n" + nonce + "\n" + payer)))
+/** Domain-separation tag for the reference preimage. */
+export const X402_REFERENCE_DOMAIN = "x1id-x402-ref:v1|api.x1id.io/dev-api";
+/** SHA-256("") in hex — the body hash of a GET/HEAD or empty body. */
+export const X402_EMPTY_BODY_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+function isUnreserved(b) {
+    return ((b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || (b >= 0x30 && b <= 0x39) ||
+        b === 0x2d || b === 0x2e || b === 0x5f || b === 0x7e);
+}
+function hexVal(c) {
+    if (c >= 0x30 && c <= 0x39)
+        return c - 0x30;
+    if (c >= 0x41 && c <= 0x46)
+        return c - 0x37;
+    if (c >= 0x61 && c <= 0x66)
+        return c - 0x57;
+    return -1;
+}
+/** Percent-decode to raw bytes. A `%` not followed by two hex digits is kept
+ *  literally (decoding never throws). */
+function pctDecode(s, plusIsSpace) {
+    const raw = new TextEncoder().encode(s);
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw[i];
+        if (c === 0x25 && i + 2 < raw.length) {
+            const hi = hexVal(raw[i + 1]);
+            const lo = hexVal(raw[i + 2]);
+            if (hi >= 0 && lo >= 0) {
+                out.push(hi * 16 + lo);
+                i += 2;
+                continue;
+            }
+        }
+        out.push(plusIsSpace && c === 0x2b ? 0x20 : c);
+    }
+    return new Uint8Array(out);
+}
+function pctEncode(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += isUnreserved(b) ? String.fromCharCode(b) : "%" + b.toString(16).toUpperCase().padStart(2, "0");
+    return s;
+}
+/** Canonicalise a URL path (see the section docs). */
+export function canonicalizeX402Path(path) {
+    const p = path === "" ? "/" : path;
+    return p
+        .split("/")
+        .map((seg) => pctEncode(pctDecode(seg, false)))
+        .join("/");
+}
+/** Canonicalise a query string (with or without the leading "?"). */
+export function canonicalizeX402Query(query) {
+    const q = query.startsWith("?") ? query.slice(1) : query;
+    const pairs = [];
+    for (const part of q.split("&")) {
+        if (part === "")
+            continue;
+        const eq = part.indexOf("=");
+        const k = eq === -1 ? part : part.slice(0, eq);
+        const v = eq === -1 ? "" : part.slice(eq + 1);
+        pairs.push([pctEncode(pctDecode(k, true)), pctEncode(pctDecode(v, true))]);
+    }
+    pairs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+    return pairs.map(([k, v]) => `${k}=${v}`).join("&");
+}
+/** The canonical request string (see the section docs). */
+export function canonicalX402Request(req) {
+    const method = req.method.toUpperCase();
+    let target = req.url;
+    const abs = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*/.exec(target);
+    if (abs)
+        target = target.slice(abs[0].length);
+    const hashAt = target.indexOf("#");
+    if (hashAt !== -1)
+        target = target.slice(0, hashAt);
+    const qAt = target.indexOf("?");
+    const path = qAt === -1 ? target : target.slice(0, qAt);
+    const query = qAt === -1 ? "" : target.slice(qAt + 1);
+    const noBody = method === "GET" || method === "HEAD" || req.body === undefined || req.body === null;
+    const bodyHash = noBody ? X402_EMPTY_BODY_HASH : toHex(sha256(req.body));
+    return `${method}\n${canonicalizeX402Path(path)}\n${canonicalizeX402Query(query)}\n${bodyHash}`;
+}
+/** Hex SHA-256 of {@link canonicalX402Request} — `accepts[].extra.requestHash`. */
+export function x402RequestHash(req) {
+    return toHex(sha256(canonicalX402Request(req)));
+}
+/** Domain-separation tag for the payer-signed redemption message (R4-D-1). */
+export const X402_REDEEM_DOMAIN = "x1id-x402-redeem:v1|api.x1id.io/dev-api";
+/**
+ * R4-D-1: the message the bound payer signs to redeem a challenge — over its
+ * `accepts[].extra.reference`, which is single-use and already bound
+ * (server-side) to the endpoint, the exact request and the payer, so the
+ * signature cannot be replayed onto another challenge. Sent as base58 in
+ * `payload.payerSig`. The 402 also carries it verbatim as
+ * `accepts[].extra.redeemMessage`.
+ */
+export function x402RedeemMessage(reference) {
+    return `${X402_REDEEM_DOMAIN}\nreference:${reference}`;
+}
+/** Derive the base58 reference pubkey for a request + challenge nonce + payer. */
+export function deriveX402Reference(p) {
+    return encodeBase58(sha256(`${X402_REFERENCE_DOMAIN}\n${p.canonicalRequest}\n${p.nonce}\n${p.payer}`));
+}

package/package.json

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