@paybond/kit 0.9.8 → 0.11.0

package/dist/policy/validate.d.ts

@@ -0,0 +1,36 @@
+import type { PaybondPolicyLoadSource } from "./load.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+export type PolicyValidatorError = {
+    path: string;
+    code: string;
+    message: string;
+};
+export type PolicyValidatorToolCounts = {
+    side_effecting: number;
+    read_only: number;
+};
+export type PolicyValidatorResult = {
+    valid: boolean;
+    policy_name: string | null;
+    tools: PolicyValidatorToolCounts;
+    errors: PolicyValidatorError[];
+};
+export type PolicyGatewayTemplateLookup = {
+    listTemplateIds(): Promise<string[]>;
+};
+export type PolicyValidatorOptions = {
+    /** When true, side-effecting tools must appear in intent.allowed_tools when that list is set. */
+    strict?: boolean;
+    /** Verify intent.policy_binding.template_id against the Harbor template catalog. */
+    checkGateway?: boolean;
+    gateway?: PolicyGatewayTemplateLookup;
+};
+/** Client-side policy alignment checks before deploy or agent bind. */
+export declare class PolicyValidator {
+    /** True when `PAYBOND_POLICY_STRICT=1`. */
+    static isStrictFromEnv(): boolean;
+    /** Validate a loaded or raw policy source. */
+    static validate(source: PaybondPolicyLoadSource, options?: PolicyValidatorOptions): Promise<PolicyValidatorResult>;
+    /** Validate an already-parsed policy document (and optional gateway checks). */
+    static validateDocument(document: PaybondPolicyDocumentV1, options?: PolicyValidatorOptions): Promise<PolicyValidatorResult>;
+}

package/dist/policy/validate.js

