@shroud-fi/x402 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/x402",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Stealth-addressed HTTP 402 payments for AI agents. EIP-3009 settlement into one-time stealth addresses.",
   "keywords": [
     "shroudfi",
@@ -27,13 +27,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@shroud-fi/core": "0.1.1",
-    "@shroud-fi/payments": "0.1.1",
-    "@shroud-fi/transport": "0.1.2"
+    "@shroud-fi/payments": "0.1.3",
+    "@shroud-fi/core": "0.1.3",
+    "@shroud-fi/transport": "0.1.4"
   },
   "peerDependencies": {
     "viem": "^2.21.0"
@@ -42,7 +45,7 @@
     "viem": "^2.21.0",
     "vitest": "^2.0.0",
     "typescript": "^5.6.0",
-    "@shroud-fi/scanning": "0.1.1"
+    "@shroud-fi/scanning": "0.1.3"
   },
   "publishConfig": {
     "access": "public"

package/src/client.ts

@@ -0,0 +1,261 @@
+/**
+ * x402 client — fetch wrapper that auto-handles 402 challenges.
+ *
+ * Flow:
+ *   1. Issue initial fetch.
+ *   2. If status !== 402, return as-is.
+ *   3. Parse X-PAYMENT-REQUIRED, validate scheme + asset + safety cap.
+ *   4. Sign EIP-3009 TransferWithAuthorization for USDC.
+ *   5. Re-issue request with `X-PAYMENT: base64(JSON(payload))`.
+ *   6. On 2xx, surface `x402Settlement` on the returned Response if the
+ *      server attached X-PAYMENT-RESPONSE.
+ *
+ * Privacy invariants:
+ *   - The signed payload is constructed in memory and forwarded directly to
+ *     the server. We never log or serialize the signature, nonce, or value.
+ *   - The client wallet address is unavoidably visible (it IS the `from`).
+ *     This is the agent's stealth-payer EOA, not a persistent identity if
+ *     used by ShroudAgent.
+ *   - Errors carry no amount, no signature, no nonce bytes.
+ */
+
+import type { Hex } from 'viem';
+import { getEip3009Token } from '@shroud-fi/transport';
+import {
+  X402_PAYMENT_REQUIRED_HEADER,
+  X402_PAYMENT_RESPONSE_HEADER,
+  X402_PAYMENT_SIGNATURE_HEADER,
+  X402_SCHEME_EXACT,
+  type X402PaymentPayload,
+  type X402PaymentRequirements,
+} from './protocol.js';
+import { X402_VERSION, DEFAULT_AUTHORIZATION_TTL_SECS } from './constants.js';
+import {
+  X402AmountMismatchError,
+  X402AssetNotSupportedError,
+  X402InvalidChallengeError,
+} from './errors.js';
+import type { X402ClientConfig, X402PaymentResult } from './types.js';
+import {
+  generateAuthorizationNonce,
+  signTransferWithAuthorization,
+} from './signing.js';
+
+/**
+ * The augmented Response surface. We can't subclass `Response` in a portable
+ * way, so we attach `x402Settlement` as a non-standard own-property.
+ */
+export interface X402Response extends Response {
+  x402Settlement?: X402PaymentResult;
+}
+
+export interface X402Client {
+  /**
+   * Wrap `fetch` with 402 auto-pay. The returned Response is augmented with
+   * `x402Settlement` when a payment was made.
+   *
+   * @param maxPriceAtomic — safety cap. If the server demands more, the
+   *   client throws X402AmountMismatchError without signing anything.
+   */
+  fetch(
+    input: string | URL | Request,
+    init?: RequestInit & { maxPriceAtomic?: bigint },
+  ): Promise<X402Response>;
+}
+
+/** Decode a 402 challenge body from the response. Tries header, then body. */
+async function readChallenge(
+  res: Response,
+): Promise<{ accepts: readonly X402PaymentRequirements[] }> {
+  // Header path (spec-canonical) first.
+  const header = res.headers.get(X402_PAYMENT_REQUIRED_HEADER);
+  if (header !== null && header.length > 0) {
+    try {
+      const parsed = JSON.parse(header) as {
+        accepts: readonly X402PaymentRequirements[];
+      };
+      if (Array.isArray(parsed.accepts) && parsed.accepts.length > 0) {
+        return parsed;
+      }
+    } catch {
+      // fall through to body parse
+    }
+  }
+  // Body fallback — some servers put the envelope in the body only.
+  try {
+    const text = await res.clone().text();
+    const parsed = JSON.parse(text) as {
+      accepts: readonly X402PaymentRequirements[];
+    };
+    if (Array.isArray(parsed.accepts) && parsed.accepts.length > 0) {
+      return parsed;
+    }
+  } catch {
+    // fall through
+  }
+  throw new X402InvalidChallengeError();
+}
+
+/** Decode the X-PAYMENT-RESPONSE header into a settlement record. */
+function readSettlement(res: Response): X402PaymentResult | undefined {
+  const header = res.headers.get(X402_PAYMENT_RESPONSE_HEADER);
+  if (header === null || header.length === 0) return undefined;
+  try {
+    // Header is base64-encoded JSON per the spec.
+    const decoded = Buffer.from(header, 'base64').toString('utf-8');
+    const parsed = JSON.parse(decoded) as {
+      transaction?: string;
+      txHash?: string;
+      settledAt?: number;
+    };
+    const txHash =
+      (parsed.transaction ?? parsed.txHash) as Hex | undefined;
+    if (txHash === undefined) return undefined;
+    return {
+      txHash,
+      settledAt:
+        typeof parsed.settledAt === 'number'
+          ? parsed.settledAt
+          : Math.floor(Date.now() / 1000),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Convert a value into a bigint safely. */
+function safeBigInt(v: unknown): bigint | null {
+  try {
+    if (typeof v === 'bigint') return v;
+    if (typeof v === 'string' || typeof v === 'number') return BigInt(v);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function createX402Client(config: X402ClientConfig): X402Client {
+  const transport = config.transport;
+  const walletClient = transport.walletClient;
+  if (walletClient === undefined || walletClient.account === undefined) {
+    // We deliberately throw at construction time so a misconfigured client
+    // can't ship to production without a wallet.
+    throw new X402AssetNotSupportedError();
+  }
+  const account = walletClient.account;
+  const chain = transport.chain;
+
+  return {
+    async fetch(input, init) {
+      const fetchImpl = globalThis.fetch;
+      const maxPriceAtomic = init?.maxPriceAtomic;
+
+      // Strip our non-standard option before passing init to fetch.
+      const passThroughInit: RequestInit = { ...(init ?? {}) };
+      delete (passThroughInit as { maxPriceAtomic?: bigint }).maxPriceAtomic;
+
+      // 1. First attempt.
+      const first = (await fetchImpl(input, passThroughInit)) as X402Response;
+      if (first.status !== 402) {
+        return first;
+      }
+
+      // 2. Decode challenge.
+      const challenge = await readChallenge(first);
+      const requirements = challenge.accepts[0];
+      if (requirements === undefined) {
+        throw new X402InvalidChallengeError();
+      }
+
+      // 3. Scheme + network + asset checks.
+      if (requirements.scheme !== X402_SCHEME_EXACT) {
+        throw new X402InvalidChallengeError();
+      }
+      // v0.1.1: accept any EIP-3009 asset registered for this chain (USDC, EURC).
+      // The exact asset is challenge-driven — the server picks; we validate
+      // membership in the registry rather than pinning to one symbol.
+      const challengedAsset = getEip3009Token(chain.id, requirements.asset);
+      if (challengedAsset === undefined) {
+        throw new X402AssetNotSupportedError();
+      }
+      const expectedNetwork = `eip155:${chain.id}`;
+      if (requirements.network !== expectedNetwork) {
+        throw new X402AssetNotSupportedError();
+      }
+
+      // 4. Safety cap.
+      const required = safeBigInt(requirements.maxAmountRequired);
+      if (required === null) {
+        throw new X402InvalidChallengeError();
+      }
+      if (maxPriceAtomic !== undefined && required > maxPriceAtomic) {
+        throw new X402AmountMismatchError();
+      }
+
+      // 5. Build authorization. validAfter=0n, validBefore=now+ttl.
+      const nowSecs = BigInt(Math.floor(Date.now() / 1000));
+      const ttl = BigInt(
+        Math.min(
+          requirements.maxTimeoutSeconds || DEFAULT_AUTHORIZATION_TTL_SECS,
+          DEFAULT_AUTHORIZATION_TTL_SECS,
+        ),
+      );
+      const validBefore = nowSecs + ttl;
+      const nonce = generateAuthorizationNonce();
+
+      const signed = await signTransferWithAuthorization({
+        account,
+        chain,
+        verifyingContract: requirements.asset,
+        input: {
+          from: account.address,
+          to: requirements.payTo,
+          value: required,
+          validAfter: 0n,
+          validBefore,
+          nonce,
+        },
+      });
+
+      // 6. Build the PaymentPayload + base64 the header.
+      const payload: X402PaymentPayload = {
+        x402Version: X402_VERSION,
+        scheme: X402_SCHEME_EXACT,
+        network: requirements.network,
+        payload: {
+          signature: signed.signature,
+          authorization: {
+            from: signed.from,
+            to: signed.to,
+            value: signed.value.toString(),
+            validAfter: signed.validAfter.toString(),
+            validBefore: signed.validBefore.toString(),
+            nonce: signed.nonce,
+          },
+        },
+      };
+      const encoded = Buffer.from(JSON.stringify(payload), 'utf-8').toString(
+        'base64',
+      );
+
+      // 7. Re-issue. Mutating the headers via a new object so the caller's
+      // original init stays untouched.
+      const retryHeaders = new Headers(passThroughInit.headers ?? undefined);
+      retryHeaders.set(X402_PAYMENT_SIGNATURE_HEADER, encoded);
+      const retryInit: RequestInit = {
+        ...passThroughInit,
+        headers: retryHeaders,
+      };
+
+      const second = (await fetchImpl(input, retryInit)) as X402Response;
+      const settlement = readSettlement(second);
+      if (settlement !== undefined) {
+        // Attach as a non-standard own-property.
+        second.x402Settlement = settlement;
+      }
+      return second;
+    },
+  };
+}
+
+export type { X402ClientConfig, X402PaymentResult } from './types.js';

package/src/constants.ts

@@ -0,0 +1,18 @@
+/**
+ * Defaults for the @shroud-fi/x402 package.
+ *
+ * Tight defaults reduce blast radius if a signed payload leaks:
+ *   - 5-minute validity window matches Coinbase CDP recommendation and the
+ *     PayAI free tier facilitator's default maxTimeoutSeconds (300).
+ *   - x402Version pinned to 2 (current shipping spec). We deliberately do NOT
+ *     implement v1 backward-compat per LOCKED-DECISIONS (whitepaper field
+ *     names are deprecated).
+ */
+
+export const X402_VERSION = 2 as const;
+
+/** Default EIP-3009 authorization validity window (seconds). */
+export const DEFAULT_AUTHORIZATION_TTL_SECS = 300;
+
+/** Default facilitator `maxTimeoutSeconds` echoed back in PaymentRequired. */
+export const DEFAULT_MAX_TIMEOUT_SECS = 300;

package/src/errors.ts

@@ -0,0 +1,78 @@
+/**
+ * x402 error hierarchy.
+ *
+ * Privacy invariants:
+ *   - No amount, value, or balance numbers in any .message string.
+ *   - No private keys, signature bytes, or nonce bytes in any .message string.
+ *   - No recipient main wallet addresses in any .message string (stealth
+ *     addresses are derivable on-chain so leaking them post-payment is fine,
+ *     but the registrant wallet is identity-bearing — never include it).
+ *   - All errors extend the same base class so callers can `instanceof X402Error`
+ *     once at the boundary.
+ */
+
+export class X402Error extends Error {
+  override readonly name: string = 'X402Error';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * The 402 challenge body (or its header) could not be parsed / is malformed.
+ * Catch-all for "we received something the spec disallows".
+ */
+export class X402InvalidChallengeError extends X402Error {
+  override readonly name: string = 'X402InvalidChallengeError';
+  constructor() {
+    super('Invalid x402 challenge payload');
+  }
+}
+
+/**
+ * The signed `PAYMENT-SIGNATURE` payload submitted by the client could not be
+ * verified against the challenge (signer mismatch, malformed JSON, expired
+ * authorization, etc).
+ */
+export class X402SignatureVerificationError extends X402Error {
+  override readonly name: string = 'X402SignatureVerificationError';
+  constructor() {
+    super('x402 signed payment payload failed verification');
+  }
+}
+
+/**
+ * Facilitator HTTP call (verify or settle) failed. Tag identifies the
+ * facilitator stage but never carries response body, token amount, or signed
+ * payload.
+ */
+export class X402FacilitatorError extends X402Error {
+  override readonly name: string = 'X402FacilitatorError';
+  constructor(stage: 'verify' | 'settle' | 'network') {
+    super(`x402 facilitator request failed (stage=${stage})`);
+  }
+}
+
+/**
+ * The server's configured asset is not the canonical USDC on the configured
+ * chain (or USDC is not deployed on the chain). Hard-fail to avoid signing
+ * authorizations against the wrong token.
+ */
+export class X402AssetNotSupportedError extends X402Error {
+  override readonly name: string = 'X402AssetNotSupportedError';
+  constructor() {
+    super('x402: requested asset is not supported on the configured chain');
+  }
+}
+
+/**
+ * The server's quoted price exceeded the client's `maxPriceAtomic` safety cap,
+ * or the verified payload's value did not equal the challenge requirement.
+ * The error carries no amount bytes — caller can read inputs separately.
+ */
+export class X402AmountMismatchError extends X402Error {
+  override readonly name: string = 'X402AmountMismatchError';
+  constructor() {
+    super('x402: payment amount exceeds caller cap or does not match challenge');
+  }
+}

package/src/facilitator.ts

@@ -0,0 +1,211 @@
+/**
+ * Facilitator HTTP client.
+ *
+ * Two endpoints per the x402 spec:
+ *   - POST /verify  — facilitator validates signature + balance + simulation.
+ *   - POST /settle  — facilitator broadcasts the on-chain settlement tx.
+ *
+ * Privacy invariants:
+ *   - We forward only the signed PaymentPayload + the PaymentRequirements. The
+ *     facilitator never receives the recipient's main wallet — only the
+ *     freshly derived stealth address (the `payTo` field of the requirements).
+ *   - We never log request/response bodies. Tags are short strings only.
+ *   - Auth token (if any) is attached as a Bearer header. We never log the
+ *     full token; tests verify the header is set but redaction is the
+ *     operator's responsibility upstream.
+ */
+
+import type { Hex } from 'viem';
+import {
+  PAYAI_FACILITATOR_URL,
+  facilitatorNetworkName,
+  type X402FacilitatorConfig,
+} from './protocol.js';
+import { X402FacilitatorError } from './errors.js';
+
+export interface FacilitatorVerifyResult {
+  readonly isValid: boolean;
+  readonly invalidReason?: string;
+  readonly payer?: string;
+}
+
+export interface FacilitatorSettleResult {
+  readonly success: boolean;
+  readonly txHash?: Hex;
+  readonly errorReason?: string;
+  readonly payer?: string;
+  readonly network?: string;
+}
+
+/** Resolve the facilitator config, defaulting to PayAI free tier. */
+export function resolveFacilitator(
+  config: X402FacilitatorConfig | undefined,
+): X402FacilitatorConfig {
+  if (config === undefined) {
+    return { url: PAYAI_FACILITATOR_URL };
+  }
+  return config;
+}
+
+/**
+ * Translate our internal x402 v2 / CAIP-2 verify+settle body into the v1 /
+ * legacy-network shape that PayAI (and the wider facilitator ecosystem)
+ * accepts on the wire. Proven end-to-end on Base mainnet (tx 0x57d84d53…)
+ * before this shipped.
+ *
+ * Transformations:
+ *   - x402Version 2 → 1 (top-level and on the payload)
+ *   - network CAIP-2 (`eip155:8453`) → legacy name (`base`) on both the
+ *     payload and the requirements
+ *   - requirements.extra trimmed to `{ name, version }` — the facilitator
+ *     does not consume our `shroudfiAnnouncement` extension and some reject
+ *     unknown extra keys
+ *   - requirements gains `mimeType: ''` (present in the canonical v1 shape)
+ *
+ * Pure — never mutates its inputs. Throws X402FacilitatorError('network') for
+ * a chain with no mapped facilitator network name.
+ */
+export function toFacilitatorRequest(args: {
+  readonly chainId: number;
+  readonly paymentRequirements: Record<string, unknown> & {
+    readonly extra?: Record<string, unknown>;
+  };
+  readonly paymentPayload: Record<string, unknown>;
+}): {
+  x402Version: 1;
+  paymentPayload: Record<string, unknown> & { x402Version: 1; network: string };
+  paymentRequirements: Record<string, unknown> & {
+    network: string;
+    mimeType: string;
+    extra: { name: string; version: string };
+  };
+} {
+  const network = facilitatorNetworkName(args.chainId);
+  if (network === undefined) {
+    throw new X402FacilitatorError('network');
+  }
+
+  const srcExtra = (args.paymentRequirements.extra ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const extra = {
+    name: String(srcExtra.name ?? ''),
+    version: String(srcExtra.version ?? ''),
+  };
+
+  const paymentRequirements = {
+    ...args.paymentRequirements,
+    network,
+    mimeType:
+      typeof args.paymentRequirements.mimeType === 'string'
+        ? (args.paymentRequirements.mimeType as string)
+        : '',
+    extra,
+  };
+
+  const paymentPayload = {
+    ...args.paymentPayload,
+    x402Version: 1 as const,
+    network,
+  };
+
+  return { x402Version: 1, paymentPayload, paymentRequirements };
+}
+
+/**
+ * Build standard headers for a facilitator request. When an Ed25519 auth
+ * token is configured, attach `Authorization: Bearer <token>`. Otherwise
+ * the request hits the PayAI free-tier endpoint (no auth required).
+ */
+export function buildFacilitatorHeaders(
+  config: X402FacilitatorConfig,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    accept: 'application/json',
+  };
+  if (config.ed25519AuthToken !== undefined) {
+    headers['authorization'] = `Bearer ${config.ed25519AuthToken}`;
+  }
+  return headers;
+}
+
+/**
+ * Call the facilitator's `/verify` endpoint. Returns the parsed verification
+ * result. Re-wraps every failure path as a tagged X402FacilitatorError so
+ * no upstream response body leaks through.
+ */
+export async function facilitatorVerify(
+  config: X402FacilitatorConfig,
+  body: unknown,
+  fetchImpl: typeof fetch = fetch,
+): Promise<FacilitatorVerifyResult> {
+  const url = `${config.url.replace(/\/+$/, '')}/verify`;
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: buildFacilitatorHeaders(config),
+      body: JSON.stringify(body),
+    });
+  } catch {
+    throw new X402FacilitatorError('network');
+  }
+  if (!res.ok) {
+    throw new X402FacilitatorError('verify');
+  }
+  let parsed: FacilitatorVerifyResult;
+  try {
+    parsed = (await res.json()) as FacilitatorVerifyResult;
+  } catch {
+    throw new X402FacilitatorError('verify');
+  }
+  return parsed;
+}
+
+/**
+ * Call the facilitator's `/settle` endpoint. Returns the parsed settle
+ * result (including the on-chain tx hash on success).
+ */
+export async function facilitatorSettle(
+  config: X402FacilitatorConfig,
+  body: unknown,
+  fetchImpl: typeof fetch = fetch,
+): Promise<FacilitatorSettleResult> {
+  const url = `${config.url.replace(/\/+$/, '')}/settle`;
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: buildFacilitatorHeaders(config),
+      body: JSON.stringify(body),
+    });
+  } catch {
+    throw new X402FacilitatorError('network');
+  }
+  if (!res.ok) {
+    throw new X402FacilitatorError('settle');
+  }
+  let raw: Record<string, unknown>;
+  try {
+    raw = (await res.json()) as Record<string, unknown>;
+  } catch {
+    throw new X402FacilitatorError('settle');
+  }
+  // Normalize the tx-hash field. The x402 facilitator spec drifted: PayAI
+  // returns `transaction`, some return `transactionHash`, our own type uses
+  // `txHash`. Accept all three so callers get a populated txHash on success.
+  const txHash = (raw.txHash ?? raw.transaction ?? raw.transactionHash) as
+    | Hex
+    | undefined;
+  return {
+    success: raw.success === true,
+    ...(txHash !== undefined ? { txHash } : {}),
+    ...(typeof raw.errorReason === 'string'
+      ? { errorReason: raw.errorReason }
+      : {}),
+    ...(typeof raw.payer === 'string' ? { payer: raw.payer } : {}),
+    ...(typeof raw.network === 'string' ? { network: raw.network } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// Public surface — @shroud-fi/x402
+// HTTP 402 + stealth-address payment routing for AI agents on Base.
+// See packages/x402/README and docs/research/competitive/x402-spec-and-ecosystem.md.
+
+// Server side
+export { createX402Server } from './server.js';
+export type {
+  X402Server,
+  X402ServerConfig,
+  X402Challenge,
+  X402PaymentRequirements,
+  X402PaymentVerification,
+} from './server.js';
+
+// Client side
+export { createX402Client } from './client.js';
+export type {
+  X402Client,
+  X402ClientConfig,
+  X402PaymentResult,
+} from './client.js';
+
+// Protocol constants + types
+export {
+  X402_PAYMENT_REQUIRED_HEADER,
+  X402_PAYMENT_SIGNATURE_HEADER,
+  X402_PAYMENT_RESPONSE_HEADER,
+  X402_SCHEME_EXACT,
+  PAYAI_FACILITATOR_URL,
+  COINBASE_FACILITATOR_URL,
+  facilitatorNetworkName,
+} from './protocol.js';
+
+// Facilitator client + adapter (v0.1.2)
+export {
+  resolveFacilitator,
+  toFacilitatorRequest,
+  facilitatorVerify,
+  facilitatorSettle,
+} from './facilitator.js';
+export type {
+  FacilitatorVerifyResult,
+  FacilitatorSettleResult,
+} from './facilitator.js';
+export type {
+  X402PaymentPayload,
+  X402SchemeId,
+  X402FacilitatorConfig,
+} from './protocol.js';
+
+// Errors
+export {
+  X402Error,
+  X402InvalidChallengeError,
+  X402SignatureVerificationError,
+  X402FacilitatorError,
+  X402AssetNotSupportedError,
+  X402AmountMismatchError,
+} from './errors.js';