@paybond/kit 0.9.8 → 0.10.0

package/dist/cli/help.js

@@ -0,0 +1,51 @@
+// Generated by kit/cli-parity/generate.mjs — do not edit by hand.
+export const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init guardrail          Scaffold a sandbox paid-tool guardrail integration file\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
+export const COMMAND_HELP = {
+    "onboarding": "Usage: paybond onboarding [--host claude|codex|openai|generic]\n\nRuns a guided, non-destructive first-run workflow: runtime check, login status, guardrail file status, MCP config preview, and doctor.\n\nExamples:\n  $ paybond onboarding\n  $ paybond onboarding --host claude --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond login",
+    "help": "Usage: paybond help [<command> [<subcommand> ...]]\n\nShows detailed help for a command path. Without arguments, prints root help.\n\nExamples:\n  $ paybond help\n  $ paybond help login\n  $ paybond help mcp install",
+    "examples": "Usage: paybond examples [<command> [<subcommand> ...]]\n\nLists copy-paste examples from the command spec. Filter with an optional command path.\n\nExamples:\n  $ paybond examples\n  $ paybond examples doctor",
+    "completion": "Usage: paybond completion bash|zsh|fish\n\nPrints a shell completion script generated from the command spec. Pipe to your shell config.\n\nExamples:\n  $ paybond completion bash >> ~/.bashrc\n  $ paybond completion zsh >> ~/.zshrc\n  $ paybond completion fish | source",
+    "login": "Usage: paybond login [--env sandbox] [--env-file .env.local] [--gateway <url>] [--no-open] [--force]\n\nStarts sandbox device login and writes PAYBOND_API_KEY to the env file.\n\nExamples:\n  $ paybond login\n  $ paybond login --no-open --format json\n\nDocs: https://docs.paybond.ai/kit/authentication\n\nNext: paybond doctor",
+    "init guardrail": "Usage: paybond init guardrail [--preset paid-tool-guard] [--framework <name>] [--out <path>] [--force]\n\nScaffolds a sandbox paid-tool guardrail integration file.\n\nExamples:\n  $ paybond init guardrail\n  $ paybond init guardrail --framework openai --out guard.ts\n\nDocs: https://docs.paybond.ai/kit/index\n\nNext: paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100",
+    "mcp serve": "Usage: paybond mcp serve\n\nRuns the stdio MCP server until the host process exits. Diagnostics print to stderr; stdout is reserved for MCP JSON-RPC.\n\nExamples:\n  $ paybond mcp serve",
+    "mcp install": "Usage: paybond mcp install --host claude|codex|openai|generic [--scope local|project|user] [--format json|toml] [--out <path>] [--env-file <path>] [--tool-policy readonly|spend-write|allowlist] [--tool-allowlist <names>]\n\nWrites a stdio MCP server entry that references PAYBOND_ENV_FILE (never raw API keys).\nDefault format is TOML for codex and JSON for other hosts. --scope local prints without writing.\nOptional --tool-policy controls which Paybond MCP tools the server exposes.\n\nExamples:\n  $ paybond mcp install --host claude\n  $ paybond mcp install --host generic --scope project --tool-policy readonly\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond mcp verify-config --host claude",
+    "mcp verify-config": "Usage: paybond mcp verify-config --host claude|codex|openai|generic [--format json|toml] [--env-file <path>] [--config <path>]\n\nValidates a generated or on-disk MCP host config without launching the MCP server.\n\nExamples:\n  $ paybond mcp verify-config --host claude\n  $ paybond mcp verify-config --host generic --config .paybond/mcp.json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond doctor --agent",
+    "mcp tools": "Usage: paybond mcp tools\n\nLists tools exposed by the local MCP server.\n\nExamples:\n  $ paybond mcp tools",
+    "doctor": "Usage: paybond doctor [--agent] [--host claude|codex|openai|generic]\n\nValidates runtime, package version, env file, key shape, principal lookup, and with --agent deep MCP checks (host config, env resolution, launch, initialize, tools/list, schema validation, stdout purity).\n\nExamples:\n  $ paybond doctor\n  $ paybond doctor --agent --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond mcp install --host claude --scope local",
+    "version": "Usage: paybond version [--verbose]\n\nPrints the installed Kit package version. With --verbose, includes runtime, platform, config paths, gateway URL, request ID, MCP tool count, and redacted credential source.\n\nExamples:\n  $ paybond version\n  $ paybond version --verbose --format json\n\nDocs: https://docs.paybond.ai/kit/package-provenance",
+    "diagnose": "Usage: paybond diagnose --redacted\n\nEmits a redacted support bundle for troubleshooting. Never prints raw API keys.\n\nExamples:\n  $ paybond diagnose --redacted\n  $ paybond diagnose --redacted --format json\n\nDocs: https://docs.paybond.ai/kit/package-provenance",
+    "config get": "Usage: paybond config get <key>\n\nExamples:\n  $ paybond config get gateway",
+    "config set": "Usage: paybond config set <key> <value>\n\nExamples:\n  $ paybond config set gateway https://api.paybond.ai",
+    "config unset": "Usage: paybond config unset <key>\n\nExamples:\n  $ paybond config unset gateway",
+    "config list": "Usage: paybond config list\n\nExamples:\n  $ paybond config list --format json",
+    "whoami": "Usage: paybond whoami\n\nResolves the authenticated principal and tenant realm.\n\nExamples:\n  $ paybond whoami\n  $ paybond whoami --format json",
+    "keys list": "Usage: paybond keys list\n\nExamples:\n  $ paybond keys list --format json",
+    "keys create": "Usage: paybond keys create --name <service-account> --role <role> [--label <label>]\n\nExamples:\n  $ paybond keys create --name ci-bot --role operator",
+    "keys rotate": "Usage: paybond keys rotate <key_id> [--yes]\n\nExamples:\n  $ paybond keys rotate key-123 --yes",
+    "keys revoke": "Usage: paybond keys revoke <key_id> [--yes]\n\nExamples:\n  $ paybond keys revoke key-123 --yes",
+    "intents list": "Usage: paybond intents list [--status <status>] [--limit <n>]\n\nExamples:\n  $ paybond intents list --limit 10",
+    "intents get": "Usage: paybond intents get <intent_id>\n\nExamples:\n  $ paybond intents get intent-123",
+    "intents create": "Usage: paybond intents create --body <json-file>\n\nExamples:\n  $ paybond intents create --body intent.json",
+    "intents fund": "Usage: paybond intents fund <intent_id> [--body <json-file>]\n\nExamples:\n  $ paybond intents fund intent-123",
+    "intents evidence": "Usage: paybond intents evidence <intent_id> --body <json-file>\n\nExamples:\n  $ paybond intents evidence intent-123 --body evidence.json",
+    "intents settlement-confirm": "Usage: paybond intents settlement-confirm <intent_id> [--body <json-file>]\n\nExamples:\n  $ paybond intents settlement-confirm intent-123",
+    "guardrails bootstrap": "Usage: paybond guardrails bootstrap --operation <name> --requested-spend-cents <n>\n\nExamples:\n  $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100",
+    "guardrails evidence": "Usage: paybond guardrails evidence --intent-id <id> --body <json-file>\n\nExamples:\n  $ paybond guardrails evidence --intent-id intent-123 --body evidence.json",
+    "spend authorize": "Usage: paybond spend authorize --intent-id <id> --token <capability> --operation <name> [--requested-spend-cents <n>]\n\nExamples:\n  $ paybond spend authorize --intent-id intent-123 --token cap --operation paid-tool",
+    "signal reputation": "Usage: paybond signal reputation --did <did>\n\nExamples:\n  $ paybond signal reputation --did did:example:alice",
+    "signal portfolio": "Usage: paybond signal portfolio\n\nExamples:\n  $ paybond signal portfolio",
+    "signal fraud": "Usage: paybond signal fraud --did <did>\n\nExamples:\n  $ paybond signal fraud --did did:example:alice",
+    "receipts get": "Usage: paybond receipts get <receipt_id>\n\nExamples:\n  $ paybond receipts get receipt-123",
+    "receipts verify": "Usage: paybond receipts verify <receipt_id>\n\nExamples:\n  $ paybond receipts verify receipt-123",
+    "mandates verify": "Usage: paybond mandates verify --body <json-file>\n\nExamples:\n  $ paybond mandates verify --body mandate.json",
+    "mandates import": "Usage: paybond mandates import --body <json-file>\n\nExamples:\n  $ paybond mandates import --body mandate.json",
+    "a2a card": "Usage: paybond a2a card\n\nExamples:\n  $ paybond a2a card",
+    "a2a contracts": "Usage: paybond a2a contracts [--contract-id <id>]\n\nExamples:\n  $ paybond a2a contracts",
+    "audit exports list": "Usage: paybond audit exports list\n\nExamples:\n  $ paybond audit exports list --format json",
+    "audit exports get": "Usage: paybond audit exports get <job_id> [--issue-download]\n\nExamples:\n  $ paybond audit exports get job-123",
+    "audit exports verify": "Usage: paybond audit exports verify <path>\n\nExamples:\n  $ paybond audit exports verify ./bundle",
+    "audit exports delete": "Usage: paybond audit exports delete <job_id> [--yes]\n\nExamples:\n  $ paybond audit exports delete job-123 --yes",
+};
+export function helpForCommand(path) {
+    return COMMAND_HELP[path] ?? ROOT_HELP;
+}

