@cmdoss/suipay-mcp 0.2.2-dev.0 → 0.2.2

package/dist/http-B4YTVw0k.d.ts

@@ -1,392 +0,0 @@
-import { GrantSnapshot } from '@cmdoss/suipay-core/policy/grant-target';
-import { McpAccessContext } from '@cmdoss/suipay-sdk/mcp/access-context';
-import { SettlementDTO } from '@cmdoss/suipay-sdk/buyer/settlement-dto';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { GetObjectJson } from '@cmdoss/suipay-sdk/agent-sdk/reads';
-import { DelegatedKeySigner, DelegatedPayerDeps } from '@cmdoss/suipay-sdk/delegated-signer/payer';
-import { TraceRunResolver, TraceSink } from '@cmdoss/suipay-core/trace/types';
-
-/**
- * Authenticated MCP request context (remote Streamable HTTP).
- * Bearer is required on /mcp; tools enforce scope from the resolved grant.
- */
-
-/**
- * Read/prepare-only shared-pool context for an authenticated MCP bearer.
- *
- * Non-custodial: the gateway holds NO key that can spend. There is deliberately
- * no `decryptDelegateSeed` and no forwarded `sponsorAuthorization` here — the
- * `pay` tool only PREPARES an unsigned `spend_account::settle_policy_payment` transaction from the
- * immutable grant snapshot (`prepareSpendAccountPayment`), and the client that
- * holds the delegate key signs locally and submits. Only signatures ever reach
- * the gateway. See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
- */
-interface McpSpendAccountPayAuth {
-    snapshot: GrantSnapshot;
-    packageId: string;
-    /**
-     * Re-verify the paying authority against a FRESH graph + injected clock at
-     * prepare time. Throws on drift/expiry so the pay tool refuses to hand back a
-     * signing request for a grant that just went paused/revoked/expired. Optional:
-     * absent for legacy/local paths.
-     */
-    assertLive?: () => Promise<void>;
-}
-interface McpAuthContext {
-    grantId: string;
-    buyerAccountId: string;
-    /** Space-separated scopes from the access token. */
-    scope: string;
-    /** Public, descriptive policy context. Never used as payment authority. */
-    access?: McpAccessContext;
-    /**
-     * When present, `pay` prepares unsigned spend_account::settle_policy_payment bytes for the
-     * client-held delegate key to sign locally — no server-side decrypt or
-     * signing. Stdio local V1 profile path remains when absent.
-     */
-    spendAccountPay?: McpSpendAccountPayAuth;
-    /**
-     * Server-scoped receipts reader, built by the /mcp route from the verified
-     * bearer's connection. The `receipts` tool calls this instead of hitting the
-     * global settlement feed with a forwarded credential — the bearer never
-     * enters the tool surface, and scoping is enforced server-side. Absent for
-     * local stdio (no connection, no settlement source).
-     */
-    listReceipts?: (challengeId?: string) => Promise<SettlementDTO[]>;
-}
-
-type McpTarget = 'dev' | 'local';
-/**
- * Public suipay-dev origins (Railway). `local` is the laptop stack from
- * `pnpm demo:testnet`. Explicit `SUIPAY_GATEWAY_URL` / `SUIPAY_CONSOLE_URL`
- * still win over the preset.
- */
-declare const MCP_TARGET_PRESETS: Record<McpTarget, {
-    consoleUrl: string;
-    gatewayUrl: string;
-}>;
-interface McpConfig {
-    /** Preset used when console/gateway env is unset. Set by `loadMcpConfig`. */
-    target?: McpTarget;
-    consoleUrl: string;
-    gatewayUrl: string;
-    rpcUrl: string;
-    network: 'testnet' | 'mainnet' | 'devnet' | 'localnet';
-    packageId: string;
-    recipient: string;
-    coinType: string;
-    sponsorUrl: string;
-    minFunded: bigint;
-    minMaxPerPayment: bigint;
-    label: string;
-}
-/**
- * CLI flags: `--local` / `-local`, `--dev` / `-dev`. Unknown args are ignored
- * so an MCP host can pass extra argv without breaking stdio.
- */
-declare function parseMcpTargetFlag(argv: readonly string[]): McpTarget | undefined;
-declare function resolveMcpTarget(env?: NodeJS.ProcessEnv, argv?: readonly string[]): McpTarget;
-/** Same public origin, or the same laptop loopback port (`localhost` ≡ `127.0.0.1`). */
-declare function sameMcpGateway(a: string, b: string): boolean;
-declare function loadMcpConfig(env?: NodeJS.ProcessEnv, argv?: readonly string[]): McpConfig;
-
-/**
- * Agent-held settlement wiring for the `pay` tool.
- *
- * The gateway prepares (it holds no key). Settlement needs the delegate key, so
- * it can only happen in the process that holds one. This module answers a single
- * question for a given grant: *is this process that grant's agent, and is it
- * configured to settle?* Any "no" returns null and `pay` falls back to handing
- * back unsigned bytes — the pre-existing behavior.
- *
- * Two conditions gate it, and the first is the security one:
- *
- * 1. **The persisted key must be the key the grant names.** A hosted gateway
- *    running this same tool code either holds no credentials file (null) or
- *    holds one for some unrelated key (address mismatch → null). It can only
- *    settle by already possessing the grant's delegate seed — which is exactly
- *    the custody ADR-0015 removed, not a state a flag protects against.
- * 2. **The settlement dependencies must all be present.** A half-configured
- *    settler is worse than none: it would sign and then fail to confirm. Missing
- *    anything → null, prepare-only.
- *
- * The key is read, never minted. See `loadLocalSigner`.
- */
-
-/** Everything `pay` needs to settle rather than prepare. */
-interface AgentHeldSettlement {
-    signer: DelegatedKeySigner;
-    getObjectJson: GetObjectJson;
-    payerDeps: DelegatedPayerDeps;
-}
-/**
- * Resolve agent-held settlement for one grant, or null to stay prepare-only.
- * Injectable so `createServer` can be driven without touching disk,
- * chain, or environment.
- */
-type AgentHeldResolver = (cfg: McpConfig, spendAccountPay: McpSpendAccountPayAuth) => AgentHeldSettlement | null;
-/** Test seam: drop the process ledger so suites do not share reservations. */
-declare function resetAgentHeldProcessLedger(): void;
-declare function resolveAgentHeldSettlement(cfg: McpConfig, spendAccountPay: McpSpendAccountPayAuth, env?: NodeJS.ProcessEnv): AgentHeldSettlement | null;
-
-/**
- * Transparent MCP wire proxy.
- *
- * This module is the *only* place in the system that parses MCP methods and
- * JSON-RPC ids. The gateway authenticates and hands over a run manager and a
- * sink; it never sniffs an MCP body a second time. Payment code emits domain
- * facts, never wire facts. That single-owner rule is what stops two subsystems
- * from disagreeing about which tool call a payment belongs to.
- *
- * Transparency is the top invariant, and it is structural rather than
- * best-effort:
- *
- *  - With no runtime, this file is a pass-through and does not touch the
- *    request or the response at all.
- *  - With a runtime, observation reads `Request.clone()` and `Response.clone()`
- *    only. The exact `Response` instance the handler produced is what the caller
- *    receives, so byte equality is by construction, not by careful copying.
- *  - Response observation is started and deliberately not awaited. A trace
- *    store that hangs cannot hold an MCP response open.
- *  - The request side cannot be fire-and-forget — the proxy must know the run
- *    and the JSON-RPC ids before the handler runs — so it is bounded instead:
- *    one deadline over envelope parsing plus run selection, and the same byte
- *    cap the response observer uses. A hung store or an oversized body costs
- *    the trace, never the request.
- *  - Every observation path is wrapped: a hostile body, a failing run manager or
- *    a throwing sink degrades to "no trace", never to a changed response.
- *
- * Volume control lives here too. One `tool_called` per JSON-RPC id and one
- * terminal `tool_result` / `tool_error` per id — never one row per SSE frame.
- */
-
-/** Everything the proxy needs to attribute wire facts to one owned run. */
-interface McpTraceRuntime {
-    buyerAccountId: string;
-    connectionId: string;
-    runs: TraceRunResolver;
-    sink: TraceSink;
-    /**
-     * HMAC secret for signed cross-request context. Supplied by the composition
-     * root so a published SDK never reads a gateway-only environment variable.
-     * Absent means internal hops carry no correlation and the gateway simply
-     * emits no linked events.
-     */
-    secret?: string | null;
-    /** Injected clock; tests pin it, production leaves it out. */
-    now?: () => number;
-}
-/** The proxy-resolved context handed down to payment code (Task 5 seams). */
-interface McpTraceContext {
-    traceId: string;
-    requestId: string | null;
-}
-interface McpTraceHooks {
-    runtime: McpTraceRuntime;
-    context: McpTraceContext;
-    sink: TraceSink;
-}
-/** One JSON-RPC message read off the request side. */
-interface McpEnvelopeEntry {
-    method: string | null;
-    jsonRpcId: string | number | null;
-    /** Canonical, header-safe request id. `null` for notifications. */
-    requestId: string | null;
-    toolName: string | null;
-    toolArguments: unknown;
-    clientName: string | null;
-    clientVersion: string | null;
-    protocolVersion: string | null;
-}
-interface McpEnvelope {
-    batch: boolean;
-    entries: McpEnvelopeEntry[];
-    /** First entry's method — what run selection keys on. */
-    method: string | null;
-    requestId: string | null;
-    clientName: string | null;
-}
-/**
- * Canonical MCP request id.
- *
- * JSON-RPC allows both `7` and `"7"` as distinct ids, and they must stay
- * distinct: correlating a payment to the wrong tool call is worse than not
- * correlating it. Numbers keep their JSON form under `n:`; strings are
- * base64url-encoded under `s:` so an id containing newlines, colons or quotes
- * survives being carried in an HTTP header without escaping games.
- */
-declare function canonicalMcpRequestId(id: unknown): string | null;
-/**
- * Read the JSON-RPC envelope from a request **clone**.
- *
- * The caller owns cloning; this consumes the body it is given. An unparsable,
- * bodiless or over-cap request yields an empty envelope rather than an error — a
- * malformed request is the transport's problem to answer, not tracing's problem
- * to block.
- */
-declare function inspectMcpEnvelope(request: Request, maxBytes?: number): Promise<McpEnvelope>;
-interface TraceMcpHttpRequestInput {
-    request: Request;
-    /**
-     * The real MCP handler. Receives the untouched original request, plus the
-     * resolved trace context when tracing is live.
-     */
-    handle: (request: Request, hooks?: McpTraceHooks) => Promise<Response>;
-    runtime?: McpTraceRuntime | null;
-    /** Cap on bytes read for observation, request and response. Never unbounded. */
-    maxObservedBytes?: number;
-    /**
-     * Deadline for envelope parsing plus run selection, the only trace work that
-     * happens before the handler. Past it the exchange proceeds untraced.
-     */
-    runSetupTimeoutMs?: number;
-}
-/**
- * Wrap one MCP HTTP exchange in observation.
- *
- * The response returned here is the exact object `handle` produced. Nothing on
- * the observation path can change it, delay it, or prevent it.
- */
-declare function traceMcpHttpRequest(input: TraceMcpHttpRequestInput): Promise<Response>;
-
-/**
- * Transport-neutral SuiPay MCP server + tool registry.
- * Used by stdio (index.ts) and Streamable HTTP (http.ts).
- * Remote HTTP passes McpAuthContext so tools enforce OAuth scope + shared-pool pay.
- */
-
-declare const PACKAGE_NAME = "@cmdoss/suipay-mcp";
-declare const TOOLS: readonly [{
-    readonly name: "access_context";
-    readonly description: "Inspect profiles, policies, service targets, spend caps, usage, and lifecycle state enforced for this authenticated SuiPay session. Call before choosing a paid service.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {};
-    };
-}, {
-    readonly name: "pay";
-    readonly description: string;
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly url: {
-                readonly type: "string";
-                readonly description: "Full gateway resource URL.";
-            };
-            readonly method: {
-                readonly type: "string";
-                readonly enum: readonly ["GET", "POST"];
-                readonly description: "HTTP method of the paid request. Defaults to GET.";
-            };
-            readonly json: {
-                readonly type: "object";
-                readonly description: "JSON request body for a POST. Sent as application/json and bound to the payment.";
-            };
-            readonly recipient: {
-                readonly type: "string";
-                readonly description: "Sui address you expect to be paid. The payment is refused, unsigned, if the prepared transaction pays anyone else.";
-            };
-            readonly maxAmount: {
-                readonly type: "string";
-                readonly description: "Atomic ceiling you will spend on this call. The payment is refused, unsigned, if the offer costs more.";
-            };
-        };
-        readonly required: readonly ["url"];
-    };
-}, {
-    readonly name: "discover";
-    readonly description: "Search SuiPay gateway resources. After login, each row includes name, path, url, catalog price, and whether the current session can cover one call at that price (descriptive only — pay still enforces the grant).";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly query: {
-                readonly type: "string";
-                readonly description: "Optional service search terms.";
-            };
-        };
-    };
-}, {
-    readonly name: "receipts";
-    readonly description: "List SuiPay settlement receipts, optionally filtered by challenge id.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly challengeId: {
-                readonly type: "string";
-                readonly description: "Optional payment challenge id.";
-            };
-        };
-    };
-}, {
-    readonly name: "suipay_login";
-    readonly description: "Mint or reuse the local delegate key (version-2, mode 0600) and return a clickable console URL immediately so the owner can bind a spend-account grant. Does not wait for the wallet. Default target is Railway suipay-dev; pass target=\"local\" (or start the binary with --local) for the laptop stack. Stdio only; hosted /mcp never holds a spendable key.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly label: {
-                readonly type: "string";
-                readonly description: "Label shown in SuiPay console.";
-            };
-            readonly target: {
-                readonly type: "string";
-                readonly enum: readonly ["dev", "local"];
-                readonly description: "Where to bind the grant. Default is Railway suipay-dev. Pass \"local\" for localhost:3000 / 127.0.0.1:4340.";
-            };
-            readonly gatewayResourceUrl: {
-                readonly type: "string";
-                readonly description: "Gateway resource URL whose 402 defines recipient, asset, and package.";
-            };
-        };
-    };
-}, {
-    readonly name: "suipay_logout";
-    readonly description: "Remove the local delegate-key credentials file. Missing file is success. Force clears a corrupt file without printing the seed.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly force: {
-                readonly type: "boolean";
-                readonly description: "Remove local credentials even if the file is unreadable.";
-            };
-        };
-    };
-}];
-/**
- * Create a Server with the public SuiPay tool surface registered.
- *
- * `trace` is the proxy-resolved run for this HTTP exchange. It is threaded into
- * tool dependencies so payment code can emit *domain* events, and nothing else:
- * this wrapper deliberately emits no tool lifecycle of its own, because the
- * proxy observes the actual JSON-RPC wire and a second source would double-count
- * every call and disagree on ids.
- */
-interface McpServerOptions {
-    /**
-     * How `pay` finds an agent-held delegate key for the authenticated grant.
-     * Defaults to the persisted local key (`resolveAgentHeldSettlement`), which
-     * returns null on any process that does not hold the key the grant names — so
-     * the default is prepare-only everywhere except the agent's own machine.
-     * Injectable for tests; there is no way to make it hand over a key the grant
-     * does not already authorize.
-     */
-    resolveAgentHeld?: AgentHeldResolver;
-}
-declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceHooks, options?: McpServerOptions): Server;
-
-/**
- * Streamable HTTP transport for SuiPay MCP.
- * Stateless per-request (sessionIdGenerator undefined) — same public tools as stdio.
- * Auth context is required for remote gateway /mcp (bearer resolved upstream).
- *
- * The optional trace runtime turns on live observation. It is a pure wrapper:
- * `traceMcpHttpRequest` reads clones and returns the transport's own Response,
- * so passing a runtime cannot change what an MCP client sees.
- */
-
-/**
- * Handle one MCP Streamable HTTP request (initialize, tools/list, tools/call, …).
- * Creates a fresh transport+server pair per request (stateless mode).
- */
-declare function handleSuipayMcpHttpRequest(req: Request, cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceRuntime | null, options?: McpServerOptions): Promise<Response>;
-
-export { type AgentHeldResolver as A, type McpConfig as M, PACKAGE_NAME as P, TOOLS as T, type McpAuthContext as a, type McpTraceHooks as b, type AgentHeldSettlement as c, MCP_TARGET_PRESETS as d, type McpEnvelope as e, type McpEnvelopeEntry as f, type McpServerOptions as g, type McpTarget as h, type McpTraceContext as i, type McpTraceRuntime as j, canonicalMcpRequestId as k, createServer as l, handleSuipayMcpHttpRequest as m, inspectMcpEnvelope as n, loadMcpConfig as o, parseMcpTargetFlag as p, resolveAgentHeldSettlement as q, resetAgentHeldProcessLedger as r, resolveMcpTarget as s, sameMcpGateway as t, traceMcpHttpRequest as u };