@paybond/kit 0.10.0 → 0.11.1

package/dist/policy/parse-text.js

@@ -0,0 +1,126 @@
+import { PaybondPolicyValidationError } from "./schema.js";
+function tokenizeYamlLines(text) {
+    const lines = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const indent = raw.search(/\S/);
+        if (indent < 0) {
+            continue;
+        }
+        lines.push({ indent, trimmed, raw });
+    }
+    return lines;
+}
+function parseYamlScalar(value) {
+    if (!value) {
+        return "";
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    if (/^-?\d+\.\d+$/.test(value)) {
+        return Number.parseFloat(value);
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function parseYamlBlock(lines, start, indent, sourceLabel) {
+    if (start >= lines.length || lines[start].indent < indent) {
+        return [{}, start];
+    }
+    if (lines[start].trimmed.startsWith("- ")) {
+        const items = [];
+        let index = start;
+        while (index < lines.length &&
+            lines[index].indent === indent &&
+            lines[index].trimmed.startsWith("- ")) {
+            const afterDash = lines[index].trimmed.slice(2).trim();
+            if (!afterDash) {
+                const [child, next] = parseYamlBlock(lines, index + 1, indent + 2, sourceLabel);
+                items.push(child);
+                index = next;
+                continue;
+            }
+            const inlineMap = /^([^:]+?):\s*(.*)$/.exec(afterDash);
+            if (inlineMap && !inlineMap[2]) {
+                const key = inlineMap[1].trim();
+                const [child, next] = parseYamlBlock(lines, index + 1, indent + 2, sourceLabel);
+                items.push({ [key]: child });
+                index = next;
+                continue;
+            }
+            if (inlineMap) {
+                items.push({
+                    [inlineMap[1].trim()]: parseYamlScalar(inlineMap[2].trim()),
+                });
+                index += 1;
+                continue;
+            }
+            items.push(parseYamlScalar(afterDash));
+            index += 1;
+        }
+        return [items, index];
+    }
+    const objectValue = {};
+    let index = start;
+    while (index < lines.length && lines[index].indent === indent) {
+        const match = /^([^:]+?):\s*(.*)$/.exec(lines[index].trimmed);
+        if (!match) {
+            throw new PaybondPolicyValidationError(`${sourceLabel} has invalid YAML line: ${lines[index].raw}`);
+        }
+        const key = match[1].trim();
+        const rest = match[2].trim();
+        if (rest) {
+            objectValue[key] = parseYamlScalar(rest);
+            index += 1;
+            continue;
+        }
+        const [child, next] = parseYamlBlock(lines, index + 1, indent + 2, sourceLabel);
+        objectValue[key] = child;
+        index = next;
+    }
+    return [objectValue, index];
+}
+function parseIndentedYaml(text, sourceLabel) {
+    const lines = tokenizeYamlLines(text);
+    if (lines.length === 0) {
+        throw new PaybondPolicyValidationError(`${sourceLabel} is empty`);
+    }
+    const [value] = parseYamlBlock(lines, 0, lines[0].indent, sourceLabel);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new PaybondPolicyValidationError(`${sourceLabel} must be a YAML object`);
+    }
+    return value;
+}
+/** Parse policy file text (JSON or YAML) into a raw document object. */
+export function parsePolicyDocumentText(text, sourceLabel = "policy file") {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        throw new PaybondPolicyValidationError(`${sourceLabel} is empty`);
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new PaybondPolicyValidationError(`${sourceLabel} must be a JSON object`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof PaybondPolicyValidationError) {
+            throw err;
+        }
+        return parseIndentedYaml(trimmed, sourceLabel);
+    }
+}

package/dist/policy/policy-api.d.ts

@@ -0,0 +1,45 @@
+import { maxSpend, maxSpendUsd, type PolicyGuardrailLayer } from "./guardrails.js";
+import { PaybondPolicy } from "./load.js";
+import { isLayeredPolicyPresetId } from "./presets.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+export type VerticalPolicyOptions = {
+    /** Per side-effecting tool spend cap in cents. */
+    maxSpend?: number;
+    /** Intent budget cap in USD. */
+    maxSpendUsd?: number;
+    /** Additional guardrail layers applied after bundled defaults. */
+    guardrails?: PolicyGuardrailLayer[];
+};
+declare function composeToPolicy(domainDocument: PaybondPolicyDocumentV1, ...layers: PolicyGuardrailLayer[]): PaybondPolicy;
+/** Programmatic policy composition API (`paybond.policyPresets.*`). */
+export declare const paybondPolicyPresets: {
+    readonly travel: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly shopping: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly saas: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly aws: (options?: VerticalPolicyOptions) => PaybondPolicy;
+    readonly readOnly: () => PaybondPolicy;
+    readonly strict: () => PaybondPolicy;
+    readonly compose: typeof composeToPolicy;
+    readonly domain: {
+        readonly travel: typeof import("./domain.js").travel;
+        readonly shopping: typeof import("./domain.js").shopping;
+        readonly saas: typeof import("./domain.js").saas;
+        readonly aws: typeof import("./domain.js").aws;
+    };
+    readonly guardrails: {
+        readonly defaultDeny: typeof import("./guardrails.js").defaultDeny;
+        readonly maxSpend: typeof maxSpend;
+        readonly maxSpendUsd: typeof maxSpendUsd;
+        readonly readOnly: typeof import("./guardrails.js").readOnly;
+        readonly readOnlySearch: typeof import("./guardrails.js").readOnlySearch;
+        readonly strict: typeof import("./guardrails.js").strict;
+        readonly requireEvidence: typeof import("./guardrails.js").requireEvidence;
+        readonly auditOnly: typeof import("./guardrails.js").auditOnly;
+        readonly allowDryRun: typeof import("./guardrails.js").allowDryRun;
+        readonly fromDocument: typeof import("./guardrails.js").guardrailLayerFromDocument;
+    };
+    readonly resolvePresetDocument: (presetId: string) => PaybondPolicyDocumentV1;
+    readonly isLayeredPreset: typeof isLayeredPolicyPresetId;
+};
+export type PaybondPolicyPresets = typeof paybondPolicyPresets;
+export {};

