@cmdoss/suipay-mcp 1.0.1

package/dist/http-B5iGH5mf.d.ts

@@ -0,0 +1,427 @@
+/**
+ * Resolve which grant policy target may pay a seller offer's targetHash (WS7.6).
+ *
+ * SINGLE SOURCE — consent validation and MCP pay MUST use this helper.
+ * Never inline "find policy by hash" in tools or consent UI.
+ *
+ * Seller offer carries targetHash only (no buyer policyId). Buyer authority
+ * is the OAuth grant snapshot of policies/targets at consent time.
+ */
+type GrantLifecycleStatus = 'pending' | 'active' | 'paused' | 'revoked' | 'expired';
+type PolicyLifecycleStatus = 'draft' | 'active' | 'paused' | 'revoked';
+interface GrantTargetBinding {
+    /** 32-byte hex target hash. */
+    targetHash: string;
+    /** Optional per-target ceiling (atomic units). */
+    maxPerPayment?: string;
+}
+interface GrantPolicyBinding {
+    /** Off-chain policy id (for audit). */
+    policyId: string;
+    /** On-chain policy id (u64) inside SharedPool. */
+    onChainPolicyId: number | string;
+    status: PolicyLifecycleStatus;
+    targets: readonly GrantTargetBinding[];
+}
+/**
+ * Immutable snapshot of buyer authority for one OAuth grant.
+ * Pool/grant object ids come from finalized on-chain objects (or fake in WS6B).
+ */
+interface GrantSnapshot {
+    grantId: string;
+    status: GrantLifecycleStatus;
+    grantObjectId: string | null;
+    poolObjectId: string;
+    coinType: string;
+    delegateAddress: string;
+    policies: readonly GrantPolicyBinding[];
+    /**
+     * `open` = unrestricted capped (no allowlist); `scoped` / omit = policy-bound.
+     */
+    accessMode?: 'scoped' | 'open';
+    /** Grant-level max per payment (atomic); used for open and as a grant ceiling. */
+    maxPerPayment?: string | null;
+    /** Grant-level session cap (atomic); open requires a positive value. */
+    sessionCap?: string | null;
+}
+type ResolveGrantTargetResult = {
+    ok: true;
+    policyId: string;
+    onChainPolicyId: number | string;
+    targetHash: string;
+    maxPerPayment?: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    coinType: string;
+    delegateAddress: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Pick the policy target that matches offer.targetHash under an active grant.
+ * Pause/revoke of grant or policy fails closed without decrypting the delegate.
+ */
+declare function resolveGrantTarget(snapshot: GrantSnapshot, offerTargetHash: string): ResolveGrantTargetResult;
+
+/**
+ * Public authorization facts exposed to authenticated MCP clients.
+ *
+ * This shape is descriptive only. Payment authorization continues to use the
+ * immutable on-chain GrantSnapshot; callers must never derive spend authority
+ * from this object.
+ */
+interface McpAccessProfile {
+    id: string;
+    name: string;
+    status: 'active' | 'disabled';
+}
+interface McpAccessTarget {
+    serviceId: string;
+    /** Friendly seller service name (live catalog), or serviceId if unresolved. */
+    name: string;
+    endpointId: string;
+    method: string;
+    path: string;
+    targetHash: string;
+    maxPerPayment: string;
+}
+interface McpAccessPolicy {
+    id: string;
+    name: string;
+    status: 'draft' | 'active' | 'paused' | 'revoked';
+    asset: string;
+    coinType: string;
+    totalCap: string;
+    spent: string;
+    maxPerPayment: string;
+    expiresAt: string | null;
+    targets: McpAccessTarget[];
+}
+interface McpAccessContext {
+    accessMode: 'scoped' | 'open';
+    grant: {
+        id: string;
+        status: 'pending' | 'active' | 'paused' | 'revoked' | 'expired';
+        sessionCap: string | null;
+        sessionSpent: string;
+        expiresAt: string | null;
+    };
+    profiles: McpAccessProfile[];
+    policies: McpAccessPolicy[];
+}
+
+/**
+ * Shared vocabulary for both 402 dialects.
+ *
+ * The central claim of this PoC is that MPP and x402 are two encodings of one
+ * payment offer, not two payment systems. Everything below the dialect codecs
+ * therefore speaks in these types; only `mpp.ts` and `x402.ts` know about
+ * headers and JSON bodies.
+ */
+
+/** Which encoding a message used. Recorded so the provider can answer in kind. */
+type Dialect = 'mpp' | 'x402';
+
+/**
+ * Canonical live-trace contract.
+ *
+ * One owner module for every observable MCP / payment / chain fact the live
+ * audience view renders. No emitter invents its own event shape: emitters call
+ * TraceSink.emit with a TraceEventInput, the dispatcher sanitizes it, and the
+ * store persists an append-only TraceEventRecord.
+ *
+ * Two rules shape everything here:
+ *
+ *  1. A trace event is *observation*, never authority. It is emitted after a
+ *     canonical decision returns and can never authorize the next step.
+ *  2. The database event id is the canonical display order and is a bigserial.
+ *     Outside the store it is always a decimal string — a JavaScript number
+ *     silently loses precision past 2^53 and would corrupt SSE resume.
+ */
+
+type TraceSource = 'mcp_wire' | 'suipay' | 'sui';
+type TraceStatus = 'started' | 'ok' | 'warning' | 'error' | 'ambiguous';
+type TraceEventKind = 'mcp_connected' | 'tools_listed' | 'tool_called' | 'tool_result' | 'tool_error' | 'challenge_received' | 'authority_matched' | 'authority_revalidated' | 'sponsor_requested' | 'transaction_sponsored' | 'delegate_signed' | 'transaction_submitted' | 'payment_finalized' | 'proof_presented' | 'upstream_delivered' | 'upstream_delivery_failed' | 'settlement_projected' | 'settlement_projection_failed' | 'receipt_issued' | 'payment_failed' | 'payment_ambiguous';
+interface TraceEventInput {
+    traceId: string;
+    requestId: string | null;
+    buyerAccountId: string;
+    connectionId: string;
+    at: string;
+    source: TraceSource;
+    kind: TraceEventKind;
+    status: TraceStatus;
+    summary: string;
+    publicPayload: Record<string, unknown>;
+    technicalPayload?: Record<string, unknown>;
+}
+/**
+ * Correlation constraints an emitter can attach to one event.
+ *
+ * `requireSoleActiveRunForBuyer` is the server-side (ADR-0011) fallback's
+ * atomicity guard: the event is persisted only if, at append time, that buyer
+ * still has exactly one active run. It closes the window between selecting the
+ * sole run and appending to it — a second run opening in between makes the
+ * append fail closed rather than land on a run that is no longer sole.
+ */
+interface TraceEmitOptions {
+    requireSoleActiveRunForBuyer?: string;
+}
+interface TraceSink {
+    emit(event: TraceEventInput, options?: TraceEmitOptions): Promise<void>;
+}
+type TraceRunEndReason = 'completed' | 'idle' | 'superseded' | 'event_cap' | 'byte_cap' | 'shutdown';
+interface TraceRun {
+    id: string;
+    buyerAccountId: string;
+    connectionId: string;
+    clientName: string | null;
+    startedAt: string;
+    lastEventAt: string;
+    endedAt: string | null;
+    endReason: TraceRunEndReason | null;
+    /** Persisted events accepted into this run. */
+    eventCount: number;
+    /** Serialized sanitized payload bytes accepted into this run. */
+    payloadBytes: number;
+}
+/** Run selection for one authenticated OAuth connection (implemented in context.ts). */
+interface TraceRunResolver {
+    resolveRun(input: {
+        buyerAccountId: string;
+        connectionId: string;
+        jsonRpcMethod: string | null;
+        clientName: string | null;
+        now: number;
+    }): Promise<TraceRun>;
+}
+
+/**
+ * The canonical `/v1/settlements` wire row. Both settlement sources - the live
+ * in-memory feed and the durable read model - normalize to this shape so the
+ * response is byte-stable regardless of whether a read model (DATABASE_URL) is
+ * configured. Consumers (MCP `receipts` tool, buyer/seller console) read
+ * `receipt.txDigest`; a source that returns its own native shape breaks them.
+ */
+interface SettlementDTO {
+    at: string;
+    resourceId?: string;
+    recipient: string;
+    dialect?: Dialect;
+    receipt: {
+        challengeId: string;
+        txDigest: string;
+        network: string;
+        payer: string;
+        amount: string;
+        asset: string;
+        status: 'settled';
+    };
+    /**
+     * Present only on the live in-memory feed. The read model dedups on
+     * (network, digest), so a durable row is never a replay - the field is
+     * omitted there rather than asserted false. Consumers must treat absent as
+     * not-replayed.
+     */
+    replayed?: boolean;
+}
+
+/**
+ * Authenticated MCP request context (remote Streamable HTTP).
+ * Bearer is required on /mcp; tools enforce scope from the resolved grant.
+ */
+
+interface McpSharedPoolPayAuth {
+    snapshot: GrantSnapshot;
+    packageId: string;
+    /** Brief decrypt only after pause/revoke checks (paySharedPoolResource). */
+    decryptDelegateSeed: () => Promise<Buffer | Uint8Array>;
+    /**
+     * Re-verify the paying authority against a FRESH graph + injected clock,
+     * immediately before decrypt. Throws on drift/expiry so the pay tool aborts
+     * (paySharedPoolResource :459). Optional: absent for legacy/local paths.
+     */
+    assertLive?: () => Promise<void>;
+    /**
+     * Authorization header value (e.g. `Bearer <token>`) the server-side payer
+     * forwards to the gateway's own `/api/sponsor` so the sponsor guard can
+     * authenticate the delegate. On `/mcp` the pay runs inside the gateway, so
+     * the sponsor call otherwise carries no caller credential and the guard 401s.
+     */
+    sponsorAuthorization?: string;
+}
+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` uses paySharedPoolResource (server-loaded snapshot +
+     * KEK-bound delegate). Stdio local V1 profile path remains when absent.
+     */
+    sharedPoolPay?: McpSharedPoolPayAuth;
+    /**
+     * 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[]>;
+}
+
+interface McpConfig {
+    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;
+}
+declare function loadMcpConfig(env?: NodeJS.ProcessEnv): McpConfig;
+
+/**
+ * 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>;
+
+/**
+ * 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): Promise<Response>;
+
+export { type Dialect as D, type GrantSnapshot as G, type McpConfig as M, type TraceSink as T, type McpAuthContext as a, type McpTraceHooks as b, type McpEnvelope as c, type McpEnvelopeEntry as d, type McpTraceContext as e, type McpTraceRuntime as f, canonicalMcpRequestId as g, handleSuipayMcpHttpRequest as h, inspectMcpEnvelope as i, loadMcpConfig as l, resolveGrantTarget as r, traceMcpHttpRequest as t };

package/dist/http.d.ts

@@ -0,0 +1 @@
+export { h as handleSuipayMcpHttpRequest } from './http-B5iGH5mf.js';

package/dist/http.js

@@ -0,0 +1,6 @@
+import {
+  handleSuipayMcpHttpRequest
+} from "./chunk-772CHNGT.js";
+export {
+  handleSuipayMcpHttpRequest
+};