@ch4p/plugin-x402 0.1.4

package/src/signer.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Tests for the x402 EIP-712 signer.
+ *
+ * Uses a well-known test private key to verify:
+ *   - walletAddress() derives the correct checksummed address.
+ *   - createEIP712Signer() produces a 65-byte EIP-712 signature.
+ *   - The signature verifies against the expected typed data.
+ *   - KNOWN_TOKENS contains correct network entries.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ethers } from 'ethers';
+import { createEIP712Signer, walletAddress, KNOWN_TOKENS } from './signer.js';
+import type { X402PaymentAuthorization } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+//
+// Using the Ethereum test private key from the hardhat / foundry well-known
+// set. This key has no real funds and is safe for testing.
+// ---------------------------------------------------------------------------
+
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const EXPECTED_ADDRESS = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+
+const SAMPLE_AUTH: X402PaymentAuthorization = {
+  from:        '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+  to:          '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  value:       '1000000', // 1 USDC
+  validAfter:  '0',
+  validBefore: '9999999999',
+  nonce:       '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+};
+
+// ---------------------------------------------------------------------------
+// walletAddress
+// ---------------------------------------------------------------------------
+
+describe('walletAddress', () => {
+  it('returns the checksummed Ethereum address for the hardhat test key', () => {
+    const addr = walletAddress(TEST_PRIVATE_KEY);
+    expect(addr).toBe(EXPECTED_ADDRESS);
+  });
+
+  it('returns a checksummed EIP-55 address (mixed-case)', () => {
+    const addr = walletAddress(TEST_PRIVATE_KEY);
+    // EIP-55 checksummed addresses are not all-lowercase.
+    expect(addr).not.toBe(addr.toLowerCase());
+  });
+});
+
+// ---------------------------------------------------------------------------
+// KNOWN_TOKENS
+// ---------------------------------------------------------------------------
+
+describe('KNOWN_TOKENS', () => {
+  it('contains a base entry with correct chainId', () => {
+    expect(KNOWN_TOKENS.base.chainId).toBe(8453);
+    expect(KNOWN_TOKENS.base.address).toMatch(/^0x/);
+  });
+
+  it('contains a base-sepolia entry with correct chainId', () => {
+    expect(KNOWN_TOKENS['base-sepolia'].chainId).toBe(84532);
+    expect(KNOWN_TOKENS['base-sepolia'].address).toMatch(/^0x/);
+  });
+
+  it('base and base-sepolia have different contract addresses', () => {
+    expect(KNOWN_TOKENS.base.address).not.toBe(KNOWN_TOKENS['base-sepolia'].address);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createEIP712Signer
+// ---------------------------------------------------------------------------
+
+describe('createEIP712Signer', () => {
+  it('returns a function (the signer callback)', () => {
+    const signer = createEIP712Signer(TEST_PRIVATE_KEY);
+    expect(typeof signer).toBe('function');
+  });
+
+  it('produces a 65-byte hex signature (0x + 130 hex chars)', async () => {
+    const signer = createEIP712Signer(TEST_PRIVATE_KEY);
+    const sig = await signer(SAMPLE_AUTH);
+
+    // EIP-712 signatures are 65 bytes: 32 (r) + 32 (s) + 1 (v).
+    // Represented as "0x" + 130 lowercase hex characters.
+    expect(sig).toMatch(/^0x[0-9a-f]{130}$/i);
+  });
+
+  it('signature verifies with ethers.verifyTypedData', async () => {
+    const signer = createEIP712Signer(TEST_PRIVATE_KEY);
+    const sig = await signer(SAMPLE_AUTH);
+
+    const domain = {
+      name:              KNOWN_TOKENS.base.name,
+      version:           KNOWN_TOKENS.base.version,
+      chainId:           KNOWN_TOKENS.base.chainId,
+      verifyingContract: KNOWN_TOKENS.base.address,
+    };
+    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:        SAMPLE_AUTH.from,
+      to:          SAMPLE_AUTH.to,
+      value:       BigInt(SAMPLE_AUTH.value),
+      validAfter:  BigInt(SAMPLE_AUTH.validAfter),
+      validBefore: BigInt(SAMPLE_AUTH.validBefore),
+      nonce:       SAMPLE_AUTH.nonce,
+    };
+
+    const recovered = ethers.verifyTypedData(domain, types, message, sig);
+    expect(recovered).toBe(EXPECTED_ADDRESS);
+  });
+
+  it('produces different signatures for different authorizations', async () => {
+    const signer = createEIP712Signer(TEST_PRIVATE_KEY);
+
+    const auth2: X402PaymentAuthorization = {
+      ...SAMPLE_AUTH,
+      nonce: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+    };
+
+    const sig1 = await signer(SAMPLE_AUTH);
+    const sig2 = await signer(auth2);
+
+    expect(sig1).not.toBe(sig2);
+  });
+
+  it('accepts custom chainId and tokenAddress opts', async () => {
+    const signer = createEIP712Signer(TEST_PRIVATE_KEY, {
+      chainId:      KNOWN_TOKENS['base-sepolia'].chainId,
+      tokenAddress: KNOWN_TOKENS['base-sepolia'].address,
+      tokenName:    KNOWN_TOKENS['base-sepolia'].name,
+      tokenVersion: KNOWN_TOKENS['base-sepolia'].version,
+    });
+
+    const sig = await signer(SAMPLE_AUTH);
+    // Should be a valid 65-byte signature.
+    expect(sig).toMatch(/^0x[0-9a-f]{130}$/i);
+
+    // Signature over base-sepolia domain should NOT verify against base domain.
+    const baseDomain = {
+      name:              KNOWN_TOKENS.base.name,
+      version:           KNOWN_TOKENS.base.version,
+      chainId:           KNOWN_TOKENS.base.chainId,
+      verifyingContract: KNOWN_TOKENS.base.address,
+    };
+    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:        SAMPLE_AUTH.from,
+      to:          SAMPLE_AUTH.to,
+      value:       BigInt(SAMPLE_AUTH.value),
+      validAfter:  BigInt(SAMPLE_AUTH.validAfter),
+      validBefore: BigInt(SAMPLE_AUTH.validBefore),
+      nonce:       SAMPLE_AUTH.nonce,
+    };
+
+    const recovered = ethers.verifyTypedData(baseDomain, types, message, sig);
+    // Different domain — recovered address should differ from expected.
+    expect(recovered).not.toBe(EXPECTED_ADDRESS);
+  });
+});

package/src/signer.ts

@@ -0,0 +1,159 @@
+/**
+ * EIP-712 signer for x402 EIP-3009 transferWithAuthorization.
+ *
+ * Provides a ready-to-use signer factory for the `x402Signer` callback in
+ * X402ToolContext.  Uses ethers.js v6 `Wallet.signTypedData()` to produce a
+ * standards-compliant EIP-712 signature over the `TransferWithAuthorization`
+ * struct defined in USDC (ERC-20 + EIP-3009).
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { createEIP712Signer, walletAddress } from '@ch4p/plugin-x402';
+ *
+ * const signer = createEIP712Signer(process.env.X402_PRIVATE_KEY!);
+ * const agentWallet = walletAddress(process.env.X402_PRIVATE_KEY!);
+ * ```
+ */
+
+import { ethers } from 'ethers';
+import type { X402PaymentAuthorization } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Well-known token addresses
+// ---------------------------------------------------------------------------
+
+/**
+ * USDC contract addresses and EIP-712 domain parameters for supported networks.
+ * Import `KNOWN_TOKENS` when you need to look up token details by network name.
+ */
+export const KNOWN_TOKENS = {
+  base: {
+    address:  '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    chainId:  8453,
+    name:     'USD Coin',
+    version:  '2',
+  },
+  'base-sepolia': {
+    address:  '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    chainId:  84532,
+    name:     'USD Coin',
+    version:  '2',
+  },
+} as const;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface EIP712SignerOpts {
+  /**
+   * EIP-712 domain chain ID.
+   * Default: 8453 (Base mainnet).
+   */
+  chainId?: number;
+  /**
+   * ERC-20 contract address whose `TransferWithAuthorization` is signed.
+   * Default: USDC on Base mainnet.
+   */
+  tokenAddress?: string;
+  /**
+   * Token name for the EIP-712 domain separator.
+   * Default: "USD Coin".
+   */
+  tokenName?: string;
+  /**
+   * Token version for the EIP-712 domain separator.
+   * Default: "2".
+   */
+  tokenVersion?: string;
+}
+
+// ---------------------------------------------------------------------------
+// EIP-712 type definitions (fixed for EIP-3009 transferWithAuthorization)
+// ---------------------------------------------------------------------------
+
+const TRANSFER_WITH_AUTHORIZATION_TYPES: Record<string, Array<{ name: string; type: string }>> = {
+  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' },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// createEIP712Signer
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an EIP-712 signer for x402 EIP-3009 `transferWithAuthorization`.
+ *
+ * Returns the `x402Signer` callback expected by `X402ToolContext`.
+ *
+ * @param privateKey  0x-prefixed hex private key. Typically sourced from an
+ *                    environment variable (e.g. `process.env.X402_PRIVATE_KEY`).
+ * @param opts        Optional overrides for chain ID, token address, name,
+ *                    and version used in the EIP-712 domain separator.
+ *
+ * @example
+ * ```ts
+ * const signer = createEIP712Signer(process.env.X402_PRIVATE_KEY!, {
+ *   chainId: 84532,  // base-sepolia
+ *   tokenAddress: KNOWN_TOKENS['base-sepolia'].address,
+ * });
+ * ```
+ */
+/** Validate a private key is a 0x-prefixed 32-byte hex string. */
+function assertValidPrivateKey(key: string): void {
+  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).',
+    );
+  }
+}
+
+export function createEIP712Signer(
+  privateKey: string,
+  opts: EIP712SignerOpts = {},
+): (authorization: X402PaymentAuthorization) => Promise<string> {
+  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: X402PaymentAuthorization): Promise<string> => {
+    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);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// walletAddress
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the checksummed Ethereum address from a private key.
+ * Use this to populate `agentWalletAddress` in `toolContextExtensions`.
+ *
+ * @param privateKey  0x-prefixed hex private key.
+ */
+export function walletAddress(privateKey: string): string {
+  assertValidPrivateKey(privateKey);
+  return new ethers.Wallet(privateKey).address;
+}

package/src/types.ts

@@ -0,0 +1,168 @@
+/**
+ * x402 Payment Required protocol types.
+ *
+ * Based on the x402 open standard for HTTP micropayments.
+ * Reference: https://www.x402.org
+ */
+
+/**
+ * Payment requirement describing what is needed to access a resource.
+ * Returned as part of the 402 Payment Required response body.
+ */
+export interface X402PaymentRequirements {
+  /** Always "exact" — pay exactly this amount. */
+  scheme: 'exact';
+  /** Network identifier (e.g. "base", "base-sepolia", "ethereum"). */
+  network: string;
+  /** Amount in the asset's smallest unit (e.g. "1000000" = 1 USDC at 6 decimals). */
+  maxAmountRequired: string;
+  /** The URL path being protected (e.g. "/api/data"). */
+  resource: string;
+  /** Human-readable payment description shown to the payer. */
+  description: string;
+  /** MIME type of the gated resource (e.g. "application/json"). */
+  mimeType: string;
+  /** Wallet address that receives the payment. */
+  payTo: string;
+  /** Seconds before the payment authorization expires. */
+  maxTimeoutSeconds: number;
+  /** ERC-20 token contract address (zero address "0x0" for native ETH). */
+  asset: string;
+  /** Scheme-specific extra data. */
+  extra: Record<string, unknown>;
+}
+
+/**
+ * Body of an HTTP 402 Payment Required response.
+ */
+export interface X402Response {
+  x402Version: 1;
+  error: 'X402';
+  accepts: X402PaymentRequirements[];
+}
+
+/**
+ * EIP-3009 transferWithAuthorization parameters.
+ * Embedded inside X402PaymentPayload.payload.
+ */
+export interface X402PaymentAuthorization {
+  /** Payer wallet address. */
+  from: string;
+  /** Recipient wallet address (must match payTo). */
+  to: string;
+  /** Transfer amount in the asset's smallest unit. */
+  value: string;
+  /** Unix timestamp (seconds) after which the auth is valid. Use "0" for immediate. */
+  validAfter: string;
+  /** Unix timestamp (seconds) before which the auth must be submitted. */
+  validBefore: string;
+  /** Random 32-byte nonce (0x hex) to prevent replay attacks. */
+  nonce: string;
+}
+
+/**
+ * Payment proof sent in the X-PAYMENT HTTP header (base64-encoded JSON).
+ */
+export interface X402PaymentPayload {
+  x402Version: 1;
+  scheme: 'exact';
+  network: string;
+  payload: {
+    /** EIP-712 signature over the EIP-3009 authorization struct. */
+    signature: string;
+    authorization: X402PaymentAuthorization;
+  };
+}
+
+/**
+ * Server-side x402 protection configuration.
+ */
+export interface X402ServerConfig {
+  /** Wallet address that receives payments. */
+  payTo: string;
+  /**
+   * Payment amount in the asset's smallest unit.
+   * Example: "1000000" = 1 USDC (6 decimals).
+   */
+  amount: string;
+  /**
+   * ERC-20 token contract address.
+   * Defaults to USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
+   */
+  asset?: string;
+  /**
+   * Network identifier.
+   * Defaults to "base".
+   */
+  network?: string;
+  /** Human-readable description shown in the 402 response. */
+  description?: string;
+  /**
+   * URL paths to gate. Supports trailing "/*" wildcard suffix.
+   * Examples: "/sessions", "/webhooks/*", "/*" (all paths).
+   * Default: all paths except /health, /.well-known/agent.json, and /pair.
+   */
+  protectedPaths?: string[];
+  /** Seconds before a payment authorization expires. Default: 300. */
+  maxTimeoutSeconds?: number;
+  /**
+   * Optional payment verifier. Called with the decoded payment and the
+   * active requirements after the X-PAYMENT header passes structural
+   * validation. Return true to grant access, false to re-issue 402.
+   *
+   * If omitted, structural validity of the X-PAYMENT header is sufficient.
+   * For production deployments, provide an on-chain verifier that calls
+   * transferWithAuthorization on the ERC-20 asset contract.
+   */
+  verifyPayment?: (
+    payment: X402PaymentPayload,
+    requirements: X402PaymentRequirements,
+  ) => Promise<boolean>;
+}
+
+/**
+ * Client-side wallet configuration for signing x402 payment authorizations.
+ * Set `x402.client.privateKey` (or `${X402_PRIVATE_KEY}` env substitution)
+ * in ~/.ch4p/config.json to enable live on-chain payments.
+ */
+export interface X402ClientConfig {
+  /**
+   * 0x-prefixed hex private key used to sign EIP-712 payment authorizations.
+   * Supports env-var substitution: `"${X402_PRIVATE_KEY}"`.
+   *
+   * ⚠️  Never commit a real private key to source control.
+   */
+  privateKey?: string;
+  /**
+   * ERC-20 token contract address.
+   * Default: USDC on Base mainnet (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
+   */
+  tokenAddress?: string;
+  /**
+   * EIP-712 domain chain ID.
+   * Default: 8453 (Base mainnet).
+   */
+  chainId?: number;
+  /**
+   * EIP-712 domain token name.
+   * Default: "USD Coin".
+   */
+  tokenName?: string;
+  /**
+   * EIP-712 domain token version.
+   * Default: "2".
+   */
+  tokenVersion?: string;
+}
+
+/**
+ * Top-level x402 plugin configuration (added to ~/.ch4p/config.json).
+ */
+export interface X402Config {
+  /** Whether x402 payment enforcement is active. Default: false. */
+  enabled?: boolean;
+  /** Server-side: protect gateway endpoints with payment requirements. */
+  server?: X402ServerConfig;
+  /** Client-side: wallet config for signing payment authorizations. */
+  client?: X402ClientConfig;
+}