@agether/sdk 1.0.0

package/dist/clients/X402Client.js

@@ -0,0 +1,303 @@
+/**
+ * x402 HTTP Client — Make paid API calls via the x402 protocol (v2)
+ *
+ * Implements the Coinbase x402 spec:
+ *   https://github.com/coinbase/x402
+ *
+ * Flow:
+ *   1. Client → Resource Server (normal request)
+ *   2. Resource Server → 402 with PaymentRequired JSON body
+ *      Body: { x402Version, error, resource, accepts: [PaymentRequirements…] }
+ *   3. Client picks a PaymentRequirements from `accepts`,
+ *      signs an EIP-3009 transferWithAuthorization (EIP-712 typed data),
+ *      builds a PaymentPayload, base64-encodes it as PAYMENT-SIGNATURE header
+ *   4. Client → Resource Server (retries with PAYMENT-SIGNATURE)
+ *   5. Resource Server forwards to Facilitator /verify → /settle
+ *   6. Resource Server → 200 + data  (or error)
+ *
+ * Chain support: Base (8453), Ethereum (1), and Hardhat fork (31337).
+ * USDC domain is resolved per-chain from USDC_DOMAINS map.
+ */
+import { ethers } from 'ethers';
+// ──────────────────── Well-known USDC metadata ────────────────────
+// EIP-3009 domain per chain (name / version / verifyingContract)
+const USDC_DOMAINS = {
+    'eip155:1': { name: 'USD Coin', version: '2', address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
+    'eip155:8453': { name: 'USD Coin', version: '2', address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
+    'eip155:84532': { name: 'USD Coin', version: '2', address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' },
+    'eip155:42161': { name: 'USD Coin', version: '2', address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' },
+    'eip155:10': { name: 'USD Coin', version: '2', address: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85' },
+};
+function chainIdFromNetwork(network) {
+    const m = network.match(/^eip155:(\d+)$/);
+    return m ? Number(m[1]) : 1;
+}
+// ──────────────────── Client ────────────────────
+export class X402Client {
+    constructor(config) {
+        this.config = config;
+        const provider = new ethers.JsonRpcProvider(config.rpcUrl);
+        this.wallet = new ethers.Wallet(config.privateKey, provider);
+    }
+    async get(url, opts) {
+        return this.request(url, { ...opts, method: 'GET' });
+    }
+    async post(url, body, opts) {
+        return this.request(url, {
+            ...opts,
+            method: 'POST',
+            body: body ? JSON.stringify(body) : undefined,
+            headers: { 'Content-Type': 'application/json', ...opts?.headers },
+        });
+    }
+    getAddress() {
+        return this.wallet.address;
+    }
+    // ──────────── Core request / 402-retry loop ────────────
+    async request(url, options) {
+        try {
+            // 1️⃣  First attempt — may get 402
+            console.log('   [1/4] Calling resource server…');
+            const response = await fetch(url, {
+                ...options,
+                headers: {
+                    ...options?.headers,
+                    'X-Agent-Id': this.config.agentId || '',
+                },
+            });
+            if (response.ok) {
+                const data = await response.json();
+                return { success: true, data };
+            }
+            if (response.status !== 402) {
+                return { success: false, error: `HTTP ${response.status}: ${await response.text()}` };
+            }
+            // 2️⃣  Parse PaymentRequired
+            console.log('   [2/4] 402 received — parsing payment requirements…');
+            const parsed = await this.parsePaymentRequired(response);
+            if (!parsed) {
+                return { success: false, error: 'Could not parse payment requirements from 402 response' };
+            }
+            const { requirements, resource } = parsed;
+            console.log(`         scheme  : ${requirements.scheme}`);
+            console.log(`         network : ${requirements.network}`);
+            console.log(`         amount  : ${requirements.amount} (atomic)`);
+            console.log(`         asset   : ${requirements.asset}`);
+            console.log(`         payTo   : ${requirements.payTo}`);
+            // 3️⃣  Sign EIP-3009 authorization & build PaymentPayload
+            console.log('   [3/4] Signing EIP-3009 transferWithAuthorization…');
+            const paymentPayload = await this.buildPaymentPayload(requirements, resource, url);
+            const paymentB64 = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
+            // Optional: risk-check via our backend
+            await this.riskCheck(paymentPayload, requirements);
+            // 4️⃣  Retry with PAYMENT-SIGNATURE header
+            console.log('   [4/4] Retrying with PAYMENT-SIGNATURE header…');
+            const paidResponse = await fetch(url, {
+                ...options,
+                headers: {
+                    ...options?.headers,
+                    'X-Agent-Id': this.config.agentId || '',
+                    // v2 header
+                    'PAYMENT-SIGNATURE': paymentB64,
+                    // v1 compat header (some servers still use this)
+                    'X-PAYMENT': paymentB64,
+                },
+            });
+            if (paidResponse.ok) {
+                const data = await paidResponse.json();
+                // Check for settlement response
+                const settlementHeader = paidResponse.headers.get('PAYMENT-RESPONSE')
+                    || paidResponse.headers.get('X-PAYMENT-RESPONSE');
+                let txHash;
+                if (settlementHeader) {
+                    try {
+                        const settlement = JSON.parse(Buffer.from(settlementHeader, 'base64').toString('utf-8'));
+                        txHash = settlement.transaction;
+                    }
+                    catch { }
+                }
+                return {
+                    success: true,
+                    data,
+                    paymentInfo: {
+                        amount: requirements.amount,
+                        asset: requirements.extra?.name || 'USDC',
+                        network: requirements.network,
+                        txHash,
+                    },
+                };
+            }
+            const errBody = await paidResponse.text();
+            return { success: false, error: `Payment rejected (HTTP ${paidResponse.status}): ${errBody}` };
+        }
+        catch (error) {
+            return { success: false, error: `Request failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    // ──────────── Parse 402 response ────────────
+    async parsePaymentRequired(response) {
+        // Strategy 1: PAYMENT-REQUIRED header (base64 JSON — some servers)
+        const prHeader = response.headers.get('PAYMENT-REQUIRED') || response.headers.get('x-payment-required');
+        if (prHeader) {
+            try {
+                const decoded = JSON.parse(Buffer.from(prHeader, 'base64').toString('utf-8'));
+                if (decoded.accepts?.length) {
+                    return { requirements: decoded.accepts[0], resource: decoded.resource };
+                }
+            }
+            catch { /* fall through */ }
+        }
+        // Strategy 2: Response body (primary method per v2 spec)
+        try {
+            const body = await response.json();
+            // v2 format: { accepts: [...] }
+            if (body.accepts && Array.isArray(body.accepts) && body.accepts.length > 0) {
+                return { requirements: body.accepts[0], resource: body.resource };
+            }
+            // v1 compat: { paymentRequirements: {...} } or { paymentRequirements: [...] }
+            if (body.paymentRequirements) {
+                const pr = Array.isArray(body.paymentRequirements) ? body.paymentRequirements[0] : body.paymentRequirements;
+                return { requirements: pr, resource: body.resource };
+            }
+            // Ultra-legacy: flat fields
+            if (body.scheme && body.network) {
+                return { requirements: body, resource: body.resource };
+            }
+        }
+        catch { /* fall through */ }
+        // Strategy 3: WWW-Authenticate header (old implementations)
+        const wwwAuth = response.headers.get('WWW-Authenticate');
+        if (wwwAuth) {
+            const m = wwwAuth.match(/x402[^"]*"([^"]+)"/);
+            if (m) {
+                try {
+                    const decoded = JSON.parse(Buffer.from(m[1], 'base64').toString('utf-8'));
+                    const reqs = Array.isArray(decoded) ? decoded[0] : decoded;
+                    return { requirements: reqs };
+                }
+                catch { /* fall through */ }
+            }
+        }
+        return null;
+    }
+    // ──────────── Build x402 v2 PaymentPayload with EIP-3009 ────────────
+    //
+    // If an AgentAccount is configured, we use it as the `from` address
+    // (smart wallet pays directly). The AgentAccount implements EIP-1271
+    // so USDC's transferWithAuthorization will call isValidSignature()
+    // to verify the owner's ECDSA signature. The facilitator detects
+    // the >65-byte or smart-wallet case and uses the bytes overload.
+    async buildPaymentPayload(reqs, resource, url) {
+        const now = Math.floor(Date.now() / 1000);
+        const validAfter = String(now - 60);
+        const validBefore = String(now + (reqs.maxTimeoutSeconds || 300));
+        const nonce = ethers.hexlify(ethers.randomBytes(32));
+        const chainId = chainIdFromNetwork(reqs.network);
+        const usdcDomain = USDC_DOMAINS[reqs.network] || USDC_DOMAINS['eip155:1'];
+        // Determine payer: AgentAccount (smart wallet) if available, else EOA
+        const payerAddress = this.config.accountAddress || this.wallet.address;
+        const isSmartWallet = !!this.config.accountAddress;
+        // EIP-712 domain for USDC's transferWithAuthorization (EIP-3009)
+        const domain = {
+            name: usdcDomain.name,
+            version: usdcDomain.version,
+            chainId,
+            verifyingContract: reqs.asset || usdcDomain.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 value = {
+            from: payerAddress, // AgentAccount or EOA
+            to: reqs.payTo,
+            value: reqs.amount,
+            validAfter,
+            validBefore,
+            nonce,
+        };
+        // EOA signs the typed data — for smart wallets, EIP-1271 validation
+        // will verify this signature against the AgentAccount's owner()
+        let signature = await this.wallet.signTypedData(domain, types, value);
+        // For smart wallets: pad the signature to >65 bytes (>130 hex chars).
+        // The Coinbase x402 facilitator uses signature length to choose the
+        // settlement path:
+        //   - 65 bytes (130 hex) → v,r,s overload (EOA) — ecrecover
+        //   - >65 bytes (>130 hex) → bytes overload (smart wallet) — EIP-1271
+        // Without padding, the facilitator would use the EOA path and
+        // ecrecover would return the EOA address, not AgentAccount → fail.
+        // With padding, USDC calls AgentAccount.isValidSignature() which
+        // extracts r,s,v from the first 65 bytes and verifies the owner.
+        if (isSmartWallet) {
+            signature = (signature + '00');
+        }
+        if (isSmartWallet) {
+            console.log(`         ✓ Signed for AgentAccount ${payerAddress.slice(0, 10)}… (EIP-1271, chain=${chainId})`);
+        }
+        else {
+            console.log(`         ✓ Signed (from=${payerAddress.slice(0, 10)}…, chain=${chainId})`);
+        }
+        return {
+            x402Version: 2,
+            resource: resource || { url, description: '', mimeType: 'application/json' },
+            accepted: {
+                scheme: reqs.scheme,
+                network: reqs.network,
+                amount: reqs.amount,
+                asset: reqs.asset,
+                payTo: reqs.payTo,
+                maxTimeoutSeconds: reqs.maxTimeoutSeconds,
+                extra: reqs.extra || {},
+            },
+            payload: {
+                signature,
+                authorization: {
+                    from: payerAddress, // AgentAccount address — facilitator checks balance here
+                    to: reqs.payTo,
+                    value: reqs.amount,
+                    validAfter,
+                    validBefore,
+                    nonce,
+                },
+            },
+        };
+    }
+    // ──────────── Risk check via our backend ────────────
+    async riskCheck(paymentPayload, reqs) {
+        try {
+            const verifyUrl = `${this.config.backendUrl}/x402/verify`;
+            const resp = await fetch(verifyUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Agent-Id': this.config.agentId || '',
+                    ...(this.config.accountAddress ? { 'X-Agent-Account': this.config.accountAddress } : {}),
+                },
+                body: JSON.stringify({
+                    x402Version: 2,
+                    paymentPayload,
+                    paymentRequirements: reqs,
+                }),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (resp.ok) {
+                const result = await resp.json();
+                const decision = resp.headers.get('X-Risk-Decision') || (result.isValid ? 'allow' : 'unknown');
+                const score = resp.headers.get('X-Risk-Score') || '?';
+                console.log(`         ✓ Risk check: ${decision} (score=${score})`);
+            }
+            else {
+                console.log(`         ⚠ Risk check failed (HTTP ${resp.status}) — continuing anyway`);
+            }
+        }
+        catch {
+            console.log('         ⚠ Risk check unavailable — continuing');
+        }
+    }
+}