@verax-ai/proxy 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,37 @@
+import type { Policy } from "./types.ts";
+export type PolicySpend = {
+    maxAmountMinor: number;
+    currency: string;
+    payees: readonly string[];
+    dailyMaxMinor?: number;
+    /** Statement stamps for this payee. Optional; never guessed. */
+    descriptors?: readonly string[];
+};
+export type PolicyRule = {
+    id: string;
+    tool: string;
+    requires: readonly string[];
+    text: string;
+    mode?: "allow" | "approve";
+    spend?: PolicySpend;
+    egress?: true;
+};
+export type PolicyDocument = {
+    version: 1;
+    default: "deny";
+    approvalTtlMs?: number;
+    egress?: readonly string[];
+    /** Body-wide: a call with no `_inputs` key is deny inputs-required. */
+    requireInputs?: true;
+    limits?: {
+        ratePerMinute?: number;
+        dailyMax?: number;
+        diskFreeBytes?: number;
+    };
+    rules: PolicyRule[];
+};
+/** Named per tool. Do not sniff `host` / `url` on arbitrary arguments. */
+export declare const HOST_EXTRACTORS: Record<string, (args: Record<string, unknown>) => string | undefined>;
+export declare function parsePolicyDocument(json: unknown): PolicyDocument;
+export declare function ruleTextHash(text: string): string;
+export declare function loadPolicy(json: unknown): Policy;

package/dist/policy.js

