@cmdoss/suipay-mcp 0.2.2-dev.4 → 0.2.2-dev.40

package/dist/{http-C8xW9F1c.d.ts → http-DvnvTrb3.d.ts}

@@ -3,8 +3,12 @@ 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 { DelegatedKeySigner, DelegatedPayerDeps, GuardedSettleFields } from '@cmdoss/suipay-sdk/delegated-signer/payer';
 import { TraceRunResolver, TraceSink } from '@cmdoss/suipay-core/trace/types';
+import { PaidHttpRequest } from '@cmdoss/suipay-sdk/protocol/paid-http-request';
+import { Dialect } from '@cmdoss/suipay-sdk/protocol/types';
+import { PayOperationDeps } from '@cmdoss/suipay-sdk/pay-operation';
+import { PaymentState, NextAction } from '@cmdoss/suipay-core/errors';
 
 /**
  * Authenticated MCP request context (remote Streamable HTTP).
@@ -16,7 +20,7 @@ import { TraceRunResolver, TraceSink } from '@cmdoss/suipay-core/trace/types';
  *
  * 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
+ * `pay` tool only PREPARES an unsigned `spend_account::settle_policy` / `settle_any_recipient` 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.
@@ -40,7 +44,7 @@ interface McpAuthContext {
     /** Public, descriptive policy context. Never used as payment authority. */
     access?: McpAccessContext;
     /**
-     * When present, `pay` prepares unsigned spend_account::settle_policy_payment bytes for the
+     * When present, `pay` prepares unsigned spend_account::settle_policy / settle_any_recipient bytes for the
      * client-held delegate key to sign locally — no server-side decrypt or
      * signing. Stdio local V1 profile path remains when absent.
      */
