@shroud-fi/x402 0.1.3 → 0.1.5

package/src/protocol.ts

@@ -0,0 +1,154 @@
+/**
+ * x402 protocol constants + wire types.
+ *
+ * v2 spec only. See docs/research/competitive/x402-spec-and-ecosystem.md §1
+ * for the canonical field names. v1 (whitepaper, deprecated) names are not
+ * accepted by this package.
+ */
+
+import type { Address, Hex } from 'viem';
+
+// ─── HTTP header names ───────────────────────────────────────────────────────
+
+/** Server → client: 402 challenge envelope (raw JSON, no base64 in v2). */
+export const X402_PAYMENT_REQUIRED_HEADER = 'X-PAYMENT-REQUIRED' as const;
+
+/**
+ * Client → server: signed PaymentPayload (base64-encoded JSON).
+ *
+ * Canonical name per the v2 spec is `X-PAYMENT`. Older drafts and some
+ * SDKs use `X-PAYMENT-SIGNATURE`; we use `X-PAYMENT` to stay aligned with
+ * the foundation SDKs (`@x402/fetch`, `@x402/axios`, `@x402/express` all
+ * read `X-PAYMENT`).
+ */
+export const X402_PAYMENT_SIGNATURE_HEADER = 'X-PAYMENT' as const;
+
+/** Server → client: settlement confirmation (base64-encoded JSON, on 2xx). */
+export const X402_PAYMENT_RESPONSE_HEADER = 'X-PAYMENT-RESPONSE' as const;
+
+// ─── Scheme identifiers ──────────────────────────────────────────────────────
+
+/** "Exact" scheme — seller knows price up front. Only scheme we support in v1. */
+export const X402_SCHEME_EXACT = 'exact' as const;
+
+export type X402SchemeId = typeof X402_SCHEME_EXACT;
+
+// ─── Facilitator URLs ────────────────────────────────────────────────────────
+
+/**
+ * PayAI Network facilitator — free tier (≤ 10k settlements/mo) requires no
+ * authentication at all. Our default.
+ */
+export const PAYAI_FACILITATOR_URL =
+  'https://facilitator.payai.network' as const;
+
+/**
+ * Coinbase CDP facilitator — secondary. Requires CDP API key for use.
+ * URL verified against research doc §3 (cdp.coinbase.com/platform/v2/x402).
+ */
+export const COINBASE_FACILITATOR_URL =
+  'https://api.cdp.coinbase.com/platform/v2/x402' as const;
+
+/**
+ * Map an EVM chain id to the x402 v1 legacy network name that facilitators
+ * (PayAI, Coinbase CDP, etc.) expect on the wire. The facilitator ecosystem
+ * standardized on these short names, NOT CAIP-2 (`eip155:8453`). Our SDK uses
+ * CAIP-2 internally and translates only at the facilitator boundary.
+ *
+ * Verified against PayAI `/supported` (2026-06-04) — Base mainnet = "base",
+ * Base Sepolia = "base-sepolia". Returns undefined for chains we don't map.
+ */
+export function facilitatorNetworkName(chainId: number): string | undefined {
+  const NAMES: Readonly<Record<number, string>> = {
+    8453: 'base',
+    84532: 'base-sepolia',
+  };
+  return NAMES[chainId];
+}
+
+// ─── Wire types ──────────────────────────────────────────────────────────────
+
+/**
+ * The `accepts[N]` entry from a v2 `PaymentRequired` object — the exact shape
+ * a client receives over the wire.
+ *
+ * Field names match the spec verbatim (NOT the v1 whitepaper names — see
+ * research doc §10.1 for the drift table).
+ */
+export interface X402PaymentRequirements {
+  /** Scheme id; only `'exact'` supported in v1. */
+  readonly scheme: X402SchemeId;
+  /** CAIP-2 network id, e.g. `'eip155:8453'`. */
+  readonly network: string;
+  /**
+   * Maximum payment amount in token base units (string-encoded to survive
+   * uint256). For scheme `exact`, this is the exact required amount.
+   *
+   * Spec field name: `maxAmountRequired`. We mirror it verbatim.
+   */
+  readonly maxAmountRequired: string;
+  /** ERC-20 contract address of the asset. */
+  readonly asset: Address;
+  /**
+   * Recipient address. In ShroudFi servers this is ALWAYS a freshly derived
+   * stealth address — never the server's main wallet.
+   */
+  readonly payTo: Address;
+  /** Authorization validity window (seconds). */
+  readonly maxTimeoutSeconds: number;
+  /** Resource being paid for (URL or pseudo-URL). */
+  readonly resource: string;
+  /** Optional human-readable description. */
+  readonly description?: string;
+  /**
+   * Scheme-specific extra data. For `exact` on EVM, contains the EIP-712
+   * domain `name` + `version` for the asset (so the client can rebuild the
+   * domain separator without having to look the token up).
+   */
+  readonly extra: {
+    readonly name: string;
+    readonly version: string;
+    /**
+     * ShroudFi-specific extension: emitted so a ShroudFi-aware client can
+     * relay the Announcement event after settlement. Forward-compatible —
+     * non-ShroudFi clients ignore unknown keys.
+     */
+    readonly shroudfiAnnouncement?: {
+      readonly ephemeralPubKey: Hex;
+      readonly viewTag: number;
+    };
+  };
+}
+
+/**
+ * The signed payload the client sends back in `X-PAYMENT`. EIP-3009
+ * `transferWithAuthorization` shape.
+ */
+export interface X402PaymentPayload {
+  readonly x402Version: 2;
+  readonly scheme: X402SchemeId;
+  readonly network: string;
+  readonly payload: {
+    readonly signature: Hex;
+    readonly authorization: {
+      readonly from: Address;
+      readonly to: Address;
+      /** uint256 as string. */
+      readonly value: string;
+      readonly validAfter: string;
+      readonly validBefore: string;
+      readonly nonce: Hex;
+    };
+  };
+}
+
+/**
+ * Optional facilitator config. When unset, the default is PayAI free-tier
+ * (no auth). When `ed25519AuthToken` is provided, the facilitator client
+ * attaches `Authorization: Bearer <token>` to every request — caller is
+ * responsible for minting the JWT per PayAI's spec (research doc §10.5).
+ */
+export interface X402FacilitatorConfig {
+  readonly url: string;
+  readonly ed25519AuthToken?: string;
+}