@@ -0,0 +1,265 @@
+import { parseIJson } from "@cedulon/core";
+import { defaultDiskFreeBytes } from "./disk.js";
+import { sha256Canonical } from "./hash.js";
+/** Named per tool. Do not sniff `host` / `url` on arbitrary arguments. */
+export const HOST_EXTRACTORS = {
+    "message.send": (args) => {
+        const to = args.to;
+        if (typeof to !== "string" || to === "")
+            return undefined;
+        const at = to.lastIndexOf("@");
+        if (at < 0)
+            return undefined;
+        const host = to.slice(at + 1).trim().toLowerCase();
+        if (host === "" || host.includes("/") || host.includes(" "))
+            return undefined;
+        return host;
+    },
+};
+const DEFAULT_APPROVAL_TTL_MS = 86_400_000;
+function asRule(raw, index) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`policy-rule-invalid:${index}`);
+    }
+    const rec = raw;
+    if (typeof rec.id !== "string" || rec.id === "") {
+        throw new Error(`policy-rule-id:${index}`);
+    }
+    if (typeof rec.tool !== "string" || rec.tool === "") {
+        throw new Error(`policy-rule-tool:${rec.id}`);
+    }
+    if (!Array.isArray(rec.requires) || rec.requires.some((s) => typeof s !== "string" || s === "")) {
+        throw new Error(`policy-rule-requires:${rec.id}`);
+    }
+    if (typeof rec.text !== "string" || rec.text.trim() === "") {
+        throw new Error(`policy-rule-text:${rec.id}`);
+    }
+    const rule = {
+        id: rec.id,
+        tool: rec.tool,
+        requires: rec.requires,
+        text: rec.text,
+    };
+    if (rec.mode !== undefined) {
+        if (rec.mode !== "allow" && rec.mode !== "approve") {
+            throw new Error(`policy-rule-mode:${rec.id}`);
+        }
+        rule.mode = rec.mode;
+    }
+    if (rec.tool === "spend") {
+        if (rule.mode !== "approve") {
+            throw new Error(`policy-rule-spend-mode:${rec.id}`);
+        }
+        if (rec.spend === undefined) {
+            throw new Error(`policy-rule-spend-missing:${rec.id}`);
+        }
+        rule.spend = asSpend(rec.spend, rec.id);
+    }
+    if (rec.egress !== undefined) {
+        if (rec.egress !== true) {
+            throw new Error(`policy-rule-egress:${rec.id}`);
+        }
+        rule.egress = true;
+    }
+    return rule;
+}
+function asSpend(raw, id) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`policy-rule-spend-missing:${id}`);
+    }
+    const rec = raw;
+    if (typeof rec.maxAmountMinor !== "number" ||
+        !Number.isInteger(rec.maxAmountMinor) ||
+        rec.maxAmountMinor <= 0) {
+        throw new Error(`policy-rule-spend-missing:${id}`);
+    }
+    if (typeof rec.currency !== "string" || !/^[A-Z]{3}$/.test(rec.currency)) {
+        throw new Error(`policy-rule-spend-missing:${id}`);
+    }
+    if (!Array.isArray(rec.payees) || rec.payees.length === 0 || rec.payees.some((p) => typeof p !== "string" || p === "")) {
+        throw new Error(`policy-rule-spend-missing:${id}`);
+    }
+    const spend = {
+        maxAmountMinor: rec.maxAmountMinor,
+        currency: rec.currency,
+        payees: rec.payees,
+    };
+    if (rec.dailyMaxMinor !== undefined) {
+        if (typeof rec.dailyMaxMinor !== "number" || !Number.isInteger(rec.dailyMaxMinor) || rec.dailyMaxMinor <= 0) {
+            throw new Error(`policy-rule-spend-missing:${id}`);
+        }
+        spend.dailyMaxMinor = rec.dailyMaxMinor;
+    }
+    if (rec.descriptors !== undefined) {
+        if (!Array.isArray(rec.descriptors) ||
+            rec.descriptors.length === 0 ||
+            rec.descriptors.some((d) => typeof d !== "string" || d === "")) {
+            throw new Error(`policy-rule-spend-descriptors:${id}`);
+        }
+        spend.descriptors = rec.descriptors;
+    }
+    return spend;
+}
+function spendArgsInvalid(args) {
+    const keys = Object.keys(args);
+    const allowed = new Set(["amountMinor", "currency", "payee", "reference"]);
+    if (keys.length !== 4 || keys.some((k) => !allowed.has(k)))
+        return true;
+    const amt = args.amountMinor;
+    if (typeof amt !== "number" || !Number.isInteger(amt) || amt <= 0)
+        return true;
+    if (typeof args.currency !== "string" || !/^[A-Z]{3}$/.test(args.currency))
+        return true;
+    if (typeof args.payee !== "string" || args.payee === "")
+        return true;
+    if (typeof args.reference !== "string" || args.reference.length > 140)
+        return true;
+    return false;
+}
+export function parsePolicyDocument(json) {
+    const raw = typeof json === "string" ? parseIJson(json) : json;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("policy-not-object");
+    }
+    const rec = raw;
+    if (rec.version !== 1) {
+        throw new Error("policy-version");
+    }
+    if (rec.default !== "deny") {
+        throw new Error("policy-default-not-deny");
+    }
+    if (!Array.isArray(rec.rules)) {
+        throw new Error("policy-rules");
+    }
+    const document = {
+        version: 1,
+        default: "deny",
+        rules: rec.rules.map(asRule),
+    };
+    if (rec.egress !== undefined) {
+        if (!Array.isArray(rec.egress) ||
+            rec.egress.some((h) => typeof h !== "string" || h.trim() === "")) {
+            throw new Error("policy-egress");
+        }
+        document.egress = rec.egress;
+    }
+    if (rec.approvalTtlMs !== undefined) {
+        if (typeof rec.approvalTtlMs !== "number" || !Number.isFinite(rec.approvalTtlMs) || rec.approvalTtlMs < 0) {
+            throw new Error("policy-approval-ttl");
+        }
+        document.approvalTtlMs = rec.approvalTtlMs;
+    }
+    if (rec.limits !== undefined) {
+        document.limits = asLimits(rec.limits);
+    }
+    if (rec.requireInputs !== undefined) {
+        if (rec.requireInputs !== true) {
+            throw new Error("policy-require-inputs");
+        }
+        document.requireInputs = true;
+    }
+    return document;
+}
+function asLimits(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("policy-limits");
+    }
+    const rec = raw;
+    const limits = {};
+    for (const key of ["ratePerMinute", "dailyMax", "diskFreeBytes"]) {
+        if (rec[key] === undefined)
+            continue;
+        const n = rec[key];
+        if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+            throw new Error("policy-limits");
+        }
+        limits[key] = n;
+    }
+    return limits;
+}
+export function ruleTextHash(text) {
+    return sha256Canonical(text);
+}
+export function loadPolicy(json) {
+    const document = parsePolicyDocument(json);
+    const hash = sha256Canonical(document);
+    const limits = {
+        diskFreeBytes: document.limits?.diskFreeBytes ?? defaultDiskFreeBytes(),
+        ...(document.limits?.ratePerMinute !== undefined ? { ratePerMinute: document.limits.ratePerMinute } : {}),
+        ...(document.limits?.dailyMax !== undefined ? { dailyMax: document.limits.dailyMax } : {}),
+    };
+    return {
+        hash,
+        approvalTtlMs: document.approvalTtlMs ?? DEFAULT_APPROVAL_TTL_MS,
+        limits,
+        ...(document.requireInputs ? { requireInputs: true } : {}),
+        rule(id) {
+            if (id === null)
+                return null;
+            const found = document.rules.find((r) => r.id === id);
+            return found ? { id: found.id, text: found.text } : null;
+        },
+        evaluate(call, principal, ctx) {
+            if (call.name === "pay") {
+                return { decision: "deny", reasonCode: "spend-not-wired", rule: null };
+            }
+            if (call.name === "spend") {
+                const rule = document.rules.find((r) => r.tool === "spend");
+                if (!rule || !rule.spend) {
+                    return { decision: "deny", reasonCode: "spend-not-wired", rule: null };
+                }
+                for (const scope of rule.requires) {
+                    if (!principal.scopes.has(scope)) {
+                        return { decision: "deny", reasonCode: "scope-missing", rule: rule.id };
+                    }
+                }
+                if (spendArgsInvalid(call.arguments)) {
+                    return { decision: "deny", reasonCode: "spend-args-invalid", rule: rule.id };
+                }
+                const amountMinor = call.arguments.amountMinor;
+                const currency = call.arguments.currency;
+                const payee = call.arguments.payee;
+                if (currency !== rule.spend.currency) {
+                    return { decision: "deny", reasonCode: "spend-currency", rule: rule.id };
+                }
+                if (amountMinor > rule.spend.maxAmountMinor) {
+                    return { decision: "deny", reasonCode: "spend-cap", rule: rule.id };
+                }
+                if (!rule.spend.payees.includes(payee)) {
+                    return { decision: "deny", reasonCode: "spend-payee", rule: rule.id };
+                }
+                if (rule.spend.dailyMaxMinor !== undefined) {
+                    const spent = ctx?.spentTodayMinor?.(currency) ?? 0;
+                    if (spent + amountMinor > rule.spend.dailyMaxMinor) {
+                        return { decision: "deny", reasonCode: "spend-daily", rule: rule.id };
+                    }
+                }
+                return { decision: "defer", reasonCode: "approval-required", rule: rule.id };
+            }
+            const rule = document.rules.find((r) => r.tool === call.name);
+            if (!rule) {
+                return { decision: "deny", reasonCode: "no-rule", rule: null };
+            }
+            for (const scope of rule.requires) {
+                if (!principal.scopes.has(scope)) {
+                    return { decision: "deny", reasonCode: "scope-missing", rule: rule.id };
+                }
+            }
+            if (rule.egress === true) {
+                const extract = HOST_EXTRACTORS[call.name];
+                const host = extract ? extract(call.arguments) : undefined;
+                if (!extract || host === undefined) {
+                    return { decision: "deny", reasonCode: "egress-host-missing", rule: rule.id };
+                }
+                const allowed = document.egress ?? [];
+                if (!allowed.includes(host)) {
+                    return { decision: "deny", reasonCode: "egress-blocked", rule: rule.id };
+                }
+            }
+            if (rule.mode === "approve") {
+                return { decision: "defer", reasonCode: "approval-required", rule: rule.id };
+            }
+            return { decision: "allow", reasonCode: "allow", rule: rule.id };
+        },
+    };
+}

package/dist/proxy.d.ts

@@ -0,0 +1,11 @@
+import type { Principal, ProxyDeps, ToolCall, ToolResult } from "./types.ts";
+export declare class LedgerDenyUnrecorded extends Error {
+    readonly reasonCode: string;
+    constructor(reasonCode: string, cause?: unknown);
+}
+export declare const REF_RE: RegExp;
+export declare function createProxy(deps: ProxyDeps): {
+    approvals: import("./approvals.ts").ApprovalsLog;
+    inputsLog: import("./types.ts").InputsLog;
+    call(call: ToolCall, principal: Principal): Promise<ToolResult>;
+};