package/dist/policy/policy-api.js

@@ -0,0 +1,61 @@
+import { bundledDefaultGuardrails, composeBundledPresetDefault, composePolicyLayers, } from "./compose.js";
+import { domain } from "./domain.js";
+import { guardrails, maxSpend, maxSpendUsd } from "./guardrails.js";
+import { PaybondPolicy } from "./load.js";
+import { isKnownPolicyPresetId, isLayeredPolicyPresetId, resolveComposedPresetDocument, } from "./presets.js";
+function verticalPolicy(presetId, options) {
+    const hasCustomizations = options?.maxSpend !== undefined ||
+        options?.maxSpendUsd !== undefined ||
+        (options?.guardrails?.length ?? 0) > 0;
+    if (!hasCustomizations) {
+        return PaybondPolicy.fromDocument(composeBundledPresetDefault(presetId));
+    }
+    const layers = [...bundledDefaultGuardrails(presetId)];
+    if (options?.maxSpend !== undefined) {
+        layers.push(maxSpend(options.maxSpend));
+    }
+    if (options?.maxSpendUsd !== undefined) {
+        layers.push(maxSpendUsd(options.maxSpendUsd));
+    }
+    if (options?.guardrails?.length) {
+        layers.push(...options.guardrails);
+    }
+    return PaybondPolicy.fromDocument(composePolicyLayers(domain[presetId](), ...layers));
+}
+function composeToPolicy(domainDocument, ...layers) {
+    return PaybondPolicy.fromDocument(composePolicyLayers(domainDocument, ...layers));
+}
+function presetPolicy(presetId) {
+    return PaybondPolicy.fromDocument(resolveComposedPresetDocument(presetId));
+}
+/** Programmatic policy composition API (`paybond.policyPresets.*`). */
+export const paybondPolicyPresets = {
+    travel(options) {
+        return verticalPolicy("travel", options);
+    },
+    shopping(options) {
+        return verticalPolicy("shopping", options);
+    },
+    saas(options) {
+        return verticalPolicy("saas", options);
+    },
+    aws(options) {
+        return verticalPolicy("aws", options);
+    },
+    readOnly() {
+        return presetPolicy("read-only");
+    },
+    strict() {
+        return presetPolicy("strict");
+    },
+    compose: composeToPolicy,
+    domain,
+    guardrails,
+    resolvePresetDocument(presetId) {
+        if (!isKnownPolicyPresetId(presetId)) {
+            throw new Error(`unknown policy preset: ${presetId}`);
+        }
+        return resolveComposedPresetDocument(presetId);
+    },
+    isLayeredPreset: isLayeredPolicyPresetId,
+};