package/dist/cli/mcp-install.d.ts

@@ -0,0 +1,41 @@
+import { type McpToolPolicyConfig } from "./mcp-policy.js";
+export type McpInstallFormat = "json" | "toml";
+export type McpInstallScope = "local" | "project" | "user";
+export type McpInstallHost = "claude" | "codex" | "openai" | "generic";
+export declare const MCP_INSTALL_HOSTS: readonly McpInstallHost[];
+export type McpServerEntry = {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+};
+export type McpInstallPlan = {
+    host: string;
+    scope: McpInstallScope;
+    format: McpInstallFormat;
+    envFile: string;
+    configPath: string | null;
+    serverCommand: string[];
+    payload: string;
+    printed: boolean;
+    toolPolicy?: McpToolPolicyConfig | null;
+};
+export declare function resolvePackageLocalMcpServerCommand(): string[];
+export declare function defaultMcpServerCommand(): string[];
+export declare function buildMcpServerEntry(envFile: string, serverCommand: string[], toolPolicy?: McpToolPolicyConfig | null): McpServerEntry;
+export declare function serializeMcpInstallPayload(format: McpInstallFormat, entry: McpServerEntry): string;
+export declare function resolveMcpInstallPath(scope: McpInstallScope, format: McpInstallFormat, out: string | undefined, cwd: string, home: string): string | null;
+export declare function defaultMcpInstallFormat(host: McpInstallHost): McpInstallFormat;
+export declare function planMcpInstall(input: {
+    host: McpInstallHost;
+    scope: McpInstallScope;
+    format: McpInstallFormat;
+    envFile: string;
+    out?: string;
+    cwd: string;
+    home: string;
+    serverCommand?: string[];
+    toolPolicy?: McpToolPolicyConfig | null;
+}): McpInstallPlan;
+export declare function parseMcpInstallHost(raw: string | undefined): McpInstallHost;
+export declare function parseMcpInstallFormat(raw: string | undefined, host: McpInstallHost): McpInstallFormat;
+export declare function parseMcpInstallScope(raw: string | undefined): McpInstallScope;

