@mingderwang/x402 0.1.0 → 0.1.1

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@mingderwang/x402",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "engines": {

package/src/index.ts

@@ -0,0 +1,307 @@
+import { randomBytesHex, NETWORKS } from '@mingderwang/wallet';
+import { verifyTypedData, Contract, JsonRpcProvider, Wallet } from 'ethers';
+
+// ---------- types ----------
+
+export interface PaymentRequirements {
+  scheme: string;
+  network: string;
+  maxAmountRequired: string;
+  asset: string;
+  payTo: string;
+  resource: string;
+  description: string;
+  mimeType?: string;
+  outputSchema?: unknown;
+  maxTimeoutSeconds: number;
+  extra?: Record<string, unknown>;
+}
+
+export interface PaymentRequirementsResponse {
+  x402Version: 1;
+  error: string;
+  accepts: PaymentRequirements[];
+}
+
+export interface Authorization {
+  from: string;
+  to: string;
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: string;
+}
+
+export interface PaymentPayload {
+  x402Version: 1;
+  scheme: 'exact';
+  network: string;
+  payload: {
+    signature: string;
+    authorization: Authorization;
+  };
+}
+
+export interface SettlementResponse {
+  success: boolean;
+  errorReason?: string;
+  transaction: string;
+  network: string;
+  payer: string;
+}
+
+export const PAYMENT_REQUIRED_HEADER = 'payment-required';
+export const PAYMENT_SIGNATURE_HEADER = 'x-payment';
+export const PAYMENT_RESPONSE_HEADER = 'payment-response';
+
+export const 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',
+} as const;
+
+// ---------- encoding ----------
+
+export function encodeJson(obj: unknown): string {
+  return Buffer.from(JSON.stringify(obj)).toString('base64');
+}
+
+export function decodeJson<T>(b64: string): T {
+  return JSON.parse(Buffer.from(b64, 'base64').toString('utf8')) as T;
+}
+
+// ---------- server: payment requirements ----------
+
+export function makePaymentRequired(
+  opts: {
+    resource: string;
+    description: string;
+    network: string;
+    amount: string; // atomic units, e.g. "500000" for 0.5 USDC
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds?: number;
+    mimeType?: string;
+    extra?: Record<string, unknown>;
+  }
+): PaymentRequirementsResponse {
+  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' },
+      },
+    ],
+  };
+}
+
+// ---------- client: 402 detection + payment construction ----------
+
+export function detectPaymentRequired(response: { status: number; headers?: Headers; text?: string }): PaymentRequirementsResponse | null {
+  if (response.status !== 402) return null;
+  const header = response.headers?.get?.(PAYMENT_REQUIRED_HEADER);
+  if (header) {
+    try {
+      return decodeJson<PaymentRequirementsResponse>(header);
+    } catch {
+      /* fall through to body */
+    }
+  }
+  if (response.text) {
+    try {
+      const parsed = JSON.parse(response.text);
+      if (parsed && Array.isArray(parsed.accepts)) return parsed as PaymentRequirementsResponse;
+    } catch {
+      /* not json */
+    }
+  }
+  return null;
+}
+
+export interface PaymentOptions {
+  wallet: Wallet;
+  requirement: PaymentRequirements;
+  nowSeconds?: number;
+}
+
+export async function makePaymentPayload({ wallet, requirement, nowSeconds }: PaymentOptions): Promise<PaymentPayload> {
+  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: 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 },
+  };
+}
+
+export function chainIdForNetwork(network: string): number {
+  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}`);
+}
+
+export function xPaymentHeader(payload: PaymentPayload): string {
+  return encodeJson(payload);
+}
+
+// ---------- server: verification + settlement ----------
+
+const TRANSFER_WITH_AUTH_ABI = [
+  'function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce)',
+  'function balanceOf(address) view returns (uint256)',
+] as const;
+
+export function verifyPaymentPayload(
+  payload: unknown,
+  requirement: PaymentRequirements
+): { isValid: boolean; payer?: string; invalidReason?: string } {
+  if (!payload || typeof payload !== 'object') {
+    return { isValid: false, invalidReason: ERROR.invalidPayload };
+  }
+  const p = payload as PaymentPayload;
+  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 };
+}
+
+export async function settlePayment(
+  payload: PaymentPayload,
+  requirement: PaymentRequirements,
+  opts: { signer?: Wallet; rpcUrl?: string; confirmations?: number }
+): Promise<SettlementResponse> {
+  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 as unknown as {
+    balanceOf: (address: string) => Promise<bigint>;
+    transferWithAuthorization: (
+      from: string, to: string, value: string, validAfter: string, validBefore: string, nonce: string
+    ) => Promise<{ hash: string; wait: (confirmations?: number) => Promise<unknown> }>;
+  };
+  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,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ...((e as any)?.shortMessage ? { errorReason: (e as { shortMessage: string }).shortMessage } : {}),
+    };
+  }
+}