package/dist/policy/presets.d.ts

@@ -0,0 +1,19 @@
+import type { LayeredPolicyPresetId } from "./compose.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+export type { LayeredPolicyPresetId };
+declare const KNOWN_POLICY_PRESET_IDS: readonly ["travel", "shopping", "saas", "aws", "read-only", "strict"];
+export type PolicyPresetId = (typeof KNOWN_POLICY_PRESET_IDS)[number];
+/** True when `value` is a bundled vertical policy preset id (not a file path). */
+export declare function isKnownPolicyPresetId(value: string): value is PolicyPresetId;
+/** True when the preset is composed from domain + guardrails layers. */
+export declare function isLayeredPolicyPresetId(value: string): value is LayeredPolicyPresetId;
+/** List bundled vertical policy preset ids shipped with Paybond Kit. */
+export declare function listPolicyPresetIds(): PolicyPresetId[];
+/** Resolve a bundled preset id to an on-disk `paybond.policy.yaml` path. */
+export declare function resolvePolicyPresetPath(presetId: string): string;
+/** Load a bundled vertical policy preset as YAML text (for tests and scaffolding). */
+export declare function readPolicyPresetYaml(presetId: PolicyPresetId): string;
+/** Resolve a bundled preset to its composed v1 policy document. */
+export declare function resolveComposedPresetDocument(presetId: PolicyPresetId): PaybondPolicyDocumentV1;
+/** @deprecated Internal alias used by YAML flat-file parity checks. */
+export declare function readComposedPresetYamlObject(presetId: LayeredPolicyPresetId): Record<string, unknown>;