package/dist/cli/mcp-install.js

@@ -0,0 +1,95 @@
+import { fileURLToPath } from "node:url";
+import { mcpToolPolicyEnv } from "./mcp-policy.js";
+export const MCP_INSTALL_HOSTS = ["claude", "codex", "openai", "generic"];
+export function resolvePackageLocalMcpServerCommand() {
+    const mcpServerJs = fileURLToPath(new URL("../mcp-server.js", import.meta.url));
+    return [process.execPath, mcpServerJs];
+}
+export function defaultMcpServerCommand() {
+    return resolvePackageLocalMcpServerCommand();
+}
+export function buildMcpServerEntry(envFile, serverCommand, toolPolicy) {
+    return {
+        command: serverCommand[0],
+        args: serverCommand.slice(1),
+        env: { PAYBOND_ENV_FILE: envFile, ...mcpToolPolicyEnv(toolPolicy ?? { policy: null, allowlist: [] }) },
+    };
+}
+export function serializeMcpInstallPayload(format, entry) {
+    if (format === "toml") {
+        const argsJson = JSON.stringify(entry.args);
+        return [
+            "# Paybond MCP stdio server — merge into your host MCP config",
+            "[mcp_servers.paybond]",
+            `command = ${JSON.stringify(entry.command)}`,
+            `args = ${argsJson}`,
+            "",
+            "[mcp_servers.paybond.env]",
+            ...Object.entries(entry.env).map(([key, value]) => `${key} = ${JSON.stringify(value)}`),
+            "",
+        ].join("\n");
+    }
+    return `${JSON.stringify({
+        mcpServers: {
+            paybond: entry,
+        },
+    }, null, 2)}\n`;
+}
+export function resolveMcpInstallPath(scope, format, out, cwd, home) {
+    if (out?.trim()) {
+        return out.trim();
+    }
+    if (scope === "local") {
+        return null;
+    }
+    const ext = format === "toml" ? "toml" : "json";
+    const base = scope === "user" ? home : cwd;
+    return `${base.replace(/\/+$/, "")}/.paybond/mcp.${ext}`;
+}
+export function defaultMcpInstallFormat(host) {
+    return host === "codex" ? "toml" : "json";
+}
+export function planMcpInstall(input) {
+    const serverCommand = input.serverCommand ?? defaultMcpServerCommand();
+    const entry = buildMcpServerEntry(input.envFile, serverCommand, input.toolPolicy);
+    const payload = serializeMcpInstallPayload(input.format, entry);
+    const configPath = resolveMcpInstallPath(input.scope, input.format, input.out, input.cwd, input.home);
+    return {
+        host: input.host,
+        scope: input.scope,
+        format: input.format,
+        envFile: input.envFile,
+        configPath,
+        serverCommand,
+        payload,
+        printed: configPath === null,
+        toolPolicy: input.toolPolicy ?? null,
+    };
+}
+export function parseMcpInstallHost(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (!value) {
+        throw new Error("missing --host (expected claude|codex|openai|generic)");
+    }
+    if (MCP_INSTALL_HOSTS.includes(value)) {
+        return value;
+    }
+    throw new Error("invalid --host (expected claude|codex|openai|generic)");
+}
+export function parseMcpInstallFormat(raw, host) {
+    if (!raw?.trim()) {
+        return defaultMcpInstallFormat(host);
+    }
+    const value = raw.trim().toLowerCase();
+    if (value === "json" || value === "toml") {
+        return value;
+    }
+    throw new Error("invalid --format (expected json|toml)");
+}
+export function parseMcpInstallScope(raw) {
+    const value = (raw ?? "project").trim().toLowerCase();
+    if (value === "local" || value === "project" || value === "user") {
+        return value;
+    }
+    throw new Error("invalid --scope (expected local|project|user)");
+}

