@mingderwang/x402 0.1.1 → 0.1.2

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@mingderwang/x402",
-  "version": "0.1.1",
-  "description": "x402 (HTTP 402 Payment Required) client + server helpers: payment requirements, EIP-3009 signing, X-PAYMENT, verification and settlement.",
+  "version": "0.1.2",
+  "description": "x402 (HTTP 402 Payment Required) client + server helpers: EIP-3009 signing, X-PAYMENT, verification and settlement. Ships an `x402` CLI.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "x402": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -24,7 +27,7 @@
     "build": "node ./scripts/build.mjs"
   },
   "dependencies": {
-    "@mingderwang/wallet": "^0.1.0",
+    "@mingderwang/wallet": "^0.1.1",
     "ethers": "^6.13.4"
   },
   "keywords": [

package/src/cli.ts

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readKeystore, loadWallet, processEnvPassword } from '@mingderwang/wallet';
+import {
+  decodeJson,
+  detectPaymentRequired,
+  makePaymentPayload,
+  verifyPaymentPayload,
+  settlePayment,
+  xPaymentHeader,
+  PAYMENT_REQUIRED_HEADER,
+  type PaymentRequirements,
+  type PaymentRequirementsResponse,
+  type PaymentPayload,
+} from './index';
+
+const VERSION = '0.1.2';
+
+const C = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  gray: (s: string) => `\x1b[90m${s}\x1b[0m`,
+};
+
+function defaultKeystore(): string {
+  return process.env.X402_WALLET_PATH ?? join(homedir(), '.wallet', 'wallet.json');
+}
+
+function promptHidden(question: string): Promise<string> {
+  const env = processEnvPassword();
+  if (env) {
+    process.stderr.write(`${question}[using WALLET_PASSWORD env]\n`);
+    return Promise.resolve(env);
+  }
+  process.stderr.write(question);
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const wasRaw = !!stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    let input = '';
+    const onData = (buf: Buffer) => {
+      const code = buf[0];
+      if (code === 3) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.exit(130);
+      }
+      if (code === 13 || code === 10) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.stderr.write('\n');
+        resolve(input);
+        return;
+      }
+      if (code === 127 || code === 8) input = input.slice(0, -1);
+      else input += buf.toString('utf8');
+    };
+    stdin.on('data', onData);
+  });
+}
+
+function parseRequirement(spec: string): PaymentRequirements {
+  const raw = existsSync(spec) ? readFileSync(spec, 'utf8') : spec;
+  const parsed = JSON.parse(raw) as PaymentRequirementsResponse | PaymentRequirements;
+  if (Array.isArray((parsed as PaymentRequirementsResponse).accepts)) {
+    const first = (parsed as PaymentRequirementsResponse).accepts[0];
+    if (!first) throw new Error('PaymentRequirementsResponse has no accepts[] entries.');
+    return first;
+  }
+  return parsed as PaymentRequirements;
+}
+
+function parsePayload(spec: string): PaymentPayload {
+  if (/^[A-Za-z0-9+/=]+$/.test(spec) && spec.length > 64) return decodeJson<PaymentPayload>(spec);
+  const raw = existsSync(spec) ? readFileSync(spec, 'utf8') : spec;
+  return JSON.parse(raw) as PaymentPayload;
+}
+
+async function loadSigner(action: string, keystorePath: string): Promise<import('ethers').Wallet> {
+  if (!existsSync(keystorePath)) {
+    console.log(C.red(`No keystore at ${keystorePath}`) + ` — create one with the \`wallet\` CLI.`);
+    process.exit(2);
+  }
+  const keystore = readKeystore(keystorePath);
+  for (let attempt = 1; ; attempt++) {
+    const password = await promptHidden(`Keystore password (${action}): `);
+    try {
+      return loadWallet(keystore, password);
+    } catch {
+      if (attempt >= 3) {
+        console.log(C.red('Incorrect password. Exiting.'));
+        process.exit(1);
+      }
+      console.log(C.red('Incorrect password, try again.'));
+    }
+  }
+}
+
+function printHeaders(set: Headers): void {
+  const h = set.get(PAYMENT_REQUIRED_HEADER);
+  if (h) console.log(`  ${C.gray('payment-required')} ${h.slice(0, 60)}…`);
+  const retry = set.get('retry-after');
+  if (retry) console.log(`  ${C.gray('retry-after')}    ${retry}`);
+}
+
+async function requestWithBody(url: string, method: string, headers: Record<string, string>): Promise<Response> {
+  return fetch(url, { method, headers });
+}
+
+// ---------- commands ----------
+
+async function cmdRequirements(url: string, method: string, hdrs: Record<string, string>): Promise<void> {
+  const res = await requestWithBody(url, method, hdrs);
+  const text = await res.text();
+  if (res.status !== 402) {
+    console.log(C.yellow(`Response is ${res.status}, not 402 — no payment required.`));
+    console.log(text.slice(0, 400));
+    process.exit(0);
+  }
+  const reqs = detectPaymentRequired({ status: res.status, headers: res.headers, text });
+  if (res.headers && res.headers.size) printHeaders(res.headers);
+  console.log(JSON.stringify(reqs, null, 2));
+}
+
+async function cmdSign(requirementArg: string, keystorePath: string, json: boolean): Promise<void> {
+  const requirement = parseRequirement(requirementArg);
+  const wallet = await loadSigner('sign', keystorePath);
+  const payload = await makePaymentPayload({ wallet, requirement });
+  const header = xPaymentHeader(payload);
+  if (json) {
+    console.log(JSON.stringify({ payload, header }, null, 2));
+    return;
+  }
+  console.log(`  ${C.bold('Signer')}    ${wallet.address}`);
+  console.log(`  ${C.bold('Network')}   ${requirement.network}`);
+  console.log(`  ${C.bold('Amount')}    ${requirement.maxAmountRequired} (${requirement.asset})`);
+  console.log('');
+  console.log(`  ${C.green('X-PAYMENT header')}:`);
+  console.log('  ' + header);
+}
+
+async function cmdPay(url: string, method: string, hdrs: Record<string, string>, keystorePath: string, json: boolean): Promise<void> {
+  const first = await requestWithBody(url, method, hdrs);
+  const firstText = await first.text();
+
+  if (first.status !== 402) {
+    console.log(C.yellow(`No payment required (${first.status}) — nothing to do.`));
+    console.log(firstText.slice(0, 400));
+    return;
+  }
+  const reqs = detectPaymentRequired({ status: first.status, headers: first.headers, text: firstText });
+  if (!reqs) {
+    console.log(C.red('402 response had no parseable payment requirements.'));
+    process.exit(1);
+  }
+  const requirement = reqs.accepts[0];
+  if (!requirement) {
+    console.log(C.red('PaymentRequirementsResponse has no accepts[] entries.'));
+    process.exit(1);
+  }
+  const wallet = await loadSigner('pay', keystorePath);
+  console.log(`  ${C.bold('Paying')} ${requirement.maxAmountRequired} ${requirement.asset} on ${requirement.network}`);
+  console.log(`  ${C.gray('from')} ${wallet.address} ${C.gray('→')} ${requirement.payTo}\n`);
+  const payload = await makePaymentPayload({ wallet, requirement });
+  const retried = await requestWithBody(url, method, { ...hdrs, 'X-PAYMENT': xPaymentHeader(payload) });
+  const body = await retried.text();
+  if (retried.status === 402) {
+    console.log(C.red(`Still 402 after payment:`));
+    console.log(body.slice(0, 400));
+    process.exit(1);
+  }
+  if (json) {
+    let parsed = null;
+    try { parsed = JSON.parse(body); } catch { /* non-json */ }
+    console.log(JSON.stringify({ status: retried.status, headers: Object.fromEntries(retried.headers.entries()), body: parsed ?? body }, null, 2));
+    return;
+  }
+  console.log(C.green(`${retried.status} ${retried.statusText}`));
+  try {
+    console.log(JSON.stringify(JSON.parse(body), null, 2));
+  } catch {
+    console.log(body.slice(0, 800));
+  }
+}
+
+async function cmdDecode(spec: string): Promise<void> {
+  const payload = parsePayload(spec);
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+async function cmdVerify(payloadArg: string, requirementArg: string): Promise<void> {
+  const payload = parsePayload(payloadArg);
+  const requirement = parseRequirement(requirementArg);
+  const result = verifyPaymentPayload(payload, requirement);
+  if (result.isValid) console.log(JSON.stringify({ isValid: true, payer: result.payer }, null, 2));
+  else console.log(JSON.stringify({ isValid: false, invalidReason: result.invalidReason }, null, 2));
+}
+
+async function cmdSettle(payloadArg: string, requirementArg: string, gasKey?: string, rpcUrl?: string): Promise<void> {
+  const payload = parsePayload(payloadArg);
+  const requirement = parseRequirement(requirementArg);
+  if (gasKey) process.env.X402_GAS_PRIVATE_KEY = gasKey;
+  if (rpcUrl) process.env.X402_RPC_URL = rpcUrl;
+  const result = await settlePayment(payload, requirement, {});
+  console.log(JSON.stringify(result, null, 2));
+}
+
+// ---------- help ----------
+
+const HELP = `x402 v${VERSION}
+
+x402 (HTTP 402 Payment Required) toolkit: sign, pay, verify and settle
+EIP-3009 USDC payments.
+
+Usage:
+  x402 requirements <url> [--method GET] [--header K:V]...
+      Print the PaymentRequirementsResponse if the URL responds 402.
+  x402 sign <requirements.json> [--wallet <keystore>]
+      Sign a payment for the first accepts[] entry; print the X-PAYMENT header base64.
+  x402 pay <url> [--method GET] [--header K:V]... [--wallet <keystore>]
+      Full round trip: hit the URL, pay the 402, retry with X-PAYMENT, print the result.
+  x402 decode <base64-or-file | payload.json>
+      Decode an X-PAYMENT header value into the PaymentPayload JSON.
+  x402 verify <payload> <requirements.json>
+      Offline signature/amount/time sanity check. payload = base64 header or JSON file.
+  x402 settle <payload> <requirements.json> [--gas-key <private>] [--rpc <url>]
+      Broadcast transferWithAuthorization (uses X402_GAS_PRIVATE_KEY / X402_RPC_URL env if set).
+
+Options:
+  --wallet <keystore>   Keystore file (default ~/.wallet/wallet.json)
+  --json                Machine-readable output
+  --header K:V          Extra HTTP header (repeatable)
+  --method <verB>       HTTP method (default GET)
+
+Password:
+  Prompts interactively, or set WALLET_PASSWORD / XSIFT_WALLET_PASSWORD in the environment.`;
+
+function printHelp(): void {
+  console.log(HELP);
+}
+
+// ---------- entry ----------
+
+interface Parsed {
+  cmd: string;
+  positional: string[];
+  opts: Record<string, string>;
+  headers: Record<string, string>;
+  json: boolean;
+}
+
+function parseArgs(args: string[]): Parsed {
+  const positional: string[] = [];
+  const opts: Record<string, string> = {};
+  const headers: Record<string, string> = {};
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a === '--header') {
+      const kv = args[++i];
+      const idx = kv ? kv.indexOf(':') : -1;
+      if (!kv || idx < 0) {
+        console.log(C.red('--header expects K:V'));
+        process.exit(1);
+      }
+      headers[kv.slice(0, idx).trim()] = kv.slice(idx + 1).trim();
+      continue;
+    }
+    if (a === '--wallet' || a === '--gas-key' || a === '--rpc' || a === '--method' || a === '--path') {
+      opts[a.slice(2)] = args[++i] ?? '';
+      continue;
+    }
+    if (!a.startsWith('--')) positional.push(a);
+  }
+  const cmd = positional[0] ?? 'help';
+  return { cmd, positional: positional.slice(1), opts, headers, json };
+}
+
+async function main(): Promise<void> {
+  const { cmd, positional, opts, headers, json } = parseArgs(process.argv.slice(2));
+  const keystore = opts.wallet ?? defaultKeystore();
+  const method = (opts.method ?? 'GET').toUpperCase();
+  switch (cmd) {
+    case 'requirements': {
+      const url = positional[0];
+      if (!url) throw new Error('usage: x402 requirements <url>');
+      return cmdRequirements(url, method, headers);
+    }
+    case 'sign': {
+      const spec = positional[0];
+      if (!spec) throw new Error('usage: x402 sign <requirements.json> [--wallet <keystore>]');
+      return cmdSign(spec, keystore, json);
+    }
+    case 'pay': {
+      const url = positional[0];
+      if (!url) throw new Error('usage: x402 pay <url> [--wallet <keystore>]');
+      return cmdPay(url, method, headers, keystore, json);
+    }
+    case 'decode': {
+      const spec = positional[0];
+      if (!spec) throw new Error('usage: x402 decode <base64-or-file>');
+      return cmdDecode(spec);
+    }
+    case 'verify': {
+      const [payloadArg, reqArg] = positional;
+      if (!payloadArg || !reqArg) throw new Error('usage: x402 verify <payload> <requirements.json>');
+      return cmdVerify(payloadArg, reqArg);
+    }
+    case 'settle': {
+      const [payloadArg, reqArg] = positional;
+      if (!payloadArg || !reqArg) throw new Error('usage: x402 settle <payload> <requirements.json>');
+      return cmdSettle(payloadArg, reqArg, opts['gas-key'], opts.rpc);
+    }
+    case 'help':
+    case '-h':
+    case '--help':
+      return printHelp();
+    case '-v':
+    case '--version':
+      return console.log(VERSION);
+    default:
+      console.log(C.red(`Unknown command: ${cmd}`) + '\n');
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exit(1);
+});