@ch4p/plugin-x402 0.1.4

package/dist/index.js

@@ -0,0 +1,330 @@
+// src/middleware.ts
+var PUBLIC_PATHS = /* @__PURE__ */ new Set([
+  "/health",
+  "/.well-known/agent.json",
+  "/pair"
+]);
+var DEFAULT_ASSET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var DEFAULT_NETWORK = "base";
+var DEFAULT_TIMEOUT = 300;
+function pathMatches(urlPath, pattern) {
+  if (pattern === "*" || pattern === "/**") return true;
+  if (pattern.endsWith("/*")) {
+    const prefix = pattern.slice(0, -2);
+    return urlPath === prefix || urlPath.startsWith(prefix + "/");
+  }
+  return urlPath === pattern;
+}
+function extractPath(url) {
+  const qIdx = url.indexOf("?");
+  return qIdx >= 0 ? url.slice(0, qIdx) : url;
+}
+function send402(res, requirements) {
+  const body = JSON.stringify({
+    x402Version: 1,
+    error: "X402",
+    accepts: [requirements]
+  });
+  res.writeHead(402, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(body)
+  });
+  res.end(body);
+}
+function decodePaymentHeader(header) {
+  try {
+    const json = Buffer.from(header, "base64").toString("utf-8");
+    const parsed = JSON.parse(json);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const p = parsed;
+    if (p["x402Version"] !== 1) return null;
+    if (p["scheme"] !== "exact") return null;
+    if (typeof p["network"] !== "string") return null;
+    const payload = p["payload"];
+    if (typeof payload !== "object" || payload === null) return null;
+    const pl = payload;
+    if (typeof pl["signature"] !== "string") return null;
+    const auth = pl["authorization"];
+    if (typeof auth !== "object" || auth === null) return null;
+    const a = auth;
+    if (typeof a["from"] !== "string" || typeof a["to"] !== "string" || typeof a["value"] !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function createX402Middleware(config) {
+  if (!config.enabled || !config.server) return null;
+  const serverCfg = config.server;
+  const asset = serverCfg.asset ?? DEFAULT_ASSET;
+  const network = serverCfg.network ?? DEFAULT_NETWORK;
+  const maxTimeoutSeconds = serverCfg.maxTimeoutSeconds ?? DEFAULT_TIMEOUT;
+  const description = serverCfg.description ?? "Payment required to access this gateway resource.";
+  const protectedPaths = serverCfg.protectedPaths ?? ["/*"];
+  return async (req, res) => {
+    const rawUrl = req.url ?? "/";
+    const urlPath = extractPath(rawUrl);
+    if (PUBLIC_PATHS.has(urlPath)) return false;
+    const isProtected = protectedPaths.some((p) => pathMatches(urlPath, p));
+    if (!isProtected) return false;
+    const requirements = {
+      scheme: "exact",
+      network,
+      maxAmountRequired: serverCfg.amount,
+      resource: urlPath,
+      description,
+      mimeType: "application/json",
+      payTo: serverCfg.payTo,
+      maxTimeoutSeconds,
+      asset,
+      extra: {}
+    };
+    const paymentHeader = req.headers["x-payment"];
+    if (!paymentHeader || typeof paymentHeader !== "string") {
+      send402(res, requirements);
+      return true;
+    }
+    const payment = decodePaymentHeader(paymentHeader);
+    if (!payment) {
+      send402(res, requirements);
+      return true;
+    }
+    if (payment.network !== network) {
+      send402(res, requirements);
+      return true;
+    }
+    if (serverCfg.verifyPayment) {
+      const allowed = await serverCfg.verifyPayment(payment, requirements);
+      if (!allowed) {
+        send402(res, requirements);
+        return true;
+      }
+    }
+    req["_x402Authenticated"] = true;
+    return false;
+  };
+}
+
+// src/x402-pay-tool.ts
+var PLACEHOLDER_SIG = "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000";
+var X402PayTool = class {
+  name = "x402_pay";
+  description = "Generate an X-PAYMENT header for a resource that returned HTTP 402 Payment Required. Provide the 402 response body JSON and a payer wallet address. Returns the base64-encoded X-PAYMENT value to include when retrying the request. Full payment execution requires an IIdentityProvider with wallet signing support.";
+  weight = "lightweight";
+  parameters = {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "The URL of the resource that returned 402 (used to match the requirement).",
+        minLength: 1
+      },
+      x402_response: {
+        type: "string",
+        description: "The JSON body of the 402 response. Stringify the x402 error response object.",
+        minLength: 2
+      },
+      wallet_address: {
+        type: "string",
+        description: "Payer wallet address (0x + 40 hex chars). If omitted, the identity provider wallet address is used when available.",
+        pattern: "^0x[0-9a-fA-F]{40}$"
+      }
+    },
+    required: ["url", "x402_response"],
+    additionalProperties: false
+  };
+  validate(args) {
+    if (typeof args !== "object" || args === null) {
+      return { valid: false, errors: ["Arguments must be an object."] };
+    }
+    const { url, x402_response, wallet_address } = args;
+    const errors = [];
+    if (typeof url !== "string" || url.trim().length === 0) {
+      errors.push("url must be a non-empty string.");
+    }
+    if (typeof x402_response !== "string" || x402_response.trim().length === 0) {
+      errors.push("x402_response must be a non-empty string.");
+    }
+    if (wallet_address !== void 0) {
+      if (typeof wallet_address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(wallet_address)) {
+        errors.push("wallet_address must be a valid Ethereum address (0x + 40 hex chars).");
+      }
+    }
+    return errors.length > 0 ? { valid: false, errors } : { valid: true };
+  }
+  async execute(args, context) {
+    const validation = this.validate(args);
+    if (!validation.valid) {
+      return {
+        success: false,
+        output: "",
+        error: `Invalid arguments: ${validation.errors.join(" ")}`
+      };
+    }
+    const { url, x402_response, wallet_address } = args;
+    const x402Context = context;
+    let response;
+    try {
+      response = JSON.parse(x402_response);
+    } catch {
+      return { success: false, output: "", error: "x402_response is not valid JSON." };
+    }
+    if (!Array.isArray(response.accepts) || response.accepts.length === 0) {
+      return {
+        success: false,
+        output: "",
+        error: 'x402 response contains no payment requirements in "accepts".'
+      };
+    }
+    const requirements = response.accepts.find((r) => r.scheme === "exact" && r.network === "base") ?? response.accepts.find((r) => r.scheme === "exact") ?? response.accepts[0];
+    const payer = wallet_address ?? x402Context.agentWalletAddress;
+    if (!payer) {
+      return {
+        success: false,
+        output: "",
+        error: "No wallet address available. Provide wallet_address or configure agentWalletAddress via toolContextExtensions in the agent runtime."
+      };
+    }
+    const nowSecs = Math.floor(Date.now() / 1e3);
+    const randomBytes = new Uint8Array(32);
+    if (typeof globalThis.crypto !== "undefined") {
+      globalThis.crypto.getRandomValues(randomBytes);
+    } else {
+      console.warn("x402: crypto.getRandomValues unavailable; using insecure Math.random fallback for nonce.");
+      for (let i = 0; i < 32; i++) {
+        randomBytes[i] = Math.floor(Math.random() * 256);
+      }
+    }
+    const nonce = "0x" + Array.from(randomBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+    const authorization = {
+      from: payer,
+      to: requirements.payTo,
+      value: requirements.maxAmountRequired,
+      validAfter: "0",
+      validBefore: String(nowSecs + requirements.maxTimeoutSeconds),
+      nonce
+    };
+    let signature;
+    let unsigned = false;
+    if (x402Context.x402Signer) {
+      try {
+        signature = await x402Context.x402Signer(authorization);
+      } catch (err) {
+        return {
+          success: false,
+          output: "",
+          error: `Signing failed: ${err.message}`
+        };
+      }
+    } else {
+      signature = PLACEHOLDER_SIG;
+      unsigned = true;
+    }
+    const paymentPayload = {
+      x402Version: 1,
+      scheme: "exact",
+      network: requirements.network,
+      payload: { signature, authorization }
+    };
+    const headerValue = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");
+    const lines = [
+      `Resource:  ${url}`,
+      `Network:   ${requirements.network}`,
+      `Amount:    ${requirements.maxAmountRequired} (asset ${requirements.asset})`,
+      `Pay to:    ${requirements.payTo}`,
+      `From:      ${payer}`,
+      "",
+      "X-PAYMENT header value (add to your retry request):",
+      headerValue
+    ];
+    if (unsigned) {
+      lines.push(
+        "",
+        "WARNING: Placeholder signature \u2014 cannot be used for real on-chain payments.",
+        "Configure an IIdentityProvider with a bound wallet to enable live signing."
+      );
+    }
+    return {
+      success: true,
+      output: lines.join("\n"),
+      metadata: {
+        headerValue,
+        network: requirements.network,
+        amount: requirements.maxAmountRequired,
+        payTo: requirements.payTo,
+        asset: requirements.asset,
+        unsigned
+      }
+    };
+  }
+};
+
+// src/signer.ts
+import { ethers } from "ethers";
+var KNOWN_TOKENS = {
+  base: {
+    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    chainId: 8453,
+    name: "USD Coin",
+    version: "2"
+  },
+  "base-sepolia": {
+    address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    chainId: 84532,
+    name: "USD Coin",
+    version: "2"
+  }
+};
+var TRANSFER_WITH_AUTHORIZATION_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" }
+  ]
+};
+function assertValidPrivateKey(key) {
+  if (!/^0x[a-fA-F0-9]{64}$/.test(key)) {
+    throw new Error(
+      "Invalid private key: expected a 0x-prefixed 64-character hex string (32 bytes)."
+    );
+  }
+}
+function createEIP712Signer(privateKey, opts = {}) {
+  assertValidPrivateKey(privateKey);
+  const wallet = new ethers.Wallet(privateKey);
+  const domain = {
+    name: opts.tokenName ?? KNOWN_TOKENS.base.name,
+    version: opts.tokenVersion ?? KNOWN_TOKENS.base.version,
+    chainId: opts.chainId ?? KNOWN_TOKENS.base.chainId,
+    verifyingContract: opts.tokenAddress ?? KNOWN_TOKENS.base.address
+  };
+  return async (auth) => {
+    const message = {
+      from: auth.from,
+      to: auth.to,
+      value: BigInt(auth.value),
+      validAfter: BigInt(auth.validAfter),
+      validBefore: BigInt(auth.validBefore),
+      nonce: auth.nonce
+    };
+    return wallet.signTypedData(domain, TRANSFER_WITH_AUTHORIZATION_TYPES, message);
+  };
+}
+function walletAddress(privateKey) {
+  assertValidPrivateKey(privateKey);
+  return new ethers.Wallet(privateKey).address;
+}
+export {
+  KNOWN_TOKENS,
+  X402PayTool,
+  createEIP712Signer,
+  createX402Middleware,
+  decodePaymentHeader,
+  pathMatches,
+  walletAddress
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ch4p/plugin-x402",
+  "version": "0.1.4",
+  "description": "x402 HTTP micropayment plugin for ch4p — server middleware and agent payment tool",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "ethers": "^6.14.0",
+    "@ch4p/core": "0.1.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @ch4p/plugin-x402 — x402 HTTP micropayment plugin
+ *
+ * Provides two components:
+ *
+ * **Server-side** (`createX402Middleware`):
+ *   Register on GatewayServer via the `preHandler` option to protect gateway
+ *   endpoints with HTTP 402 Payment Required. Responds with structured x402
+ *   payment requirements and verifies X-PAYMENT headers on retry.
+ *
+ * **Client-side** (`X402PayTool`):
+ *   Register in the agent's ToolRegistry to let the agent pay for x402-gated
+ *   resources. Builds the X-PAYMENT header value from a 402 response body.
+ *   Plug in an `x402Signer` via toolContextExtensions for live signing.
+ *
+ * Config key in ~/.ch4p/config.json: `"x402"`
+ */
+
+export { createX402Middleware } from './middleware.js';
+export type { X402PreHandler } from './middleware.js';
+export { pathMatches, decodePaymentHeader } from './middleware.js';
+
+export { X402PayTool } from './x402-pay-tool.js';
+export type { X402ToolContext } from './x402-pay-tool.js';
+
+export { createEIP712Signer, walletAddress, KNOWN_TOKENS } from './signer.js';
+export type { EIP712SignerOpts } from './signer.js';
+
+export type {
+  X402Config,
+  X402ClientConfig,
+  X402ServerConfig,
+  X402Response,
+  X402PaymentRequirements,
+  X402PaymentPayload,
+  X402PaymentAuthorization,
+} from './types.js';