package/dist/cli/mcp-policy.d.ts

@@ -0,0 +1,23 @@
+export type McpToolPolicy = "readonly" | "spend-write" | "allowlist";
+export declare const MCP_TOOL_POLICY_ENV = "PAYBOND_MCP_TOOL_POLICY";
+export declare const MCP_TOOL_ALLOWLIST_ENV = "PAYBOND_MCP_TOOL_ALLOWLIST";
+export declare const LIVE_MONEY_TOOL_NAMES: Set<string>;
+export type McpToolPolicyConfig = {
+    policy: McpToolPolicy | null;
+    allowlist: readonly string[];
+};
+export type McpToolAnnotations = {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+};
+export declare function parseMcpToolPolicy(raw: string | undefined): McpToolPolicyConfig;
+export declare function parseMcpToolAllowlist(raw: string | undefined): string[];
+export declare function mergeMcpToolPolicy(policy: McpToolPolicyConfig, allowlist?: readonly string[]): McpToolPolicyConfig;
+export declare function mcpToolPolicyEnv(config: McpToolPolicyConfig): Record<string, string>;
+export declare function toolAnnotationsFlags(annotations: McpToolAnnotations | undefined): {
+    readOnly: boolean;
+    destructive: boolean;
+};
+export declare function toolAllowedByPolicy(name: string, annotations: McpToolAnnotations | undefined, config: McpToolPolicyConfig): boolean;
+export declare function validateMcpToolSchema(tool: Record<string, unknown>): string[];
+export declare function isLiveMoneyTool(name: string, annotations: McpToolAnnotations | undefined): boolean;