package/dist/policy/presets.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { composeBundledPresetDefault, composeLayeredPolicyPresetDocument, isLayeredPolicyPreset, } from "./compose.js";
+import { parsePolicyDocumentText } from "./parse-text.js";
+import { parsePaybondPolicyDocumentV1, } from "./schema.js";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const KNOWN_POLICY_PRESET_IDS = [
+    "travel",
+    "shopping",
+    "saas",
+    "aws",
+    "read-only",
+    "strict",
+];
+function presetCandidatePaths(presetId) {
+    const fileName = `${presetId}.yaml`;
+    const roots = [
+        join(MODULE_DIR, "../../policy/presets"),
+        join(MODULE_DIR, "../../../policy/presets"),
+        join(MODULE_DIR, "../../../../kit/policy/presets"),
+    ];
+    return roots.map((root) => join(root, fileName));
+}
+/** True when `value` is a bundled vertical policy preset id (not a file path). */
+export function isKnownPolicyPresetId(value) {
+    return KNOWN_POLICY_PRESET_IDS.includes(value.trim());
+}
+/** True when the preset is composed from domain + guardrails layers. */
+export function isLayeredPolicyPresetId(value) {
+    return isLayeredPolicyPreset(value);
+}
+/** List bundled vertical policy preset ids shipped with Paybond Kit. */
+export function listPolicyPresetIds() {
+    return [...KNOWN_POLICY_PRESET_IDS];
+}
+/** Resolve a bundled preset id to an on-disk `paybond.policy.yaml` path. */
+export function resolvePolicyPresetPath(presetId) {
+    const trimmed = presetId.trim();
+    if (!isKnownPolicyPresetId(trimmed)) {
+        throw new Error(`unknown policy preset: ${trimmed}`);
+    }
+    for (const candidate of presetCandidatePaths(trimmed)) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`policy preset file not found for: ${trimmed}`);
+}
+/** Load a bundled vertical policy preset as YAML text (for tests and scaffolding). */
+export function readPolicyPresetYaml(presetId) {
+    const path = resolvePolicyPresetPath(presetId);
+    return readFileSync(path, "utf8");
+}
+/** Resolve a bundled preset to its composed v1 policy document. */
+export function resolveComposedPresetDocument(presetId) {
+    if (isLayeredPolicyPreset(presetId)) {
+        return composeBundledPresetDefault(presetId);
+    }
+    const flatPath = resolvePolicyPresetPath(presetId);
+    return parsePaybondPolicyDocumentV1(parsePolicyDocumentText(readPolicyPresetYaml(presetId), flatPath));
+}
+/** @deprecated Internal alias used by YAML flat-file parity checks. */
+export function readComposedPresetYamlObject(presetId) {
+    return composeLayeredPolicyPresetDocument(presetId);
+}

package/dist/policy/registry.d.ts

@@ -0,0 +1,7 @@
+import { PaybondToolRegistry } from "../agent/registry.js";
+import { PaybondToolRegistryConfig } from "../agent/types.js";
+import type { PaybondPolicyDocumentV1 } from "./schema.js";
+/** Convert a validated policy document into middleware registry config. */
+export declare function policyDocumentToToolRegistryConfig(document: PaybondPolicyDocumentV1): PaybondToolRegistryConfig;
+/** Build a validated {@link PaybondToolRegistry} from a policy document. */
+export declare function policyToToolRegistry(document: PaybondPolicyDocumentV1): PaybondToolRegistry;

package/dist/policy/registry.js

@@ -0,0 +1,33 @@
+import { createPaybondToolRegistry } from "../agent/registry.js";
+import { resolveSpendCentsFromJsonPath } from "./json-path.js";
+/** Convert a validated policy document into middleware registry config. */
+export function policyDocumentToToolRegistryConfig(document) {
+    const sideEffecting = {};
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        if (!entry.side_effecting) {
+            continue;
+        }
+        const policy = {
+            evidencePreset: entry.evidence_preset,
+        };
+        if (entry.operation?.trim()) {
+            policy.operation = entry.operation.trim();
+        }
+        if (entry.max_spend_cents !== undefined) {
+            policy.spendCents = entry.max_spend_cents;
+        }
+        else if (entry.spend_from_args) {
+            const path = entry.spend_from_args;
+            policy.spendCents = (args) => resolveSpendCentsFromJsonPath(args, path, toolName);
+        }
+        sideEffecting[toolName] = policy;
+    }
+    return {
+        defaultDeny: document.default_deny,
+        sideEffecting,
+    };
+}
+/** Build a validated {@link PaybondToolRegistry} from a policy document. */
+export function policyToToolRegistry(document) {
+    return createPaybondToolRegistry(policyDocumentToToolRegistryConfig(document));
+}

package/dist/policy/reload.d.ts

