@oobe-protocol-labs/sap-mcp-server 0.3.0 → 0.7.0

package/dist/payments/monetization-gate.js

@@ -6,13 +6,16 @@ import { HTTPFacilitatorClient, x402HTTPResourceServer, x402ResourceServer } fro
 import { registerExactSvmScheme } from '@x402/svm/exact/server';
 import { logger } from '../core/logger.js';
 import { NativeHttpAdapter, parseJsonBody, readRequestBody } from './http-adapter.js';
-import { parseJsonRpcBody } from './json-rpc.js';
+import { isRecord, parseJsonRpcBody } from './json-rpc.js';
 import { formatUsdPrice, resolvePaymentDecision } from './pricing.js';
-import { hashRequestBody, UsageLedger } from './usage-ledger.js';
+import { hashPaymentRequest, UsageLedger } from './usage-ledger.js';
+import { isTransientRpcError } from './facilitator-rpc-fallback.js';
 const SOLANA_MAINNET_CAIP2 = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
 const SOLANA_DEVNET_CAIP2 = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
 const SOLANA_TESTNET_CAIP2 = 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z';
 const PAID_ROUTE_PATTERN = 'POST /mcp/paid/*';
+const USDC_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const USDC_DEVNET = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
 /**
  * @name McpMonetizationGate
  * @description Applies x402 payment verification and settlement before forwarding requests to the MCP transport.
@@ -70,7 +73,7 @@ export class McpMonetizationGate {
      * @name handle
      * @description Authorizes a request via x402 when required, then forwards it to MCP and settles on success.
      */