package/src/server.ts

@@ -0,0 +1,313 @@
+/**
+ * x402 server — challenge generation + signed-payment verification.
+ *
+ * Privacy invariants enforced here:
+ *   - Every challenge derives a FRESH stealth address from the recipient's
+ *     meta-address. The recipient's main wallet NEVER appears in the
+ *     PaymentRequired body.
+ *   - The facilitator is only ever shown the stealth `payTo` — same property.
+ *   - Error paths never include amount values, signature bytes, or the
+ *     server's spend key.
+ */
+
+import { decodeMetaAddress } from '@shroud-fi/core';
+import { prepareStealthPayment } from '@shroud-fi/payments';
+import { getEip3009Token } from '@shroud-fi/transport';
+import {
+  X402_PAYMENT_REQUIRED_HEADER,
+  X402_SCHEME_EXACT,
+  type X402PaymentPayload,
+  type X402PaymentRequirements,
+} from './protocol.js';
+import { X402_VERSION, DEFAULT_MAX_TIMEOUT_SECS } from './constants.js';
+import {
+  X402AssetNotSupportedError,
+  X402InvalidChallengeError,
+} from './errors.js';
+import type {
+  X402Challenge,
+  X402PaymentVerification,
+  X402ServerConfig,
+} from './types.js';
+import {
+  facilitatorSettle,
+  facilitatorVerify,
+  resolveFacilitator,
+  toFacilitatorRequest,
+} from './facilitator.js';
+import {
+  verifyTransferWithAuthorizationSignature,
+  type TransferWithAuthorizationInput,
+} from './signing.js';
+
+/**
+ * Encode a CAIP-2 network id from a chain id. EVM only.
+ */
+function caip2(chainId: number): string {
+  return `eip155:${chainId}`;
+}
+
+/**
+ * Robust bigint coercion that accepts decimal strings, hex strings,
+ * numbers, and bigints. Throws X402InvalidChallengeError on anything else.
+ */
+function toBigInt(v: unknown): bigint {
+  if (typeof v === 'bigint') return v;
+  if (typeof v === 'number') return BigInt(v);
+  if (typeof v === 'string') {
+    try {
+      return BigInt(v);
+    } catch {
+      throw new X402InvalidChallengeError();
+    }
+  }
+  throw new X402InvalidChallengeError();
+}
+
+export interface X402Server {
+  /**
+   * Build a 402 challenge for a given resource. Each call derives a fresh
+   * stealth address — calls are deliberately non-idempotent.
+   */
+  challenge(args: {
+    resource: string;
+    description?: string;
+    priceAtomic?: bigint;
+  }): Promise<X402Challenge>;
+  /**
+   * Verify a signed payload submitted by the client. Optionally settles via
+   * the configured facilitator.
+   *
+   * When `skipFacilitator: true` is passed, verify returns `valid: true` after
+   * signature recovery succeeds and does NOT contact the facilitator. The
+   * caller is then responsible for settling the EIP-3009 authorization on-chain
+   * itself (e.g. by calling `USDC.transferWithAuthorization` directly through
+   * its own walletClient). Use this when the operator runs its own settler EOA
+   * and does not want a facilitator in the trust chain — e.g. headless
+   * agent-to-agent demos, anon-stack deployments.
+   */
+  verify(args: {
+    signedPayload: string | X402PaymentPayload;
+    challenge: X402Challenge;
+    skipFacilitator?: boolean;
+  }): Promise<X402PaymentVerification>;
+}
+
+/**
+ * Build an X402Server bound to a single recipient meta-address + asset.
+ */
+export function createX402Server(config: X402ServerConfig): X402Server {
+  // v0.1.1: validate the asset is an EIP-3009 token registered for the chain.
+  // Previously hardcoded to USDC; the EIP-3009 registry now also lists EURC on
+  // Base mainnet, with room for future Circle-issued assets without changing
+  // this file. Lookup is case-insensitive on the asset address.
+  const token = getEip3009Token(config.chainId, config.asset);
+  if (token === undefined) {
+    throw new X402AssetNotSupportedError();
+  }
+  const assetDomain = token.domain;
+
+  // Pre-decode the meta-address ONCE — repeated decodes would waste cycles.
+  // The decode validates curve membership; downstream errors become
+  // X402InvalidChallengeError.
+  let decoded;
+  try {
+    decoded = decodeMetaAddress(config.recipientMetaAddress);
+  } catch {
+    throw new X402InvalidChallengeError();
+  }
+
+  const facilitator = resolveFacilitator(config.facilitator);
+
+  return {
+    async challenge({ resource, description, priceAtomic }) {
+      const price = priceAtomic ?? config.defaultPriceAtomic;
+
+      // Derive a fresh stealth address per call. prepareStealthPayment hashes
+      // a fresh ephemeral key internally — uniqueness is built in.
+      const prepared = prepareStealthPayment(decoded);
+
+      const requirements: X402PaymentRequirements = {
+        scheme: X402_SCHEME_EXACT,
+        network: caip2(config.chainId),
+        maxAmountRequired: price.toString(),
+        asset: config.asset,
+        payTo: prepared.stealthAddress,
+        maxTimeoutSeconds: DEFAULT_MAX_TIMEOUT_SECS,
+        resource,
+        ...(description !== undefined ? { description } : {}),
+        extra: {
+          name: assetDomain.name,
+          version: assetDomain.version,
+          shroudfiAnnouncement: {
+            ephemeralPubKey: prepared.ephemeralPubKey,
+            viewTag: prepared.viewTag,
+          },
+        },
+      };
+
+      const body = {
+        x402Version: X402_VERSION,
+        error: 'Payment required',
+        accepts: [requirements] as const,
+      } as const;
+
+      return {
+        status: 402,
+        headers: {
+          [X402_PAYMENT_REQUIRED_HEADER]: JSON.stringify(body),
+          'content-type': 'application/json',
+        },
+        body,
+        announcement: {
+          ephemeralPubKey: prepared.ephemeralPubKey,
+          viewTag: prepared.viewTag,
+          stealthAddress: prepared.stealthAddress,
+        },
+      };
+    },
+
+    async verify({ signedPayload, challenge, skipFacilitator }) {
+      // 1. Decode incoming payload.
+      let payload: X402PaymentPayload;
+      if (typeof signedPayload === 'string') {
+        try {
+          // Spec: header value is base64-encoded JSON.
+          const decodedJson = Buffer.from(signedPayload, 'base64').toString(
+            'utf-8',
+          );
+          payload = JSON.parse(decodedJson) as X402PaymentPayload;
+        } catch {
+          return { valid: false, error: 'malformed_payload' };
+        }
+      } else {
+        payload = signedPayload;
+      }
+
+      // 2. Structural checks. Tagged failures only — no field values in errors.
+      if (
+        payload.x402Version !== 2 ||
+        payload.scheme !== X402_SCHEME_EXACT ||
+        payload.network !== caip2(config.chainId)
+      ) {
+        return { valid: false, error: 'scheme_mismatch' };
+      }
+      const auth = payload.payload?.authorization;
+      const sig = payload.payload?.signature;
+      if (auth === undefined || sig === undefined) {
+        return { valid: false, error: 'malformed_payload' };
+      }
+
+      const accepted = challenge.body.accepts[0];
+      if (accepted === undefined) {
+        return { valid: false, error: 'malformed_challenge' };
+      }
+
+      // 3. Authorization fields must address the same stealth `payTo` and the
+      //    exact required amount.
+      let value: bigint;
+      let validAfter: bigint;
+      let validBefore: bigint;
+      try {
+        value = toBigInt(auth.value);
+        validAfter = toBigInt(auth.validAfter);
+        validBefore = toBigInt(auth.validBefore);
+      } catch {
+        return { valid: false, error: 'malformed_payload' };
+      }
+
+      if (
+        auth.to.toLowerCase() !== accepted.payTo.toLowerCase()
+      ) {
+        return { valid: false, error: 'recipient_mismatch' };
+      }
+      let requiredAmount: bigint;
+      try {
+        requiredAmount = toBigInt(accepted.maxAmountRequired);
+      } catch {
+        return { valid: false, error: 'malformed_challenge' };
+      }
+      if (value !== requiredAmount) {
+        return { valid: false, error: 'amount_mismatch' };
+      }
+
+      // 4. Time window.
+      const nowSecs = BigInt(Math.floor(Date.now() / 1000));
+      if (validBefore <= nowSecs) {
+        return { valid: false, error: 'expired' };
+      }
+      if (validAfter > nowSecs) {
+        return { valid: false, error: 'not_yet_valid' };
+      }
+
+      // 5. Signature recovery.
+      const authInput: TransferWithAuthorizationInput = {
+        from: auth.from,
+        to: auth.to,
+        value,
+        validAfter,
+        validBefore,
+        nonce: auth.nonce,
+      };
+      const recovered = await verifyTransferWithAuthorizationSignature({
+        chainId: config.chainId,
+        verifyingContract: config.asset,
+        authorization: authInput,
+        signature: sig,
+      });
+      if (
+        recovered === null ||
+        recovered.toLowerCase() !== auth.from.toLowerCase()
+      ) {
+        return { valid: false, error: 'signature_invalid' };
+      }
+
+      // 6a. Self-settle mode: caller handles on-chain settlement, we return
+      // valid:true after signature recovery. No facilitator contact.
+      if (skipFacilitator === true) {
+        return { valid: true };
+      }
+
+      // 6b. Facilitator submission. Caller gets the settled tx hash.
+      // We send the facilitator only what it needs: the requirements + the
+      // signed payload. The recipient's main wallet is never in this body
+      // because `accepted.payTo` is the freshly derived stealth address.
+      try {
+        // Translate our v2/CAIP-2 body into the v1/legacy-network shape the
+        // facilitator expects. Proven against PayAI on Base mainnet
+        // (tx 0x57d84d53…). Same body drives both /verify and /settle.
+        const facilitatorBody = toFacilitatorRequest({
+          chainId: config.chainId,
+          paymentRequirements: accepted as unknown as Record<string, unknown>,
+          paymentPayload: payload as unknown as Record<string, unknown>,
+        });
+        const verifyResult = await facilitatorVerify(
+          facilitator,
+          facilitatorBody,
+        );
+        if (!verifyResult.isValid) {
+          return { valid: false, error: 'facilitator_rejected' };
+        }
+        const settle = await facilitatorSettle(facilitator, facilitatorBody);
+        if (!settle.success || settle.txHash === undefined) {
+          return { valid: false, error: 'facilitator_settle_failed' };
+        }
+        return { valid: true, settledTxHash: settle.txHash };
+      } catch {
+        // Facilitator unreachable / non-2xx. Return signature-verified=true
+        // so the caller can decide whether to retry or fall back. The signed
+        // payload remains cryptographically valid even when the facilitator
+        // path failed.
+        return { valid: false, error: 'facilitator_unreachable' };
+      }
+    },
+  };
+}
+
+/** Re-export so consumers don't have to dig into types.ts. */
+export type {
+  X402Challenge,
+  X402PaymentVerification,
+  X402ServerConfig,
+} from './types.js';
+export type { X402PaymentRequirements } from './protocol.js';

