@cmdoss/suipay-mcp 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { M as McpConfig, a as McpAuthContext, b as McpTraceHooks, G as GrantSnapshot, T as TraceSink, D as Dialect } from './http-B5iGH5mf.js';
+export { c as McpEnvelope, d as McpEnvelopeEntry, e as McpTraceContext, f as McpTraceRuntime, g as canonicalMcpRequestId, h as handleSuipayMcpHttpRequest, i as inspectMcpEnvelope, l as loadMcpConfig, r as resolveGrantTarget, t as traceMcpHttpRequest } from './http-B5iGH5mf.js';
+
+/** Holds a key and signs transaction bytes. Never leaves the payer. */
+interface Wallet {
+    readonly address: string;
+    signTransaction(txBytes: string): Promise<string>;
+}
+
+type PaidHttpMethod = 'GET' | 'POST';
+interface PaidHttpRequest {
+    url: string;
+    method: PaidHttpMethod;
+    /** Exact wire bytes. Empty for GET. */
+    body: Uint8Array;
+    /** Normalized media type, or null when no body is sent. */
+    contentType: string | null;
+    /** `hashRequestBody(body)` — the single canonical body hash. */
+    bodyHash: string;
+}
+
+interface SuiPayCredentials {
+    /** 64-hex Ed25519 seed. NEVER logged. */
+    delegatePrivateKey: string;
+    delegatePublicKeyHex: string;
+    delegateAddress: string;
+    ownerAddress: string;
+    allowanceId: string;
+    packageId: string;
+    coinType: string;
+    /** Allowance recipient = the resource's payTo. */
+    recipient: string;
+    gatewayUrl: string;
+    network: string;
+    maxPerPayment: string;
+    label?: string;
+    createdAt: string;
+    version: 1;
+}
+type SignerSource = 'secret-key' | 'credentials' | 'mnemonic';
+interface PaymentProfile {
+    creds: SuiPayCredentials;
+    wallet: Wallet;
+    source: SignerSource;
+}
+/**
+ * Load a historical V1 allowance payment profile, if present.
+ * ADR-0010: not for new settlement. Callers that pay must refuse this profile
+ * and point operators at shared_pool OAuth / delegated-signer flows.
+ */
+declare function loadPaymentProfile(): PaymentProfile | null;
+
+/**
+ * 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: "Fetch a paid HTTP resource and settle its MPP challenge via shared_pool (remote OAuth MCP). Local V1 allowance pay is retired. Use method POST with json to pay for a JSON request body; the body you send is signed into the offer, so it cannot be changed after payment.";
+    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 required: readonly ["url"];
+    };
+}, {
+    readonly name: "discover";
+    readonly description: "Search SuiPay gateway resources.";
+    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: "Legacy V1 allowance login (retired). Returns an error directing you to remote MCP OAuth or delegated-signer provisioning.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly label: {
+                readonly type: "string";
+                readonly description: "Label shown in SuiPay console.";
+            };
+            readonly gatewayResourceUrl: {
+                readonly type: "string";
+                readonly description: "Gateway resource URL whose 402 defines recipient, asset, and package.";
+            };
+        };
+    };
+}, {
+    readonly name: "suipay_logout";
+    readonly description: "Remove local SuiPay credentials. Refuses while live allowance holds funds unless forced.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly force: {
+                readonly type: "boolean";
+                readonly description: "Remove local credentials even if allowance still holds funds.";
+            };
+        };
+    };
+}];
+/**
+ * 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.
+ */
+declare function createSuipayMcpServer(cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceHooks): Server;
+
+interface PayResult {
+    status: 'ok' | 'failed' | 'ambiguous';
+    paid: boolean;
+    body?: unknown;
+    receipt?: unknown;
+    code?: string;
+    detail?: string;
+    txDigest?: string;
+}
+
+/**
+ * SharedPool pay-then-prove client (WS7.6).
+ *
+ * Flow: 402 Offer → resolveGrantTarget(snapshot, offer.targetHash) → build
+ * shared_pool::pay kind → sponsor → briefly decrypt delegate, sign, wipe →
+ * execute → wait finality → present MPP proof.
+ *
+ * Pause/revoke is checked via resolveGrantTarget BEFORE decrypt.
+ * Never accepts gas from the buyer. No blind retry on ambiguous finality.
+ */
+
+interface SharedPoolPaySession {
+    snapshot: GrantSnapshot;
+    /**
+     * Decrypt delegate seed for signing. Caller must only implement this after
+     * pause/revoke checks. Returns 32-byte seed; payer wipes after sign.
+     */
+    decryptDelegateSeed: () => Promise<Buffer | Uint8Array>;
+    /** SharedPool package id (V2). */
+    packageId: string;
+    /**
+     * Re-assert the grant is still live (not paused/revoked) against canonical
+     * state, invoked immediately before decrypt to close the snapshot→decrypt
+     * race: the snapshot is loaded when the request begins, and a pause/revoke
+     * arriving after that must stop key decryption — not merely fail on-chain.
+     * Throw to abort. Optional; when absent, only the request-time snapshot gates
+     * decrypt (on-chain rejection remains the final backstop).
+     */
+    assertLive?: () => Promise<void>;
+    /**
+     * Authorization header value (e.g. `Bearer <token>`) sent to the gateway's
+     * `/api/sponsor` create/execute calls. Required when the payer runs inside
+     * the gateway (remote `/mcp`): the sponsor guard authenticates the delegate
+     * from this bearer, and without it the internal sponsor call is unauthorized.
+     */
+    sponsorAuthorization?: string;
+}
+interface SharedPoolPayDeps {
+    fetchImpl?: typeof fetch;
+    /** Build only-transaction-kind bytes for shared_pool::pay. */
+    buildPayKind?: (input: {
+        delegate: string;
+        coinType: string;
+        poolObjectId: string;
+        grantObjectId: string;
+        policyId: number | string;
+        targetHash: string;
+        amount: string;
+        paymentIdHash: Uint8Array;
+        termsHash: Uint8Array;
+    }) => Promise<{
+        kindBytes: string;
+    }>;
+    /** Wait for chain finality of a digest. */
+    getFinalizedTx?: (digest: string) => Promise<{
+        status: 'success' | 'failed';
+        reason?: string;
+    } | null>;
+    /**
+     * Live trace for this payment.
+     *
+     * Two jobs, both purely observational. Emission records what the canonical
+     * decisions already returned — an event is written *after* a check passes and
+     * can never be the thing that lets the next step run. Signing attaches
+     * correlation headers to the internal sponsor and settle hops so the gateway
+     * can attribute its own facts to the same run; the sponsor allowlist, guard
+     * and simulation gates behave identically with or without them.
+     */
+    trace?: SharedPoolPayTrace;
+}
+interface SharedPoolPayTrace {
+    sink: TraceSink;
+    traceId: string;
+    requestId: string | null;
+    buyerAccountId: string;
+    connectionId: string;
+    /** HMAC secret for signed cross-request context. Absent disables signing. */
+    secret?: string | null;
+    /** Injected clock, for tests. */
+    now?: () => number;
+}
+/** Default kind builder (no chain client — pure PTB). */
+declare function buildSharedPoolPayKind(input: {
+    packageId: string;
+    delegate: string;
+    coinType: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    policyId: number | string;
+    targetHash: string;
+    amount: string;
+    paymentIdHash: Uint8Array;
+    termsHash: Uint8Array;
+}): Promise<{
+    kindBytes: string;
+}>;
+declare function paySharedPoolResource(args: {
+    url: string;
+    /**
+     * The one normalized paid request, replayed byte for byte on the unpaid and
+     * the paid call. Omitted by legacy GET callers.
+     */
+    request?: PaidHttpRequest;
+    session: SharedPoolPaySession;
+    cfg: McpConfig;
+    deps?: SharedPoolPayDeps;
+    /**
+     * Preferred dialect when the 402 advertises both (WS12.3).
+     * Default: mpp (pay-then-prove). x402 = gateway-submitted credential.
+     */
+    preferredDialect?: Dialect;
+}): Promise<PayResult>;
+
+declare function loadBootProfile(load?: typeof loadPaymentProfile): {
+    profile: ReturnType<typeof loadPaymentProfile>;
+    unreadable: boolean;
+};
+declare function main(): Promise<void>;
+
+export { McpTraceHooks, PACKAGE_NAME, type SharedPoolPaySession, TOOLS, buildSharedPoolPayKind, createSuipayMcpServer, loadBootProfile, main, paySharedPoolResource };