@@ -0,0 +1,150 @@
+import { getCompletionPreset, listCompletionPresetIds, } from "../completion-catalog.js";
+import { isVendorPack } from "../completion-resolve.js";
+import { PaybondPolicy } from "./load.js";
+import { PaybondPolicyValidationError, } from "./schema.js";
+function issueToError(issue) {
+    return {
+        path: issue.path,
+        code: issue.code,
+        message: issue.message,
+    };
+}
+function pushError(errors, path, code, message) {
+    errors.push({ path, code, message });
+}
+function countTools(document) {
+    let sideEffecting = 0;
+    let readOnly = 0;
+    for (const entry of Object.values(document.tools)) {
+        if (entry.side_effecting) {
+            sideEffecting += 1;
+        }
+        else {
+            readOnly += 1;
+        }
+    }
+    return { side_effecting: sideEffecting, read_only: readOnly };
+}
+function catalogHasPreset(presetId) {
+    return listCompletionPresetIds().includes(presetId);
+}
+function validatePresetReference(errors, toolName, presetId) {
+    if (!catalogHasPreset(presetId)) {
+        pushError(errors, `tools.${toolName}.evidence_preset`, "policy.unknown_evidence_preset", `unknown completion preset: ${presetId}`);
+        return;
+    }
+    try {
+        getCompletionPreset(presetId);
+    }
+    catch {
+        pushError(errors, `tools.${toolName}.evidence_preset`, "policy.unknown_evidence_preset", `unknown completion preset: ${presetId}`);
+    }
+}
+function validateVendorPackReference(errors, toolName, vendorPackId) {
+    let preset;
+    try {
+        preset = getCompletionPreset(vendorPackId);
+    }
+    catch {
+        pushError(errors, `tools.${toolName}.vendor_pack`, "policy.unknown_vendor_pack", `unknown vendor pack preset: ${vendorPackId}`);
+        return;
+    }
+    if (!isVendorPack(preset)) {
+        pushError(errors, `tools.${toolName}.vendor_pack`, "policy.invalid_vendor_pack", `preset ${vendorPackId} is not a vendor_pack entry`);
+    }
+}
+function validateIntentAlignment(document, errors, strict) {
+    const allowedTools = document.intent?.allowed_tools;
+    if (!allowedTools || allowedTools.length === 0) {
+        return;
+    }
+    const registered = new Set(Object.keys(document.tools));
+    for (const toolName of allowedTools) {
+        if (!registered.has(toolName)) {
+            pushError(errors, `intent.allowed_tools`, "policy.allowed_tool_not_registered", `allowed tool "${toolName}" is not declared in tools`);
+        }
+    }
+    if (!strict || !document.default_deny) {
+        return;
+    }
+    const allowed = new Set(allowedTools);
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        if (entry.side_effecting && !allowed.has(toolName)) {
+            pushError(errors, `tools.${toolName}`, "policy.side_effecting_not_allowed", `side-effecting tool "${toolName}" is missing from intent.allowed_tools (default_deny is true)`);
+        }
+    }
+}
+function validateToolEntries(document, errors) {
+    for (const [toolName, entry] of Object.entries(document.tools)) {
+        if (entry.side_effecting) {
+            if (!entry.evidence_preset) {
+                pushError(errors, `tools.${toolName}.evidence_preset`, "policy.missing_evidence_preset", "side-effecting tools must declare evidence_preset");
+            }
+            else {
+                validatePresetReference(errors, toolName, entry.evidence_preset);
+            }
+        }
+        else if (entry.evidence_preset) {
+            validatePresetReference(errors, toolName, entry.evidence_preset);
+        }
+        if (entry.vendor_pack) {
+            validateVendorPackReference(errors, toolName, entry.vendor_pack);
+        }
+    }
+}
+async function validateGatewayTemplate(document, errors, gateway) {
+    const templateId = document.intent?.policy_binding?.template_id;
+    if (!templateId) {
+        return;
+    }
+    const templateIds = await gateway.listTemplateIds();
+    if (!templateIds.includes(templateId)) {
+        pushError(errors, "intent.policy_binding.template_id", "policy.unknown_policy_template", `policy template "${templateId}" was not found in the Harbor catalog`);
+    }
+}
+function validateDocumentSync(document, options = {}) {
+    const strict = options.strict ?? PolicyValidator.isStrictFromEnv();
+    const errors = [];
+    validateToolEntries(document, errors);
+    validateIntentAlignment(document, errors, strict);
+    return {
+        valid: errors.length === 0,
+        policy_name: document.name,
+        tools: countTools(document),
+        errors,
+    };
+}
+/** Client-side policy alignment checks before deploy or agent bind. */
+export class PolicyValidator {
+    /** True when `PAYBOND_POLICY_STRICT=1`. */
+    static isStrictFromEnv() {
+        return process.env.PAYBOND_POLICY_STRICT === "1";
+    }
+    /** Validate a loaded or raw policy source. */
+    static async validate(source, options = {}) {
+        try {
+            const policy = await PaybondPolicy.load(source);
+            return PolicyValidator.validateDocument(policy.document, options);
+        }
+        catch (err) {
+            if (err instanceof PaybondPolicyValidationError) {
+                return {
+                    valid: false,
+                    policy_name: null,
+                    tools: { side_effecting: 0, read_only: 0 },
+                    errors: err.issues.map(issueToError),
+                };
+            }
+            throw err;
+        }
+    }
+    /** Validate an already-parsed policy document (and optional gateway checks). */
+    static async validateDocument(document, options = {}) {
+        const result = validateDocumentSync(document, options);
+        if (options.checkGateway && options.gateway) {
+            await validateGatewayTemplate(document, result.errors, options.gateway);
+            result.valid = result.errors.length === 0;
+        }
+        return result;
+    }
+}

package/dist/policy/watcher.d.ts

