@paybond/kit 0.10.0 → 0.11.1

package/dist/mcp-policy-reload.js

@@ -0,0 +1,200 @@
+import { resolve } from "node:path";
+import { PaybondUnregisteredSideEffectingToolError } from "./agent/types.js";
+import { loadPolicySnapshotFromFile, reloadPolicyOnHandle, } from "./policy/reload.js";
+import { parsePolicyEffectiveResolveResponse, } from "./policy/load-effective.js";
+import { parsePolicyRemoteValidateResponse, policyValidateQueryString, } from "./policy/validate-remote.js";
+import { PaybondPolicyReloadController } from "./policy/watcher.js";
+export const MCP_POLICY_FILE_ENV = "PAYBOND_POLICY_FILE";
+export const MCP_POLICY_RELOAD_ENV = "PAYBOND_POLICY_RELOAD";
+export const MCP_POLICY_RELOAD_ALLOW_LOOSEN_ENV = "PAYBOND_POLICY_RELOAD_ALLOW_LOOSEN";
+export class McpPolicyReloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpPolicyReloadError";
+    }
+}
+export function createMcpPolicyGatewayAdapter(client) {
+    return {
+        async validatePolicy(document, options) {
+            const qs = policyValidateQueryString(options ?? {});
+            const body = await client.postJSON(`/v1/policy/validate${qs}`, document);
+            return parsePolicyRemoteValidateResponse(body);
+        },
+        async resolvePolicyEffective(orgPolicyId, overlay, options) {
+            let path = `/v1/org-policies/${encodeURIComponent(orgPolicyId)}/effective`;
+            const currentDigest = options?.currentDigest?.trim();
+            if (currentDigest) {
+                path += `?digest=${encodeURIComponent(currentDigest)}`;
+            }
+            const body = await client.postJSON(path, overlay);
+            return parsePolicyEffectiveResolveResponse(body);
+        },
+    };
+}
+export function parseMcpPolicyReloadMode(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (!value || value === "off") {
+        return "off";
+    }
+    if (value === "watch" || value === "poll") {
+        return value;
+    }
+    throw new Error("invalid PAYBOND_POLICY_RELOAD (expected watch|poll|off)");
+}
+export function parseMcpPolicyReloadConfig(env) {
+    const policyFile = (env[MCP_POLICY_FILE_ENV] ?? "").trim();
+    if (!policyFile) {
+        return null;
+    }
+    return {
+        policyFile: resolve(policyFile),
+        reloadMode: parseMcpPolicyReloadMode(env[MCP_POLICY_RELOAD_ENV]),
+        allowLoosen: env[MCP_POLICY_RELOAD_ALLOW_LOOSEN_ENV] === "1",
+    };
+}
+/** MCP reload controller shim — delegates to {@link McpPolicyReloadGate}. */
+class McpPolicyReloadRunner {
+    gate;
+    constructor(gate) {
+        this.gate = gate;
+    }
+    reloadPolicy(options) {
+        return this.gate.reloadPolicy(options);
+    }
+}
+/**
+ * Long-lived MCP policy gate: versioned snapshot, safe reload, and spend-gate registry checks.
+ */
+export class McpPolicyReloadGate {
+    config;
+    _snapshot;
+    _inFlightCount = 0;
+    _lastAllowedTools = [];
+    _controller;
+    _reloadDefaults = {};
+    policyFilePath;
+    lastReloadAt;
+    lastReloadError;
+    constructor(config, snapshot) {
+        this.config = config;
+        this.policyFilePath = config.policyFile;
+        this._snapshot = snapshot;
+    }
+    static async open(config, options) {
+        const snapshot = await loadPolicySnapshotFromFile(config.policyFile);
+        const gate = new McpPolicyReloadGate(config, snapshot);
+        const runner = new McpPolicyReloadRunner(gate);
+        gate._reloadDefaults = {
+            file: config.policyFile,
+            allowLoosen: config.allowLoosen,
+            gateway: options?.gateway,
+        };
+        if (config.reloadMode === "watch") {
+            gate._controller = PaybondPolicyReloadController.start(runner, { watch: { debounceMs: config.watchDebounceMs } }, config.policyFile);
+        }
+        else if (config.reloadMode === "poll") {
+            gate._reloadDefaults.remote = true;
+            gate._reloadDefaults.resolveInheritance = true;
+            gate._controller = PaybondPolicyReloadController.start(runner, {
+                poll: {
+                    intervalMs: config.pollIntervalMs,
+                    remote: true,
+                    resolveInheritance: true,
+                    gateway: options?.gateway,
+                },
+            }, config.policyFile);
+        }
+        return gate;
+    }
+    get currentSnapshot() {
+        return this._snapshot;
+    }
+    get policyDigest() {
+        return this._snapshot?.digest;
+    }
+    get inFlightCount() {
+        return this._inFlightCount;
+    }
+    get registry() {
+        const snapshot = this._snapshot;
+        if (!snapshot) {
+            throw new McpPolicyReloadError("policy snapshot is not loaded");
+        }
+        return snapshot.registry;
+    }
+    applyPolicySnapshot(snapshot) {
+        this._snapshot = snapshot;
+    }
+    async reloadPolicy(options = {}) {
+        try {
+            const result = await reloadPolicyOnHandle(this, {
+                ...this._reloadDefaults,
+                ...options,
+                allowedTools: this._lastAllowedTools,
+            });
+            if (result.applied) {
+                this.lastReloadAt = new Date().toISOString();
+                this.lastReloadError = undefined;
+            }
+            return result;
+        }
+        catch (err) {
+            this.lastReloadError = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+    }
+    beginToolCall() {
+        this._inFlightCount += 1;
+    }
+    endToolCall() {
+        this._inFlightCount = Math.max(0, this._inFlightCount - 1);
+    }
+    /**
+     * Enforce paybond.policy.yaml registry rules before Harbor spend authorization.
+     * Pins policy_digest for the current MCP tool invocation.
+     */
+    assertSpendGate(input) {
+        const operation = input.operation.trim();
+        const toolName = (input.toolName ?? operation).trim();
+        if (!operation) {
+            throw new McpPolicyReloadError("operation must be non-empty");
+        }
+        this._lastAllowedTools = input.allowedTools;
+        const policyDigest = this._snapshot?.digest;
+        const resolution = this.registry.resolveTool(toolName, {
+            allowedTools: input.allowedTools,
+        });
+        if (resolution.kind === "passthrough") {
+            return { operation, requestedSpendCents: 0, policyDigest };
+        }
+        if (resolution.kind === "denied") {
+            throw new PaybondUnregisteredSideEffectingToolError(resolution.toolName, resolution.operation);
+        }
+        if (!input.allowedTools.includes(operation)) {
+            throw new McpPolicyReloadError(`operation "${operation}" is not in intent allowed_tools (${input.allowedTools.join(", ")})`);
+        }
+        const requestedSpendCents = input.requestedSpendCents ??
+            this.registry.resolveSpendCents(toolName, input.arguments) ??
+            0;
+        return {
+            operation: resolution.operation,
+            requestedSpendCents,
+            policyDigest,
+        };
+    }
+    status() {
+        return {
+            enabled: true,
+            policy_file: this.policyFilePath,
+            policy_digest: this.policyDigest,
+            policy_loaded_at: this._snapshot?.loadedAt,
+            reload_mode: this.config.reloadMode,
+            last_reload_at: this.lastReloadAt ?? this._controller?.state.lastReloadAt,
+            last_reload_error: this.lastReloadError ?? this._controller?.state.lastReloadError,
+        };
+    }
+    stop() {
+        this._controller?.stop();
+        this._controller = undefined;
+    }
+}

package/dist/mcp-sep2828-evidence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Maps SEP-2828-style MCP decision/outcome execution records into artifact_attested evidence.
+ *
+ * Wire shapes follow the draft SEP-2828 pairing model: decision record (pre-side-effect) and
+ * outcome record (post-execution) linked via backLink and outcomeDerived.decisionDigest.
+ */
+export type Sep2828BackLink = {
+    attestationDigest: string;
+    attestationNonce?: string;
+};
+export type Sep2828DecisionRecord = {
+    backLink?: Sep2828BackLink;
+    decisionDerived?: {
+        decision?: "allow" | "block" | "escalate";
+    };
+};
+export type Sep2828OutcomeRecord = {
+    backLink?: Sep2828BackLink;
+    outcomeDerived?: {
+        status?: "executed" | "refused" | "errored";
+        decisionDigest?: string;
+        resultCommitment?: string;
+        completedAt?: string;
+    };
+};
+export type ArtifactAttestedEvidence = {
+    artifact_blake3_hex: string[];
+    operation: string;
+    vendor_ref_id: string;
+};
+/** Strips sha256:/blake3: prefixes so digests fit artifact_blake3_hex entries. */
+export declare function stripDigestPrefix(digest: string): string;
+/**
+ * Converts paired SEP-2828 decision and outcome records into artifact_attested evidence fields.
+ */
+export declare function mapSep2828ReceiptsToArtifactAttestedEvidence(decisionInput: Record<string, unknown>, outcomeInput: Record<string, unknown>): ArtifactAttestedEvidence;

package/dist/mcp-sep2828-evidence.js

@@ -0,0 +1,65 @@
+/**
+ * Maps SEP-2828-style MCP decision/outcome execution records into artifact_attested evidence.
+ *
+ * Wire shapes follow the draft SEP-2828 pairing model: decision record (pre-side-effect) and
+ * outcome record (post-execution) linked via backLink and outcomeDerived.decisionDigest.
+ */
+import { verifySep2828ReceiptPair } from "./sep2828-signature.js";
+function readObject(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function readBackLink(record) {
+    const backLink = readObject(record.backLink);
+    if (!backLink) {
+        return undefined;
+    }
+    const digest = backLink.attestationDigest;
+    if (typeof digest !== "string" || digest.length === 0) {
+        return undefined;
+    }
+    const nonce = backLink.attestationNonce;
+    return {
+        attestationDigest: digest,
+        attestationNonce: typeof nonce === "string" ? nonce : undefined,
+    };
+}
+/** Strips sha256:/blake3: prefixes so digests fit artifact_blake3_hex entries. */
+export function stripDigestPrefix(digest) {
+    return digest.replace(/^(sha256|blake3):/i, "");
+}
+function pushDigest(hashes, digest) {
+    if (typeof digest !== "string" || digest.length === 0) {
+        return;
+    }
+    const normalized = stripDigestPrefix(digest);
+    if (!hashes.includes(normalized)) {
+        hashes.push(normalized);
+    }
+}
+/**
+ * Converts paired SEP-2828 decision and outcome records into artifact_attested evidence fields.
+ */
+export function mapSep2828ReceiptsToArtifactAttestedEvidence(decisionInput, outcomeInput) {
+    verifySep2828ReceiptPair(decisionInput, outcomeInput);
+    const outcomeDerived = readObject(outcomeInput.outcomeDerived);
+    const status = typeof outcomeDerived?.status === "string" ? outcomeDerived.status : "";
+    const operation = status === "executed" ? "attested" : "pending";
+    const backLink = readBackLink(outcomeInput) ?? readBackLink(decisionInput);
+    const hashes = [];
+    if (outcomeDerived) {
+        pushDigest(hashes, outcomeDerived.decisionDigest);
+        pushDigest(hashes, outcomeDerived.resultCommitment);
+    }
+    if (hashes.length === 0 && backLink) {
+        pushDigest(hashes, backLink.attestationDigest);
+    }
+    const vendorRef = backLink?.attestationDigest ?? "mcp-unknown";
+    return {
+        artifact_blake3_hex: hashes,
+        operation,
+        vendor_ref_id: vendorRef,
+    };
+}

package/dist/mcp-server.d.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { type McpToolPolicyConfig } from "./cli/mcp-policy.js";
+import { type McpEvidencePolicy } from "./mcp-evidence-policy.js";
+import { type McpCapabilityTokenCacheConfig } from "./mcp-capability-token-cache.js";
+import { type McpPolicyReloadConfig } from "./mcp-policy-reload.js";
 type JSONRPCID = string | number | null;
 type JSONRPCRequest = {
     jsonrpc?: unknown;
@@ -30,6 +33,9 @@ export type PaybondMCPSettings = {
     principalPath?: string;
     maxRetries?: number;
     toolPolicy?: McpToolPolicyConfig;
+    evidencePolicy?: McpEvidencePolicy;
+    policyReload?: McpPolicyReloadConfig | null;
+    capabilityTokenCache?: McpCapabilityTokenCacheConfig;
 };
 export declare function formatMcpStdioFrame(response: JSONRPCResponse): string;
 export declare class PaybondMCPServer {