@oobe-protocol-labs/sap-mcp-server 0.9.16 → 0.9.21

package/dist/remote/server.js

@@ -8,7 +8,6 @@ import { existsSync, readFileSync } from 'fs';
 import * as http from 'http';
 import { dirname, join, posix } from 'path';
 import { fileURLToPath } from 'url';
-import { Connection } from '@solana/web3.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { getDataDir, loadConfig } from '../config/env.js';
 import { MCP_SERVER_VERSION } from '../core/constants.js';
@@ -17,10 +16,12 @@ import { createSapMcpServer } from '../server/create-server.js';
 import { AuthManager } from './auth/index.js';
 import { McpMonetizationGate, buildPricingCatalog, resolvePaymentNetwork } from '../payments/index.js';
 import { generatePayShProviderYaml } from '../payments/pay-sh-spec.js';
+import { listPremiumPlugins, premiumPrivatePluginSupport, publicPremiumProviderStatus, getPremiumMetrics, } from '../premium/index.js';
 import { RemoteRateLimiter, buildRemoteRateLimitConfigFromEnv } from './rate-limiter.js';
 import { renderLandingPage } from './public-home/index.js';
-import { parseJsonBody, readRequestBody } from '../payments/http-adapter.js';
-import { decodeInputBytes, deserializeTransaction } from '../tools/transaction-tools.js';
+import { TX_SUBMIT_PATH, submitSignedTransactionFromHttp } from './tx-relay.js';
+import { tryPremiumRoute } from './premium-routes.js';
+import { PremiumMemoryManager } from './premium-memory.js';
 const PUBLIC_SERVER_TITLE = 'SAP MCP Server | OOBE Protocol';
 const PUBLIC_SERVER_DESCRIPTION = 'Hosted Solana-native MCP gateway for Synapse Agent Protocol tools, x402/pay.sh monetization, SNS identity, and agent operations.';
 const LOGO_ASSET_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'assets', 'explorer_logo.png');
@@ -40,10 +41,6 @@ const SOLANA_DEVNET_CAIP2 = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
 const USDC_MAINNET_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 const USDC_DEVNET_MINT = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
 const MCP_REGISTRY_AUTH_PATH = '/.well-known/mcp-registry-auth';
-const TX_SUBMIT_PATH = '/tx/submit';
-const TX_SUBMIT_MAX_BODY_BYTES = 512_000;
-const TX_SUBMIT_DEFAULT_CONFIRMATION_TIMEOUT_MS = 90_000;
-const TX_SUBMIT_MAX_CONFIRMATION_TIMEOUT_MS = 180_000;
 let logoAssetCache;
 let oobeLogoAssetCache;
 let paymentStatsCache;
@@ -292,110 +289,6 @@ function writeMcpJsonRpcError(res, status, code, id, message, data) {
         },
     });
 }
