nullpath-mcp 1.2.0 → 1.3.0

package/src/lib/eip3009.ts

@@ -0,0 +1,201 @@
+/**
+ * EIP-3009: Transfer With Authorization for USDC
+ *
+ * Implements typed data structures and signing for USDC's
+ * TransferWithAuthorization function, enabling gasless transfers
+ * where a third party can submit the transaction.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-3009
+ */
+
+import type { WalletClient } from 'viem';
+
+/**
+ * USDC contract address on Base mainnet
+ */
+export const USDC_ADDRESS_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' as const;
+
+/**
+ * USDC decimals (standard across all networks)
+ */
+export const USDC_DECIMALS = 6;
+
+/**
+ * EIP-712 Domain for USDC on Base
+ */
+export const USDC_DOMAIN = {
+  name: 'USD Coin',
+  version: '2',
+  chainId: 8453,
+  verifyingContract: USDC_ADDRESS_BASE,
+} as const;
+
+/**
+ * EIP-712 types for TransferWithAuthorization
+ */
+export const 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' },
+  ],
+} as const;
+
+/**
+ * Parameters for TransferWithAuthorization
+ */
+export interface TransferAuthorizationParams {
+  /** Sender address (must match wallet) */
+  from: `0x${string}`;
+  /** Recipient address */
+  to: `0x${string}`;
+  /** Amount in atomic units (6 decimals for USDC) */
+  value: bigint;
+  /** Unix timestamp after which the authorization is valid */
+  validAfter: bigint;
+  /** Unix timestamp before which the authorization is valid */
+  validBefore: bigint;
+  /** Unique nonce (32 bytes) to prevent replay */
+  nonce: `0x${string}`;
+}
+
+/**
+ * Signed authorization ready to submit on-chain
+ */
+export interface SignedTransferAuthorization extends TransferAuthorizationParams {
+  /** EIP-712 signature */
+  signature: `0x${string}`;
+  /** Signature v component */
+  v: number;
+  /** Signature r component */
+  r: `0x${string}`;
+  /** Signature s component */
+  s: `0x${string}`;
+}
+
+/**
+ * Generate a cryptographically random nonce (32 bytes)
+ */
+export function generateNonce(): `0x${string}` {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')}` as `0x${string}`;
+}
+
+/**
+ * Convert USD amount to USDC atomic units
+ */
+export function usdToAtomicUsdc(usd: number): bigint {
+  return BigInt(Math.round(usd * 10 ** USDC_DECIMALS));
+}
+
+/**
+ * Convert USDC atomic units to USD
+ */
+export function atomicUsdcToUsd(atomic: bigint): number {
+  return Number(atomic) / 10 ** USDC_DECIMALS;
+}
+
+/**
+ * Sign a TransferWithAuthorization message
+ *
+ * Creates an EIP-712 signature that authorizes a transfer of USDC
+ * from the signer's wallet to a recipient. The signature can be
+ * submitted by anyone to execute the transfer.
+ *
+ * @param walletClient - viem wallet client with signing capability
+ * @param params - Transfer authorization parameters
+ * @returns Signed authorization with signature components
+ *
+ * @example
+ * ```ts
+ * const signed = await signTransferAuthorization(walletClient, {
+ *   from: '0x...',
+ *   to: '0x...',
+ *   value: usdToAtomicUsdc(0.10),
+ *   validAfter: 0n,
+ *   validBefore: BigInt(Math.floor(Date.now() / 1000) + 3600),
+ *   nonce: generateNonce(),
+ * });
+ * ```
+ */
+export async function signTransferAuthorization(
+  walletClient: WalletClient,
+  params: TransferAuthorizationParams
+): Promise<SignedTransferAuthorization> {
+  const account = walletClient.account;
+  if (!account) {
+    throw new Error('Wallet client must have an account');
+  }
+
+  // Verify from address matches wallet
+  if (params.from.toLowerCase() !== account.address.toLowerCase()) {
+    throw new Error(
+      `From address ${params.from} does not match wallet address ${account.address}`
+    );
+  }
+
+  // Sign the typed data
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: USDC_DOMAIN,
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: 'TransferWithAuthorization',
+    message: {
+      from: params.from,
+      to: params.to,
+      value: params.value,
+      validAfter: params.validAfter,
+      validBefore: params.validBefore,
+      nonce: params.nonce,
+    },
+  });
+
+  // Validate signature length (65 bytes = 130 hex chars + 0x prefix)
+  if (signature.length !== 132) {
+    throw new Error(`Unexpected signature length: ${signature.length}, expected 132`);
+  }
+
+  // Extract v, r, s components from signature
+  const r = `0x${signature.slice(2, 66)}` as `0x${string}`;
+  const s = `0x${signature.slice(66, 130)}` as `0x${string}`;
+  const v = parseInt(signature.slice(130, 132), 16);
+
+  return {
+    ...params,
+    signature,
+    v,
+    r,
+    s,
+  };
+}
+
+/**
+ * Create transfer authorization params with sensible defaults
+ *
+ * @param from - Sender address
+ * @param to - Recipient address
+ * @param amountUsd - Amount in USD
+ * @param validitySeconds - How long the authorization is valid (default 5 minutes)
+ * @returns TransferAuthorizationParams ready for signing
+ */
+export function createTransferAuthorizationParams(
+  from: `0x${string}`,
+  to: `0x${string}`,
+  amountUsd: number,
+  validitySeconds: number = 300
+): TransferAuthorizationParams {
+  const now = Math.floor(Date.now() / 1000);
+
+  return {
+    from,
+    to,
+    value: usdToAtomicUsdc(amountUsd),
+    validAfter: 0n, // Valid immediately
+    validBefore: BigInt(now + validitySeconds),
+    nonce: generateNonce(),
+  };
+}