@@ -0,0 +1,29 @@
+import { type PaybondPolicyReloadBindConfig, type PaybondPolicyReloadOptions, type PaybondPolicyReloadResult } from "./reload.js";
+/** Minimal reload surface for background watch/poll schedulers. */
+export type PolicyReloadRunner = {
+    reloadPolicy(options?: PaybondPolicyReloadOptions): Promise<PaybondPolicyReloadResult>;
+};
+export type PaybondPolicyReloadControllerState = {
+    watch: boolean;
+    poll: boolean;
+    policyFilePath?: string;
+    lastReloadAt?: string;
+    lastReloadError?: string;
+};
+/** Background file watcher and Gateway poll scheduler for policy hot-reload. */
+export declare class PaybondPolicyReloadController {
+    private readonly runner;
+    private fileWatcher;
+    private pollTimer;
+    private debounceTimer;
+    private reloadInFlight;
+    private readonly policyFilePath;
+    private readonly reloadDefaults;
+    readonly state: PaybondPolicyReloadControllerState;
+    private constructor();
+    static start(runner: PolicyReloadRunner, config: PaybondPolicyReloadBindConfig, policyFilePath: string): PaybondPolicyReloadController | undefined;
+    private startFileWatch;
+    private startGatewayPoll;
+    private triggerReload;
+    stop(): void;
+}

package/dist/policy/watcher.js

