@paybond/kit 0.10.0 → 0.11.0

package/dist/policy/guardrail-spec.d.ts

@@ -0,0 +1,17 @@
+import { guardrails, type PolicyGuardrailLayer } from "./guardrails.js";
+export type GuardrailCatalogEntry = {
+    id: string;
+    title: string;
+    description: string;
+    parameterized?: boolean;
+};
+/** Built-in guardrail ids accepted by `policy init --guardrails` and solution manifests. */
+export declare const GUARDRAIL_CATALOG_ENTRIES: GuardrailCatalogEntry[];
+/** Resolve a solution-manifest guardrail token (for example `max_spend_usd_200`). */
+export declare function resolveGuardrailManifestToken(token: string): PolicyGuardrailLayer;
+/** Parse one guardrail token from CLI `--guardrails` or solution manifests. */
+export declare function parseGuardrailSpec(spec: string): PolicyGuardrailLayer;
+/** Parse a comma-separated guardrail spec list from CLI flags. */
+export declare function parseGuardrailSpecs(csv: string): PolicyGuardrailLayer[];
+export declare function listGuardrailCatalogEntries(): GuardrailCatalogEntry[];
+export { guardrails };

package/dist/policy/guardrail-spec.js

@@ -0,0 +1,140 @@
+import { auditOnly, allowDryRun, defaultDeny, guardrails, maxSpend, maxSpendUsd, readOnly, readOnlySearch, requireEvidence, strict, } from "./guardrails.js";
+/** Built-in guardrail ids accepted by `policy init --guardrails` and solution manifests. */
+export const GUARDRAIL_CATALOG_ENTRIES = [
+    {
+        id: "default-deny",
+        title: "Default deny",
+        description: "Require explicit tool registration (default_deny: true)",
+    },
+    {
+        id: "read-only",
+        title: "Read only",
+        description: "Keep only non-side-effecting tools",
+    },
+    {
+        id: "read-only-search",
+        title: "Read-only search",
+        description: "Keep only non-side-effecting search.* tools",
+    },
+    {
+        id: "strict",
+        title: "Strict",
+        description: "Tight caps, default deny, and evidence required on side-effecting tools",
+    },
+    {
+        id: "require-evidence",
+        title: "Require evidence",
+        description: "Validate evidence_preset on side-effecting tools at compose time",
+    },
+    {
+        id: "audit-only",
+        title: "Audit only",
+        description: "Reserved governance hook (no-op layer today)",
+    },
+    {
+        id: "allow-dry-run",
+        title: "Allow dry run",
+        description: "Reserved governance hook (no-op layer today)",
+    },
+    {
+        id: "max-spend:<usd>",
+        title: "Max spend (USD)",
+        description: "Cap intent budget and side-effecting tool spend (USD parameter)",
+        parameterized: true,
+    },
+    {
+        id: "max-spend-cents:<cents>",
+        title: "Max spend (cents)",
+        description: "Cap side-effecting tool spend in cents",
+        parameterized: true,
+    },
+    {
+        id: "max-spend-usd:<usd>",
+        title: "Max spend budget (USD)",
+        description: "Cap intent budget max_spend_usd only",
+        parameterized: true,
+    },
+];
+function normalizeGuardrailToken(token) {
+    return token.trim().toLowerCase().replace(/_/g, "-");
+}
+function parsePositiveNumber(raw, label) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${label} requires a non-negative number`);
+    }
+    return value;
+}
+/** Resolve a solution-manifest guardrail token (for example `max_spend_usd_200`). */
+export function resolveGuardrailManifestToken(token) {
+    const trimmed = token.trim();
+    const manifestUsd = /^max_spend_usd_(\d+(?:\.\d+)?)$/i.exec(trimmed);
+    if (manifestUsd) {
+        return maxSpendUsd(parsePositiveNumber(manifestUsd[1], "max_spend_usd"));
+    }
+    return parseGuardrailSpec(trimmed);
+}
+/** Parse one guardrail token from CLI `--guardrails` or solution manifests. */
+export function parseGuardrailSpec(spec) {
+    const normalized = normalizeGuardrailToken(spec);
+    if (!normalized) {
+        throw new Error("guardrail spec must not be empty");
+    }
+    const maxSpendMatch = /^max-spend:(\d+(?:\.\d+)?)$/.exec(normalized);
+    if (maxSpendMatch) {
+        const usd = parsePositiveNumber(maxSpendMatch[1], "max-spend");
+        return {
+            caps: {
+                budgetMaxSpendUsd: usd,
+                sideEffectingMaxSpendCents: Math.round(usd * 100),
+            },
+        };
+    }
+    const maxSpendUsdMatch = /^max-spend-usd:(\d+(?:\.\d+)?)$/.exec(normalized);
+    if (maxSpendUsdMatch) {
+        return maxSpendUsd(parsePositiveNumber(maxSpendUsdMatch[1], "max-spend-usd"));
+    }
+    const maxSpendCentsMatch = /^max-spend-cents:(\d+)$/.exec(normalized);
+    if (maxSpendCentsMatch) {
+        return maxSpend(parsePositiveNumber(maxSpendCentsMatch[1], "max-spend-cents"));
+    }
+    switch (normalized) {
+        case "default-deny":
+        case "defaultdeny":
+            return defaultDeny();
+        case "read-only":
+        case "readonly":
+            return readOnly();
+        case "read-only-search":
+        case "readonlysearch":
+            return readOnlySearch();
+        case "strict":
+            return strict();
+        case "require-evidence":
+        case "requireevidence":
+            return requireEvidence();
+        case "audit-only":
+        case "auditonly":
+            return auditOnly();
+        case "allow-dry-run":
+        case "allowdryrun":
+            return allowDryRun();
+        default:
+            throw new Error(`unknown guardrail: ${spec}`);
+    }
+}
+/** Parse a comma-separated guardrail spec list from CLI flags. */
+export function parseGuardrailSpecs(csv) {
+    const tokens = csv
+        .split(",")
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+    if (tokens.length === 0) {
+        throw new Error("guardrails list must include at least one entry");
+    }
+    return tokens.map((token) => parseGuardrailSpec(token));
+}
+export function listGuardrailCatalogEntries() {
+    return [...GUARDRAIL_CATALOG_ENTRIES];
+}
+export { guardrails };

package/dist/policy/guardrails.d.ts

@@ -0,0 +1,48 @@
+import type { PaybondPolicyIntentSection, PaybondPolicyToolEntry } from "./schema.js";
+/** Partial policy patch applied on top of a domain document during compose. */
+export type PolicyGuardrailLayer = {
+    default_deny?: boolean;
+    tools?: Record<string, Partial<PaybondPolicyToolEntry>>;
+    intent?: Partial<PaybondPolicyIntentSection>;
+    filters?: {
+        readOnly?: boolean;
+        readOnlySearch?: boolean;
+    };
+    caps?: {
+        sideEffectingMaxSpendCents?: number;
+        budgetMaxSpendUsd?: number;
+    };
+    requireEvidence?: boolean;
+};
+/** Require `default_deny: true` (stricter wins when stacked). */
+export declare function defaultDeny(): PolicyGuardrailLayer;
+/** Cap every side-effecting tool at `cents` (stricter min wins when stacked). */
+export declare function maxSpend(cents: number): PolicyGuardrailLayer;
+/** Cap intent budget at `usd` dollars (stricter min wins when stacked). */
+export declare function maxSpendUsd(usd: number): PolicyGuardrailLayer;
+/** Keep only non-side-effecting tools and intersect allowed_tools. */
+export declare function readOnly(): PolicyGuardrailLayer;
+/** Keep only non-side-effecting search.* tools. */
+export declare function readOnlySearch(): PolicyGuardrailLayer;
+/** Tight caps, default deny, and evidence required on side-effecting tools. */
+export declare function strict(): PolicyGuardrailLayer;
+/** Governance hook: validate evidence presets at compose time (no extra fields). */
+export declare function requireEvidence(): PolicyGuardrailLayer;
+/** Governance hook reserved for audit-only execution modes (no-op layer today). */
+export declare function auditOnly(): PolicyGuardrailLayer;
+/** Governance hook reserved for dry-run modes (no-op layer today). */
+export declare function allowDryRun(): PolicyGuardrailLayer;
+/** Convert a bundled guardrails YAML object into a compose layer. */
+export declare function guardrailLayerFromDocument(document: Record<string, unknown>): PolicyGuardrailLayer;
+export declare const guardrails: {
+    readonly defaultDeny: typeof defaultDeny;
+    readonly maxSpend: typeof maxSpend;
+    readonly maxSpendUsd: typeof maxSpendUsd;
+    readonly readOnly: typeof readOnly;
+    readonly readOnlySearch: typeof readOnlySearch;
+    readonly strict: typeof strict;
+    readonly requireEvidence: typeof requireEvidence;
+    readonly auditOnly: typeof auditOnly;
+    readonly allowDryRun: typeof allowDryRun;
+    readonly fromDocument: typeof guardrailLayerFromDocument;
+};

package/dist/policy/guardrails.js

@@ -0,0 +1,72 @@
+/** Require `default_deny: true` (stricter wins when stacked). */
+export function defaultDeny() {
+    return { default_deny: true };
+}
+/** Cap every side-effecting tool at `cents` (stricter min wins when stacked). */
+export function maxSpend(cents) {
+    if (!Number.isInteger(cents) || cents < 0) {
+        throw new Error("maxSpend requires a non-negative integer cents value");
+    }
+    return { caps: { sideEffectingMaxSpendCents: cents } };
+}
+/** Cap intent budget at `usd` dollars (stricter min wins when stacked). */
+export function maxSpendUsd(usd) {
+    if (typeof usd !== "number" || usd < 0 || !Number.isFinite(usd)) {
+        throw new Error("maxSpendUsd requires a non-negative finite USD value");
+    }
+    return { caps: { budgetMaxSpendUsd: usd } };
+}
+/** Keep only non-side-effecting tools and intersect allowed_tools. */
+export function readOnly() {
+    return { filters: { readOnly: true } };
+}
+/** Keep only non-side-effecting search.* tools. */
+export function readOnlySearch() {
+    return { filters: { readOnlySearch: true } };
+}
+/** Tight caps, default deny, and evidence required on side-effecting tools. */
+export function strict() {
+    return {
+        default_deny: true,
+        caps: { sideEffectingMaxSpendCents: 1000, budgetMaxSpendUsd: 10 },
+        requireEvidence: true,
+    };
+}
+/** Governance hook: validate evidence presets at compose time (no extra fields). */
+export function requireEvidence() {
+    return { requireEvidence: true };
+}
+/** Governance hook reserved for audit-only execution modes (no-op layer today). */
+export function auditOnly() {
+    return {};
+}
+/** Governance hook reserved for dry-run modes (no-op layer today). */
+export function allowDryRun() {
+    return {};
+}
+/** Convert a bundled guardrails YAML object into a compose layer. */
+export function guardrailLayerFromDocument(document) {
+    const layer = {};
+    if (document.default_deny === true) {
+        layer.default_deny = true;
+    }
+    if (document.tools && typeof document.tools === "object" && !Array.isArray(document.tools)) {
+        layer.tools = document.tools;
+    }
+    if (document.intent && typeof document.intent === "object" && !Array.isArray(document.intent)) {
+        layer.intent = document.intent;
+    }
+    return layer;
+}
+export const guardrails = {
+    defaultDeny,
+    maxSpend,
+    maxSpendUsd,
+    readOnly,
+    readOnlySearch,
+    strict,
+    requireEvidence,
+    auditOnly,
+    allowDryRun,
+    fromDocument: guardrailLayerFromDocument,
+};

package/dist/policy/index.d.ts

@@ -0,0 +1,21 @@
+export { canonicalPolicyDocumentDigest, policyDocumentToDict, policyVersionLabel, } from "./digest.js";
+export { PaybondPolicy, type PaybondPolicyLoadSource, type PaybondPolicyLoadEffectiveResult } from "./load.js";
+export { isKnownPolicyPresetId, isLayeredPolicyPresetId, listPolicyPresetIds, readPolicyPresetYaml, resolveComposedPresetDocument, resolvePolicyPresetPath, type LayeredPolicyPresetId, type PolicyPresetId, } from "./presets.js";
+export { assertLayeredPresetMatchesFlat, bundledDefaultGuardrails, composeBundledPresetDefault, composeLayeredPolicyPresetDocument, composePolicyLayers, composePolicyPresetLayers, isLayeredPolicyPreset, LAYERED_POLICY_PRESET_IDS, } from "./compose.js";
+export { domain } from "./domain.js";
+export { auditOnly, allowDryRun, defaultDeny, guardrailLayerFromDocument, guardrails, maxSpend, maxSpendUsd, readOnly, readOnlySearch, requireEvidence, strict, type PolicyGuardrailLayer, } from "./guardrails.js";
+export { paybondPolicyPresets, type PaybondPolicyPresets, type VerticalPolicyOptions } from "./policy-api.js";
+export { createPolicySnapshot, createPolicySnapshotFromEffective, type CreatePolicySnapshotInput, type PaybondPolicySnapshot, type PaybondPolicySnapshotSource, } from "./snapshot.js";
+export { parsePolicyExtendsRef, renderOrgBasePolicyYaml, renderPaybondPolicyYaml, renderTenantOverlayPolicyYaml, scaffoldOrgBasePolicy, scaffoldPaybondPolicy, scaffoldPolicyFromPreset, scaffoldTenantOverlayPolicy, type ScaffoldOrgBasePolicyOptions, type ScaffoldPaybondPolicyOptions, type ScaffoldPolicyFromPresetOptions, type ScaffoldTenantOverlayPolicyOptions, } from "./init.js";
+export { PaybondPolicyIntentSpecError, policyToIntentCreateInput, type PaybondPolicyIntentCreateInput, type PaybondPolicyIntentCreateOverrides, } from "./intent-spec.js";
+export { PaybondPolicySandboxBootstrapError, policySandboxBootstrap, type PaybondPolicySandboxBootstrapOptions, } from "./sandbox-bootstrap.js";
+export { resolveJsonPath, resolveSpendCentsFromJsonPath } from "./json-path.js";
+export { parsePolicyDocumentText } from "./parse-text.js";
+export { policyDocumentToToolRegistryConfig, policyToToolRegistry, } from "./registry.js";
+export { mergePaybondPolicies, toEffectivePolicyDocument, type PolicyMergeDeniedWidening, type PolicyMergeOptions, type PolicyMergeReport, type PolicyMergeResult, } from "./merge.js";
+export { PAYBOND_POLICY_SCHEMA_VERSION, PAYBOND_POLICY_SCHEMA_VERSION_V2, PaybondPolicyValidationError, isPaybondPolicyDocumentV1, isPaybondPolicyDocumentV2, isPaybondPolicyOverlay, parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1, parsePaybondPolicyDocumentV2, paybondPolicyDocumentV1Schema, paybondPolicyDocumentV2Schema, type PaybondPolicyBinding, type PaybondPolicyBindingOverride, type PaybondPolicyBudget, type PaybondPolicyDocument, type PaybondPolicyDocumentV1, type PaybondPolicyDocumentV2, type PaybondPolicyExtends, type PaybondPolicyIntentOverrideSection, type PaybondPolicyIntentSection, type PaybondPolicyOverrides, type PaybondPolicyToolEntry, type PaybondPolicyToolOverrideEntry, type PaybondPolicyValidationIssue, } from "./schema.js";
+export { PolicyValidator, type PolicyGatewayTemplateLookup, type PolicyValidatorError, type PolicyValidatorOptions, type PolicyValidatorResult, type PolicyValidatorToolCounts, } from "./validate.js";
+export { parsePolicyRemoteValidateResponse, policyRemoteValidateResultToDict, policyValidateQueryString, validatePolicyPayloadRemote, validatePolicyRemote, type PolicyRemoteValidateCheck, type PolicyRemoteValidateClient, type PolicyRemoteValidateIssue, type PolicyRemoteValidateOptions, type PolicyRemoteValidateResult, } from "./validate-remote.js";
+export { parseMergeReport, parsePolicyEffectiveResolveResponse, resolvePolicyEffectiveRemote, type PolicyEffectiveResolveClient, type PolicyEffectiveResolveResult, } from "./load-effective.js";
+export { PaybondPolicyReloadController, type PaybondPolicyReloadControllerState, type PolicyReloadRunner, } from "./watcher.js";
+export { PaybondPolicyReloadError, PaybondPolicyReloadUnchangedError, applyPolicySnapshotToRun, detectPolicyLoosening, loadPolicySnapshotFromEffectivePoll, loadPolicySnapshotFromFile, reloadPolicyOnHandle, reloadPolicyOnRun, requiresIntentRebind, type PaybondPolicyReloadBindConfig, type PaybondPolicyReloadFailedEvent, type PaybondPolicyReloadOptions, type PaybondPolicyReloadResult, type PaybondPolicyReloadedEvent, type PolicyReloadHandle, } from "./reload.js";

package/dist/policy/index.js

@@ -0,0 +1,21 @@
+export { canonicalPolicyDocumentDigest, policyDocumentToDict, policyVersionLabel, } from "./digest.js";
+export { PaybondPolicy } from "./load.js";
+export { isKnownPolicyPresetId, isLayeredPolicyPresetId, listPolicyPresetIds, readPolicyPresetYaml, resolveComposedPresetDocument, resolvePolicyPresetPath, } from "./presets.js";
+export { assertLayeredPresetMatchesFlat, bundledDefaultGuardrails, composeBundledPresetDefault, composeLayeredPolicyPresetDocument, composePolicyLayers, composePolicyPresetLayers, isLayeredPolicyPreset, LAYERED_POLICY_PRESET_IDS, } from "./compose.js";
+export { domain } from "./domain.js";
+export { auditOnly, allowDryRun, defaultDeny, guardrailLayerFromDocument, guardrails, maxSpend, maxSpendUsd, readOnly, readOnlySearch, requireEvidence, strict, } from "./guardrails.js";
+export { paybondPolicyPresets } from "./policy-api.js";
+export { createPolicySnapshot, createPolicySnapshotFromEffective, } from "./snapshot.js";
+export { parsePolicyExtendsRef, renderOrgBasePolicyYaml, renderPaybondPolicyYaml, renderTenantOverlayPolicyYaml, scaffoldOrgBasePolicy, scaffoldPaybondPolicy, scaffoldPolicyFromPreset, scaffoldTenantOverlayPolicy, } from "./init.js";
+export { PaybondPolicyIntentSpecError, policyToIntentCreateInput, } from "./intent-spec.js";
+export { PaybondPolicySandboxBootstrapError, policySandboxBootstrap, } from "./sandbox-bootstrap.js";
+export { resolveJsonPath, resolveSpendCentsFromJsonPath } from "./json-path.js";
+export { parsePolicyDocumentText } from "./parse-text.js";
+export { policyDocumentToToolRegistryConfig, policyToToolRegistry, } from "./registry.js";
+export { mergePaybondPolicies, toEffectivePolicyDocument, } from "./merge.js";
+export { PAYBOND_POLICY_SCHEMA_VERSION, PAYBOND_POLICY_SCHEMA_VERSION_V2, PaybondPolicyValidationError, isPaybondPolicyDocumentV1, isPaybondPolicyDocumentV2, isPaybondPolicyOverlay, parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1, parsePaybondPolicyDocumentV2, paybondPolicyDocumentV1Schema, paybondPolicyDocumentV2Schema, } from "./schema.js";
+export { PolicyValidator, } from "./validate.js";
+export { parsePolicyRemoteValidateResponse, policyRemoteValidateResultToDict, policyValidateQueryString, validatePolicyPayloadRemote, validatePolicyRemote, } from "./validate-remote.js";
+export { parseMergeReport, parsePolicyEffectiveResolveResponse, resolvePolicyEffectiveRemote, } from "./load-effective.js";
+export { PaybondPolicyReloadController, } from "./watcher.js";
+export { PaybondPolicyReloadError, PaybondPolicyReloadUnchangedError, applyPolicySnapshotToRun, detectPolicyLoosening, loadPolicySnapshotFromEffectivePoll, loadPolicySnapshotFromFile, reloadPolicyOnHandle, reloadPolicyOnRun, requiresIntentRebind, } from "./reload.js";

package/dist/policy/init.d.ts

@@ -0,0 +1,102 @@
+import { type LayeredPolicyPresetId } from "./compose.js";
+import { type PolicyPresetId } from "./presets.js";
+export type ScaffoldPaybondPolicyOptions = {
+    out: string;
+    operation: string;
+    evidencePreset: string;
+    force?: boolean;
+};
+export type ScaffoldPolicyFromPresetOptions = {
+    out: string;
+    presetId: PolicyPresetId;
+    /** Intent budget and side-effecting tool cap override in USD. */
+    maxSpendUsd?: number;
+    force?: boolean;
+};
+export type ScaffoldComposedPolicyOptions = {
+    out: string;
+    domainId: LayeredPolicyPresetId;
+    guardrails: string;
+    force?: boolean;
+};
+export type ScaffoldOrgBasePolicyOptions = {
+    out: string;
+    policyId: string;
+    operation: string;
+    evidencePreset: string;
+    maxSpendCents?: number;
+    force?: boolean;
+};
+export type ScaffoldTenantOverlayPolicyOptions = {
+    out: string;
+    extendsRef: string;
+    name?: string;
+    operation?: string;
+    evidencePreset?: string;
+    basePolicy?: string;
+    force?: boolean;
+};
+/** Parse `org_id/org_policy_id` extends reference used by CLI and docs. */
+export declare function parsePolicyExtendsRef(ref: string): {
+    orgId: string;
+    orgPolicyId: string;
+};
+/** Render a starter paybond.policy.yaml document. */
+export declare function renderPaybondPolicyYaml(options: ScaffoldPaybondPolicyOptions): string;
+/** Render a v2 org base policy document (no extends). */
+export declare function renderOrgBasePolicyYaml(options: ScaffoldOrgBasePolicyOptions): string;
+/** Write a v2 org base policy file for platform operators. */
+export declare function scaffoldOrgBasePolicy(options: ScaffoldOrgBasePolicyOptions): Promise<{
+    out: string;
+    policy_id: string;
+    operation: string;
+    evidence_preset: string;
+    bytes_written: number;
+}>;
+/** Render a v2 tenant overlay policy that extends an org base. */
+export declare function renderTenantOverlayPolicyYaml(options: ScaffoldTenantOverlayPolicyOptions): string;
+/** Write a v2 tenant overlay policy file extending an org base. */
+export declare function scaffoldTenantOverlayPolicy(options: ScaffoldTenantOverlayPolicyOptions): Promise<{
+    out: string;
+    name: string;
+    org_id: string;
+    org_policy_id: string;
+    operation?: string;
+    evidence_preset?: string;
+    bytes_written: number;
+}>;
+/** Render a bundled preset as editable local YAML with a scaffold header comment. */
+export declare function renderPolicyPresetScaffoldYaml(presetId: PolicyPresetId, options?: {
+    maxSpendUsd?: number;
+}): string;
+/** Render a composed domain + guardrails policy as editable local YAML. */
+export declare function renderComposedPolicyScaffoldYaml(options: ScaffoldComposedPolicyOptions): string;
+/** Preview composed domain + guardrails YAML for `paybond policy presets show`. */
+export declare function renderComposedPolicyPreviewYaml(options: Pick<ScaffoldComposedPolicyOptions, "domainId" | "guardrails">): string;
+/** Preview composed policy YAML for `paybond policy presets show`. */
+export declare function renderPolicyPresetPreviewYaml(presetId: PolicyPresetId, options?: {
+    maxSpendUsd?: number;
+}): string;
+/** Write a bundled vertical preset to an owned local policy file. */
+export declare function scaffoldPolicyFromPreset(options: ScaffoldPolicyFromPresetOptions): Promise<{
+    out: string;
+    preset: string;
+    name: string;
+    bytes_written: number;
+}>;
+/** Write a composed domain + guardrails policy file. */
+export declare function scaffoldComposedPolicy(options: ScaffoldComposedPolicyOptions): Promise<{
+    out: string;
+    domain: string;
+    guardrails: string;
+    name: string;
+    bytes_written: number;
+}>;
+/** Write a starter paybond.policy.yaml file. */
+export declare function scaffoldPaybondPolicy(options: ScaffoldPaybondPolicyOptions): Promise<{
+    out: string;
+    name: string;
+    operation: string;
+    evidence_preset: string;
+    bytes_written: number;
+}>;