package/src/lib/payment.ts

@@ -0,0 +1,334 @@
+/**
+ * Payment Integration for nullpath MCP Client
+ *
+ * Handles x402 payment flow:
+ * 1. Parse 402 Payment Required responses
+ * 2. Sign EIP-3009 TransferWithAuthorization
+ * 3. Encode payment header for retry
+ */
+
+import {
+  signTransferAuthorization,
+  generateNonce,
+  USDC_ADDRESS_BASE,
+  type TransferAuthorizationParams,
+  type SignedTransferAuthorization,
+} from './eip3009.js';
+import {
+  createWallet,
+  isWalletConfigured,
+  WalletNotConfiguredError,
+  InvalidPrivateKeyError,
+  type NullpathWallet,
+} from './wallet.js';
+
+/** Expected network for payments (Base mainnet) */
+const EXPECTED_NETWORK = 8453;
+
+/**
+ * Payment requirements from 402 response
+ */
+export interface PaymentRequirements {
+  /** Recipient wallet address */
+  recipient: `0x${string}`;
+  /** Amount in atomic USDC units */
+  amount: bigint;
+  /** USDC contract address */
+  asset: `0x${string}`;
+  /** Chain ID (8453 for Base) */
+  network: number;
+  /** Unix timestamp - authorization valid after */
+  validAfter: bigint;
+  /** Unix timestamp - authorization valid before */
+  validBefore: bigint;
+}
+
+/**
+ * Payment header payload
+ */
+export interface PaymentPayload {
+  signature: string;
+  from: string;
+  to: string;
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: string;
+}
+
+/**
+ * Error thrown when payment is required but cannot be made
+ */
+export class PaymentRequiredError extends Error {
+  constructor(
+    message: string,
+    public readonly requirements?: PaymentRequirements
+  ) {
+    super(message);
+    this.name = 'PaymentRequiredError';
+  }
+}
+
+/**
+ * Error thrown when payment signing fails
+ */
+export class PaymentSigningError extends Error {
+  constructor(message: string, public readonly cause?: Error) {
+    super(message);
+    this.name = 'PaymentSigningError';
+  }
+}
+
+/**
+ * Parse 402 Payment Required response headers
+ *
+ * Extracts payment requirements from X-PAYMENT-REQUIRED header.
+ * The header contains base64-encoded JSON with payment details.
+ *
+ * @param response - Fetch Response object
+ * @returns PaymentRequirements or null if not a 402 response
+ */
+export function parsePaymentRequired(response: Response): PaymentRequirements | null {
+  if (response.status !== 402) {
+    return null;
+  }
+
+  const header = response.headers.get('X-PAYMENT-REQUIRED');
+  if (!header) {
+    // Try legacy header name
+    const legacyHeader = response.headers.get('X-Payment-Required');
+    if (!legacyHeader) {
+      throw new PaymentRequiredError(
+        'Payment required but X-PAYMENT-REQUIRED header missing'
+      );
+    }
+    return parsePaymentHeader(legacyHeader);
+  }
+
+  return parsePaymentHeader(header);
+}
+
+/**
+ * Parse the payment header value
+ */
+function parsePaymentHeader(header: string): PaymentRequirements {
+  try {
+    // Decode base64
+    const decoded = Buffer.from(header, 'base64').toString('utf-8');
+    const data = JSON.parse(decoded);
+
+    // Extract and validate required fields
+    const recipient = data.recipient || data.payee;
+    const amount = data.amount || data.maxAmountRequired;
+    const asset = data.asset || data.usdcAddress;
+    const network = data.network || data.chainId || 8453;
+    
+    // Default validity window: now to 5 minutes from now
+    const now = Math.floor(Date.now() / 1000);
+    const validAfter = BigInt(data.validAfter || 0);
+    const validBefore = BigInt(data.validBefore || now + 300);
+
+    // Ensure authorization window is still valid
+    if (validBefore <= BigInt(now)) {
+      throw new Error(`Payment authorization expired: validBefore ${validBefore} is in the past`);
+    }
+
+    if (!recipient || !amount) {
+      throw new Error('Missing recipient or amount');
+    }
+
+    return {
+      recipient: recipient as `0x${string}`,
+      amount: BigInt(amount),
+      asset: (asset || USDC_ADDRESS_BASE) as `0x${string}`,
+      network: Number(network),
+      validAfter,
+      validBefore,
+    };
+  } catch (error) {
+    throw new PaymentRequiredError(
+      `Failed to parse payment requirements: ${error instanceof Error ? error.message : 'unknown error'}`
+    );
+  }
+}
+
+/**
+ * Sign a payment using EIP-3009 TransferWithAuthorization
+ *
+ * @param wallet - NullpathWallet instance
+ * @param requirements - Payment requirements from 402 response
+ * @returns Signed authorization
+ */
+export async function signPayment(
+  wallet: NullpathWallet,
+  requirements: PaymentRequirements
+): Promise<SignedTransferAuthorization> {
+  // Validate that the requested payment matches our signing configuration
+  const requestedNetwork = requirements.network;
+  const requestedAsset = requirements.asset?.toLowerCase();
+  const expectedAsset = USDC_ADDRESS_BASE.toLowerCase();
+
+  if (requestedNetwork !== EXPECTED_NETWORK || requestedAsset !== expectedAsset) {
+    throw new PaymentRequiredError(
+      `Payment requirements mismatch: requested network ${requestedNetwork} and asset ${requirements.asset} ` +
+      `do not match supported Base mainnet USDC (network ${EXPECTED_NETWORK}, asset ${USDC_ADDRESS_BASE}).`
+    );
+  }
+
+  try {
+    const params: TransferAuthorizationParams = {
+      from: wallet.address,
+      to: requirements.recipient,
+      value: requirements.amount,
+      validAfter: requirements.validAfter,
+      validBefore: requirements.validBefore,
+      nonce: generateNonce(),
+    };
+
+    return await signTransferAuthorization(wallet.client, params);
+  } catch (error) {
+    throw new PaymentSigningError(
+      `Failed to sign payment: ${error instanceof Error ? error.message : 'unknown error'}`,
+      error instanceof Error ? error : undefined
+    );
+  }
+}
+
+/**
+ * Encode signed authorization as X-PAYMENT header value
+ *
+ * @param signed - Signed transfer authorization
+ * @returns Base64-encoded JSON string for X-PAYMENT header
+ */
+export function encodePaymentHeader(signed: SignedTransferAuthorization): string {
+  const payload: PaymentPayload = {
+    signature: signed.signature,
+    from: signed.from,
+    to: signed.to,
+    value: signed.value.toString(),
+    validAfter: signed.validAfter.toString(),
+    validBefore: signed.validBefore.toString(),
+    nonce: signed.nonce,
+  };
+
+  return Buffer.from(JSON.stringify(payload)).toString('base64');
+}
+
+/**
+ * Build headers for fetch, properly handling Headers instances
+ */
+function buildHeaders(base?: RequestInit['headers'], extra?: Record<string, string>): Headers {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const headers = new Headers(base as any);
+  if (extra) {
+    for (const [key, value] of Object.entries(extra)) {
+      headers.set(key, value);
+    }
+  }
+  return headers;
+}
+
+/**
+ * Execute a fetch request with automatic x402 payment handling
+ *
+ * If the server returns 402 Payment Required:
+ * 1. Parse payment requirements
+ * 2. Sign EIP-3009 authorization
+ * 3. Retry with X-PAYMENT header
+ *
+ * @param url - Request URL
+ * @param options - Fetch options
+ * @returns Fetch Response
+ * @throws WalletNotConfiguredError if 402 and no wallet
+ * @throws PaymentSigningError if signing fails
+ */
+export async function fetchWithPayment(
+  url: string,
+  options: RequestInit = {}
+): Promise<Response> {
+  // Build headers properly (handles both plain objects and Headers instances)
+  const initialHeaders = buildHeaders(options.headers, {
+    'Content-Type': 'application/json',
+  });
+
+  // Make initial request
+  const response = await fetch(url, {
+    ...options,
+    headers: initialHeaders,
+  });
+
+  // Check for 402 Payment Required
+  if (response.status !== 402) {
+    return response;
+  }
+
+  // Payment required - check if wallet is configured
+  if (!isWalletConfigured()) {
+    throw new WalletNotConfiguredError();
+  }
+
+  // Parse payment requirements
+  const requirements = parsePaymentRequired(response);
+  if (!requirements) {
+    throw new PaymentRequiredError('Payment required but could not parse requirements');
+  }
+
+  // Create wallet and sign payment
+  let wallet: NullpathWallet;
+  try {
+    wallet = createWallet();
+  } catch (error) {
+    if (error instanceof InvalidPrivateKeyError) {
+      throw new PaymentSigningError(
+        `Invalid wallet configuration: ${error.message}`,
+        error
+      );
+    }
+    throw error;
+  }
+
+  const signed = await signPayment(wallet, requirements);
+  const paymentHeader = encodePaymentHeader(signed);
+
+  // Build retry headers with payment
+  const retryHeaders = buildHeaders(options.headers, {
+    'Content-Type': 'application/json',
+    'X-PAYMENT': paymentHeader,
+  });
+
+  // Retry with payment header
+  const retryResponse = await fetch(url, {
+    ...options,
+    headers: retryHeaders,
+  });
+
+  // If still 402, payment was rejected
+  if (retryResponse.status === 402) {
+    const errorBody = await retryResponse.text().catch(() => '');
+    throw new PaymentRequiredError(
+      `Payment was rejected by the server: ${errorBody || 'no details'}`,
+      requirements
+    );
+  }
+
+  // Handle other errors on retry
+  if (!retryResponse.ok) {
+    const errorBody = await retryResponse.text().catch(() => '');
+    throw new Error(`Payment submitted but request failed (${retryResponse.status}): ${errorBody}`);
+  }
+
+  return retryResponse;
+}
+
+/**
+ * Format amount in human-readable USDC (using bigint arithmetic to avoid precision loss)
+ */
+export function formatUsdcAmount(atomic: bigint): string {
+  const whole = atomic / 1_000_000n;
+  const fraction = atomic % 1_000_000n;
+  const fractionStr = fraction.toString().padStart(6, '0');
+  return `$${whole.toString()}.${fractionStr} USDC`;
+}
+
+// Re-export wallet utilities for convenience
+export { isWalletConfigured, WalletNotConfiguredError, InvalidPrivateKeyError } from './wallet.js';

