@oobe-protocol-labs/sap-mcp-server 0.9.1 → 0.9.3

package/dist/payments/x402-paid-call.js

@@ -12,11 +12,13 @@ import { Connection, PublicKey } from '@solana/web3.js';
 import { loadConfig } from '../config/env.js';
 import { getActiveProfile, getProfileConfigPath } from '../config/profiles.js';
 import { MCP_SERVER_VERSION } from '../core/constants.js';
+import { getCachedSession, cacheSession, invalidateSession } from './mcp-session-cache.js';
 export const DEFAULT_X402_PAID_CALL_ENDPOINT = 'https://mcp.sap.oobeprotocol.ai/mcp';
 const MCP_PROTOCOL_VERSION = '2025-06-18';
 const DEFAULT_MAX_ATTEMPTS = 3;
 const MAX_ALLOWED_ATTEMPTS = 5;
 const RETRY_BASE_DELAY_MS = 500;
+const MAX_EXTERNAL_BODY_BYTES = 256 * 1024;
 const MAINNET_USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 const DEVNET_USDC_MINT = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
 /**
@@ -59,6 +61,167 @@ export async function executeX402PaidCall(input) {
     }
     throw new Error('x402 paid call exhausted retries.');
 }
+/**
+ * @name executeX402BatchPaidCall
+ * @description Executes multiple paid tool calls in parallel with a shared MCP session.
+ *   Uses concurrency-limited parallelism (default 3) to avoid overwhelming the hosted server.
+ *   Each call gets its own x402 challenge and payment — no shared payment across calls.
+ */
+export async function executeX402BatchPaidCall(input) {
+    if (!input.confirm) {
+        throw new Error('Batch x402 paid calls require confirm: true because they sign payment payloads.');
+    }
+    if (!Number.isFinite(input.maxPriceUsd) || input.maxPriceUsd <= 0) {
+        throw new Error('Batch x402 paid calls require a positive maxPriceUsd spending cap.');
+    }
+    if (!input.calls || input.calls.length === 0) {
+        throw new Error('Batch x402 paid calls require at least one call.');
+    }
+    const endpoint = input.endpoint ?? DEFAULT_X402_PAID_CALL_ENDPOINT;
+    const profileName = input.profileName ?? getActiveProfile();
+    const config = loadPaymentProfile(input.profileName);
+    const signer = await loadClientSigner(config);
+    const httpClient = createHttpPaymentClient(signer);
+    const sessionId = await initializeMcpSession(endpoint);
+    const maxAttempts = normalizeMaxAttempts(input.maxAttempts);
+    const maxTotalUsd = normalizeBatchMaxTotalUsd(input.maxTotalUsd, input.maxPriceUsd, input.calls.length);
+    const enforceExplicitTotalCap = input.maxTotalUsd !== undefined;
+    const concurrency = enforceExplicitTotalCap ? 1 : Math.max(1, Math.min(input.concurrency ?? 3, 8));
+    const signerAddress = String(signer.address);
+    // Execute calls with limited concurrency
+    const results = [];
+    const queue = Array.from(input.calls.entries());
+    let reservedAmountUsd = 0;
+    async function processOne(index) {
+        while (index < queue.length) {
+            const [, call] = queue[index];
+            if (reservedAmountUsd + input.maxPriceUsd > maxTotalUsd) {
+                results[index] = {
+                    success: false,
+                    error: `batch_max_total_exceeded: refusing ${call.toolName}; per-call cap ${formatClientUsd(input.maxPriceUsd)} would exceed batch cap ${formatClientUsd(maxTotalUsd)}.`,
+                    toolName: call.toolName,
+                };
+                index += concurrency;
+                continue;
+            }
+            reservedAmountUsd += input.maxPriceUsd;
+            const requestBody = buildToolCallRequest(call.toolName, call.arguments);
+            const transientRetries = [];
+            let lastError;
+            for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+                try {
+                    const result = await executePaidAttempt({
+                        endpoint,
+                        sessionId,
+                        signerAddress,
+                        httpClient,
+                        requestBody,
+                        profileName,
+                        maxPriceUsd: input.maxPriceUsd,
+                        attempt,
+                        transientRetries,
+                    });
+                    results[index] = result;
+                    break;
+                }
+                catch (error) {
+                    const retry = classifyPaidCallRetry(error);
+                    if (!retry.retryable || attempt >= maxAttempts) {
+                        lastError = error instanceof Error ? error.message : String(error);
+                        results[index] = {
+                            success: false,
+                            error: lastError,
+                            toolName: call.toolName,
+                        };
+                        break;
+                    }
+                    transientRetries.push(retry.reason);
+                    await sleep(RETRY_BASE_DELAY_MS * attempt);
+                }
+            }
+            index += concurrency;
+        }
+    }
+    // Launch concurrent workers
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, (_, i) => processOne(i));
+    await Promise.all(workers);
+    const succeeded = results.filter(r => r.success).length;
+    const totalAmountUsd = results.reduce((sum, r) => sum + ('payment' in r ? r.payment.amountUsd : 0), 0);
+    return {
+        success: succeeded === results.length,
+        endpoint,
+        sessionId,
+        totalCalls: input.calls.length,
+        succeeded,
+        failed: results.length - succeeded,
+        totalAmountUsd,
+        results,
+        audit: {
+            profileName,
+            signerAddress,
+            totalAmountUsd,
+            maxTotalUsd,
+            callCount: input.calls.length,
+            concurrency,
+        },
+    };
+}
+function normalizeBatchMaxTotalUsd(value, maxPriceUsd, callCount) {
+    const defaultTotal = maxPriceUsd * callCount;
+    if (value === undefined) {
+        return defaultTotal;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error('Batch x402 paid calls require maxTotalUsd to be positive when provided.');
+    }
+    if (value < maxPriceUsd) {
+        throw new Error('Batch x402 paid calls require maxTotalUsd to be at least maxPriceUsd for one call.');
+    }
+    return value;
+}
+function formatClientUsd(value) {
+    return `$${value.toFixed(6).replace(/0+$/, '').replace(/\.$/, '')}`;
+}
+/**
+ * @name executeExternalX402Call
+ * @description Calls a generic HTTP x402 endpoint by fetching its challenge, signing locally, retrying with the payment header, and returning the receipt.
+ */
+export async function executeExternalX402Call(input) {
+    validateExternalInput(input);
+    const url = normalizeExternalUrl(input.url);
+    const method = normalizeHttpMethod(input.method);
+    const profileName = input.profileName ?? getActiveProfile();
+    const config = loadPaymentProfile(input.profileName);
+    const signer = await loadClientSigner(config);
+    const httpClient = createHttpPaymentClient(signer);
+    const maxAttempts = normalizeMaxAttempts(input.maxAttempts);
+    const transientRetries = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await executeExternalPaidAttempt({
+                url,
+                method,
+                headers: normalizeExternalHeaders(input.headers),
+                body: input.body,
+                signerAddress: String(signer.address),
+                httpClient,
+                profileName,
+                maxPriceUsd: input.maxPriceUsd,
+                attempt,
+                transientRetries,
+            });
+        }
+        catch (error) {
+            const retry = classifyPaidCallRetry(error);
+            if (!retry.retryable || attempt >= maxAttempts) {
+                throw error;
+            }
+            transientRetries.push(retry.reason);
+            await sleep(RETRY_BASE_DELAY_MS * attempt);
+        }
+    }
+    throw new Error('external x402 call exhausted retries.');
+}
 /**
  * @name getX402PaymentReadiness
  * @description Checks local profile, signer, RPC, balances, and commerce policy for hosted paid/write workflows.
@@ -229,6 +392,15 @@ export function inspectX402Receipt(receiptHeader) {
 }
 async function executePaidAttempt(options) {
     const unpaid = await postMcp(options.endpoint, options.requestBody, options.sessionId);
+    // If the cached session expired server-side, invalidate and re-initialize once
+    if (unpaid.response.status === 404 || isSessionNotFound(unpaid.body)) {
+        if (options.sessionRefreshAttempted) {
+            throw new Error(`MCP session refresh failed: ${JSON.stringify(unpaid.body)}`);
+        }
+        invalidateSession(options.endpoint);
+        const freshSession = await initializeMcpSession(options.endpoint);
+        return executePaidAttempt({ ...options, sessionId: freshSession, sessionRefreshAttempted: true });
+    }
     const paymentRequired = getPaymentRequiredResponse(options.httpClient, unpaid.response, unpaid.body);
     const selectedRequirements = selectSingleRequirement(paymentRequired, options.maxPriceUsd);
     const amountUsd = paymentRequirementsAmountUsd(selectedRequirements);
@@ -288,6 +460,94 @@ async function executePaidAttempt(options) {
         audit,
     };
 }
+async function executeExternalPaidAttempt(options) {
+    const unpaid = await fetchExternal(options.url, options.method, options.headers, options.body);
+    if (unpaid.response.status !== 402) {
+        return buildExternalResultWithoutPayment(options, unpaid);
+    }
+    const paymentRequired = getPaymentRequiredResponse(options.httpClient, unpaid.response, unpaid.body);
+    const selectedRequirements = selectSingleRequirement(paymentRequired, options.maxPriceUsd);
+    const amountUsd = paymentRequirementsAmountUsd(selectedRequirements);
+    const paymentPayload = await options.httpClient.createPaymentPayload({
+        ...paymentRequired,
+        accepts: [selectedRequirements],
+    });
+    const paymentHeaders = options.httpClient.encodePaymentSignatureHeader(paymentPayload);
+    const paid = await fetchExternal(options.url, options.method, {
+        ...options.headers,
+        ...paymentHeaders,
+    }, options.body);
+    const paymentResult = await options.httpClient.processPaymentResult(paymentPayload, name => paid.response.headers.get(name), paid.response.status);
+    if (!paid.response.ok) {
+        throw new Error(`External x402 call failed with HTTP ${paid.response.status}: ${JSON.stringify(paid.body)}`);
+    }
+    const audit = {
+        intentId: buildExternalIntentId(options.url, options.method),
+        profileName: options.profileName,
+        signerAddress: options.signerAddress,
+        url: options.url,
+        method: options.method,
+        payment: {
+            amountUsd,
+            network: selectedRequirements.network,
+            asset: selectedRequirements.asset,
+            payTo: selectedRequirements.payTo,
+        },
+        receipt: {
+            present: Boolean(paymentResult.settleResponse),
+            ...(paymentResult.settleResponse?.transaction ? { transaction: paymentResult.settleResponse.transaction } : {}),
+            ...(paymentResult.settleResponse?.network ? { network: paymentResult.settleResponse.network } : {}),
+            ...(paymentResult.settleResponse?.amount ? { amount: paymentResult.settleResponse.amount } : {}),
+            ...(paymentResult.settleResponse?.payer ? { payer: paymentResult.settleResponse.payer } : {}),
+        },
+        attempts: options.attempt,
+        transientRetries: options.transientRetries,
+        secretMaterial: 'keypair-bytes-never-returned',
+    };
+    return {
+        success: true,
+        url: options.url,
+        method: options.method,
+        signerAddress: options.signerAddress,
+        payment: audit.payment,
+        settlement: paymentResult.settleResponse,
+        response: {
+            status: paid.response.status,
+            headers: safeResponseHeaders(paid.response.headers),
+            body: paid.body,
+        },
+        attempts: options.attempt,
+        transientRetries: options.transientRetries,
+        audit,
+    };
+}
+function buildExternalResultWithoutPayment(options, result) {
+    const audit = {
+        intentId: buildExternalIntentId(options.url, options.method),
+        profileName: options.profileName,
+        signerAddress: options.signerAddress,
+        url: options.url,
+        method: options.method,
+        receipt: { present: false },
+        attempts: options.attempt,
+        transientRetries: options.transientRetries,
+        secretMaterial: 'keypair-bytes-never-returned',
+    };
+    return {
+        success: result.response.ok,
+        url: options.url,
+        method: options.method,
+        signerAddress: options.signerAddress,
+        response: {
+            status: result.response.status,
+            headers: safeResponseHeaders(result.response.headers),
+            body: result.body,
+        },
+        attempts: options.attempt,
+        transientRetries: options.transientRetries,
+        audit,
+    };
+}
 function validateInput(input) {
     if (!input.confirm) {
         throw new Error('x402 paid calls require confirm: true because they sign a payment payload.');
@@ -299,6 +559,17 @@ function validateInput(input) {
         throw new Error('Provide either body or toolName.');
     }
 }
+function validateExternalInput(input) {
+    if (!input.confirm) {
+        throw new Error('external x402 calls require confirm: true because they sign a payment payload.');
+    }
+    if (!Number.isFinite(input.maxPriceUsd) || input.maxPriceUsd <= 0) {
+        throw new Error('external x402 calls require a positive maxPriceUsd spending cap.');
+    }
+    if (!input.url || typeof input.url !== 'string') {
+        throw new Error('url is required for external x402 calls.');
+    }
+}
 function loadPaymentProfile(profileName) {
     if (profileName) {
         return loadConfig(getProfileConfigPath(profileName));
@@ -327,6 +598,11 @@ function createHttpPaymentClient(signer) {
     return new x402HTTPClient(client);
 }
 async function initializeMcpSession(endpoint) {
+    // Check cache first — reuse session if still valid (5min TTL)
+    const cached = getCachedSession(endpoint);
+    if (cached) {
+        return cached;
+    }
     const initBody = {
         jsonrpc: '2.0',
         id: 'sap-x402-paid-call-init',
@@ -350,6 +626,8 @@ async function initializeMcpSession(endpoint) {
         throw new Error('Hosted MCP initialize response did not include mcp-session-id.');
     }
     await postMcp(endpoint, initializedBody, sessionId);
+    // Cache the session for reuse by subsequent paid calls
+    cacheSession(endpoint, sessionId);
     return sessionId;
 }
 function buildToolCallRequest(toolName, args) {
@@ -381,6 +659,50 @@ async function postMcp(endpoint, body, sessionId, extraHeaders = {}) {
         body: parseMcpHttpBody(text, response.headers.get('content-type') ?? ''),
     };
 }
+async function fetchExternal(url, method, headers, body) {
+    const hasBody = method !== 'GET' && method !== 'HEAD' && body !== undefined;
+    const requestHeaders = {
+        Accept: 'application/json',
+        ...headers,
+    };
+    let requestBody;
+    if (hasBody) {
+        if (typeof body === 'string') {
+            requestBody = body;
+        }
+        else {
+            requestHeaders['Content-Type'] = requestHeaders['Content-Type'] ?? requestHeaders['content-type'] ?? 'application/json';
+            requestBody = JSON.stringify(body);
+        }
+        if (Buffer.byteLength(requestBody) > MAX_EXTERNAL_BODY_BYTES) {
+            throw new Error(`External x402 request body exceeds ${MAX_EXTERNAL_BODY_BYTES} bytes.`);
+        }
+    }
+    const response = await fetch(url, {
+        method,
+        headers: requestHeaders,
+        ...(requestBody !== undefined ? { body: requestBody } : {}),
+    });
+    const text = await response.text();
+    return {
+        response,
+        body: parseExternalHttpBody(text, response.headers.get('content-type') ?? ''),
+    };
+}
+function parseExternalHttpBody(text, contentType) {
+    if (!text.trim()) {
+        return null;
+    }
+    if (contentType.includes('application/json') || text.trim().startsWith('{') || text.trim().startsWith('[')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
 function getPaymentRequiredResponse(httpClient, response, body) {
     return httpClient.getPaymentRequiredResponse(name => response.headers.get(name), body);
 }
@@ -468,9 +790,97 @@ function normalizeMaxAttempts(value) {
     }
     return value;
 }
+function normalizeExternalUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error('External x402 URL must use http or https.');
+    }
+    if (url.username || url.password) {
+        throw new Error('External x402 URL must not contain embedded credentials.');
+    }
+    assertExternalHostAllowed(url.hostname);
+    return url.toString();
+}
+function assertExternalHostAllowed(hostname) {
+    const normalized = hostname.toLowerCase();
+    if (normalized === 'localhost' || normalized.endsWith('.localhost') || normalized.endsWith('.local')) {
+        throw new Error('External x402 URL must not target local hostnames.');
+    }
+    if (normalized === '0.0.0.0' || normalized === '::' || normalized === '::1' || normalized.startsWith('127.')) {
+        throw new Error('External x402 URL must not target loopback addresses.');
+    }
+    if (normalized.startsWith('10.') ||
+        normalized.startsWith('192.168.') ||
+        /^172\.(1[6-9]|2\d|3[0-1])\./.test(normalized) ||
+        normalized.startsWith('169.254.')) {
+        throw new Error('External x402 URL must not target private or link-local addresses.');
+    }
+}
+function normalizeHttpMethod(value) {
+    const method = (value ?? 'POST').toUpperCase();
+    const allowed = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+    if (!allowed.has(method)) {
+        throw new Error('method must be one of GET, POST, PUT, PATCH, or DELETE.');
+    }
+    return method;
+}
+function normalizeExternalHeaders(value) {
+    const headers = {};
+    for (const [key, rawValue] of Object.entries(value ?? {})) {
+        const normalized = key.toLowerCase();
+        if (normalized === 'payment-signature' || normalized === 'x-payment' || normalized === 'payment-response' || normalized === 'x-payment-response') {
+            throw new Error(`Do not provide ${key}; the local x402 helper creates payment headers itself.`);
+        }
+        if (normalized === 'authorization' || normalized === 'cookie' || normalized === 'set-cookie') {
+            throw new Error(`Refusing to forward sensitive header ${key} through generic x402 helper.`);
+        }
+        headers[key] = String(rawValue);
+    }
+    return headers;
+}
+function safeResponseHeaders(headers) {
+    const safe = new Set([
+        'content-type',
+        'payment-response',
+        'x-payment-response',
+        'x402-version',
+        'x-request-id',
+    ]);
+    const out = {};
+    headers.forEach((value, key) => {
+        if (safe.has(key.toLowerCase())) {
+            out[key] = value;
+        }
+    });
+    return out;
+}
 function classifyPaidCallRetry(error) {
     const message = error instanceof Error ? error.message : String(error);
     const normalized = message.toLowerCase();
+    // Explicit maxPriceUsd exceeded check — not retryable, agent needs to raise the cap
+    if (normalized.includes('exceeds maxpriceusd')) {
+        return {
+            retryable: false,
+            reason: 'max_price_exceeded',
+            hint: 'The tool cost exceeds the maxPriceUsd cap. Use sap_estimate_tool_cost to get the expected cost, then retry with maxPriceUsd set to at least 1.5x the estimated price.',
+        };
+    }
+    // Session not found — not retryable with same session, but the caller should re-initialize
+    if (normalized.includes('mcp_session_not_found') || normalized.includes('mcp_session_required')) {
+        return {
+            retryable: false,
+            reason: 'session_expired',
+            hint: 'The MCP session expired. The session cache has been invalidated. Retry with a fresh session.',
+        };
+    }
+    // Hosted local signer required — not retryable via x402, use local sap_payments
+    if (normalized.includes('hosted_local_signer_required')) {
+        return {
+            retryable: false,
+            reason: 'local_signer_required',
+            hint: 'This tool requires a local Solana signature. Do NOT use sap_payments_call_paid_tool. Use the local sap_payments equivalent (e.g. sap_payments_register_agent, sap_payments_finalize_transaction).',
+        };
+    }
     const retryable = containsAny(normalized, [
         'blockhashnotfound',
         'blockhash not found',
@@ -509,6 +919,15 @@ function sleep(ms) {
 function isJsonRpcError(value) {
     return value !== null && typeof value === 'object' && 'error' in value;
 }
+function isSessionNotFound(body) {
+    if (!isJsonRpcError(body))
+        return false;
+    const error = body.error;
+    if (!error || typeof error !== 'object')
+        return false;
+    const message = error.message;
+    return message === 'mcp_session_not_found' || message === 'mcp_session_required';
+}
 function networkFromRpcUrl(value) {
     if (!value) {
         return 'mainnet-beta';
@@ -584,7 +1003,7 @@ async function readBalanceSnapshot(rpcUrl, signerAddress, usdcMint, autoPayX402B
 }
 function readAgentCommercePolicy() {
     return {
-        autoPayX402BelowUsd: readPositiveNumberEnv('SAP_MCP_X402_AUTO_PAY_MAX_USD', 0.02),
+        autoPayX402BelowUsd: readPositiveNumberEnv('SAP_MCP_X402_AUTO_PAY_MAX_USD', 0.05),
         dailyX402LimitUsd: readOptionalPositiveNumberEnv('SAP_MCP_X402_DAILY_LIMIT_USD'),
         maxTradeUsd: readOptionalPositiveNumberEnv('SAP_MCP_MAX_TRADE_USD') ?? 10,
         maxSlippageBps: readPositiveNumberEnv('SAP_MCP_MAX_SLIPPAGE_BPS', 100),
@@ -656,6 +1075,14 @@ function buildIntentId(requestBody, sessionId) {
     });
     return `sap-intent-${createHash('sha256').update(source).digest('hex').slice(0, 16)}`;
 }
+function buildExternalIntentId(url, method) {
+    const source = JSON.stringify({
+        url,
+        method,
+        at: Date.now(),
+    });
+    return `sap-external-x402-${createHash('sha256').update(source).digest('hex').slice(0, 16)}`;
+}
 function parseCliArgs(argv) {
     const parsed = { confirm: false };
     for (let index = 0; index < argv.length; index += 1) {