nullpath-mcp 1.2.0 → 1.3.0

package/dist/lib/payment.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidPrivateKeyError = exports.WalletNotConfiguredError = exports.isWalletConfigured = exports.PaymentSigningError = exports.PaymentRequiredError = void 0;
+exports.parsePaymentRequired = parsePaymentRequired;
+exports.signPayment = signPayment;
+exports.encodePaymentHeader = encodePaymentHeader;
+exports.fetchWithPayment = fetchWithPayment;
+exports.formatUsdcAmount = formatUsdcAmount;
+const eip3009_js_1 = require("./eip3009.js");
+const wallet_js_1 = require("./wallet.js");
+/** Expected network for payments (Base mainnet) */
+const EXPECTED_NETWORK = 8453;
+/**
+ * Error thrown when payment is required but cannot be made
+ */
+class PaymentRequiredError extends Error {
+    requirements;
+    constructor(message, requirements) {
+        super(message);
+        this.requirements = requirements;
+        this.name = 'PaymentRequiredError';
+    }
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+/**
+ * Error thrown when payment signing fails
+ */
+class PaymentSigningError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'PaymentSigningError';
+    }
+}
+exports.PaymentSigningError = 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
+ */
+function parsePaymentRequired(response) {
+    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) {
+    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,
+            amount: BigInt(amount),
+            asset: (asset || eip3009_js_1.USDC_ADDRESS_BASE),
+            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
+ */
+async function signPayment(wallet, requirements) {
+    // Validate that the requested payment matches our signing configuration
+    const requestedNetwork = requirements.network;
+    const requestedAsset = requirements.asset?.toLowerCase();
+    const expectedAsset = eip3009_js_1.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 ${eip3009_js_1.USDC_ADDRESS_BASE}).`);
+    }
+    try {
+        const params = {
+            from: wallet.address,
+            to: requirements.recipient,
+            value: requirements.amount,
+            validAfter: requirements.validAfter,
+            validBefore: requirements.validBefore,
+            nonce: (0, eip3009_js_1.generateNonce)(),
+        };
+        return await (0, eip3009_js_1.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
+ */
+function encodePaymentHeader(signed) {
+    const payload = {
+        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, extra) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const headers = new Headers(base);
+    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
+ */
+async function fetchWithPayment(url, options = {}) {
+    // 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 (!(0, wallet_js_1.isWalletConfigured)()) {
+        throw new wallet_js_1.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;
+    try {
+        wallet = (0, wallet_js_1.createWallet)();
+    }
+    catch (error) {
+        if (error instanceof wallet_js_1.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)
+ */
+function formatUsdcAmount(atomic) {
+    const whole = atomic / 1000000n;
+    const fraction = atomic % 1000000n;
+    const fractionStr = fraction.toString().padStart(6, '0');
+    return `$${whole.toString()}.${fractionStr} USDC`;
+}
+// Re-export wallet utilities for convenience
+var wallet_js_2 = require("./wallet.js");
+Object.defineProperty(exports, "isWalletConfigured", { enumerable: true, get: function () { return wallet_js_2.isWalletConfigured; } });
+Object.defineProperty(exports, "WalletNotConfiguredError", { enumerable: true, get: function () { return wallet_js_2.WalletNotConfiguredError; } });
+Object.defineProperty(exports, "InvalidPrivateKeyError", { enumerable: true, get: function () { return wallet_js_2.InvalidPrivateKeyError; } });
+//# sourceMappingURL=payment.js.map

package/dist/lib/payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.js","sourceRoot":"","sources":["../../src/lib/payment.ts"],"names":[],"mappings":"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"}

package/dist/lib/wallet.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 { type WalletClient, type Account } from 'viem';
+/**
+ * Environment variable name for the wallet private key
+ */
+export declare 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 declare class WalletNotConfiguredError extends Error {
+    constructor();
+}
+/**
+ * Error thrown when private key is invalid
+ */
+export declare class InvalidPrivateKeyError extends Error {
+    constructor(reason: 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 declare function createWallet(config?: WalletConfig): NullpathWallet;
+/**
+ * Check if wallet is configured (without creating it)
+ *
+ * @returns true if NULLPATH_WALLET_KEY is set
+ */
+export declare function isWalletConfigured(): boolean;
+/**
+ * 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 declare function getWalletAddress(): `0x${string}` | null;
+//# sourceMappingURL=wallet.d.ts.map

package/dist/lib/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/lib/wallet.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA4B,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAIjF;;GAEG;AACH,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,MAAM,EAAE,YAAY,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,qBAAqB;IACrB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;;CAOlD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,MAAM,EAAE,MAAM;CAI3B;AA4BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,cAAc,CA0BlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,MAAM,EAAE,GAAG,IAAI,CAWvD"}

package/dist/lib/wallet.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Wallet Client Setup for nullpath MCP Client
+ *
+ * Creates a viem wallet client from the NULLPATH_WALLET_KEY
+ * environment variable for signing EIP-3009 payments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidPrivateKeyError = exports.WalletNotConfiguredError = exports.WALLET_KEY_ENV = void 0;
+exports.createWallet = createWallet;
+exports.isWalletConfigured = isWalletConfigured;
+exports.getWalletAddress = getWalletAddress;
+const viem_1 = require("viem");
+const accounts_1 = require("viem/accounts");
+const chains_1 = require("viem/chains");
+/**
+ * Environment variable name for the wallet private key
+ */
+exports.WALLET_KEY_ENV = 'NULLPATH_WALLET_KEY';
+/**
+ * Error thrown when wallet is not configured
+ */
+class WalletNotConfiguredError extends Error {
+    constructor() {
+        super(`Wallet not configured. Set ${exports.WALLET_KEY_ENV} environment variable with your private key.`);
+        this.name = 'WalletNotConfiguredError';
+    }
+}
+exports.WalletNotConfiguredError = WalletNotConfiguredError;
+/**
+ * Error thrown when private key is invalid
+ */
+class InvalidPrivateKeyError extends Error {
+    constructor(reason) {
+        super(`Invalid private key: ${reason}`);
+        this.name = 'InvalidPrivateKeyError';
+    }
+}
+exports.InvalidPrivateKeyError = InvalidPrivateKeyError;
+/**
+ * Normalize private key to proper format
+ *
+ * Accepts keys with or without 0x prefix
+ */
+function normalizePrivateKey(key) {
+    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;
+}
+/**
+ * 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);
+ * ```
+ */
+function createWallet(config) {
+    // Get private key from config or environment
+    const rawKey = config?.privateKey ?? process.env[exports.WALLET_KEY_ENV];
+    if (!rawKey) {
+        throw new WalletNotConfiguredError();
+    }
+    // Normalize and validate
+    const privateKey = normalizePrivateKey(rawKey);
+    // Create account from private key
+    const account = (0, accounts_1.privateKeyToAccount)(privateKey);
+    // Create wallet client for Base mainnet
+    const client = (0, viem_1.createWalletClient)({
+        account,
+        chain: chains_1.base,
+        transport: (0, viem_1.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
+ */
+function isWalletConfigured() {
+    return !!process.env[exports.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
+ */
+function getWalletAddress() {
+    const rawKey = process.env[exports.WALLET_KEY_ENV];
+    if (!rawKey)
+        return null;
+    try {
+        const privateKey = normalizePrivateKey(rawKey);
+        const account = (0, accounts_1.privateKeyToAccount)(privateKey);
+        return account.address;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=wallet.js.map

package/dist/lib/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/lib/wallet.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAsGH,oCA0BC;AAOD,gDAEC;AAUD,4CAWC;AA5JD,+BAAiF;AACjF,4CAAoD;AACpD,wCAAmC;AAEnC;;GAEG;AACU,QAAA,cAAc,GAAG,qBAAqB,CAAC;AAwBpD;;GAEG;AACH,MAAa,wBAAyB,SAAQ,KAAK;IACjD;QACE,KAAK,CACH,8BAA8B,sBAAc,8CAA8C,CAC3F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAPD,4DAOC;AAED;;GAEG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,MAAc;QACxB,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,GAAW;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAE3B,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;IAErE,iDAAiD;IACjD,IAAI,QAAQ,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC3B,MAAM,IAAI,sBAAsB,CAC9B,mCAAmC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CACzD,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,sBAAsB,CAAC,0CAA0C,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,QAAyB,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,YAAY,CAAC,MAAqB;IAChD,6CAA6C;IAC7C,MAAM,MAAM,GAAG,MAAM,EAAE,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAc,CAAC,CAAC;IAEjE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACvC,CAAC;IAED,yBAAyB;IACzB,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE/C,kCAAkC;IAClC,MAAM,OAAO,GAAG,IAAA,8BAAmB,EAAC,UAAU,CAAC,CAAC;IAEhD,wCAAwC;IACxC,MAAM,MAAM,GAAG,IAAA,yBAAkB,EAAC;QAChC,OAAO;QACP,KAAK,EAAE,aAAI;QACX,SAAS,EAAE,IAAA,WAAI,EAAC,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC;IAEH,OAAO;QACL,MAAM;QACN,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,gBAAgB;IAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAA,8BAAmB,EAAC,UAAU,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC,OAAO,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}