package/dist/cli/mcp-policy.js

@@ -0,0 +1,104 @@
+export const MCP_TOOL_POLICY_ENV = "PAYBOND_MCP_TOOL_POLICY";
+export const MCP_TOOL_ALLOWLIST_ENV = "PAYBOND_MCP_TOOL_ALLOWLIST";
+export const LIVE_MONEY_TOOL_NAMES = new Set([
+    "paybond_fund_intent",
+    "paybond_confirm_settlement",
+]);
+export function parseMcpToolPolicy(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (!value) {
+        return { policy: null, allowlist: [] };
+    }
+    if (value === "readonly" || value === "spend-write" || value === "allowlist") {
+        return { policy: value, allowlist: [] };
+    }
+    throw new Error("invalid --tool-policy (expected readonly|spend-write|allowlist)");
+}
+export function parseMcpToolAllowlist(raw) {
+    if (!raw?.trim()) {
+        return [];
+    }
+    const items = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (items.length === 0) {
+        throw new Error("invalid --tool-allowlist (expected comma-separated tool names)");
+    }
+    return items;
+}
+export function mergeMcpToolPolicy(policy, allowlist) {
+    const mergedAllowlist = allowlist ?? policy.allowlist;
+    if (policy.policy === "allowlist" && mergedAllowlist.length === 0) {
+        throw new Error("--tool-allowlist is required when --tool-policy allowlist");
+    }
+    if (policy.policy !== "allowlist" && mergedAllowlist.length > 0) {
+        throw new Error("--tool-allowlist is only valid with --tool-policy allowlist");
+    }
+    return { policy: policy.policy, allowlist: [...mergedAllowlist] };
+}
+export function mcpToolPolicyEnv(config) {
+    if (config.policy === null) {
+        return {};
+    }
+    const env = {
+        [MCP_TOOL_POLICY_ENV]: config.policy,
+    };
+    if (config.policy === "allowlist") {
+        env[MCP_TOOL_ALLOWLIST_ENV] = config.allowlist.join(",");
+    }
+    return env;
+}
+export function toolAnnotationsFlags(annotations) {
+    return {
+        readOnly: annotations?.readOnlyHint === true,
+        destructive: annotations?.destructiveHint === true,
+    };
+}
+export function toolAllowedByPolicy(name, annotations, config) {
+    if (config.policy === null) {
+        return true;
+    }
+    const { readOnly, destructive } = toolAnnotationsFlags(annotations);
+    if (config.policy === "readonly") {
+        return readOnly;
+    }
+    if (config.policy === "spend-write") {
+        return !isLiveMoneyTool(name, annotations);
+    }
+    if (config.policy === "allowlist") {
+        return new Set(config.allowlist).has(name);
+    }
+    return true;
+}
+export function validateMcpToolSchema(tool) {
+    const errors = [];
+    const name = typeof tool.name === "string" ? tool.name : "";
+    if (!name.trim()) {
+        errors.push("tool missing non-empty name");
+    }
+    const description = tool.description;
+    if (typeof description !== "string" || !description.trim()) {
+        errors.push(`${name || "<unknown>"}: missing description`);
+    }
+    const inputSchema = tool.inputSchema;
+    if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+        errors.push(`${name || "<unknown>"}: inputSchema must be an object`);
+    }
+    else if (inputSchema.type !== "object") {
+        errors.push(`${name || "<unknown>"}: inputSchema.type must be object`);
+    }
+    const outputSchema = tool.outputSchema;
+    if (outputSchema !== undefined && (typeof outputSchema !== "object" || Array.isArray(outputSchema))) {
+        errors.push(`${name || "<unknown>"}: outputSchema must be an object when present`);
+    }
+    const annotations = tool.annotations;
+    if (annotations !== undefined && (typeof annotations !== "object" || Array.isArray(annotations))) {
+        errors.push(`${name || "<unknown>"}: annotations must be an object when present`);
+    }
+    return errors;
+}
+export function isLiveMoneyTool(name, annotations) {
+    const { destructive } = toolAnnotationsFlags(annotations);
+    return destructive || LIVE_MONEY_TOOL_NAMES.has(name);
+}

