@paybond/kit 0.9.7 → 0.10.0

package/dist/mcp-server.js

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
-// @ts-ignore Node builtins are available in the published CLI runtime.
+import { Buffer } from "node:buffer";
 import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runCli } from "./cli/router.js";
+import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, toolAllowedByPolicy, } from "./cli/mcp-policy.js";
 import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.9.7";
+const SERVER_VERSION = "0.10.0";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
@@ -14,7 +19,10 @@ const TOOL_SELECTION_METADATA = {
         title: "Get Paybond Principal",
         annotations: readOnlyToolAnnotations("Get Paybond Principal"),
         outputSchema: outputObjectSchema({
-            tenant_id: { type: "string", description: "Tenant bound to the configured Paybond API key." },
+            tenant_id: {
+                type: "string",
+                description: "Tenant bound to the configured Paybond API key.",
+            },
             subject: { type: "string" },
             roles: { type: "array", items: { type: "string" } },
         }),
@@ -25,10 +33,22 @@ const TOOL_SELECTION_METADATA = {
             "Do not use this to create, fund, or modify intents; use paybond_authorize_agent_spend as the clearer gate before side-effecting agent tools.",
         annotations: additiveMutationToolAnnotations("Verify Paybond Capability"),
         outputSchema: outputObjectSchema({
-            allow: { type: "boolean", description: "Whether the requested operation is allowed." },
-            tenant: { type: "string", description: "Tenant echoed by the gateway." },
-            intent_id: { type: "string", description: "Verified Harbor intent UUID." },
-            audit_id: { type: "string", description: "Gateway audit identifier when available." },
+            allow: {
+                type: "boolean",
+                description: "Whether the requested operation is allowed.",
+            },
+            tenant: {
+                type: "string",
+                description: "Tenant echoed by the gateway.",
+            },
+            intent_id: {
+                type: "string",
+                description: "Verified Harbor intent UUID.",
+            },
+            audit_id: {
+                type: "string",
+                description: "Gateway audit identifier when available.",
+            },
         }, ["tenant", "intent_id"]),
     },
     paybond_authorize_agent_spend: {
@@ -37,10 +57,22 @@ const TOOL_SELECTION_METADATA = {
             "Do not use this for creating, funding, or changing intents; call paybond_create_spend_intent or paybond_fund_intent first when no funded capability token exists.",
         annotations: additiveMutationToolAnnotations("Authorize Agent Spend"),
         outputSchema: outputObjectSchema({
-            allow: { type: "boolean", description: "Whether the requested operation is allowed." },
-            tenant: { type: "string", description: "Tenant echoed by the gateway." },
-            intent_id: { type: "string", description: "Verified Harbor intent UUID." },
-            audit_id: { type: "string", description: "Gateway audit identifier when available." },
+            allow: {
+                type: "boolean",
+                description: "Whether the requested operation is allowed.",
+            },
+            tenant: {
+                type: "string",
+                description: "Tenant echoed by the gateway.",
+            },
+            intent_id: {
+                type: "string",
+                description: "Verified Harbor intent UUID.",
+            },
+            audit_id: {
+                type: "string",
+                description: "Gateway audit identifier when available.",
+            },
         }, ["tenant", "intent_id"]),
     },
     paybond_bootstrap_sandbox_guardrail: {
@@ -57,7 +89,14 @@ const TOOL_SELECTION_METADATA = {
             sandbox_lifecycle_status: { type: "string" },
             settlement_rail: { type: "string" },
             settlement_mode: { type: "string" },
-        }, ["tenant_id", "intent_id", "capability_token", "operation", "requested_spend_cents", "sandbox_lifecycle_status"]),
+        }, [
+            "tenant_id",
+            "intent_id",
+            "capability_token",
+            "operation",
+            "requested_spend_cents",
+            "sandbox_lifecycle_status",
+        ]),
     },
     paybond_submit_sandbox_guardrail_evidence: {
         title: "Submit Sandbox Guardrail Evidence",
@@ -72,13 +111,22 @@ const TOOL_SELECTION_METADATA = {
             sandbox_lifecycle_status: { type: "string" },
             predicate_passed: { type: "boolean" },
             payload_digest: { type: "string" },
-        }, ["tenant_id", "intent_id", "operation", "requested_spend_cents", "sandbox_lifecycle_status"]),
+        }, [
+            "tenant_id",
+            "intent_id",
+            "operation",
+            "requested_spend_cents",
+            "sandbox_lifecycle_status",
+        ]),
     },
     paybond_list_intents: {
         title: "List Harbor Intents",
         annotations: readOnlyToolAnnotations("List Harbor Intents"),
         outputSchema: outputObjectSchema({
-            items: { type: "array", items: { type: "object", additionalProperties: true } },
+            items: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
             next_cursor: { type: "string" },
         }),
     },