@@ -0,0 +1,86 @@
+import type { PaybondAgentRun } from "../agent/run.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+import { type PaybondPolicySnapshot } from "./snapshot.js";
+import { type PolicyRemoteValidateClient } from "./validate-remote.js";
+import type { PolicyEffectiveResolveClient } from "./load-effective.js";
+/** Options for {@link PaybondAgentRun.reloadPolicy}. */
+export type PaybondPolicyReloadOptions = {
+    /** Policy file path; defaults to the path used at bind when omitted. */
+    file?: string;
+    /** Run Gateway `POST /v1/policy/validate` before applying (recommended in production). */
+    remote?: boolean;
+    /** Resolve org inheritance via Gateway effective endpoint before validate. */
+    resolveInheritance?: boolean;
+    /** Allow policy loosening (higher caps, new side-effecting tools). Default deny. */
+    allowLoosen?: boolean;
+    /** Gateway client for remote validate / effective resolution. */
+    gateway?: PolicyRemoteValidateClient & PolicyEffectiveResolveClient;
+};
+export type PaybondPolicyReloadResult = {
+    applied: boolean;
+    previousDigest?: string;
+    newDigest?: string;
+    unchanged?: boolean;
+};
+export type PaybondPolicyReloadFailedEvent = {
+    error: PaybondPolicyReloadError;
+};
+export type PaybondPolicyReloadedEvent = {
+    previousDigest: string;
+    newDigest: string;
+};
+/** Structured reload failure (parse, validate, loosening, intent drift). */
+export declare class PaybondPolicyReloadError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Thrown internally when poll/file reload finds an unchanged digest. */
+export declare class PaybondPolicyReloadUnchangedError extends Error {
+    constructor();
+}
+export type PaybondPolicyReloadBindConfig = {
+    /** Watch the bound policy file and reload on change. */
+    watch?: boolean | {
+        debounceMs?: number;
+        file?: string;
+    };
+    /** Poll Gateway for effective inherited policy changes. */
+    poll?: {
+        intervalMs?: number;
+        file?: string;
+        remote?: boolean;
+        resolveInheritance?: boolean;
+        gateway?: PolicyRemoteValidateClient & PolicyEffectiveResolveClient;
+    };
+};
+/** Load a versioned snapshot from a policy file path. */
+export declare function loadPolicySnapshotFromFile(filePath: string): Promise<PaybondPolicySnapshot>;
+/** Poll Gateway effective resolution; returns unchanged when digest matches. */
+export declare function loadPolicySnapshotFromEffectivePoll(options: {
+    overlayPath: string;
+    gateway: PolicyEffectiveResolveClient;
+    currentDigest?: string;
+}): Promise<{
+    snapshot?: PaybondPolicySnapshot;
+    unchanged: boolean;
+}>;
+/** Detect policy loosening between two effective documents. */
+export declare function detectPolicyLoosening(previous: PaybondPolicyDocumentV1, next: PaybondPolicyDocumentV1): string[];
+/** True when reloaded policy requires operations outside the bound intent. */
+export declare function requiresIntentRebind(document: PaybondPolicyDocumentV1, allowedTools: readonly string[]): boolean;
+/** Mutable policy reload surface shared by agent runs and MCP servers. */
+export type PolicyReloadHandle = {
+    readonly policyFilePath?: string;
+    readonly policyDigest?: string;
+    readonly currentSnapshot?: PaybondPolicySnapshot;
+    readonly inFlightCount: number;
+    applyPolicySnapshot(snapshot: PaybondPolicySnapshot): void;
+};
+/** Reload policy for any {@link PolicyReloadHandle} (agent run or MCP gate). */
+export declare function reloadPolicyOnHandle(handle: PolicyReloadHandle, options?: PaybondPolicyReloadOptions & {
+    allowedTools?: readonly string[];
+}): Promise<PaybondPolicyReloadResult>;
+/** Apply a validated snapshot to a run (atomic registry swap). */
+export declare function applyPolicySnapshotToRun(run: PaybondAgentRun, snapshot: PaybondPolicySnapshot): PaybondPolicyReloadResult;
+/** Core reload pipeline: load, validate, guard, swap. */
+export declare function reloadPolicyOnRun(run: PaybondAgentRun, options?: PaybondPolicyReloadOptions): Promise<PaybondPolicyReloadResult>;