@verax-ai/proxy 0.1.0

package/dist/proxy.js

@@ -0,0 +1,533 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { signDecisionRecord } from "@cedulon/core";
+import { approvePending, approvalsLogFor, drainApprovalCommands } from "./approvals.js";
+import { diskProbe } from "./disk.js";
+import { effectDescriptor, sha256Canonical } from "./hash.js";
+import { inputsLogFor } from "./inputs.js";
+import { countedWork, hasPrimaryEffect, lookupDecisionByRef, lookupReauthByHash, lookupResolvedBy, noteResolution, noteTenantRef, } from "./ledger.js";
+import { spokenReason } from "./spoken-reason.js";
+import { tenantKey } from "./tenant.js";
+function scopedClaimsRef(principal, raw) {
+    if (principal.iss || principal.tenant || principal.org) {
+        return `${tenantKey(principal)}:${raw}`;
+    }
+    return raw;
+}
+function principalInputs(principal) {
+    return {
+        brain: principal.brain,
+        scopes: [...principal.scopes].sort(),
+        ...(principal.iss ? { iss: principal.iss } : {}),
+        ...(principal.tenant ? { tenant: principal.tenant } : {}),
+        ...(principal.org ? { org: principal.org } : {}),
+    };
+}
+export class LedgerDenyUnrecorded extends Error {
+    reasonCode;
+    constructor(reasonCode, cause) {
+        super(`ledger-deny-unrecorded:${reasonCode}`);
+        this.name = "LedgerDenyUnrecorded";
+        this.reasonCode = reasonCode;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+export const REF_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function denied(reasonCode, ref, call) {
+    const spoken = spokenReason(reasonCode);
+    if (spoken !== reasonCode) {
+        const payload = { error: spoken };
+        if (call && typeof call.arguments.id === "string") {
+            payload.id = call.arguments.id;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: `denied:${reasonCode}:${ref}` }],
+        isError: true,
+    };
+}
+function deferred(ref) {
+    return {
+        content: [{ type: "text", text: `deferred:approval-required:${ref}` }],
+        isError: true,
+    };
+}
+function allowedReplay(ref) {
+    return {
+        content: [{ type: "text", text: `allowed:${ref}` }],
+        isError: false,
+    };
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    Object.freeze(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreeze(item);
+    }
+    else {
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+    }
+    return value;
+}
+function thrownPayload(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message };
+    }
+    return { name: "thrown" };
+}
+function declaredInputs(args) {
+    if (!Object.prototype.hasOwnProperty.call(args, "_inputs"))
+        return null;
+    const raw = args._inputs;
+    if (!Array.isArray(raw))
+        return "invalid";
+    const out = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            return "invalid";
+        const rec = item;
+        if (typeof rec.id !== "string" || rec.id === "" || typeof rec.versionHash !== "string" || rec.versionHash === "") {
+            return "invalid";
+        }
+        const row = {
+            id: rec.id,
+            versionHash: rec.versionHash,
+        };
+        if (rec.source !== undefined) {
+            if (rec.source === null || typeof rec.source !== "object" || Array.isArray(rec.source)) {
+                return "invalid";
+            }
+            row.source = rec.source;
+        }
+        out.push(row);
+    }
+    return out;
+}
+function readRef(args) {
+    if (!Object.prototype.hasOwnProperty.call(args, "_ref"))
+        return null;
+    const raw = args._ref;
+    if (typeof raw !== "string" || !REF_RE.test(raw))
+        return "invalid";
+    return raw;
+}
+function toolCallOf(call) {
+    const args = { ...call.arguments };
+    delete args._inputs;
+    delete args._ref;
+    return { name: call.name, arguments: args };
+}
+export function createProxy(deps) {
+    const inputsLog = deps.inputsLog ?? inputsLogFor(deps.ledger);
+    const approvals = approvalsLogFor(deps.ledger);
+    deps.ledger.effectSigner = deps.effectSigner;
+    const ledgerDir = deps.ledger.dir;
+    const stateDir = typeof ledgerDir === "string" ? ledgerDir : null;
+    if (stateDir === null) {
+        process.stderr.write("verax-proxy: halt and disk limits are inactive without a ledger directory\n");
+    }
+    async function writeRecord(opts) {
+        const inputsHash = sha256Canonical(opts.inputs);
+        await inputsLog.append(opts.ref, opts.inputs);
+        await deps.ledger.appendDecisionChained((prevRecordHash) => signDecisionRecord({
+            decider: opts.decider ?? "verax-proxy",
+            subject: opts.subject,
+            requestHash: opts.requestHash,
+            policyHash: deps.policy.hash,
+            inputsHash,
+            decision: opts.decision,
+            reasonCode: opts.reasonCode,
+            ref: opts.ref,
+            effectHash: opts.effectHash,
+            // The class of effect this decision names, in this channel's own
+            // vocabulary: the call it decided about. An allow must carry one, and
+            // a refusal names what it refused, so the audit can hold a decision
+            // and an effect row to the same word.
+            effectClass: opts.subject,
+            timestampMs: opts.timestampMs,
+            nonce: opts.ref,
+            prevRecordHash,
+        }, deps.recordSigner.privateKeyPem, deps.recordSigner.publicKeyPem));
+        if (opts.inputs.approver?.resolves) {
+            const kind = opts.reasonCode === "expired" ? "expired" : opts.decision === "allow" ? "allow" : null;
+            if (kind)
+                noteResolution(deps.ledger, opts.inputs.approver.resolves, { ref: opts.ref, kind });
+        }
+    }
+    async function writeRecordOrUnrecorded(opts) {
+        if (diskProbe.failAppend) {
+            throw new LedgerDenyUnrecorded("ledger-disk-low");
+        }
+        try {
+            await writeRecord(opts);
+        }
+        catch (err) {
+            if (opts.reasonCode === "ledger-disk-low") {
+                throw new LedgerDenyUnrecorded("ledger-disk-low", err);
+            }
+            throw err;
+        }
+    }
+    function rateBound(timestampMs, wouldCount) {
+        if (!wouldCount)
+            return null;
+        const limits = deps.policy.limits;
+        if (limits.ratePerMinute === undefined && limits.dailyMax === undefined)
+            return null;
+        const counts = countedWork(deps.ledger, timestampMs);
+        if (!counts.ok)
+            return "rate-limited";
+        if (limits.ratePerMinute !== undefined && counts.minute >= limits.ratePerMinute)
+            return "rate-limited";
+        if (limits.dailyMax !== undefined && counts.day >= limits.dailyMax)
+            return "daily-limited";
+        return null;
+    }
+    function utcDayStart(ms) {
+        const d = new Date(ms);
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+    }
+    function spentTodayMinorOf(rows, nowMs, currency) {
+        const start = utcDayStart(nowMs);
+        const end = start + 86_400_000;
+        let sum = 0;
+        for (const row of rows) {
+            if (row.subject !== "spend")
+                continue;
+            if (row.status !== "pending" && row.status !== "approved")
+                continue;
+            const created = row.createdAtMs ?? row.expiresAtMs - deps.policy.approvalTtlMs;
+            if (created < start || created >= end)
+                continue;
+            if (row.args.currency !== currency)
+                continue;
+            const amt = row.args.amountMinor;
+            if (typeof amt === "number")
+                sum += amt;
+        }
+        return sum;
+    }
+    async function spendReauth(requestHash, inputs, timestampMs, subject) {
+        const existingReauth = await lookupReauthByHash(deps.ledger, requestHash);
+        if (existingReauth)
+            return denied("spend-reauth-required", existingReauth);
+        const ref = deps.nonce();
+        await writeRecord({
+            decision: "deny",
+            reasonCode: "spend-reauth-required",
+            ref,
+            requestHash,
+            inputs,
+            effectHash: null,
+            subject,
+            timestampMs,
+        });
+        return denied("spend-reauth-required", ref);
+    }
+    async function runInner(call, principal, ref) {
+        const dispatchedName = call.name;
+        const dispatchedArgs = deepFreeze(structuredClone(call.arguments));
+        const dispatchedHash = sha256Canonical(effectDescriptor(dispatchedName, dispatchedArgs));
+        const thrownHash = sha256Canonical(effectDescriptor(dispatchedName, dispatchedArgs, true));
+        const frozenCall = Object.freeze({
+            name: dispatchedName,
+            arguments: dispatchedArgs,
+        });
+        try {
+            const result = await deps.inner(frozenCall, principal, ref);
+            const row = {
+                ref,
+                effectHash: dispatchedHash,
+                effectClass: dispatchedName,
+                timestampMs: deps.now(),
+                actor: principal.brain,
+            };
+            await deps.ledger.appendEffect(row, "self", sha256Canonical(result));
+            return result;
+        }
+        catch (err) {
+            const row = {
+                ref,
+                effectHash: thrownHash,
+                effectClass: `${dispatchedName}:threw`,
+                timestampMs: deps.now(),
+                actor: principal.brain,
+            };
+            await deps.ledger.appendEffect(row, "self", sha256Canonical(thrownPayload(err)));
+            throw err;
+        }
+    }
+    async function resolveInputs(call, principal, timestampMs) {
+        const declared = declaredInputs(call.arguments);
+        if (declared === "invalid") {
+            return {
+                inputs: { principal: principalInputs(principal), inputs: [] },
+                reasonCode: "input-invalid",
+            };
+        }
+        if (declared === null && deps.policy.requireInputs === true) {
+            return {
+                inputs: { principal: principalInputs(principal), inputs: [] },
+                reasonCode: "inputs-required",
+            };
+        }
+        const rows = [];
+        if (declared) {
+            for (const item of declared) {
+                const got = deps.resolveInput ? await deps.resolveInput(item.id, principal) : null;
+                if (!got ||
+                    got.versionHash !== item.versionHash ||
+                    got.validFromMs > timestampMs ||
+                    got.validUntilMs < timestampMs) {
+                    return {
+                        inputs: { principal: principalInputs(principal), inputs: [] },
+                        reasonCode: "input-invalid",
+                    };
+                }
+                const row = {
+                    id: item.id,
+                    versionHash: item.versionHash,
+                    validFromMs: got.validFromMs,
+                    validUntilMs: got.validUntilMs,
+                };
+                if (item.source)
+                    row.source = item.source;
+                rows.push(row);
+            }
+        }
+        return {
+            inputs: { principal: principalInputs(principal), inputs: rows },
+            reasonCode: null,
+        };
+    }
+    return {
+        approvals,
+        inputsLog,
+        async call(call, principal) {
+            if (stateDir) {
+                await drainApprovalCommands(stateDir, async (cmd) => {
+                    const defer = await lookupDecisionByRef(deps.ledger, cmd.ref);
+                    if (!defer || defer.decision !== "defer")
+                        return;
+                    await approvePending({
+                        ledger: deps.ledger,
+                        recordSigner: deps.recordSigner,
+                        now: deps.now,
+                        nonce: deps.nonce,
+                        ref: cmd.ref,
+                        approverId: cmd.approverId,
+                        // Only `verax approve` queues a command, when the ledger is locked.
+                        via: "cli",
+                        policyHash: defer.policyHash,
+                        approvals,
+                        inputsLog,
+                    });
+                });
+            }
+            const dispatched = toolCallOf(call);
+            const requestHash = sha256Canonical(dispatched);
+            const timestampMs = deps.now();
+            const resolved = await resolveInputs(call, principal, timestampMs);
+            if (stateDir && existsSync(join(stateDir, "halted"))) {
+                const ref = deps.nonce();
+                await writeRecord({
+                    decision: "deny",
+                    reasonCode: "halted",
+                    ref,
+                    requestHash,
+                    inputs: resolved.inputs,
+                    effectHash: null,
+                    subject: call.name,
+                    timestampMs,
+                });
+                return denied("halted", ref);
+            }
+            if (stateDir && diskProbe.freeBytes(stateDir) < deps.policy.limits.diskFreeBytes) {
+                const ref = deps.nonce();
+                await writeRecordOrUnrecorded({
+                    decision: "deny",
+                    reasonCode: "ledger-disk-low",
+                    ref,
+                    requestHash,
+                    inputs: resolved.inputs,
+                    effectHash: null,
+                    subject: call.name,
+                    timestampMs,
+                });
+                return denied("ledger-disk-low", ref);
+            }
+            const given = readRef(call.arguments);
+            if (given === "invalid") {
+                const ref = deps.nonce();
+                await writeRecord({
+                    decision: "deny",
+                    reasonCode: "ref-invalid",
+                    ref,
+                    requestHash,
+                    inputs: resolved.inputs,
+                    effectHash: null,
+                    subject: call.name,
+                    timestampMs,
+                });
+                return denied("ref-invalid", ref);
+            }
+            if (typeof given === "string") {
+                // The ledger, the approvals snapshot and the resolution index all key on the
+                // scoped ref. The brain only ever sees and resends the raw `_ref` it chose.
+                const scopedRef = scopedClaimsRef(principal, given);
+                const existing = await lookupDecisionByRef(deps.ledger, given, tenantKey(principal));
+                if (existing) {
+                    if (existing.requestHash !== requestHash) {
+                        const ref = deps.nonce();
+                        await writeRecord({
+                            decision: "deny",
+                            reasonCode: "ref-reuse",
+                            ref,
+                            requestHash,
+                            inputs: resolved.inputs,
+                            effectHash: null,
+                            subject: call.name,
+                            timestampMs,
+                        });
+                        return denied("ref-reuse", ref);
+                    }
+                    if (existing.decision === "defer") {
+                        const snap = await approvals.get(scopedRef);
+                        const boundHit = lookupResolvedBy(deps.ledger, scopedRef);
+                        if (boundHit?.kind === "expired") {
+                            if (snap?.status === "pending")
+                                await approvals.updateStatus(scopedRef, "expired");
+                            return denied("expired", boundHit.ref);
+                        }
+                        if (snap && timestampMs > snap.expiresAtMs) {
+                            const expireRef = deps.nonce();
+                            await writeRecord({
+                                decision: "deny",
+                                reasonCode: "expired",
+                                ref: expireRef,
+                                requestHash,
+                                inputs: {
+                                    ...resolved.inputs,
+                                    approver: { id: "verax-proxy", via: "proxy", resolves: scopedRef },
+                                },
+                                effectHash: null,
+                                subject: call.name,
+                                timestampMs,
+                            });
+                            await approvals.updateStatus(scopedRef, "expired");
+                            return denied("expired", expireRef);
+                        }
+                        const allowRef = snap?.allowRef ?? (boundHit?.kind === "allow" ? boundHit.ref : undefined);
+                        const allow = allowRef ? await lookupDecisionByRef(deps.ledger, allowRef) : null;
+                        if (allow?.ref && allow.decision === "allow" && allow.reasonCode === "approved-by-operator") {
+                            const bound = await inputsLog.get(allow.ref);
+                            if (bound?.approver?.resolves && bound.approver.resolves !== scopedRef) {
+                                return deferred(given);
+                            }
+                            if (!snap?.allowRef) {
+                                await approvals.updateStatus(scopedRef, "approved", { allowRef: allow.ref });
+                            }
+                            if (await hasPrimaryEffect(deps.ledger, allow.ref))
+                                return allowedReplay(allow.ref);
+                            if (allow.subject === "spend") {
+                                return spendReauth(requestHash, resolved.inputs, timestampMs, call.name);
+                            }
+                            return runInner(dispatched, principal, allow.ref);
+                        }
+                        return deferred(given);
+                    }
+                    if (existing.decision === "deny") {
+                        return denied(existing.reasonCode, given, call);
+                    }
+                    if (existing.decision === "allow" && existing.ref) {
+                        if (await hasPrimaryEffect(deps.ledger, existing.ref)) {
+                            return allowedReplay(existing.ref);
+                        }
+                        if (existing.subject === "spend") {
+                            return spendReauth(requestHash, resolved.inputs, timestampMs, call.name);
+                        }
+                        return runInner(dispatched, principal, existing.ref);
+                    }
+                }
+            }
+            let spendCtx;
+            if (dispatched.name === "spend") {
+                const approvalRows = await approvals.listAll();
+                spendCtx = {
+                    spentTodayMinor: (currency) => spentTodayMinorOf(approvalRows, timestampMs, currency),
+                };
+            }
+            const verdict = deps.policy.evaluate(dispatched, principal, spendCtx);
+            let reasonCode = resolved.reasonCode ?? verdict.reasonCode;
+            let decision = resolved.reasonCode ? "deny" : verdict.decision;
+            const bound = rateBound(timestampMs, decision === "allow" || decision === "defer");
+            if (bound) {
+                decision = "deny";
+                reasonCode = bound;
+            }
+            if (!bound &&
+                decision === "allow" &&
+                deps.checkTenantMismatch &&
+                (await deps.checkTenantMismatch(dispatched, principal))) {
+                decision = "deny";
+                reasonCode = "tenant-mismatch";
+            }
+            const ref = typeof given === "string" ? scopedClaimsRef(principal, given) : deps.nonce();
+            // What the brain is told: its own `_ref`, so a retry carries the same key back.
+            const shown = typeof given === "string" ? given : ref;
+            const allow = decision === "allow";
+            await writeRecord({
+                decision,
+                reasonCode,
+                ref,
+                requestHash,
+                inputs: resolved.inputs,
+                effectHash: allow ? sha256Canonical(effectDescriptor(dispatched.name, dispatched.arguments)) : null,
+                subject: call.name,
+                timestampMs,
+            });
+            if (typeof given === "string") {
+                noteTenantRef(deps.ledger, tenantKey(principal), given);
+            }
+            if (decision === "defer") {
+                const rule = deps.policy.rule(verdict.rule);
+                const amount = dispatched.name === "spend" ? dispatched.arguments.amountMinor : dispatched.arguments.amount;
+                const payee = dispatched.arguments.payee;
+                const currency = dispatched.arguments.currency;
+                await approvals.append({
+                    ref,
+                    requestHash,
+                    subject: dispatched.name,
+                    args: dispatched.arguments,
+                    ruleId: verdict.rule,
+                    ruleText: rule?.text ?? null,
+                    inputsSummary: {
+                        count: resolved.inputs.inputs.length,
+                        ids: resolved.inputs.inputs.map((i) => i.id),
+                    },
+                    ...(amount !== undefined ? { amount } : {}),
+                    ...(payee !== undefined ? { payee } : {}),
+                    ...(currency !== undefined ? { currency } : {}),
+                    createdAtMs: timestampMs,
+                    expiresAtMs: timestampMs + deps.policy.approvalTtlMs,
+                    status: "pending",
+                    brain: principal.brain,
+                });
+                return deferred(shown);
+            }
+            if (!allow) {
+                return denied(reasonCode, shown, call);
+            }
+            return runInner(dispatched, principal, ref);
+        },
+    };
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,81 @@
+import type { EffectRow } from "@cedulon/effect-extract";
+import type { ApprovalRow } from "./approvals.ts";
+import type { LedgerEffect } from "./types.ts";
+export type ChannelRow = {
+    channel: string;
+    externalId: string;
+    occurredAtMs: number;
+    subject: string;
+    actor?: string;
+    ref?: string;
+    nearestEffectDtMs?: number;
+    amountMinor?: number;
+    currency?: string;
+    credit?: boolean;
+    reason?: string;
+    /** Statement text when parsed from a card CSV. */
+    descriptor?: string;
+    datePrecision?: "day" | "minute";
+    /** Window used for this row. Set by reconcile. */
+    toleranceMs?: number;
+};
+export type CardCsvSkip = {
+    line: number;
+    reason: string;
+};
+export type ParsedCardCsv = ChannelRow[] & {
+    skipped: CardCsvSkip[];
+};
+export type ReconcileReport = {
+    scope: {
+        channel: string;
+        windowStartMs: number;
+        windowEndMs: number;
+        rowCount: number;
+        skipped?: CardCsvSkip[];
+        /** Policy snapshot hash when card descriptors were read from one file. */
+        policyHash?: string;
+    };
+    matched: Array<{
+        channel: ChannelRow;
+        effect: EffectRow;
+        datePrecision?: "day" | "minute";
+        toleranceMs?: number;
+    }>;
+    ghost: ChannelRow[];
+    unsent: EffectRow[];
+    authorizedUnpaid: EffectRow[];
+    outOfScope: ChannelRow[];
+};
+export type CardCsvOpts = {
+    currency: string;
+    columns?: {
+        date: string;
+        amount: string;
+        description: string;
+        id?: string;
+    };
+    delimiter?: ";" | ",";
+    decimal?: "," | ".";
+    dateFormat?: "DD.MM.YYYY" | "YYYY-MM-DD";
+    /**
+     * Minutes east of UTC that the statement's printed times are in (Istanbul: 180).
+     * A statement prints local wall-clock time and names no zone, so without this the
+     * time cannot be placed on the clock and the row stays a day row.
+     */
+    tzOffsetMinutes?: number;
+};
+export declare function parseCardCsv(text: string, opts: CardCsvOpts): ParsedCardCsv;
+export declare function parseChannelJsonl(text: string): ChannelRow[];
+/** Read-only: does not take ledger.lock. */
+export declare function loadEffectsFromDir(stateDir: string): LedgerEffect[];
+export declare function reconcile(channelRows: readonly ChannelRow[], effects: readonly LedgerEffect[], opts?: {
+    toleranceMs?: number;
+    window?: {
+        startMs: number;
+        endMs: number;
+    };
+    approvals?: readonly ApprovalRow[];
+    skipped?: CardCsvSkip[];
+    descriptorsByPayee?: Readonly<Record<string, readonly string[]>>;
+}): ReconcileReport;