@@ -55,7 +59,19 @@ interface McpAuthContext {
     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;
@@ -67,8 +83,23 @@ interface McpConfig {
     minFunded: bigint;
     minMaxPerPayment: bigint;
     label: string;
+    /**
+     * Optional override of the gateway's published `ExclusionDirectory` id.
+     * When null, pay reads `GET /v1/delegate/deployment` and turns the resolver
+     * on only if that response names one. The id here does not choose the
+     * directory a settle uses — the offer's `registryIdentity` does.
+     */
+    exclusionDirectoryObjectId: string | null;
 }
-declare function loadMcpConfig(env?: NodeJS.ProcessEnv): McpConfig;
+/**
+ * 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.
@@ -229,6 +260,244 @@ interface TraceMcpHttpRequestInput {
  */
 declare function traceMcpHttpRequest(input: TraceMcpHttpRequestInput): Promise<Response>;
 
+/**
+ * Shared pay-request helpers.
+ *
+ * The V1 allowance sponsored payer (ADR-0010) is retired; only the
+ * rail-neutral request surface the SpendAccount payer depends on survives here:
+ * the `PayResult` shape every payer returns. `paidRequestInit` is the SDK helper
+ * that builds the one RequestInit replayed byte for byte on both calls.
+ */
+
+type PayResult = {
+    status: 'ok' | 'failed' | 'ambiguous';
+    /**
+     * `true` — settlement confirmed. `false` — money did not leave the
+     * account. `'unknown'` — execute/finality did not resolve; a retry can
+     * pay twice.
+     */
+    paid: boolean | 'unknown';
+    /** Whether money moved; always agrees with `paid`. */
+    paymentState?: PaymentState;
+    body?: unknown;
+    receipt?: unknown;
+    /** Registry code on a failed or ambiguous result. */
+    code?: string;
+    retryable?: boolean;
+    nextAction?: NextAction;
+    supportCode?: string;
+    detail?: string;
+    txDigest?: string;
+    paymentId?: string;
+    challengeId?: string;
+    httpStatus?: number;
+    responseClass?: 'unpaid_ok' | 'rejected' | 'unavailable';
+};
+
+/**
+ * SpendAccount PREPARE-only client (non-custodial MCP).
+ *
+ * The remote MCP `pay` tool runs inside the gateway, which holds NO key that can
+ * spend. So this module does not sign or submit: it PREPARES a payment and hands
+ * back an unsigned `spend_account::settle_policy` / `settle_any_recipient` transaction plus everything the client
+ * needs. The client — which holds the delegate key — sponsors, signs locally,
+ * and submits through the same personal-message challenge → local-sign → submit flow the
+ * REST/SDK delegate path uses. Only signatures ever reach the gateway; the
+ * private key is never placed in an HTTP body, a bearer, or any header.
+ *
+ * Flow: 402 Offer → request-binding → package/network SSOT →
+ * resolveGrantTarget(snapshot, offer.targetHash) (pause/revoke gate) → cap/coin
+ * checks → assertLive (fresh authority) → build unsigned kind bytes → return the
+ * signing request. There is deliberately no sponsor call, no decrypt, no
+ * signature, and no forwarded bearer here.
+ *
+ * See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
+ */
+
+type SharedObjectReader = (objectId: string) => Promise<{
+    owner?: unknown;
+} | null | undefined>;
+/**
+ * Read/prepare-only session for the non-custodial MCP pay tool. It carries the
+ * immutable grant snapshot and an optional prepare-time live gate — and no key,
+ * by construction. There is no `decryptDelegateSeed` and no `sponsorAuthorization`.
+ */
+interface SpendAccountPrepareSession {
+    snapshot: GrantSnapshot;
+    /** SpendAccount package id (V2). */
+    packageId: string;
+    /**
+     * Re-assert the grant is still live (not paused/revoked/expired) against fresh
+     * canonical state, invoked immediately before a signing request is handed back.
+     * Throw to abort. Optional; when absent, only the request-time snapshot gates
+     * the prepare (on-chain `spend_account::settle_policy` remains the final backstop for any
+     * spend the client later submits).
+     */
+    assertLive?: () => Promise<void>;
+}
+interface SpendAccountPayDeps {
+    fetchImpl?: typeof fetch;
+    /**
+     * Build only-transaction-kind bytes for the canonical guarded debit
+     * (`spend_account::settle_policy` / `settle_any_recipient`).
+     *
+     * The guarded-settle fields ({@link GuardedSettleFields}) are required on the
+     * fresh lineage: every delegate settle consumes the shared exclusion marker.
+     * Dropping them fails closed rather than building an unguarded call that no
+     * longer exists on chain.
+     */
+    buildPayKind?: (input: {
+        delegate: string;
+        coinType: string;
+        poolObjectId: string;
+        grantObjectId: string;
+        policyId: number | string;
+        targetHash: string;
+        amount: string;
+        paymentIdHash: Uint8Array;
+        termsHash: Uint8Array;
+        recipient?: string;
+        accessMode?: 'scoped' | 'open';
+    } & GuardedSettleFields) => Promise<{
+        kindBytes: string;
+    }>;
+    /**
+     * Resolve the per-recipient `RecipientRegistry` bound in the offer's exclusion
+     * directory (guarded offers only). Injected seam for tests; production
+     * leaves it unset and the prepare wires a live gRPC-backed resolver from the
+     * configured `ExclusionDirectory` id when present, else fails closed.
+     */
+    resolveExclusionRegistry?: PayOperationDeps['resolveExclusionRegistry'];
+    /**
+     * Read a shared object's owner so prepare binds the real initial version.
+     * Missing owner fails the prepare; version 1 is not a substitute.
+     */
+    readSharedObject?: SharedObjectReader;
+    /**
+     * Live trace for this prepare. Purely observational: emission records what the
+     * canonical read decisions already returned — an event is written after a check
+     * passes and can never be the thing that lets the next step run.
+     */
+    trace?: SpendAccountPayTrace;
+}
+interface SpendAccountPayTrace {
+    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;
+}
+/** The unsigned payment the client signs locally and submits. */
+interface SpendAccountSigningRequest {
+    /**
+     * Unsigned `spend_account::settle_policy` / `settle_any_recipient` transaction-kind bytes (base64), sender set to
+     * `delegateAddress`. The client sponsors these for gas, signs with the delegate
+     * key, and submits — the gateway never receives the key.
+     */
+    unsignedKindBytes: string;
+    delegateAddress: string;
+    packageId: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    /** On-chain policy id the pay is bound to. */
+    policyId: number | string;
+    coinType: string;
+    targetHash: string;
+    amount: string;
+    /** Hex (no 0x) of the payment-id hash bound into the transaction. */
+    paymentIdHashHex: string;
+    /** Hex (no 0x) of the terms hash bound into the transaction. */
+    termsHashHex: string;
+    challengeId: string;
+    /** The exact paid request to replay after the client submits. */
+    resource: {
+        url: string;
+        method: string;
+    };
+    dialect: Dialect;
+    /** Recipient the agent requested (offer.payTo). */
+    recipient: string;
+    /** Where the client (holding the key) sponsors and submits. */
+    submit: {
+        sponsorUrl: string;
+        executeUrl: string;
+        moveCallTarget: string;
+    };
+    /**
+     * ISO-8601 timestamp when this prepared operation expires. After this time the
+     * unsigned bytes are no longer valid and the client must re-call pay() for a
+     * fresh prepare. Derived from the offer TTL.
+     */
+    expiresAt: string;
+    /** Restated hard rule for the agent host. */
+    note: string;
+}
+interface PreparedPayment {
+    status: 'prepared';
+    paid: false;
+    signingRequest: SpendAccountSigningRequest;
+}
+/** Prepared signing request, or a canonical failure (never a spend). */
+type SpendAccountPrepareResult = PreparedPayment | PayResult;
+/** Default kind builder (no chain client — pure PTB). */
+declare function buildSpendAccountPayKind(input: {
+    packageId: string;
+    delegate: string;
+    coinType: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    policyId: number | string;
+    targetHash: string;
+    amount: string;
+    paymentIdHash: Uint8Array;
+    termsHash: Uint8Array;
+    poolInitialSharedVersion?: string;
+    grantInitialSharedVersion?: string;
+    clockInitialSharedVersion?: string;
+} & GuardedSettleFields): Promise<{
+    kindBytes: string;
+}>;
+/**
+ * Refuse blind signing: a client validating a sponsored transaction must be able
+ * to prove the sponsored bytes reconstruct the intended spend_account::settle_policy. Kept
+ * here (and exported) so both the client signer and its tests share one check.
+ */
+declare function verifySpendAccountPayReconstructs(bytes: string, expected: {
+    kindBytes: string;
+    packageId: string;
+    delegate: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    amount: string;
+}): void;
+/**
+ * Prepare a delegate payment WITHOUT signing. Reads the 402 offer, binds it,
+ * gates on the immutable grant snapshot + a fresh authority check, builds the
+ * unsigned transaction, and returns a signing request. The client holding the
+ * delegate key signs locally and submits. This function never decrypts, signs,
+ * sponsors, or submits.
+ *
+ * Uses `resolvePayment` from the SDK pay-operation module for the
+ * shared offer-acquisition + authority-resolution pipeline (steps 1–5 + assertLive
+ * + hash derivation + buildPayKind). This module wraps that with MCP-specific
+ * concerns: trace events, dialect-mode ceiling check, and signing-request
+ * construction.
+ */
+declare function prepareSpendAccountPayment(args: {
+    url: string;
+    /** The one normalized paid request, replayed byte for byte after signing. */
+    request?: PaidHttpRequest;
+    session: SpendAccountPrepareSession;
+    cfg: McpConfig;
+    deps?: SpendAccountPayDeps;
+    /** Preferred dialect when the 402 advertises both (default mpp). */
+    preferredDialect?: Dialect;
+}): Promise<SpendAccountPrepareResult>;
+
 /**
  * Transport-neutral SuiPay MCP server + tool registry.
  * Used by stdio (index.ts) and Streamable HTTP (http.ts).
@@ -262,6 +531,14 @@ declare const TOOLS: readonly [{
                 readonly type: "object";
                 readonly description: "JSON request body for a POST. Sent as application/json and bound to the payment.";
             };
+            readonly file: {
+                readonly type: "string";
+                readonly description: "Absolute path under SUIPAY_MCP_FILE_ROOT (unset disables attach). Stdio POST only; requires fileField. Regular non-empty file whose decoded size fits the paid-body ceiling. Not a URL, FIFO, device, or path under ~/.suipay. Bytes fill json[fileField] as canonical base64.";
+            };
+            readonly fileField: {
+                readonly type: "string";
+                readonly description: "JSON key to set from file (e.g. contentBase64). Required with file. Pattern [A-Za-z][A-Za-z0-9_]{0,63}. Must not already be present on json.";
+            };
             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.";
@@ -275,7 +552,7 @@ declare const TOOLS: readonly [{
     };
 }, {
     readonly name: "discover";
-    readonly description: "Search SuiPay gateway resources.";
+    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: {
@@ -299,7 +576,7 @@ declare const TOOLS: readonly [{
     };
 }, {
     readonly name: "suipay_login";
-    readonly description: "Mint or reuse the local delegate key (version-2, mode 0600) and open the console with the public address only so the owner can bind a spend-account grant. Stdio only; hosted /mcp never holds a spendable key.";
+    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: {
@@ -307,6 +584,11 @@ declare const TOOLS: readonly [{
                 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.";
@@ -345,6 +627,13 @@ interface McpServerOptions {
      * does not already authorize.
      */
     resolveAgentHeld?: AgentHeldResolver;
+    /** Override the exclusion-registry resolver (tests / offline). */
+    resolveExclusionRegistry?: SpendAccountPayDeps['resolveExclusionRegistry'];
+    /**
+     * Wire that created this server. Hosted HTTP never forwards `file` into `pay`.
+     * Stdio is the default so existing tests stay local.
+     */
+    transport?: 'stdio' | 'http';
 }
 declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceHooks, options?: McpServerOptions): Server;
 