package/dist/cli/mcp-verify-config.d.ts

@@ -0,0 +1,37 @@
+import { type McpInstallFormat, type McpInstallHost, type McpInstallScope, type McpServerEntry } from "./mcp-install.js";
+import { type McpToolPolicyConfig } from "./mcp-policy.js";
+export type McpConfigSource = "generated" | "file";
+export type McpConfigValidationIssue = {
+    field: string;
+    message: string;
+};
+export type McpConfigValidationResult = {
+    ok: boolean;
+    host: string;
+    source: McpConfigSource;
+    configPath: string | null;
+    issues: McpConfigValidationIssue[];
+    entry?: McpServerEntry;
+    toolPolicy?: McpToolPolicyConfig;
+    message: string;
+};
+export declare function parseMcpHostEntry(payload: string, format: McpInstallFormat): McpServerEntry;
+export declare function validateMcpHostConfig(input: {
+    host: McpInstallHost;
+    format: McpInstallFormat;
+    payload: string;
+    cwd: string;
+    expectedEnvFile?: string;
+    source?: McpConfigSource;
+    configPath?: string | null;
+}): McpConfigValidationResult;
+export declare function verifyMcpInstallPlan(input: {
+    host: McpInstallHost;
+    scope?: McpInstallScope;
+    format: McpInstallFormat;
+    envFile: string;
+    cwd: string;
+    home: string;
+    configPath?: string;
+    toolPolicy?: McpToolPolicyConfig;
+}): Promise<McpConfigValidationResult>;

package/dist/cli/mcp-verify-config.js