package/src/signing.ts

@@ -0,0 +1,176 @@
+/**
+ * EIP-3009 `TransferWithAuthorization` typed-data signing for x402.
+ *
+ * Privacy invariants:
+ *   - The private key never leaves the viem `account` object. We do not
+ *     extract it, log it, or attach it to errors.
+ *   - The signed payload (`signature`, `nonce`, `value`) is never logged,
+ *     stringified into errors, or stored. Caller is responsible for sending
+ *     it directly to the server in the `X-PAYMENT` header.
+ *   - `nonce` is a fresh 32 bytes per call via `crypto.getRandomValues`,
+ *     never reused.
+ */
+
+import type { Account, Address, Chain, Hex } from 'viem';
+import { getEip3009Token } from '@shroud-fi/transport';
+import { X402AssetNotSupportedError } from './errors.js';
+
+/**
+ * EIP-3009 `TransferWithAuthorization` typed-data types.
+ * Exported for tests; the runtime signer constructs the same object inline.
+ */
+export const TransferWithAuthorizationTypes = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+} as const;
+
+/**
+ * The cleartext authorization fields. Caller passes them in; signer hashes,
+ * signs, and returns both signature + the authorization (so the caller can
+ * forward the unsigned data alongside the signature).
+ */
+export interface TransferWithAuthorizationInput {
+  readonly from: Address;
+  readonly to: Address;
+  readonly value: bigint;
+  readonly validAfter: bigint;
+  readonly validBefore: bigint;
+  readonly nonce: Hex;
+}
+
+export interface SignedTransferWithAuthorization {
+  readonly signature: Hex;
+  readonly nonce: Hex;
+  readonly from: Address;
+  readonly to: Address;
+  readonly value: bigint;
+  readonly validAfter: bigint;
+  readonly validBefore: bigint;
+}
+
+/**
+ * Generate a fresh 32-byte nonce for EIP-3009. Uses Web Crypto (available in
+ * Node 20+ and all browsers). Never reuse — each authorization needs a
+ * unique nonce to avoid replay.
+ */
+export function generateAuthorizationNonce(): Hex {
+  const bytes = new Uint8Array(32);
+  // Web Crypto is globally available on Node 20+; deliberately not using
+  // `node:crypto.randomBytes` so the module stays runtime-agnostic.
+  globalThis.crypto.getRandomValues(bytes);
+  let hex = '0x';
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, '0');
+  }
+  return hex as Hex;
+}
+
+/**
+ * Sign an EIP-3009 `TransferWithAuthorization` over any registered EIP-3009
+ * asset (USDC, EURC). The EIP-712 domain is derived from the asset's entry in
+ * the EIP-3009 registry — using the wrong domain would silently produce an
+ * invalid signature.
+ *
+ * @throws X402AssetNotSupportedError if the verifyingContract address is not
+ *         registered as an EIP-3009 token on the chain.
+ */
+export async function signTransferWithAuthorization(args: {
+  readonly account: Account;
+  readonly chain: Chain;
+  readonly verifyingContract: Address;
+  readonly input: TransferWithAuthorizationInput;
+}): Promise<SignedTransferWithAuthorization> {
+  const { account, chain, verifyingContract, input } = args;
+  const token = getEip3009Token(chain.id, verifyingContract);
+  if (token === undefined) {
+    throw new X402AssetNotSupportedError();
+  }
+
+  const domain = {
+    name: token.domain.name,
+    version: token.domain.version,
+    chainId: chain.id,
+    verifyingContract,
+  } as const;
+
+  if (account.signTypedData === undefined) {
+    // Local account; viem provides .signTypedData for privateKeyToAccount.
+    // For JSON-RPC accounts the caller must provide a wrapper. Treat as
+    // unsupported configuration rather than leaking the underlying error.
+    throw new X402AssetNotSupportedError();
+  }
+
+  const signature = await account.signTypedData({
+    domain,
+    types: TransferWithAuthorizationTypes,
+    primaryType: 'TransferWithAuthorization',
+    message: {
+      from: input.from,
+      to: input.to,
+      value: input.value,
+      validAfter: input.validAfter,
+      validBefore: input.validBefore,
+      nonce: input.nonce,
+    },
+  });
+
+  return {
+    signature,
+    nonce: input.nonce,
+    from: input.from,
+    to: input.to,
+    value: input.value,
+    validAfter: input.validAfter,
+    validBefore: input.validBefore,
+  };
+}
+
+/**
+ * Verify a `TransferWithAuthorization` signature on the server side.
+ * Returns the recovered signer address (`from`) or `null` on failure.
+ *
+ * NOTE: we do NOT throw on failure — caller maps `null` → verify.valid=false
+ * with an error tag. Throwing here would risk leaking signature bytes via
+ * thrown error stacks.
+ */
+export async function verifyTransferWithAuthorizationSignature(args: {
+  readonly chainId: number;
+  readonly verifyingContract: Address;
+  readonly authorization: TransferWithAuthorizationInput;
+  readonly signature: Hex;
+}): Promise<Address | null> {
+  const { chainId, verifyingContract, authorization, signature } = args;
+  const token = getEip3009Token(chainId, verifyingContract);
+  if (token === undefined) return null;
+
+  const { recoverTypedDataAddress } = await import('viem');
+  try {
+    return await recoverTypedDataAddress({
+      domain: {
+        name: token.domain.name,
+        version: token.domain.version,
+        chainId,
+        verifyingContract,
+      },
+      types: TransferWithAuthorizationTypes,
+      primaryType: 'TransferWithAuthorization',
+      message: {
+        from: authorization.from,
+        to: authorization.to,
+        value: authorization.value,
+        validAfter: authorization.validAfter,
+        validBefore: authorization.validBefore,
+        nonce: authorization.nonce,
+      },
+      signature,
+    });
+  } catch {
+    return null;
+  }
+}