-async function submitSignedTransactionFromHttp(req, config) {
-    const body = parseJsonBody(await readRequestBody(req, TX_SUBMIT_MAX_BODY_BYTES));
-    const input = parseTxSubmitRelayInput(body);
-    const encodedTransaction = input.signedTransaction ?? input.transaction;
-    if (!encodedTransaction) {
-        throw new Error('signedTransaction is required.');
-    }
-    const encoding = input.encoding ?? 'base64';
-    const rawTransaction = decodeInputBytes(encodedTransaction, encoding);
-    deserializeTransaction(encodedTransaction, encoding);
-    const connection = new Connection(config.rpcUrl, config.commitment ?? 'confirmed');
-    const signature = await connection.sendRawTransaction(rawTransaction, {
-        skipPreflight: input.skipPreflight,
-        maxRetries: input.maxRetries ?? config.maxRetries,
-    });
-    const confirmationTimeoutMs = boundTxSubmitConfirmationTimeout(input.confirmationTimeoutMs);
-    const desiredCommitment = input.commitment ?? 'confirmed';
-    const confirmation = await waitForTxSubmitSignatureStatus(connection, signature, confirmationTimeoutMs, desiredCommitment);
-    return {
-        success: confirmation.success,
-        submitted: true,
-        signature,
-        confirmationStatus: confirmation.status,
-        retrySafe: confirmation.retrySafe,
-        ...(confirmation.slot === undefined ? {} : { slot: confirmation.slot }),
-        explorerUrl: `https://solscan.io/tx/${signature}`,
-        audit: {
-            intentId: input.intentId ?? `sap-tx-${Date.now()}`,
-            submittedVia: 'hosted-submit-relay',
-            signerBoundary: 'already-signed-transaction-only',
-            confirmationTimeoutMs,
-            desiredCommitment,
-            retrySafe: confirmation.retrySafe,
-            secretMaterial: 'never-received',
-            rule: confirmation.success
-                ? 'OOBE hosted relay submitted already-signed bytes and observed the transaction on-chain before returning success. The relay never signs and never receives keypair material.'
-                : 'OOBE hosted relay submitted already-signed bytes but did not observe the requested confirmation state before timeout. Retry only when retrySafe is true and the user confirms.',
-        },
-    };
-}
-function parseTxSubmitRelayInput(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error('JSON object body is required.');
-    }
-    const record = value;
-    const commitment = record.commitment;
-    if (commitment !== undefined && !['processed', 'confirmed', 'finalized'].includes(commitment)) {
-        throw new Error('commitment must be processed, confirmed, or finalized.');
-    }
-    if (record.encoding !== undefined && !['base64', 'base58'].includes(record.encoding)) {
-        throw new Error('encoding must be base64 or base58.');
-    }
-    return record;
-}
-async function waitForTxSubmitSignatureStatus(connection, signature, timeoutMs, desiredCommitment) {
-    const startedAt = Date.now();
-    let lastStatus = 'missing';
-    let lastSlot;
-    while (Date.now() - startedAt < timeoutMs) {
-        const statuses = await connection.getSignatureStatuses([signature], { searchTransactionHistory: true });
-        const status = statuses.value[0];
-        if (status?.err) {
-            return {
-                success: false,
-                retrySafe: true,
-                status: 'failed',
-                ...(status.slot === undefined ? {} : { slot: status.slot }),
-            };
-        }
-        if (status) {
-            lastStatus = status.confirmationStatus ?? 'processed';
-            lastSlot = status.slot;
-            if (txSubmitCommitmentReached(lastStatus, desiredCommitment)) {
-                return {
-                    success: true,
-                    retrySafe: false,
-                    status: lastStatus,
-                    ...(lastSlot === undefined ? {} : { slot: lastSlot }),
-                };
-            }
-        }
-        await new Promise(resolve => setTimeout(resolve, 2_000));
-    }
-    return {
-        success: false,
-        retrySafe: lastStatus === 'missing',
-        status: lastStatus === 'missing' ? 'expired_or_not_landed' : lastStatus,
-        ...(lastSlot === undefined ? {} : { slot: lastSlot }),
-    };
-}
-function txSubmitCommitmentReached(current, desired) {
-    const rank = {
-        processed: 1,
-        confirmed: 2,
-        finalized: 3,
-    };
-    return (rank[current] ?? 0) >= rank[desired];
-}
-function boundTxSubmitConfirmationTimeout(value) {
-    if (!Number.isFinite(value)) {
-        return TX_SUBMIT_DEFAULT_CONFIRMATION_TIMEOUT_MS;
-    }
-    return Math.max(15_000, Math.min(Number(value), TX_SUBMIT_MAX_CONFIRMATION_TIMEOUT_MS));
-}
 /**
  * @name readSingleHeader
  * @description Reads one normalized HTTP header value without accepting ambiguous arrays.
@@ -654,7 +547,10 @@ function readPaymentStatsFromLedger() {
         totalVolumeUsd: 0,
         totalSettlements: 0,
         totalPaymentRequests: 0,
+        totalChallengesReturned: 0,
         totalVerifiedPayments: 0,
+        totalVerificationFailures: 0,
+        totalEligibilityBlocks: 0,
         totalFailedSettlements: 0,
         uniqueRemoteCallers: 0,
         uniqueUserAgents: 0,
@@ -682,9 +578,18 @@ function readPaymentStatsFromLedger() {
         if (event.event === 'payment_required') {
             stats.totalPaymentRequests += 1;
         }
+        if (event.event === 'payment_challenge_returned') {
+            stats.totalChallengesReturned += 1;
+        }
         if (event.event === 'payment_verified') {
             stats.totalVerifiedPayments += 1;
         }
+        if (event.event === 'payment_verification_failed') {
+            stats.totalVerificationFailures += 1;
+        }
+        if (event.event === 'payment_eligibility_blocked') {
+            stats.totalEligibilityBlocks += 1;
+        }
         if (event.event === 'payment_settled') {
             stats.totalSettlements += 1;
             stats.totalVolumeUsd += event.priceUsd ?? 0;
@@ -801,6 +706,13 @@ export function buildPublicServerInfo(req, config) {
             serverInfo: `${baseUrl}/server.json`,
             pricing: `${baseUrl}/pricing.json`,
             openApi: `${baseUrl}/openapi.json`,
+            premiumCatalog: `${baseUrl}/premium/catalog.json`,
+            premiumStreams: `${baseUrl}/premium/streams.json`,
+            premiumWebhooks: `${baseUrl}/premium/webhooks.json`,
+            premiumHealth: `${baseUrl}/premium/health.json`,
+            premiumActivate: `${baseUrl}/premium/activate`,
+            premiumStreamBase: `${baseUrl}/premium/stream`,
+            premiumWebhookRegister: `${baseUrl}/premium/webhook/register`,
             x402Discovery: `${baseUrl}/.well-known/x402`,
             smitheryConfigSchema: `${baseUrl}/smithery.config.schema.json`,
             smitheryServerCard: `${baseUrl}/.well-known/mcp/server-card.json`,
@@ -867,6 +779,49 @@ export function buildMarketplaceConfigurationMetadata(req, config) {
         },
     };
 }
+/**
+ * @name buildPremiumDiscoveryDocument
+ * @description Builds public premium stream/webhook/plugin contracts for agent runtimes and marketplaces.
+ */
+export function buildPremiumDiscoveryDocument(req, config, type) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    const plugins = listPremiumPlugins();
+    const capabilities = plugins.flatMap(plugin => plugin.capabilities
+        .filter(capability => !type || capability.type === type)
+        .map(capability => ({
+        ...capability,
+        pluginId: plugin.id,
+        providerReady: capability.providerEnv.every(envName => Boolean(process.env[envName])),
+    })));
+    return {
+        version: '1.0.0',
+        service: 'sap-mcp-server',
+        serverVersion: MCP_SERVER_VERSION,
+        kind: type ? `premium-${type}-catalog` : 'premium-plugin-catalog',
+        title: type ? `SAP MCP Premium ${type === 'stream' ? 'Stream' : 'Webhook'} Catalog` : 'SAP MCP Premium Plugin Catalog',
+        description: 'Public, secret-free premium capability contracts for SAP MCP. Discovery and planning are free; live delivery requires x402/pay.sh settlement and configured providers.',
+        links: {
+            catalog: `${baseUrl}/premium/catalog.json`,
+            streams: `${baseUrl}/premium/streams.json`,
+            webhooks: `${baseUrl}/premium/webhooks.json`,
+            docs: `${baseUrl}/docs/18_PREMIUM_PLUGIN_RUNTIME.md`,
+            mcp: `${baseUrl}/mcp`,
+            pricing: `${baseUrl}/pricing.json`,
+            x402Discovery: `${baseUrl}/.well-known/x402`,
+            payShProvider: `${baseUrl}/pay/provider.yml`,
+        },
+        monetization: {
+            planning: 'free',
+            liveDelivery: 'x402/pay.sh required when the selected provider is live and the session is activated.',
+            sourceOfTruth: `${baseUrl}/pricing.json`,
+            localBridgeTool: 'sap_payments_call_paid_tool',
+        },
+        providerStatus: publicPremiumProviderStatus(),
+        privatePluginSupport: premiumPrivatePluginSupport(),
+        capabilities,
+        ...(type ? {} : { plugins }),
+    };
+}
 /**
  * @name readSmitheryConfigSchema
  * @description Reads the published Smithery JSON schema from the packaged root.
@@ -1002,6 +957,13 @@ export function buildOpenApiSpec(req, config) {
             resources: [`${baseUrl}/mcp`],
             openApi: `${baseUrl}/openapi.json`,
             pricing: `${baseUrl}/pricing.json`,
+            premiumCatalog: `${baseUrl}/premium/catalog.json`,
+            premiumStreams: `${baseUrl}/premium/streams.json`,
+            premiumWebhooks: `${baseUrl}/premium/webhooks.json`,
+            premiumHealth: `${baseUrl}/premium/health.json`,
+            premiumActivate: `${baseUrl}/premium/activate`,
+            premiumStreamBase: `${baseUrl}/premium/stream`,
+            premiumWebhookRegister: `${baseUrl}/premium/webhook/register`,
             x402Discovery: `${baseUrl}/.well-known/x402`,
             payShProvider: `${baseUrl}/pay/provider.yml`,
             ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
@@ -1179,6 +1141,171 @@ export function buildOpenApiSpec(req, config) {
                     },
                 },
             },
+            '/premium/catalog.json': {
+                get: {
+                    operationId: 'fetchPremiumCatalog',
+                    summary: 'Fetch premium plugin catalog',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Secret-free premium plugin, stream, webhook, schema, pricing, and provider readiness metadata.',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            version: { type: 'string' },
+                                            service: { type: 'string' },
+                                            kind: { type: 'string' },
+                                            capabilities: { type: 'array', items: { type: 'object', additionalProperties: true } },
+                                            providerStatus: { type: 'object', additionalProperties: { type: 'boolean' } },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            '/premium/streams.json': {
+                get: {
+                    operationId: 'fetchPremiumStreams',
+                    summary: 'Fetch premium stream catalog',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Secret-free premium stream contracts with schemas, x402/pay.sh pricing, and provider readiness.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                    },
+                },
+            },
+            '/premium/webhooks.json': {
+                get: {
+                    operationId: 'fetchPremiumWebhooks',
+                    summary: 'Fetch premium webhook catalog',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Secret-free premium webhook contracts with signed delivery expectations, pricing, and provider readiness.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                    },
+                },
+            },
+            '/premium/health.json': {
+                get: {
+                    operationId: 'fetchPremiumHealth',
+                    summary: 'Fetch premium subsystem health and metrics',
+                    tags: ['Premium'],
+                    responses: {
+                        '200': {
+                            description: 'Premium subsystem metrics: active/pending/blocked sessions, events delivered, revenue, active streams/webhooks, and provider health.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                    },
+                },
+            },
+            '/premium/activate': {
+                post: {
+                    operationId: 'activatePremiumSession',
+                    summary: 'Activate a premium session with a verified x402/pay.sh receipt',
+                    tags: ['Premium'],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['sessionId', 'paymentReceipt'],
+                                    properties: {
+                                        sessionId: { type: 'string' },
+                                        paymentReceipt: { type: 'string' },
+                                        payerAddress: { type: 'string' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Session activated successfully.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                        '400': { description: 'Missing required fields.' },
+                        '402': { description: 'Session not in pending_payment status.' },
+                    },
+                },
+            },
+            '/premium/stream/{sessionId}': {
+                get: {
+                    operationId: 'openPremiumStream',
+                    summary: 'Open an SSE stream for an active premium session',
+                    tags: ['Premium'],
+                    parameters: [
+                        { name: 'sessionId', in: 'path', required: true, schema: { type: 'string' } },
+                        { name: 'subscriptionKey', in: 'query', schema: { type: 'string' } },
+                        { name: 'since', in: 'query', schema: { type: 'string' } },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'SSE event stream. Each event is `event: <type>\\ndata: <json>\\n\\n`.',
+                            content: { 'text/event-stream': { schema: { type: 'string' } } },
+                        },
+                        '403': { description: 'Session not active.' },
+                        '406': { description: 'Accept: text/event-stream required.' },
+                    },
+                },
+            },
+            '/premium/webhook/register': {
+                post: {
+                    operationId: 'registerPremiumWebhook',
+                    summary: 'Register an HTTPS webhook target for signed premium event delivery',
+                    tags: ['Premium'],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['sessionId', 'targetUrl', 'events'],
+                                    properties: {
+                                        sessionId: { type: 'string' },
+                                        targetUrl: { type: 'string', format: 'uri' },
+                                        events: { type: 'array', items: { type: 'string' }, minItems: 1 },
+                                        signingPublicKey: { type: 'string' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '201': {
+                            description: 'Webhook subscription created. Delivery worker started in background.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                        '400': { description: 'Missing required fields.' },
+                        '402': { description: 'Session not active or URL invalid.' },
+                    },
+                },
+            },
+            '/premium/webhook/{subscriptionId}/status': {
+                get: {
+                    operationId: 'getPremiumWebhookStatus',
+                    summary: 'Check webhook subscription status and recent delivery records',
+                    tags: ['Premium'],
+                    parameters: [
+                        { name: 'subscriptionId', in: 'path', required: true, schema: { type: 'string' } },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Subscription status with recent delivery attempts.',
+                            content: { 'application/json': { schema: { type: 'object' } } },
+                        },
+                        '404': { description: 'Subscription not found.' },
+                    },
+                },
+            },
         },
     };
 }
@@ -1705,6 +1832,8 @@ export class RemoteMCPServer {
     httpTuning;
     sessionCleanupInterval;
     httpServer;
+    monetizationGate;
+    premiumMemoryManager;
     constructor(config) {
         this.appConfig = loadConfig();
         initLogger({
@@ -1727,7 +1856,10 @@ export class RemoteMCPServer {
         this.validateAuthConfig();
         await this.rateLimiter.initialize();
         this.startSessionCleanup();
-        const monetizationGate = await McpMonetizationGate.create(this.appConfig);
+        this.monetizationGate = await McpMonetizationGate.create(this.appConfig);
+        // Start premium memory background GC.
+        this.premiumMemoryManager = new PremiumMemoryManager();
+        this.premiumMemoryManager.start();
         this.httpServer = http.createServer(async (req, res) => {
             if (this.applyCors(req, res)) {
                 return;
@@ -1753,6 +1885,51 @@ export class RemoteMCPServer {
                 }, isHeadMethod(req.method));
                 return;
             }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/catalog.json') {
+                writeJson(res, 200, buildPremiumDiscoveryDocument(req, this.config), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/streams.json') {
+                writeJson(res, 200, buildPremiumDiscoveryDocument(req, this.config, 'stream'), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/webhooks.json') {
+                writeJson(res, 200, buildPremiumDiscoveryDocument(req, this.config, 'webhook'), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/premium/health.json') {
+                try {
+                    const metrics = await getPremiumMetrics();
+                    writeJson(res, 200, {
+                        version: '1.0.0',
+                        service: 'sap-mcp-server',
+                        serverVersion: MCP_SERVER_VERSION,
+                        timestamp: new Date().toISOString(),
+                        ...metrics,
+                    }, {
+                        'Cache-Control': 'public, max-age=15',
+                    }, isHeadMethod(req.method));
+                }
+                catch (error) {
+                    writeJson(res, 500, {
+                        error: 'premium_health_error',
+                        message: error instanceof Error ? error.message : 'Unknown error.',
+                    });
+                }
+                return;
+            }
+            // Premium delivery rail routes (activation, SSE stream, webhook register/status).
+            // These are not public read-only — they handle POST and GET with side effects.
+            const handledByPremiumRoute = await tryPremiumRoute(req, res);
+            if (handledByPremiumRoute) {
+                return;
+            }
             if (isPublicReadMethod(req.method) && url.pathname === '/smithery.config.schema.json') {
                 writeJson(res, 200, readSmitheryConfigSchema(), {
                     'Cache-Control': 'public, max-age=300',
@@ -1943,8 +2120,8 @@ export class RemoteMCPServer {
                         sessionIdGenerator: undefined,
                     });
                     await perRequestServer.connect(perRequestTransport);
-                    if (monetizationGate) {
-                        await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                    if (this.monetizationGate) {
+                        await this.monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
                             // Extract tool names from parsed JSON-RPC body for logging
                             loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
                             loggedMethod = extractJsonRpcMethod(parsedBody);
@@ -1960,8 +2137,8 @@ export class RemoteMCPServer {
                 }
                 else {
                     // Stateful mode: route each request to the transport created by its initialize response.
-                    if (monetizationGate) {
-                        await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                    if (this.monetizationGate) {
+                        await this.monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
                             loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
                             loggedMethod = extractJsonRpcMethod(parsedBody);
                             await this.handleStatefulMcpRequest(mcpReq, mcpRes, parsedBody);
@@ -2051,7 +2228,12 @@ export class RemoteMCPServer {
                 resolve();
             }, 5_000);
         });
+        await this.monetizationGate?.close();
+        this.monetizationGate = undefined;
         await this.rateLimiter.close();
+        // Premium subsystem graceful shutdown: stop streams, webhooks, providers, clear stores.
+        await this.premiumMemoryManager?.shutdown();
+        this.premiumMemoryManager = undefined;
     }
     /**
      * @name validateAuthConfig