@@ -0,0 +1,112 @@
+import { watch } from "node:fs";
+import { resolve } from "node:path";
+const DEFAULT_WATCH_DEBOUNCE_MS = 500;
+const DEFAULT_POLL_INTERVAL_MS = 60_000;
+/** Background file watcher and Gateway poll scheduler for policy hot-reload. */
+export class PaybondPolicyReloadController {
+    runner;
+    fileWatcher;
+    pollTimer;
+    debounceTimer;
+    reloadInFlight = false;
+    policyFilePath;
+    reloadDefaults;
+    state;
+    constructor(runner, options) {
+        this.runner = runner;
+        this.policyFilePath = options.policyFilePath;
+        this.reloadDefaults = options.reloadDefaults;
+        this.state = options.state;
+    }
+    static start(runner, config, policyFilePath) {
+        const watchEnabled = config.watch === true || typeof config.watch === "object";
+        const pollEnabled = config.poll !== undefined;
+        if (!watchEnabled && !pollEnabled) {
+            return undefined;
+        }
+        const resolvedPath = resolve(policyFilePath);
+        const reloadDefaults = {
+            file: resolvedPath,
+            remote: config.poll?.remote,
+            resolveInheritance: config.poll?.resolveInheritance,
+            gateway: config.poll?.gateway,
+        };
+        const controller = new PaybondPolicyReloadController(runner, {
+            policyFilePath: resolvedPath,
+            reloadDefaults,
+            state: {
+                watch: watchEnabled,
+                poll: pollEnabled,
+                policyFilePath: resolvedPath,
+            },
+        });
+        if (watchEnabled) {
+            controller.startFileWatch(config.watch);
+        }
+        if (pollEnabled) {
+            controller.startGatewayPoll(config.poll ?? {});
+        }
+        return controller;
+    }
+    startFileWatch(watchConfig) {
+        const debounceMs = typeof watchConfig === "object" && watchConfig.debounceMs !== undefined
+            ? watchConfig.debounceMs
+            : DEFAULT_WATCH_DEBOUNCE_MS;
+        this.fileWatcher = watch(this.policyFilePath, () => {
+            if (this.debounceTimer) {
+                clearTimeout(this.debounceTimer);
+            }
+            this.debounceTimer = setTimeout(() => {
+                void this.triggerReload({ remote: false });
+            }, debounceMs);
+        });
+    }
+    startGatewayPoll(pollConfig) {
+        const intervalMs = pollConfig.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.pollTimer = setInterval(() => {
+            void this.triggerReload({
+                remote: pollConfig.remote ?? true,
+                resolveInheritance: pollConfig.resolveInheritance ?? true,
+                gateway: pollConfig.gateway ?? this.reloadDefaults.gateway,
+            });
+        }, intervalMs);
+    }
+    async triggerReload(overrides) {
+        if (this.reloadInFlight) {
+            return;
+        }
+        this.reloadInFlight = true;
+        try {
+            const result = await this.runner.reloadPolicy({
+                ...this.reloadDefaults,
+                ...overrides,
+                file: this.policyFilePath,
+            });
+            if (result.applied) {
+                this.state.lastReloadAt = new Date().toISOString();
+                this.state.lastReloadError = undefined;
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.state.lastReloadError = message;
+        }
+        finally {
+            this.reloadInFlight = false;
+        }
+    }
+    stop() {
+        if (this.fileWatcher) {
+            this.fileWatcher.close();
+            this.fileWatcher = undefined;
+        }
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+    }
+}

package/dist/principal-intent.d.ts

@@ -4,11 +4,19 @@
  */
 /** Tenant-configured settlement rail names. Clients may request a rail, not a destination. */
 export type SettlementRail = "stripe_connect" | "stripe_ach_debit" | "x402_usdc_base";
+export type CompletionContractSnapshot = {
+    completionPresetId: string;
+    vendorContractProvider?: string;
+    vendorApiVersion?: string;
+    vendorSchemaDigestHex?: string;
+    canonicalSchemaDigestHex: string;
+};
 export declare function intentCreationSignBytesRaw(input: {
     tenantId: string;
     intentId: string;
     principalDid: string;
     payeeDid: string;
+    payeePubkeyBytes: Uint8Array;
     amountCents: number;
     currency: string;
     deadlineRfc3339: string;
@@ -18,13 +26,55 @@ export declare function intentCreationSignBytesRaw(input: {
     predicateRef: string;
     allowedTools: string[];
     settlementRail: SettlementRail;
+    completionContract?: CompletionContractSnapshot;
 }): Uint8Array;
+export type PolicyBindingRef = {
+    templateId: string;
+    versionSeq: number;
+};
+export type PublishedPolicyHead = {
+    templateId: string;
+    versionSeq: number;
+    materializedPredicate: Record<string, unknown>;
+    policyContentDigestHex: string;
+};
+/** Bincode payload for managed-policy intent creation (wire format revision byte `5`). */
+export declare function intentCreationSignBytesWithPolicyBinding(input: {
+    tenantId: string;
+    intentId: string;
+    principalDid: string;
+    payeeDid: string;
+    payeePubkeyBytes: Uint8Array;
+    amountCents: number;
+    currency: string;
+    deadlineRfc3339: string;
+    budget: Record<string, unknown>;
+    evidenceSchema: Record<string, unknown>;
+    materializedPredicate: Record<string, unknown>;
+    predicateRef: string;
+    allowedTools: string[];
+    settlementRail: SettlementRail;
+    policyBinding: PolicyBindingRef;
+    policyContentDigestHex: string;
+    completionContract?: CompletionContractSnapshot;
+}): Uint8Array;
+export type BuildSignedCreateIntentWithPolicyBindingParams = Omit<BuildSignedCreateIntentParams, "predicate"> & {
+    policyBinding: PolicyBindingRef;
+    publishedPolicyHead: PublishedPolicyHead;
+    completionPresetId?: string;
+    completionContract?: CompletionContractSnapshot;
+};
+/**
+ * Build a Harbor `POST /intents` JSON body with signing v5 and a published managed-policy head.
+ */
+export declare function buildSignedCreateIntentBodyWithPolicyBinding(params: BuildSignedCreateIntentWithPolicyBindingParams): Record<string, unknown>;
 export type BuildSignedCreateIntentParams = {
     tenantId: string;
     intentId: string;
     principalDid: string;
     principalSigningSeed: Uint8Array;
     payeeDid: string;
+    payeeSigningSeed: Uint8Array;
     budget: Record<string, unknown>;
     predicate: Record<string, unknown>;
     currency: string;
@@ -35,6 +85,8 @@ export type BuildSignedCreateIntentParams = {
     predicateRef?: string;
     /** Rail request for the new intent. Harbor resolves the destination server-side. */
     settlementRail: SettlementRail;
+    completionPresetId?: string;
+    completionContract?: CompletionContractSnapshot;
 };
 /**
  * Build a Harbor `POST /intents` JSON body with principal Ed25519 detached signature.