@paybond/kit 0.9.8 → 0.11.0

package/dist/cli/mcp-policy.js

@@ -0,0 +1,110 @@
+export const MCP_TOOL_POLICY_ENV = "PAYBOND_MCP_TOOL_POLICY";
+export const MCP_TOOL_ALLOWLIST_ENV = "PAYBOND_MCP_TOOL_ALLOWLIST";
+export const DEFAULT_MCP_TOOL_POLICY = "spend-write";
+export const LIVE_MONEY_TOOL_NAMES = new Set([
+    "paybond_fund_intent",
+    "paybond_confirm_settlement",
+]);
+export function defaultMcpToolPolicyConfig() {
+    return { policy: DEFAULT_MCP_TOOL_POLICY, allowlist: [] };
+}
+export function resolveMcpToolPolicy(config) {
+    if (config.policy !== null) {
+        return config;
+    }
+    return defaultMcpToolPolicyConfig();
+}
+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) {
+    const resolved = resolveMcpToolPolicy(config);
+    const env = {
+        [MCP_TOOL_POLICY_ENV]: resolved.policy ?? DEFAULT_MCP_TOOL_POLICY,
+    };
+    if (resolved.policy === "allowlist") {
+        env[MCP_TOOL_ALLOWLIST_ENV] = resolved.allowlist.join(",");
+    }
+    return env;
+}
+export function toolAnnotationsFlags(annotations) {
+    return {
+        readOnly: annotations?.readOnlyHint === true,
+        destructive: annotations?.destructiveHint === true,
+    };
+}
+export function toolAllowedByPolicy(name, annotations, config) {
+    const resolved = resolveMcpToolPolicy(config);
+    const { readOnly, destructive } = toolAnnotationsFlags(annotations);
+    if (resolved.policy === "readonly") {
+        return readOnly;
+    }
+    if (resolved.policy === "spend-write") {
+        return !isLiveMoneyTool(name, annotations);
+    }
+    if (resolved.policy === "allowlist") {
+        return new Set(resolved.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,172 @@
+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, resolveMcpToolPolicy, } 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() ?? "";
+    try {
+        toolPolicy = resolveMcpToolPolicy(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,88 @@
+const SENSITIVE_SEED_EXACT_FIELDS = new Set(["payee_signing_seed", "agent_recognition_signing_seed"]);
+function isSensitiveSeedKey(key) {
+    const lowered = key.toLowerCase();
+    if (SENSITIVE_SEED_EXACT_FIELDS.has(lowered)) {
+        return true;
+    }
+    return lowered.endsWith("_seed") || lowered.endsWith("_seed_hex");
+}
+function hasRedactableScalarContent(value) {
+    if (typeof value === "string") {
+        return value.trim().length > 0;
+    }
+    if (value instanceof Uint8Array) {
+        return value.length > 0;
+    }
+    return false;
+}
+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)) {
+            const lowered = key.toLowerCase();
+            if (lowered === "capability_token" ||
+                lowered === "access_token" ||
+                lowered === "refresh_token" ||
+                (lowered.endsWith("_token") && lowered !== "token_type")) {
+                out[key] = hasRedactableScalarContent(child) ? "[redacted]" : child;
+                continue;
+            }
+            if (lowered === "api_key" || lowered.endsWith("_api_key")) {
+                out[key] = typeof child === "string" ? maskApiKey(child) : child;
+                continue;
+            }
+            if (isSensitiveSeedKey(key)) {
+                out[key] = hasRedactableScalarContent(child) ? "[redacted]" : child;
+                continue;
+            }
+            if (child && typeof child === "object") {
+                out[key] = redactSensitiveFields(child);
+                continue;
+            }
+            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>;