package/src/lib/wallet.ts

@@ -0,0 +1,164 @@
+/**
+ * Wallet Client Setup for nullpath MCP Client
+ *
+ * Creates a viem wallet client from the NULLPATH_WALLET_KEY
+ * environment variable for signing EIP-3009 payments.
+ */
+
+import { createWalletClient, http, type WalletClient, type Account } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+
+/**
+ * Environment variable name for the wallet private key
+ */
+export const WALLET_KEY_ENV = 'NULLPATH_WALLET_KEY';
+
+/**
+ * Wallet configuration
+ */
+export interface WalletConfig {
+  /** Private key (with or without 0x prefix) */
+  privateKey?: string;
+  /** RPC URL for Base (optional, uses default public RPC) */
+  rpcUrl?: string;
+}
+
+/**
+ * Wallet client with account information
+ */
+export interface NullpathWallet {
+  /** viem wallet client for signing */
+  client: WalletClient;
+  /** Account derived from private key */
+  account: Account;
+  /** Wallet address */
+  address: `0x${string}`;
+}
+
+/**
+ * Error thrown when wallet is not configured
+ */
+export class WalletNotConfiguredError extends Error {
+  constructor() {
+    super(
+      `Wallet not configured. Set ${WALLET_KEY_ENV} environment variable with your private key.`
+    );
+    this.name = 'WalletNotConfiguredError';
+  }
+}
+
+/**
+ * Error thrown when private key is invalid
+ */
+export class InvalidPrivateKeyError extends Error {
+  constructor(reason: string) {
+    super(`Invalid private key: ${reason}`);
+    this.name = 'InvalidPrivateKeyError';
+  }
+}
+
+/**
+ * Normalize private key to proper format
+ *
+ * Accepts keys with or without 0x prefix
+ */
+function normalizePrivateKey(key: string): `0x${string}` {
+  const trimmed = key.trim();
+
+  // Add 0x prefix if missing
+  const prefixed = trimmed.startsWith('0x') ? trimmed : `0x${trimmed}`;
+
+  // Validate length (0x + 64 hex chars = 66 chars)
+  if (prefixed.length !== 66) {
+    throw new InvalidPrivateKeyError(
+      `Expected 64 hex characters, got ${prefixed.length - 2}`
+    );
+  }
+
+  // Validate hex format
+  if (!/^0x[0-9a-fA-F]{64}$/.test(prefixed)) {
+    throw new InvalidPrivateKeyError('Must contain only hexadecimal characters');
+  }
+
+  return prefixed as `0x${string}`;
+}
+
+/**
+ * Create a wallet client from configuration or environment
+ *
+ * @param config - Optional wallet configuration. If not provided,
+ *                 reads from NULLPATH_WALLET_KEY environment variable.
+ * @returns NullpathWallet with client, account, and address
+ * @throws WalletNotConfiguredError if no private key available
+ * @throws InvalidPrivateKeyError if private key format is invalid
+ *
+ * @example
+ * ```ts
+ * // From environment variable
+ * const wallet = createWallet();
+ *
+ * // From explicit config
+ * const wallet = createWallet({ privateKey: '0x...' });
+ *
+ * // Use for signing
+ * const signed = await signTransferAuthorization(wallet.client, params);
+ * ```
+ */
+export function createWallet(config?: WalletConfig): NullpathWallet {
+  // Get private key from config or environment
+  const rawKey = config?.privateKey ?? process.env[WALLET_KEY_ENV];
+
+  if (!rawKey) {
+    throw new WalletNotConfiguredError();
+  }
+
+  // Normalize and validate
+  const privateKey = normalizePrivateKey(rawKey);
+
+  // Create account from private key
+  const account = privateKeyToAccount(privateKey);
+
+  // Create wallet client for Base mainnet
+  const client = createWalletClient({
+    account,
+    chain: base,
+    transport: http(config?.rpcUrl),
+  });
+
+  return {
+    client,
+    account,
+    address: account.address,
+  };
+}
+
+/**
+ * Check if wallet is configured (without creating it)
+ *
+ * @returns true if NULLPATH_WALLET_KEY is set
+ */
+export function isWalletConfigured(): boolean {
+  return !!process.env[WALLET_KEY_ENV];
+}
+
+/**
+ * Get wallet address without full client setup
+ *
+ * Useful for checking the configured address without
+ * creating a full wallet client.
+ *
+ * @returns Wallet address or null if not configured
+ */
+export function getWalletAddress(): `0x${string}` | null {
+  const rawKey = process.env[WALLET_KEY_ENV];
+  if (!rawKey) return null;
+
+  try {
+    const privateKey = normalizePrivateKey(rawKey);
+    const account = privateKeyToAccount(privateKey);
+    return account.address;
+  } catch {
+    return null;
+  }
+}

package/dist/__tests__/x402.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=x402.test.d.ts.map

package/dist/__tests__/x402.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"x402.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/x402.test.ts"],"names":[],"mappings":""}