-    async handle(request, response, next) {
+    async handle(request, response, next, options = {}) {
         if (!shouldInspectRequest(request)) {
             await next(request, response);
             return;
@@ -82,20 +85,81 @@ export class McpMonetizationGate {
             parsedBody = parseJsonBody(rawBody);
         }
         catch (error) {
+            // Non-JSON or empty body (e.g. x402scan probing, GET requests, health checks).
+            // Return a 402 payment challenge with the standard x402 body so discovery
+            // scanners can detect the paywall.
+            if (shouldInspectRequest(request)) {
+                await this.returnX402Challenge(request, response, { jsonrpc: '2.0', method: 'tools/list', params: {} });
+                return;
+            }
             logger.warn('Failed to parse monetized MCP request', { error });
             writeJson(response, 400, { error: 'Invalid JSON-RPC request body' });
             return;
         }
         const parsedMcp = parseJsonRpcBody(parsedBody);
         const decision = resolvePaymentDecision(parsedMcp, this.monetization);
+        // For non-MCP clients (x402 scanners, curl without Accept header), always
+        // return 402 — the paywall must fire before body validation per the x402
+        // discovery spec: "Registration probes must reach a 402 challenge before
+        // body/query validation rejects the request."
+        // MCP SDK uniquely sends Accept: application/json, text/event-stream.
+        // x402scan sends Accept: */* or Accept: application/json (without text/event-stream).
+        // Only text/event-stream is a reliable MCP SDK marker.
+        const acceptHeader = request.headers['accept'] || '';
+        const isMcpSdkClient = acceptHeader.includes('text/event-stream');
         if (!decision.required) {
+            if (shouldInspectRequest(request) && !isMcpSdkClient) {
+                // x402 scanner probing with arbitrary body — return 402 challenge
+                await this.returnX402Challenge(request, response, parsedBody);
+                return;
+            }
             await next(request, response, parsedBody);
             return;
         }
-        const requestHash = hashRequestBody(rawBody);
+        const requiredDecision = decision;
+        const requestHash = hashPaymentRequest(rawBody, parsedBody);
         const virtualPath = buildPaidVirtualPath(decision, requestHash);
+        // Standard x402 scanners and non-MCP HTTP clients must see a normal HTTP
+        // 402 challenge before MCP transport/session validation runs. MCP SDK
+        // clients are the only callers that need the JSON-RPC compatible 200 error.
+        const paymentHeader = request.headers['payment-signature'] ??
+            request.headers['x-payment'];
+        if (!paymentHeader && !isMcpSdkClient) {
+            await this.returnX402Challenge(request, response, parsedBody, virtualPath);
+            return;
+        }
+        const validationFailure = options.validatePaidRequest?.({
+            request,
+            parsedBody,
+            decision: requiredDecision,
+        });
+        if (validationFailure) {
+            writeJsonRpcError(response, parsedBody, validationFailure.code, validationFailure.message, validationFailure.data);
+            return;
+        }
         const metadata = buildRequestMetadata(request, requestHash, virtualPath);
         await this.usageLedger.recordDecision(metadata, decision);
+        logger.info('Payment required', {
+            toolNames: decision.toolNames,
+            price: decision.price,
+            callerIp: metadata.remoteAddress,
+            requestHash: requestHash.slice(0, 12),
+        });
+        // ── Fast path: Payment-Signature header present ────────────────────────
+        if (paymentHeader) {
+            await this.handleSignedPayment({
+                request,
+                response,
+                next,
+                parsedBody,
+                decision: requiredDecision,
+                metadata,
+                paymentHeader,
+                virtualPath,
+            });
+            return;
+        }
+        // ── Normal path: no Payment-Signature header, generate 402 response ──────
         const context = this.buildRequestContext(request, parsedBody, virtualPath);
         const paymentResult = await this.httpResourceServer.processHTTPRequest(context, {
             appName: 'SAP MCP Server',
@@ -103,7 +167,88 @@ export class McpMonetizationGate {
             testnet: resolvePaymentNetwork(this.appConfig) !== SOLANA_MAINNET_CAIP2,
         });
         if (paymentResult.type === 'payment-error') {
-            writePaymentInstructions(response, paymentResult.response);
+            // V1 compatibility: @x402/svm V1 exact scheme checks maxAmountRequired but
+            // V2 resource server only emits amount. Patch the 402 response body to add
+            // maxAmountRequired so V1-only clients and facilitators can verify payments.
+            patchV1Compatibility(paymentResult.response);
+            // Extract the x402 PaymentRequired object from the PAYMENT-REQUIRED header.
+            // The x402 resource server puts the accepts[] (with extra.feePayer) in this
+            // header as base64-encoded JSON.
+            let acceptsFromHeader = undefined;
+            try {
+                const paymentRequiredHeader = paymentResult.response.headers?.['payment-required'] ??
+                    paymentResult.response.headers?.['PAYMENT-REQUIRED'];
+                if (typeof paymentRequiredHeader === 'string') {
+                    const decoded = Buffer.from(paymentRequiredHeader, 'base64').toString('utf-8');
+                    const paymentRequired = JSON.parse(decoded);
+                    acceptsFromHeader = paymentRequired.accepts;
+                }
+            }
+            catch {
+                // Header not present or invalid — fall back to body
+            }
+            // Determine if this is a genuine MCP SDK client or an x402 scanner.
+            // isMcpSdkClient was already determined above from the Accept header.
+            // MCP SDK sends Accept: application/json, text/event-stream.
+            // x402 scanners (x402scan.com) send standard HTTP requests without MCP Accept.
+            const responseBody = paymentResult.response.body;
+            const jsonRpcId = extractJsonRpcId(parsedBody);
+            // Use accepts from header (has extra.feePayer) or fall back to body
+            const paymentRequiredHeader = paymentResult.response.headers?.['payment-required'] ??
+                paymentResult.response.headers?.['PAYMENT-REQUIRED'];
+            if (typeof paymentRequiredHeader === 'string') {
+                response.setHeader('PAYMENT-REQUIRED', paymentRequiredHeader);
+            }
+            const paymentRequirements = acceptsFromHeader ??
+                responseBody?.accepts ??
+                responseBody?.paymentRequirements ??
+                responseBody;
+            if (!isMcpSdkClient) {
+                // x402 scanner or non-MCP HTTP client — return standard HTTP 402
+                // with the full PaymentRequired object (x402Version, accepts, resource)
+                // decoded from the PAYMENT-REQUIRED header as the response body.
+                const prHeaderDecoded = paymentRequiredHeader;
+                let x402Body = {
+                    error: 'Payment required',
+                    accepts: paymentRequirements,
+                };
+                if (typeof prHeaderDecoded === 'string') {
+                    try {
+                        x402Body = JSON.parse(Buffer.from(prHeaderDecoded, 'base64').toString('utf-8'));
+                    }
+                    catch {
+                        // fall back to the simple body
+                    }
+                }
+                response.writeHead(402, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify(x402Body));
+                return;
+            }
+            // MCP SDK client — return HTTP 200 with JSON-RPC error (the SDK hangs on 402)
+            writeJson(response, 200, {
+                jsonrpc: '2.0',
+                id: jsonRpcId,
+                error: {
+                    code: -32001,
+                    message: 'payment_required',
+                    data: {
+                        protocol: 'x402',
+                        paymentRequirements,
+                        instructions: {
+                            header: 'Payment-Signature',
+                            settlementHeader: 'Payment-Response',
+                            requestHashBinding: 'json-rpc-method-and-params',
+                            requiredRetryHeaders: ['Payment-Signature', 'mcp-session-id', 'mcp-protocol-version'],
+                            paymentSignatureFormat: 'base64(JSON.stringify({ x402Version, accepted: paymentRequirements[0], payload, resource }))',
+                            steps: [
+                                'Initialize the MCP session first and reuse the returned mcp-session-id for the unpaid call and paid retry.',
+                                'Build the payment from paymentRequirements[0] / accepts[0] returned by this response.',
+                                'Retry the same MCP method and params with the Payment-Signature header.',
+                            ],
+                        },
+                    },
+                },
+            });
             return;
         }
         if (paymentResult.type === 'no-payment-required') {
@@ -111,6 +256,11 @@ export class McpMonetizationGate {
             return;
         }
         await this.usageLedger.recordVerified(metadata, decision);
+        logger.info('Payment verified', {
+            toolNames: decision.toolNames,
+            price: decision.price,
+            requestHash: metadata.requestHash.slice(0, 12),
+        });
         await this.forwardAndSettle({
             request,
             response,
@@ -122,7 +272,146 @@ export class McpMonetizationGate {
             parsedBody,
         });
     }
-    buildRequestContext(request, parsedBody, virtualPath) {
+    /**
+     * @name handleSignedPayment
+     * @description Verifies a client-supplied x402 payment payload against the original accepted requirements.
+     */
+    async handleSignedPayment(options) {
+        let parsedPayment;
+        try {
+            parsedPayment = parsePaymentHeader(options.paymentHeader);
+        }
+        catch (error) {
+            logger.warn('Invalid Payment-Signature header', {
+                error,
+                requestHash: options.metadata.requestHash.slice(0, 12),
+            });
+            writeJsonRpcError(options.response, options.parsedBody, -32002, 'payment_verification_failed', {
+                reason: 'invalid_payment_signature_header',
+                hint: 'Payment-Signature must be base64(JSON) containing x402Version, accepted, and payload.',
+            });
+            return;
+        }
+        const validationError = validatePaymentRequirementsForDecision(parsedPayment.paymentRequirements, parsedPayment.paymentPayload, options.decision, this.appConfig, options.virtualPath);
+        if (validationError) {
+            logger.warn('Payment requirements rejected before facilitator verify', {
+                reason: validationError,
+                toolNames: options.decision.toolNames,
+                requestHash: options.metadata.requestHash.slice(0, 12),
+            });
+            writeJsonRpcError(options.response, options.parsedBody, -32002, 'payment_verification_failed', {
+                reason: validationError,
+                hint: 'Retry with Payment-Signature generated from this request paymentRequirements[0] / accepts[0]. Preserve the initialized MCP session id.',
+            });
+            return;
+        }
+        logger.info('Payment-Signature detected — direct facilitator verification', {
+            toolNames: options.decision.toolNames,
+            price: options.decision.price,
+            requestHash: options.metadata.requestHash.slice(0, 12),
+        });
+        let verifyResult;
+        try {
+            verifyResult = await this.callFacilitator('verify', {
+                x402Version: parsedPayment.x402Version,
+                paymentPayload: parsedPayment.paymentPayload,
+                paymentRequirements: parsedPayment.paymentRequirements,
+            });
+        }
+        catch (error) {
+            const failure = classifyFacilitatorError(error);
+            logger.warn('Payment verification facilitator call failed', {
+                reason: failure.reason,
+                message: failure.message,
+                retryable: failure.retryable,
+                requestHash: options.metadata.requestHash.slice(0, 12),
+            });
+            writeJsonRpcError(options.response, options.parsedBody, -32002, 'payment_verification_failed', failure);
+            return;
+        }
+        if (!verifyResult.isValid) {
+            const failure = classifyVerifyFailure(verifyResult);
+            logger.warn('Payment verification failed', {
+                reason: failure.reason,
+                message: failure.message,
+                retryable: failure.retryable,
+                category: failure.category,
+                payer: verifyResult.payer,
+                requestHash: options.metadata.requestHash.slice(0, 12),
+            });
+            writeJsonRpcError(options.response, options.parsedBody, -32002, 'payment_verification_failed', failure);
+            return;
+        }
+        await this.usageLedger.recordVerified(options.metadata, options.decision);
+        const buffered = bufferResponse(options.response);
+        try {
+            await options.next(options.request, options.response, options.parsedBody);
+            await buffered.waitForEnd();
+        }
+        catch (error) {
+            await this.usageLedger.recordCanceled(options.metadata, options.decision, 'handler_threw', error instanceof Error ? error.message : String(error));
+            buffered.restore();
+            throw error;
+        }
+        if (options.response.statusCode >= 400) {
+            await this.usageLedger.recordCanceled(options.metadata, options.decision, 'handler_failed', `MCP handler returned HTTP ${options.response.statusCode}`);
+            buffered.restoreAndReplay();
+            return;
+        }
+        let settlement;
+        try {
+            settlement = await this.callFacilitator('settle', {
+                x402Version: parsedPayment.x402Version,
+                paymentPayload: parsedPayment.paymentPayload,
+                paymentRequirements: parsedPayment.paymentRequirements,
+            });
+        }
+        catch (error) {
+            const failure = classifyFacilitatorError(error);
+            await this.usageLedger.recordCanceled(options.metadata, options.decision, 'handler_failed', failure.message ?? failure.reason ?? 'facilitator_settle_failed');
+            buffered.restore();
+            writeJsonRpcError(options.response, options.parsedBody, -32003, 'payment_settlement_failed', failure);
+            return;
+        }
+        await this.usageLedger.recordSettlement(options.metadata, options.decision, settlement);
+        if (!settlement.success) {
+            logger.warn('Settlement failed', {
+                toolNames: options.decision.toolNames,
+                price: options.decision.price,
+                requestHash: options.metadata.requestHash.slice(0, 12),
+                errorReason: settlement.errorReason,
+            });
+            buffered.restore();
+            writeJsonRpcError(options.response, options.parsedBody, -32003, 'payment_settlement_failed', {
+                reason: settlement.errorReason,
+                message: settlement.errorMessage,
+            });
+            return;
+        }
+        logger.info('Settlement success', {
+            toolNames: options.decision.toolNames,
+            price: options.decision.price,
+            tx: settlement.transaction,
+            amount: settlement.amount,
+            payer: settlement.payer,
+            requestHash: options.metadata.requestHash.slice(0, 12),
+        });
+        setPaymentResponseHeaders(options.response, settlement);
+        buffered.restoreAndReplay();
+    }
+    async callFacilitator(path, body) {
+        const response = await fetch(buildFacilitatorUrl(this.monetization, path), {
+            method: 'POST',
+            headers: buildFacilitatorHeaders(this.monetization),
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const bodyText = await response.text().catch(() => '');
+            throw new Error(`Facilitator ${path} failed with HTTP ${response.status}${bodyText ? `: ${bodyText}` : ''}`);
+        }
+        return await response.json();
+    }
+    buildRequestContext(request, parsedBody, virtualPath, method = request.method ?? 'POST') {
         const adapter = new NativeHttpAdapter({
             request,
             path: virtualPath,
@@ -131,10 +420,53 @@ export class McpMonetizationGate {
         return {
             adapter,
             path: virtualPath,
-            method: request.method ?? 'POST',
+            method,
             paymentHeader: adapter.getHeader('payment-signature') ?? adapter.getHeader('x-payment'),
         };
     }
+    /**
+     * @name returnX402Challenge
+     * @description Returns a standard HTTP 402 payment challenge for non-MCP clients
+     * (x402scan discovery, curl, health checks). Decodes the PaymentRequired object
+     * from the PAYMENT-REQUIRED header and returns it as the response body so x402
+     * scanners can validate the challenge format.
+     */
+    async returnX402Challenge(request, response, parsedBody, virtualPath = '/mcp/paid/read-premium/x402scan-probe/tools/list') {
+        // Use a path that matches the PAID_ROUTE_PATTERN ('POST /mcp/paid/*')
+        // so the x402 resource server generates a payment challenge.
+        const context = this.buildRequestContext(request, parsedBody, virtualPath, 'POST');
+        const paymentResult = await this.httpResourceServer.processHTTPRequest(context, {
+            appName: 'SAP MCP Server',
+            currentUrl: context.adapter.getUrl(),
+            testnet: resolvePaymentNetwork(this.appConfig) !== SOLANA_MAINNET_CAIP2,
+        });
+        if (paymentResult.type !== 'payment-error') {
+            // No payment required for this route — fall through
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ ok: true }));
+            return;
+        }
+        patchV1Compatibility(paymentResult.response);
+        // Set the PAYMENT-REQUIRED header from the x402 resource server
+        const prHeader = paymentResult.response.headers?.['payment-required'] ??
+            paymentResult.response.headers?.['PAYMENT-REQUIRED'];
+        if (typeof prHeader === 'string') {
+            response.setHeader('PAYMENT-REQUIRED', prHeader);
+        }
+        // Decode the PaymentRequired object from the header and return it as the body.
+        // x402 scanners expect: { x402Version, error, accepts, resource }
+        let x402Body = paymentResult.response.body ?? { error: 'Payment required' };
+        if (typeof prHeader === 'string') {
+            try {
+                x402Body = JSON.parse(Buffer.from(prHeader, 'base64').toString('utf-8'));
+            }
+            catch {
+                // fall back to the response body
+            }
+        }
+        response.writeHead(402, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify(x402Body));
+    }
     async forwardAndSettle(options) {
         const buffered = bufferResponse(options.response);
         try {
@@ -179,11 +511,26 @@ export class McpMonetizationGate {
             responseHeaders,
         });
         await this.usageLedger.recordSettlement(options.metadata, options.decision, settlement);
+        const decision = options.decision;
         if (!settlement.success) {
+            logger.warn('Settlement failed', {
+                toolNames: decision.toolNames,
+                price: decision.price,
+                requestHash: options.metadata.requestHash.slice(0, 12),
+                errorReason: settlement.errorReason,
+            });
             options.buffered.restore();
             writePaymentInstructions(options.response, settlement.response);
             return;
         }
+        logger.info('Settlement success', {
+            toolNames: decision.toolNames,
+            price: decision.price,
+            tx: settlement.transaction,
+            amount: settlement.amount,
+            payer: settlement.payer,
+            requestHash: options.metadata.requestHash.slice(0, 12),
+        });
         for (const [name, value] of Object.entries(settlement.headers)) {
             options.response.setHeader(name, value);
         }
@@ -286,16 +633,216 @@ function buildPayShCheckoutUrl(config, decision) {
     return url.toString();
 }
 function shouldInspectRequest(request) {
-    return request.method === 'POST' && Boolean(request.url?.startsWith('/mcp'));
+    // Accept both GET and POST on /mcp so x402 discovery scanners (x402scan.com)
+    // that probe with GET requests trigger the payment challenge.
+    return Boolean(request.url?.startsWith('/mcp'));
 }
 /**
  * @name buildPaidVirtualPath
- * @description Builds the paid x402 virtual resource path, bound to the exact JSON-RPC request hash.
+ * @description Builds the paid x402 virtual resource path, bound to the canonical MCP method-and-params hash.
  */
 export function buildPaidVirtualPath(decision, requestHash) {
     const toolSegment = decision.toolNames.map(name => encodeURIComponent(name)).join(',');
     return `/mcp/paid/${decision.tier}/${requestHash}/${toolSegment}`;
 }
+function parsePaymentHeader(header) {
+    const parsed = parsePaymentHeaderJson(header);
+    if (!isRecord(parsed)) {
+        throw new Error('Payment-Signature must decode to a JSON object.');
+    }
+    const accepted = parsePaymentRequirements(parsed.accepted);
+    const paymentPayload = {
+        x402Version: typeof parsed.x402Version === 'number' ? parsed.x402Version : 2,
+        accepted,
+        payload: isRecord(parsed.payload) ? parsed.payload : {},
+        ...(isRecord(parsed.resource) ? { resource: parseResourceInfo(parsed.resource) } : {}),
+        ...(isRecord(parsed.extensions) ? { extensions: parsed.extensions } : {}),
+    };
+    return {
+        x402Version: paymentPayload.x402Version,
+        paymentPayload,
+        paymentRequirements: accepted,
+    };
+}
+function parsePaymentHeaderJson(header) {
+    const candidates = [
+        Buffer.from(header, 'base64').toString('utf-8'),
+        header,
+    ];
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            // Try the next representation. Some legacy clients sent raw JSON.
+        }
+    }
+    throw new Error('Invalid Payment-Signature header.');
+}
+function parsePaymentRequirements(value) {
+    if (!isRecord(value)) {
+        throw new Error('Payment-Signature payload is missing accepted payment requirements.');
+    }
+    const scheme = requireString(value, 'scheme');
+    const network = requireString(value, 'network');
+    const asset = requireString(value, 'asset');
+    const amount = requireString(value, 'amount');
+    const payTo = requireString(value, 'payTo');
+    const maxTimeoutSeconds = requireNumber(value, 'maxTimeoutSeconds');
+    const extra = isRecord(value.extra) ? value.extra : {};
+    const maxAmountRequired = typeof value.maxAmountRequired === 'string'
+        ? value.maxAmountRequired
+        : amount;
+    return {
+        scheme,
+        network,
+        asset,
+        amount,
+        maxAmountRequired,
+        payTo,
+        maxTimeoutSeconds,
+        extra,
+    };
+}
+function parseResourceInfo(value) {
+    const resource = {
+        url: requireString(value, 'url'),
+    };
+    if (typeof value.description === 'string')
+        resource.description = value.description;
+    if (typeof value.mimeType === 'string')
+        resource.mimeType = value.mimeType;
+    if (typeof value.serviceName === 'string')
+        resource.serviceName = value.serviceName;
+    if (Array.isArray(value.tags) && value.tags.every(tag => typeof tag === 'string')) {
+        resource.tags = value.tags;
+    }
+    if (typeof value.iconUrl === 'string')
+        resource.iconUrl = value.iconUrl;
+    return resource;
+}
+function validatePaymentRequirementsForDecision(requirements, payload, decision, config, virtualPath) {
+    const network = resolvePaymentNetwork(config);
+    const expectedAmount = usdToUsdcBaseUnits(decision.priceUsd);
+    const expectedAsset = getUsdcAsset(network);
+    const expectedPayTo = config.monetization.payTo;
+    if (requirements.scheme !== 'exact')
+        return 'unsupported_scheme';
+    if (requirements.network !== network)
+        return 'network_mismatch';
+    if (requirements.payTo !== expectedPayTo)
+        return 'pay_to_mismatch';
+    if (requirements.amount !== expectedAmount)
+        return 'amount_mismatch';
+    if (requirements.maxAmountRequired && requirements.maxAmountRequired !== expectedAmount) {
+        return 'max_amount_required_mismatch';
+    }
+    if (requirements.asset !== expectedAsset)
+        return 'asset_mismatch';
+    if (!isRecord(requirements.extra) || typeof requirements.extra.feePayer !== 'string') {
+        return 'missing_fee_payer';
+    }
+    if (payload.accepted.amount !== requirements.amount || payload.accepted.payTo !== requirements.payTo) {
+        return 'payload_accepted_mismatch';
+    }
+    if (payload.resource?.url && !payload.resource.url.includes(virtualPath)) {
+        return 'resource_mismatch';
+    }
+    return undefined;
+}
+function usdToUsdcBaseUnits(priceUsd) {
+    return Math.round(priceUsd * 1_000_000).toString();
+}
+function getUsdcAsset(network) {
+    return network === SOLANA_MAINNET_CAIP2 ? USDC_MAINNET : USDC_DEVNET;
+}
+function requireString(record, key) {
+    const value = record[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Missing required string field: ${key}`);
+    }
+    return value;
+}
+function requireNumber(record, key) {
+    const value = record[key];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Missing required number field: ${key}`);
+    }
+    return value;
+}
+function buildFacilitatorUrl(config, path) {
+    const baseUrl = config.facilitatorUrl;
+    if (!baseUrl) {
+        throw new Error('SAP MCP monetization requires SAP_MCP_X402_FACILITATOR_URL');
+    }
+    return `${baseUrl.replace(/\/+$/, '')}/${path}`;
+}
+function buildFacilitatorHeaders(config) {
+    return {
+        'Content-Type': 'application/json',
+        ...(config.facilitatorAuthToken ? { Authorization: `Bearer ${config.facilitatorAuthToken}` } : {}),
+    };
+}
+function setPaymentResponseHeaders(response, settlement) {
+    const encoded = Buffer.from(JSON.stringify(settlement), 'utf-8').toString('base64');
+    response.setHeader('PAYMENT-RESPONSE', encoded);
+    response.setHeader('X-PAYMENT-RESPONSE', encoded);
+}
+function classifyVerifyFailure(verifyResult) {
+    const reason = verifyResult.invalidReason;
+    const message = verifyResult.invalidMessage;
+    const combined = [reason, message].filter(Boolean).join(': ');
+    const retryable = isTransientFacilitatorFailure(combined);
+    if (retryable) {
+        return {
+            reason,
+            message,
+            retryable: true,
+            category: 'facilitator_rpc',
+            hint: 'The payment could not be simulated because the facilitator or its Solana RPC returned a transient gateway/availability error. Retry the same paid call; if it repeats, check facilitator health, configured RPC fallbacks, and the facilitator PM2 logs.',
+        };
+    }
+    return {
+        reason,
+        message,
+        retryable: false,
+        category: 'client_payment',
+        hint: 'Check USDC balance, network, payTo, feePayer, token account setup, and that the payment was built from this exact request challenge.',
+    };
+}
+function classifyFacilitatorError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const retryable = isTransientFacilitatorFailure(message);
+    return {
+        reason: retryable ? 'facilitator_unavailable' : 'facilitator_request_failed',
+        message,
+        retryable,
+        category: retryable ? 'facilitator_unavailable' : 'client_payment',
+        hint: retryable
+            ? 'The facilitator or one of its RPC endpoints is temporarily unavailable. Retry the paid call; if it repeats, verify facilitator /health, /supported, auth token, and RPC fallback configuration.'
+            : 'The facilitator rejected the verification or settlement request. Check the payment payload, accepted requirements, facilitator URL, and facilitator auth token.',
+    };
+}
+function isTransientFacilitatorFailure(message) {
+    if (!message) {
+        return false;
+    }
+    const normalized = message.toLowerCase();
+    return isTransientRpcError(message)
+        || containsAny(normalized, [
+            'transaction_simulation_failed',
+            'smart_wallet_simulation_failed',
+            'facilitator verify failed with http 502',
+            'facilitator verify failed with http 503',
+            'facilitator verify failed with http 504',
+            'facilitator settle failed with http 502',
+            'facilitator settle failed with http 503',
+            'facilitator settle failed with http 504',
+        ]);
+}
+function containsAny(message, needles) {
+    return needles.some(needle => message.includes(needle));
+}
 function buildRequestMetadata(request, requestHash, virtualPath) {
     const paymentHeader = request.headers['payment-signature'] ?? request.headers['x-payment'];
     return {
@@ -322,6 +869,17 @@ function writeJson(response, status, body) {
     response.writeHead(status, { 'Content-Type': 'application/json' });
     response.end(JSON.stringify(body));
 }
+function writeJsonRpcError(response, requestBody, code, message, data) {
+    writeJson(response, 200, {
+        jsonrpc: '2.0',
+        id: extractJsonRpcId(requestBody),
+        error: {
+            code,
+            message,
+            ...(data === undefined ? {} : { data }),
+        },
+    });
+}
 function getResponseHeaders(response) {
     const headers = {};
     for (const [name, value] of Object.entries(response.getHeaders())) {
@@ -412,4 +970,55 @@ function replayBufferedCall(call, writeHead, write, end, flushHeaders) {
             return;
     }
 }
+/**
+ * @name extractJsonRpcId
+ * @description Extracts the JSON-RPC id from a parsed request body for response correlation.
+ */
+function extractJsonRpcId(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const record = body;
+    if (typeof record.id === 'string' || typeof record.id === 'number')
+        return record.id;
+    if (Array.isArray(body) && body.length > 0) {
+        return extractJsonRpcId(body[0]);
+    }
+    return null;
+}
+/**
+ * @name patchV1Compatibility
+ * @description Patches the x402 402 response body to add maxAmountRequired (V1) alongside amount (V2).
+ * The @x402/svm V1 exact scheme verifier checks maxAmountRequired, but the V2 resource server
+ * only emits amount. This ensures V1-compatible clients and facilitators can verify payments.
+ */
+function patchV1Compatibility(instructions) {
+    if (instructions.isHtml || !instructions.body) {
+        return;
+    }
+    const body = instructions.body;
+    if (!body || typeof body !== 'object') {
+        return;
+    }
+    // x402 response body: { accepts: [{ amount, ... }, ...], ... }
+    const accepts = body.accepts;
+    if (Array.isArray(accepts)) {
+        for (const req of accepts) {
+            if (req && typeof req === 'object' && 'amount' in req && !('maxAmountRequired' in req)) {
+                req.maxAmountRequired = req.amount;
+            }
+        }
+    }
+    // Also patch top-level paymentRequirements if present
+    const requirements = body.paymentRequirements;
+    if (Array.isArray(requirements)) {
+        for (const req of requirements) {
+            if (req && typeof req === 'object' && 'amount' in req && !('maxAmountRequired' in req)) {
+                req.maxAmountRequired = req.amount;
+            }
+        }
+    }
+    else if (requirements && typeof requirements === 'object' && 'amount' in requirements && !('maxAmountRequired' in requirements)) {
+        requirements.maxAmountRequired = requirements.amount;
+    }
+}
 //# sourceMappingURL=monetization-gate.js.map