package/dist/index.js

@@ -0,0 +1,32 @@
+import {
+  loadBootProfile,
+  loadMcpConfig,
+  main
+} from "./chunk-5I6V7N3R.js";
+import {
+  PACKAGE_NAME,
+  TOOLS,
+  buildSharedPoolPayKind,
+  canonicalMcpRequestId,
+  createSuipayMcpServer,
+  handleSuipayMcpHttpRequest,
+  inspectMcpEnvelope,
+  paySharedPoolResource,
+  resolveGrantTarget,
+  traceMcpHttpRequest
+} from "./chunk-772CHNGT.js";
+export {
+  PACKAGE_NAME,
+  TOOLS,
+  buildSharedPoolPayKind,
+  canonicalMcpRequestId,
+  createSuipayMcpServer,
+  handleSuipayMcpHttpRequest,
+  inspectMcpEnvelope,
+  loadBootProfile,
+  loadMcpConfig,
+  main,
+  paySharedPoolResource,
+  resolveGrantTarget,
+  traceMcpHttpRequest
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@cmdoss/suipay-mcp",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "SuiPay MCP — pay MPP-gated APIs from an on-chain allowance.",
+  "bin": {
+    "suipay": "dist/bin/suipay.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "e2e:protocol:testnet": "tsx scripts/e2e-protocol-testnet.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mysten/sui": "2.23.1",
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  }
+}