@@ -106,7 +154,10 @@ const TOOL_SELECTION_METADATA = {
         outputSchema: outputObjectSchema({
             tenant_id: { type: "string" },
             score_model_version: { type: "string" },
-            operators: { type: "array", items: { type: "object", additionalProperties: true } },
+            operators: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
         }),
     },
     paybond_get_signed_portfolio_artifact: {
@@ -144,14 +195,20 @@ const TOOL_SELECTION_METADATA = {
         outputSchema: outputObjectSchema({
             name: { type: "string" },
             version: { type: "string" },
-            skills: { type: "array", items: { type: "object", additionalProperties: true } },
+            skills: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
         }),
     },
     paybond_list_a2a_task_contracts: {
         title: "List A2A Task Contracts",
         annotations: readOnlyToolAnnotations("List A2A Task Contracts"),
         outputSchema: outputObjectSchema({
-            contracts: { type: "array", items: { type: "object", additionalProperties: true } },
+            contracts: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
         }),
     },
     paybond_get_a2a_task_contract: {
@@ -327,8 +384,12 @@ function parseGatewayErrorEnvelope(text) {
         if (body === null || Array.isArray(body) || typeof body !== "object") {
             return {};
         }
-        const errorCode = typeof body.error === "string" && body.error.trim() ? body.error.trim() : undefined;
-        const errorMessage = typeof body.message === "string" && body.message.trim() ? body.message.trim() : undefined;
+        const errorCode = typeof body.error === "string" && body.error.trim()
+            ? body.error.trim()
+            : undefined;
+        const errorMessage = typeof body.message === "string" && body.message.trim()
+            ? body.message.trim()
+            : undefined;
         return { errorCode, errorMessage };
     }
     catch {
@@ -369,7 +430,9 @@ class GatewayAPIClient {
                         accept: "application/json",
                         authorization: `Bearer ${this.apiKey}`,
                         ...(extraHeaders ?? {}),
-                        ...(payload === undefined ? {} : { "content-type": "application/json" }),
+                        ...(payload === undefined
+                            ? {}
+                            : { "content-type": "application/json" }),
                     },
                     ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
                 });
@@ -382,7 +445,8 @@ class GatewayAPIClient {
                 await delay(backoffMs(attempt));
                 continue;
             }
-            if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < this.maxRetries) {
+            if ([429, 500, 502, 503, 504].includes(res.status) &&
+                attempt + 1 < this.maxRetries) {
                 const retryAfter = parseRetryAfterSeconds(res.headers.get("retry-after"));
                 await delay(retryAfter != null ? retryAfter * 1000 : backoffMs(attempt));
                 continue;
@@ -620,7 +684,9 @@ class PaybondMCPRuntime {
     async fundHarborIntent(init) {
         return this.gateway.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/fund`, {}, gatewayMutationHeaders(await this.tenantId(), init.recognitionProof, {
             ...optionalMutationHeaders(init.idempotencyKey),
-            ...(init.paymentSignature?.trim() ? { "payment-signature": init.paymentSignature.trim() } : {}),
+            ...(init.paymentSignature?.trim()
+                ? { "payment-signature": init.paymentSignature.trim() }
+                : {}),
         }));
     }
     async submitHarborEvidence(init) {
@@ -643,16 +709,22 @@ function gatewayMutationHeaders(tenantId, recognitionProof, extraHeaders) {
         [agentRecognitionProofHeader]: encodeRecognitionProofHeader(recognitionProof),
     };
 }
+export function formatMcpStdioFrame(response) {
+    const body = JSON.stringify(response);
+    return `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`;
+}
 export class PaybondMCPServer {
     runtime;
     tools;
+    toolPolicy;
     initialized = false;
     constructor(settings) {
         if (!settings.apiKey.trim()) {
             throw new Error("PAYBOND_API_KEY is required");
         }
+        this.toolPolicy = settings.toolPolicy ?? { policy: null, allowlist: [] };
         this.runtime = new PaybondMCPRuntime(settings);
-        this.tools = this.buildTools(settings);
+        this.tools = this.buildTools(settings).filter((tool) => toolAllowedByPolicy(tool.name, tool.annotations, this.toolPolicy));
     }
     listTools() {
         return this.tools.map((tool) => ({
@@ -660,8 +732,12 @@ export class PaybondMCPServer {
             title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
-            ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
-            ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+            ...(tool.outputSchema === undefined
+                ? {}
+                : { outputSchema: tool.outputSchema }),
+            ...(tool.annotations === undefined
+                ? {}
+                : { annotations: tool.annotations }),
         }));
     }
     async callTool(name, args = {}) {
@@ -672,6 +748,17 @@ export class PaybondMCPServer {
                 isError: true,
             };
         }
+        if (!toolAllowedByPolicy(name, tool.annotations, this.toolPolicy)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Tool blocked by ${MCP_TOOL_POLICY_ENV}=${this.toolPolicy.policy ?? "unset"}: ${name}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
         try {
             const value = await tool.call(args);
             return toToolResult(value);
@@ -740,7 +827,9 @@ export class PaybondMCPServer {
             case "tools/call": {
                 const params = ensureObject(message.params, "tools/call params");
                 const name = stringArg(params.name, "name");
-                const args = params.arguments === undefined ? {} : ensureObject(params.arguments, "arguments");
+                const args = params.arguments === undefined
+                    ? {}
+                    : ensureObject(params.arguments, "arguments");
                 return {
                     jsonrpc: "2.0",
                     id: message.id,
@@ -752,26 +841,36 @@ export class PaybondMCPServer {
         }
     }
     runStdio() {
-        let buffer = "";
-        process.stdin.setEncoding("utf8");
+        let buffer = Buffer.alloc(0);
         process.stdin.on("data", (chunk) => {
-            buffer += chunk;
+            buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8")]);
             while (true) {
-                const newlineIndex = buffer.indexOf("\n");
-                if (newlineIndex < 0) {
+                const headerEnd = buffer.indexOf("\r\n\r\n");
+                if (headerEnd < 0) {
                     break;
                 }
-                const line = buffer.slice(0, newlineIndex).trim();
-                buffer = buffer.slice(newlineIndex + 1);
-                if (!line) {
-                    continue;
+                const headerText = buffer.subarray(0, headerEnd).toString("ascii");
+                const contentLength = Number.parseInt(headerText
+                    .split("\r\n")
+                    .find((line) => line.toLowerCase().startsWith("content-length:"))
+                    ?.split(":", 2)[1]
+                    ?.trim() ?? "", 10);
+                if (!Number.isFinite(contentLength) || contentLength <= 0) {
+                    break;
                 }
-                void this.handleLine(line);
+                const bodyStart = headerEnd + 4;
+                const frameEnd = bodyStart + contentLength;
+                if (buffer.length < frameEnd) {
+                    break;
+                }
+                const body = buffer.subarray(bodyStart, frameEnd).toString("utf8");
+                buffer = buffer.subarray(frameEnd);
+                void this.handleLine(body);
             }
         });
         process.stdin.on("end", () => {
-            if (buffer.trim()) {
-                void this.handleLine(buffer.trim());
+            if (buffer.length > 0) {
+                void this.handleLine(buffer.toString("utf8"));
             }
         });
         process.stdin.resume();
@@ -791,7 +890,7 @@ export class PaybondMCPServer {
         }
     }
     writeResponse(response) {
-        process.stdout.write(`${JSON.stringify(response)}\n`);
+        process.stdout.write(formatMcpStdioFrame(response));
     }
     buildTools(settings) {
         const tools = [
@@ -805,12 +904,18 @@ export class PaybondMCPServer {
                 name: "paybond_verify_capability",
                 description: "Verify a capability token returned by a created or funded Paybond intent for one tenant-bound Harbor intent.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Canonical Harbor intent UUID.",
+                    },
                     token: {
                         type: "string",
                         description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
                     },
-                    operation: { type: "string", description: "Delegated operation or tool name." },
+                    operation: {
+                        type: "string",
+                        description: "Delegated operation or tool name.",
+                    },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Optional requested spend in cents for this tool call.",
@@ -829,12 +934,18 @@ export class PaybondMCPServer {
                 name: "paybond_authorize_agent_spend",
                 description: "Provider-agnostic spend gate: verify the funded intent's capability token before a side-effecting tool, paid API, vendor action, or settlement workflow executes.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Canonical Harbor intent UUID.",
+                    },
                     token: {
                         type: "string",
                         description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
                     },
-                    operation: { type: "string", description: "Delegated operation or tool name." },
+                    operation: {
+                        type: "string",
+                        description: "Delegated operation or tool name.",
+                    },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Optional requested spend in cents for this tool call.",
@@ -853,12 +964,18 @@ export class PaybondMCPServer {
                 name: "paybond_bootstrap_sandbox_guardrail",
                 description: "Bootstrap a sandbox-only Paybond guardrail intent for a first paid-tool integration. Tenant scope is derived from the configured service-account API key and the route never touches live settlement rails.",
                 inputSchema: objectSchema({
-                    operation: { type: "string", description: "Delegated operation or paid tool name." },
+                    operation: {
+                        type: "string",
+                        description: "Delegated operation or paid tool name.",
+                    },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Sandbox spend amount in cents to authorize for the sample tool call.",
                     },
-                    currency: { type: "string", description: "Optional ISO currency code; defaults at the gateway." },
+                    currency: {
+                        type: "string",
+                        description: "Optional ISO currency code; defaults at the gateway.",
+                    },
                     evidence_schema: { type: "object", additionalProperties: true },
                     metadata: { type: "object", additionalProperties: true },
                     idempotency_key: { type: "string" },
@@ -867,8 +984,12 @@ export class PaybondMCPServer {
                     operation: stringArg(args.operation, "operation"),
                     requestedSpendCents: intArg(args.requested_spend_cents, "requested_spend_cents"),
                     currency: optionalString(args.currency),
-                    evidenceSchema: args.evidence_schema === undefined ? undefined : ensureObject(args.evidence_schema, "evidence_schema"),
-                    metadata: args.metadata === undefined ? undefined : ensureObject(args.metadata, "metadata"),
+                    evidenceSchema: args.evidence_schema === undefined
+                        ? undefined
+                        : ensureObject(args.evidence_schema, "evidence_schema"),
+                    metadata: args.metadata === undefined
+                        ? undefined
+                        : ensureObject(args.metadata, "metadata"),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -876,10 +997,16 @@ export class PaybondMCPServer {
                 name: "paybond_submit_sandbox_guardrail_evidence",
                 description: "Submit evidence for a sandbox-only Paybond guardrail intent. Tenant scope is derived from the configured service-account API key and simulator settlement remains sandbox-only.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Sandbox guardrail intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Sandbox guardrail intent UUID.",
+                    },
                     payload: { type: "object", additionalProperties: true },
                     artifacts: { type: "array", items: { type: "string" } },
-                    operation: { type: "string", description: "Optional operation override for the evidence record." },
+                    operation: {
+                        type: "string",
+                        description: "Optional operation override for the evidence record.",
+                    },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Optional sandbox spend amount override for the evidence record.",
@@ -889,13 +1016,19 @@ export class PaybondMCPServer {
                 }, ["intent_id"]),
                 call: async (args) => this.runtime.submitSandboxGuardrailEvidence({
                     intentId: uuidArg(args.intent_id, "intent_id"),
-                    payload: args.payload === undefined ? undefined : ensureObject(args.payload, "payload"),
-                    artifacts: args.artifacts === undefined ? undefined : stringArrayArg(args.artifacts, "artifacts"),
+                    payload: args.payload === undefined
+                        ? undefined
+                        : ensureObject(args.payload, "payload"),
+                    artifacts: args.artifacts === undefined
+                        ? undefined
+                        : stringArrayArg(args.artifacts, "artifacts"),
                     operation: optionalString(args.operation),
                     requestedSpendCents: args.requested_spend_cents === undefined
                         ? undefined
                         : intArg(args.requested_spend_cents, "requested_spend_cents"),
-                    metadata: args.metadata === undefined ? undefined : ensureObject(args.metadata, "metadata"),
+                    metadata: args.metadata === undefined
+                        ? undefined
+                        : ensureObject(args.metadata, "metadata"),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -919,7 +1052,10 @@ export class PaybondMCPServer {
                 name: "paybond_get_intent",
                 description: "Fetch one tenant-scoped Harbor intent detail through the gateway operator view.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Canonical Harbor intent UUID.",
+                    },
                 }, ["intent_id"]),
                 call: async (args) => this.runtime.getIntent(uuidArg(args.intent_id, "intent_id")),
             },
@@ -1160,6 +1296,7 @@ export function settingsFromEnv(env = process.env) {
         maxRetries: optionalEnv(env.PAYBOND_MCP_MAX_RETRIES)
             ? intArg(optionalEnv(env.PAYBOND_MCP_MAX_RETRIES), "PAYBOND_MCP_MAX_RETRIES")
             : 3,
+        toolPolicy: mergeMcpToolPolicy(parseMcpToolPolicy(optionalEnv(env[MCP_TOOL_POLICY_ENV])), parseMcpToolAllowlist(optionalEnv(env[MCP_TOOL_ALLOWLIST_ENV]))),
     };
 }
 export function main(argv = process.argv.slice(2)) {
@@ -1314,18 +1451,6 @@ function toToolResult(value) {
         structuredContent: value,
     };
 }
-function jsonObjectFromValue(value) {
-    if (value === null) {
-        return {};
-    }
-    if (Array.isArray(value)) {
-        return { items: value };
-    }
-    if (typeof value !== "object") {
-        return { value };
-    }
-    return JSON.parse(JSON.stringify(value));
-}
 function responseError(id, code, message) {
     return {
         jsonrpc: "2.0",
@@ -1365,19 +1490,15 @@ function formatError(err) {
     return String(err);
 }
 function normalizeFileURL(url) {
-    return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
+    return url.startsWith("file:///var/")
+        ? url.replace("file:///var/", "file:///private/var/")
+        : url;
 }
 async function invokedFromCLI() {
     const scriptPath = process.argv[1];
     if (!scriptPath) {
         return false;
     }
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const fs = (await import("node:fs/promises"));
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const path = (await import("node:path"));
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const url = (await import("node:url"));
     async function realFileURL(filePath) {
         let resolved = path.resolve(filePath);
         try {
@@ -1387,14 +1508,21 @@ async function invokedFromCLI() {
             // If realpath fails, compare the absolute path. This keeps direct execution
             // working even when the script path disappears during process startup.
         }
-        return normalizeFileURL(url.pathToFileURL(resolved).href);
+        return normalizeFileURL(pathToFileURL(resolved).href);
     }
-    return (await realFileURL(scriptPath)) === (await realFileURL(url.fileURLToPath(import.meta.url)));
+    return ((await realFileURL(scriptPath)) ===
+        (await realFileURL(fileURLToPath(import.meta.url))));
 }
 invokedFromCLI().then((invoked) => {
-    if (invoked && main() !== 0) {
-        process.exitCode = 1;
+    if (!invoked) {
+        return;
     }
+    runCli(["mcp", "serve", ...process.argv.slice(2)]).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        process.stderr.write(`${formatError(err)}\n`);
+        process.exitCode = 1;
+    });
 }, (err) => {
     process.stderr.write(`${formatError(err)}\n`);
     process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "mcpName": "io.github.nonameuserd/paybond",
   "description": "Paybond Kit for TypeScript: agent spend governance for paid tool calls with spend authorization, evidence receipts, refunds, disputes, hosted Gateway sessions, and settlement.",
   "license": "Apache-2.0",
@@ -8,7 +8,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "paybond": "dist/login.js",
+    "paybond": "dist/cli.js",
+    "paybond-kit-login": "dist/login.js",
     "paybond-init": "dist/init.js",
     "paybond-mcp-server": "dist/mcp-server.js"
   },
@@ -77,6 +78,7 @@
   "scripts": {
     "clean": "node ./scripts/clean-dist.mjs",
     "build": "npm run clean && tsc -p tsconfig.json",
+    "generate:cli-contract": "node ../cli-parity/generate.mjs",
     "test": "vitest run",
     "pack:dry-run": "npm pack --dry-run",
     "verify:release": "node ./scripts/verify-release.mjs",
@@ -88,6 +90,7 @@
     "uuid": "^14.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.8"
   }