@@ -364,4 +653,4 @@ declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: Mcp
  */
 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, type McpEnvelope as d, type McpEnvelopeEntry as e, type McpServerOptions as f, type McpTraceContext as g, type McpTraceRuntime as h, canonicalMcpRequestId as i, createServer as j, handleSuipayMcpHttpRequest as k, inspectMcpEnvelope as l, loadMcpConfig as m, resolveAgentHeldSettlement as n, resetAgentHeldProcessLedger as r, traceMcpHttpRequest as t };
+export { type AgentHeldResolver as A, traceMcpHttpRequest as B, verifySpendAccountPayReconstructs as C, type McpConfig as M, PACKAGE_NAME as P, type SpendAccountSigningRequest as S, TOOLS as T, type McpAuthContext as a, type McpTraceHooks as b, type SpendAccountPayDeps as c, type AgentHeldSettlement as d, MCP_TARGET_PRESETS as e, type McpEnvelope as f, type McpEnvelopeEntry as g, type McpServerOptions as h, type McpTarget as i, type McpTraceContext as j, type McpTraceRuntime as k, type PreparedPayment as l, type SpendAccountPrepareResult as m, type SpendAccountPrepareSession as n, buildSpendAccountPayKind as o, canonicalMcpRequestId as p, createServer as q, handleSuipayMcpHttpRequest as r, inspectMcpEnvelope as s, loadMcpConfig as t, parseMcpTargetFlag as u, prepareSpendAccountPayment as v, resetAgentHeldProcessLedger as w, resolveAgentHeldSettlement as x, resolveMcpTarget as y, sameMcpGateway as z };

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-export { k as handleSuipayMcpHttpRequest } from './http-C8xW9F1c.js';
+export { r as handleSuipayMcpHttpRequest } from './http-DvnvTrb3.js';
 import '@cmdoss/suipay-core/policy/grant-target';
 import '@cmdoss/suipay-sdk/mcp/access-context';
 import '@cmdoss/suipay-sdk/buyer/settlement-dto';
@@ -6,3 +6,7 @@ import '@modelcontextprotocol/sdk/server/index.js';
 import '@cmdoss/suipay-sdk/agent-sdk/reads';
 import '@cmdoss/suipay-sdk/delegated-signer/payer';
 import '@cmdoss/suipay-core/trace/types';
+import '@cmdoss/suipay-sdk/protocol/paid-http-request';
+import '@cmdoss/suipay-sdk/protocol/types';
+import '@cmdoss/suipay-sdk/pay-operation';
+import '@cmdoss/suipay-core/errors';

package/dist/http.js

@@ -1,6 +1,6 @@
 import {
   handleSuipayMcpHttpRequest
-} from "./chunk-KDOGSB5I.js";
+} from "./chunk-YMOMYFKL.js";
 export {
   handleSuipayMcpHttpRequest
 };