@mingderwang/x402 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @mingderwang/x402
+
+`HTTP 402 Payment Required` helpers for the [x402](https://github.com/x402-foundation/specs) standard — payment requirements, EIP-3009 signing, `X-PAYMENT`, verification, and on-chain settlement.
+
+Built on ethers v6 + `@mingderwang/wallet`.
+
+## Install
+
+```bash
+npm install @mingderwang/x402
+```
+
+## Client side — detect a paywall and pay
+
+```ts
+import { detectPaymentRequired, makePaymentPayload, makePaymentRequired } from '@mingderwang/x402';
+
+const res = await fetch('https://api.example.com/resource', { headers: { authorization: 'Bearer ...' } });
+if (res.status === 402) {
+  const reqs = detectPaymentRequired({ status: res.status, headers: res.headers, text: await res.text() });
+  const payload = await makePaymentPayload({ wallet, requirement: reqs.accepts[0] });
+  const retry = await fetch('https://api.example.com/resource', {
+    headers: { 'x-payment': Buffer.from(JSON.stringify(payload)).toString('base64') },
+  });
+}
+```
+
+## Server side — issue requirements, verify, settle
+
+```ts
+import { makePaymentRequired, verifyPaymentPayload, settlePayment } from '@mingderwang/x402';
+
+const requirement = makePaymentRequired({
+  resource: '/api/resource', description: 'Pay per use',
+  network: 'ethereum-sepolia', amount: '500000', /* 0.5 USDC (6 decimals) */
+  asset: usdcAddress, payTo: sellerAddress,
+}).accepts[0];
+
+const check = verifyPaymentPayload(parsedXPayment, requirement); // { isValid, payer }
+if (!check.isValid) return new Response(JSON.stringify({ x402Version: 1, error: check.invalidReason }), { status: 402 });
+
+const settled = await settlePayment(parsedXPayment, requirement, {}); // broadcasts transferWithAuthorization (needs X402_GAS_PRIVATE_KEY)
+```
+
+- Scheme: `exact`, network/asset/timeouts configurable.
+- Replay protection: keep signed nonces; reject repeats with `invalid_transaction_state`.
+- Errors follow the spec: `insufficient_funds`, `invalid_exact_evm_payload_*`, etc.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from '../src/index';

package/dist/index.js

@@ -0,0 +1,218 @@
+// src/index.ts
+import { randomBytesHex, NETWORKS } from "@mingderwang/wallet";
+import { verifyTypedData, Contract, JsonRpcProvider, Wallet } from "ethers";
+var PAYMENT_REQUIRED_HEADER = "payment-required";
+var PAYMENT_SIGNATURE_HEADER = "x-payment";
+var PAYMENT_RESPONSE_HEADER = "payment-response";
+var ERROR = {
+  insufficientFunds: "insufficient_funds",
+  invalidValidAfter: "invalid_exact_evm_payload_authorization_valid_after",
+  invalidValidBefore: "invalid_exact_evm_payload_authorization_valid_before",
+  invalidValue: "invalid_exact_evm_payload_authorization_value",
+  invalidSignature: "invalid_exact_evm_payload_signature",
+  recipientMismatch: "invalid_exact_evm_payload_recipient_mismatch",
+  invalidNetwork: "invalid_network",
+  invalidPayload: "invalid_payload",
+  invalidPaymentRequirements: "invalid_payment_requirements",
+  invalidScheme: "invalid_scheme",
+  invalidVersion: "invalid_x402_version",
+  invalidTxState: "invalid_transaction_state"
+};
+function encodeJson(obj) {
+  return Buffer.from(JSON.stringify(obj)).toString("base64");
+}
+function decodeJson(b64) {
+  return JSON.parse(Buffer.from(b64, "base64").toString("utf8"));
+}
+function makePaymentRequired(opts) {
+  return {
+    x402Version: 1,
+    error: `${PAYMENT_SIGNATURE_HEADER.toUpperCase()} header is required`,
+    accepts: [
+      {
+        scheme: "exact",
+        network: opts.network,
+        maxAmountRequired: opts.amount,
+        asset: opts.asset.toLowerCase(),
+        payTo: opts.payTo.toLowerCase(),
+        resource: opts.resource,
+        description: opts.description,
+        mimeType: opts.mimeType ?? "application/json",
+        outputSchema: null,
+        maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 300,
+        extra: opts.extra ?? { name: "USDC", version: "2" }
+      }
+    ]
+  };
+}
+function detectPaymentRequired(response) {
+  if (response.status !== 402)
+    return null;
+  const header = response.headers?.get?.(PAYMENT_REQUIRED_HEADER);
+  if (header) {
+    try {
+      return decodeJson(header);
+    } catch {}
+  }
+  if (response.text) {
+    try {
+      const parsed = JSON.parse(response.text);
+      if (parsed && Array.isArray(parsed.accepts))
+        return parsed;
+    } catch {}
+  }
+  return null;
+}
+async function makePaymentPayload({ wallet, requirement, nowSeconds }) {
+  const { NETWORKS: _net } = { NETWORKS };
+  const chainId = chainIdForNetwork(requirement.network);
+  const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+  const value = BigInt(requirement.maxAmountRequired);
+  const domain = {
+    name: "USD Coin",
+    version: "2",
+    chainId,
+    verifyingContract: requirement.asset
+  };
+  const types = {
+    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" }
+    ]
+  };
+  const authorization = {
+    from: wallet.address,
+    to: requirement.payTo,
+    value: value.toString(),
+    validAfter: (now - 60).toString(),
+    validBefore: (now + requirement.maxTimeoutSeconds).toString(),
+    nonce: randomBytesHex(32)
+  };
+  const signature = await wallet.signTypedData(domain, types, { from: authorization.from, to: authorization.to, value: authorization.value, validAfter: authorization.validAfter, validBefore: authorization.validBefore, nonce: authorization.nonce });
+  return {
+    x402Version: 1,
+    scheme: "exact",
+    network: requirement.network,
+    payload: { signature, authorization }
+  };
+}
+function chainIdForNetwork(network) {
+  for (const n of Object.values(NETWORKS)) {
+    if (n.networkId === network)
+      return n.chainId;
+  }
+  const m = /-(\d+)$/.exec(network);
+  if (m)
+    return Number(m[1]);
+  throw new Error(`Unknown network ${network}`);
+}
+function xPaymentHeader(payload) {
+  return encodeJson(payload);
+}
+var TRANSFER_WITH_AUTH_ABI = [
+  "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce)",
+  "function balanceOf(address) view returns (uint256)"
+];
+function verifyPaymentPayload(payload, requirement) {
+  if (!payload || typeof payload !== "object") {
+    return { isValid: false, invalidReason: ERROR.invalidPayload };
+  }
+  const p = payload;
+  if (p.x402Version !== 1)
+    return { isValid: false, invalidReason: ERROR.invalidVersion };
+  if (p.scheme !== "exact")
+    return { isValid: false, invalidReason: ERROR.invalidScheme };
+  if (p.network !== requirement.network)
+    return { isValid: false, invalidReason: ERROR.invalidNetwork };
+  const a = p.payload?.authorization;
+  const sig = p.payload?.signature;
+  if (!a || !sig)
+    return { isValid: false, invalidReason: ERROR.invalidPayload };
+  const now = Math.floor(Date.now() / 1000);
+  const validAfter = Number(a.validAfter);
+  const validBefore = Number(a.validBefore);
+  if (now < validAfter)
+    return { isValid: false, invalidReason: ERROR.invalidValidAfter };
+  if (now > validBefore)
+    return { isValid: false, invalidReason: ERROR.invalidValidBefore };
+  if (BigInt(a.value) < BigInt(requirement.maxAmountRequired)) {
+    return { isValid: false, invalidReason: ERROR.invalidValue };
+  }
+  if (a.to.toLowerCase() !== requirement.payTo.toLowerCase()) {
+    return { isValid: false, invalidReason: ERROR.recipientMismatch };
+  }
+  if (!/^0x[a-fA-F0-9]{40}$/.test(a.from) || !/^0x[a-fA-F0-9]{64}$/.test(a.nonce)) {
+    return { isValid: false, invalidReason: ERROR.invalidPayload };
+  }
+  const chainId = chainIdForNetwork(requirement.network);
+  const domain = { name: "USD Coin", version: "2", chainId, verifyingContract: requirement.asset };
+  const types = {
+    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" }
+    ]
+  };
+  const message = { from: a.from, to: a.to, value: a.value, validAfter: a.validAfter, validBefore: a.validBefore, nonce: a.nonce };
+  try {
+    const signer = verifyTypedData(domain, types, message, sig);
+    if (signer.toLowerCase() !== a.from.toLowerCase()) {
+      return { isValid: false, invalidReason: ERROR.invalidSignature };
+    }
+  } catch {
+    return { isValid: false, invalidReason: ERROR.invalidSignature };
+  }
+  return { isValid: true, payer: a.from };
+}
+async function settlePayment(payload, requirement, opts) {
+  const a = payload.payload.authorization;
+  const network = requirement.network;
+  const rpc = opts.rpcUrl ?? process.env.X402_RPC_URL;
+  const provider = new JsonRpcProvider(rpc);
+  const signer = opts.signer ?? (process.env.X402_GAS_PRIVATE_KEY ? new Wallet(process.env.X402_GAS_PRIVATE_KEY, provider) : undefined);
+  if (!signer) {
+    return { success: false, errorReason: "server has no gas signer configured", transaction: "", network, payer: a.from };
+  }
+  const contract = new Contract(requirement.asset, TRANSFER_WITH_AUTH_ABI, signer);
+  const erc20 = contract;
+  try {
+    const balance = await erc20.balanceOf(a.from);
+    if (balance < BigInt(a.value)) {
+      return { success: false, errorReason: ERROR.insufficientFunds, transaction: "", network, payer: a.from };
+    }
+    const tx = await erc20.transferWithAuthorization(a.from, a.to, a.value, a.validAfter, a.validBefore, a.nonce);
+    await tx.wait(opts.confirmations ?? 1);
+    return { success: true, transaction: tx.hash, network, payer: a.from };
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ERROR.invalidTxState,
+      transaction: "",
+      network,
+      payer: a.from,
+      ...e?.shortMessage ? { errorReason: e.shortMessage } : {}
+    };
+  }
+}
+export {
+  xPaymentHeader,
+  verifyPaymentPayload,
+  settlePayment,
+  makePaymentRequired,
+  makePaymentPayload,
+  encodeJson,
+  detectPaymentRequired,
+  decodeJson,
+  chainIdForNetwork,
+  PAYMENT_SIGNATURE_HEADER,
+  PAYMENT_RESPONSE_HEADER,
+  PAYMENT_REQUIRED_HEADER,
+  ERROR
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mingderwang/x402",
+  "version": "0.1.0",
+  "description": "x402 (HTTP 402 Payment Required) client + server helpers: payment requirements, EIP-3009 signing, X-PAYMENT, verification and settlement.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node ./scripts/build.mjs"
+  },
+  "dependencies": {
+    "@mingderwang/wallet": "^0.1.0",
+    "ethers": "^6.13.4"
+  },
+  "keywords": [
+    "x402",
+    "http402",
+    "payment",
+    "eip-3009",
+    "usdc",
+    "paywall"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mingderwang/network-vulnerability-scanner.git"
+  }
+}