@@ -0,0 +1,174 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { defaultMcpServerCommand, planMcpInstall, } from "./mcp-install.js";
+import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, } from "./mcp-policy.js";
+function validationMessage(ok, issues) {
+    if (ok) {
+        return "MCP host config is valid";
+    }
+    return issues[0]?.message ?? "invalid MCP config";
+}
+function parseTomlPaybondEntry(payload) {
+    const section = "[mcp_servers.paybond]";
+    if (!payload.includes(section)) {
+        throw new Error("missing [mcp_servers.paybond] section");
+    }
+    const afterSection = payload.split(section, 1)[1] ?? "";
+    const envSection = "[mcp_servers.paybond.env]";
+    const [block, envBlock = ""] = afterSection.includes(envSection)
+        ? afterSection.split(envSection)
+        : [afterSection, ""];
+    const commandMatch = /command\s*=\s*(.+)/.exec(block);
+    const argsMatch = /args\s*=\s*(\[[\s\S]*?\])/.exec(block);
+    if (!commandMatch?.[1]) {
+        throw new Error("missing paybond command");
+    }
+    const command = JSON.parse(commandMatch[1].trim());
+    const args = argsMatch?.[1] ? JSON.parse(argsMatch[1]) : [];
+    const env = {};
+    for (const line of envBlock.split("\n")) {
+        const stripped = line.trim();
+        if (!stripped || stripped.startsWith("#") || !stripped.includes("=")) {
+            continue;
+        }
+        const [key, value] = stripped.split("=", 2);
+        env[key.trim()] = JSON.parse(value.trim());
+    }
+    return { command, args, env };
+}
+export function parseMcpHostEntry(payload, format) {
+    const parsed = format === "toml"
+        ? parseTomlPaybondEntry(payload)
+        : (() => {
+            const body = JSON.parse(payload);
+            const servers = body.mcpServers;
+            if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+                throw new Error("missing mcpServers object");
+            }
+            const paybond = servers.paybond;
+            if (!paybond || typeof paybond !== "object" || Array.isArray(paybond)) {
+                throw new Error("missing mcpServers.paybond entry");
+            }
+            return paybond;
+        })();
+    const command = parsed.command;
+    if (typeof command !== "string" || !command.trim()) {
+        throw new Error("missing paybond command");
+    }
+    const args = parsed.args;
+    if (!Array.isArray(args) || !args.every((item) => typeof item === "string")) {
+        throw new Error("paybond args must be a string array");
+    }
+    const envRaw = parsed.env;
+    if (envRaw !== undefined && (typeof envRaw !== "object" || Array.isArray(envRaw))) {
+        throw new Error("paybond env must be an object");
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(envRaw ?? {})) {
+        env[key] = String(value);
+    }
+    return {
+        command,
+        args: [...args],
+        env,
+    };
+}
+function validateEntry(entry, cwd, expectedEnvFile) {
+    const issues = [];
+    if ("PAYBOND_API_KEY" in entry.env) {
+        issues.push({ field: "env", message: "config must reference PAYBOND_ENV_FILE, not PAYBOND_API_KEY" });
+    }
+    const envFile = entry.env.PAYBOND_ENV_FILE?.trim() ?? "";
+    if (!envFile) {
+        issues.push({ field: "env", message: "missing PAYBOND_ENV_FILE" });
+    }
+    else if (expectedEnvFile && envFile !== expectedEnvFile) {
+        issues.push({
+            field: "env",
+            message: `PAYBOND_ENV_FILE mismatch: config=${JSON.stringify(envFile)} expected=${JSON.stringify(expectedEnvFile)}`,
+        });
+    }
+    const resolvedEnv = path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(cwd, envFile);
+    if (envFile && !existsSync(resolvedEnv)) {
+        issues.push({ field: "env", message: `env file not found: ${resolvedEnv}` });
+    }
+    if (!entry.command.trim()) {
+        issues.push({ field: "command", message: "missing MCP server command" });
+    }
+    let toolPolicy;
+    const rawPolicy = entry.env[MCP_TOOL_POLICY_ENV]?.trim() ?? "";
+    const rawAllowlist = entry.env[MCP_TOOL_ALLOWLIST_ENV]?.trim() ?? "";
+    if (rawPolicy || rawAllowlist) {
+        try {
+            toolPolicy = mergeMcpToolPolicy(parseMcpToolPolicy(rawPolicy || undefined), parseMcpToolAllowlist(rawAllowlist || undefined));
+        }
+        catch (err) {
+            issues.push({
+                field: "tool_policy",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { issues, toolPolicy };
+}
+export function validateMcpHostConfig(input) {
+    try {
+        const entry = parseMcpHostEntry(input.payload, input.format);
+        const { issues, toolPolicy } = validateEntry(entry, input.cwd, input.expectedEnvFile);
+        const ok = issues.length === 0;
+        return {
+            ok,
+            host: input.host,
+            source: input.source ?? "generated",
+            configPath: input.configPath ?? null,
+            issues,
+            entry,
+            toolPolicy,
+            message: validationMessage(ok, issues),
+        };
+    }
+    catch (err) {
+        const issues = [{ field: "config", message: err instanceof Error ? err.message : String(err) }];
+        return {
+            ok: false,
+            host: input.host,
+            source: input.source ?? "generated",
+            configPath: input.configPath ?? null,
+            issues,
+            message: validationMessage(false, issues),
+        };
+    }
+}
+export async function verifyMcpInstallPlan(input) {
+    let payload;
+    let source = "generated";
+    let configPath = input.configPath ?? null;
+    if (input.configPath) {
+        payload = await readFile(input.configPath, "utf8");
+        source = "file";
+    }
+    else {
+        const plan = planMcpInstall({
+            host: input.host,
+            scope: input.scope ?? "local",
+            format: input.format,
+            envFile: input.envFile,
+            cwd: input.cwd,
+            home: input.home,
+            serverCommand: defaultMcpServerCommand(),
+            toolPolicy: input.toolPolicy,
+        });
+        payload = plan.payload;
+        configPath = plan.configPath;
+    }
+    return validateMcpHostConfig({
+        host: input.host,
+        format: input.format,
+        payload,
+        cwd: input.cwd,
+        expectedEnvFile: input.envFile,
+        source,
+        configPath,
+    });
+}

package/dist/cli/redact.d.ts

@@ -0,0 +1,4 @@
+export declare function maskApiKey(rawKey: string): string;
+export declare function redactSensitiveFields(value: unknown): unknown;
+export declare function isSensitiveConfigKey(key: string): boolean;
+export declare function redactConfigValue(key: string, value: string): string;

package/dist/cli/redact.js

@@ -0,0 +1,67 @@
+export function maskApiKey(rawKey) {
+    const trimmed = rawKey.trim();
+    const parts = trimmed.split("_");
+    if (parts.length >= 5 && parts[0] === "paybond" && parts[1] === "sk") {
+        const environment = parts[2];
+        const keyId = parts[3];
+        const redactedKeyId = keyId.length > 12 ? `${keyId.slice(0, 8)}...${keyId.slice(-4)}` : "redacted";
+        return `paybond_sk_${environment}_${redactedKeyId}`;
+    }
+    return "paybond_sk_...";
+}
+export function redactSensitiveFields(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSensitiveFields(item));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (child && typeof child === "object") {
+                out[key] = redactSensitiveFields(child);
+                continue;
+            }
+            const lowered = key.toLowerCase();
+            if (lowered === "capability_token" ||
+                lowered === "access_token" ||
+                lowered === "refresh_token" ||
+                (lowered.endsWith("_token") && lowered !== "token_type")) {
+                out[key] = typeof child === "string" && child.trim() ? "[redacted]" : child;
+            }
+            else if (lowered === "api_key" || lowered.endsWith("_api_key")) {
+                out[key] = typeof child === "string" ? maskApiKey(child) : child;
+            }
+            else {
+                out[key] = child;
+            }
+        }
+        return out;
+    }
+    return value;
+}
+const SENSITIVE_CONFIG_KEY_EXACT = new Set([
+    "api_key",
+    "paybond_api_key",
+    "secret",
+    "client_secret",
+    "password",
+]);
+const SENSITIVE_CONFIG_KEY_TOKEN_ALLOWLIST = new Set(["token_type", "token_endpoint"]);
+export function isSensitiveConfigKey(key) {
+    const lowered = key.toLowerCase();
+    if (SENSITIVE_CONFIG_KEY_EXACT.has(lowered)) {
+        return true;
+    }
+    if (lowered.endsWith("_token") && !SENSITIVE_CONFIG_KEY_TOKEN_ALLOWLIST.has(lowered)) {
+        return true;
+    }
+    if (lowered.endsWith("_api_key") || lowered.endsWith("_secret") || lowered.endsWith("_password")) {
+        return true;
+    }
+    return false;
+}
+export function redactConfigValue(key, value) {
+    if (!isSensitiveConfigKey(key)) {
+        return value;
+    }
+    return value.trim() ? maskApiKey(value) : "";
+}

package/dist/cli/request-id.d.ts

@@ -0,0 +1,2 @@
+/** Generate a correlation id suitable for Gateway request headers and JSON envelopes. */
+export declare function generateRequestId(): string;

package/dist/cli/request-id.js

@@ -0,0 +1,5 @@
+import { v4 as uuidv4 } from "uuid";
+/** Generate a correlation id suitable for Gateway request headers and JSON envelopes. */
+export function generateRequestId() {
+    return `01${uuidv4().replace(/-/g, "").slice(0, 24).toUpperCase()}`;
+}

package/dist/cli/router.d.ts

@@ -0,0 +1,2 @@
+import { type CliDependencies } from "./types.js";
+export declare function runCli(argv: string[], deps?: CliDependencies): Promise<number>;