@verax-ai/proxy 0.1.2 → 0.1.4

package/dist/in-flight-log.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Called before `inner` runs. A failure here must not block the call.
+ *
+ * The stamp is wall-clock time and not the proxy's injected `now`: a mark is
+ * not a ledger row, and taking a tick from a deterministic clock would shift
+ * every timestamp recorded after it — the golden ledger caught exactly that.
+ */
+export declare function markStarted(stateDir: string, ref: string, subject: string): void;
+/** Called once the effect row is written, on success and on failure alike. */
+export declare function markEnded(stateDir: string, ref: string): void;
+/** True when a run started and no end was recorded: the outcome is unknown. */
+export declare function startedWithoutEnd(stateDir: string, ref: string): boolean;

package/dist/in-flight-log.js

@@ -0,0 +1,65 @@
+/**
+ * Durable in-flight marks: "this ref started running".
+ *
+ * The in-memory registry that stops a second run dies with the process. On the
+ * approved path an `allow` does not mean the tool ran — it means the operator
+ * said yes — so a restarted body cannot tell "approved, never started" from
+ * "approved, started, crashed before the effect". Without that distinction it
+ * has to either run everything twice or run nothing at all.
+ *
+ * A mark is one empty file per ref, created before `inner` and removed after
+ * the effect is written. One file per ref rather than a shared log because two
+ * refs may start and finish at the same moment: file create and unlink need no
+ * lock, a shared append-only log would need a compaction pass and would race.
+ *
+ * A mark left behind by a crash is exactly the signal wanted: it outlives the
+ * process, and the retry that finds it answers `outcome-unknown` instead of
+ * running the tool a second time.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const KLASOR = "in-flight";
+/** Ref may carry a tenant prefix and any path character; the name never does. */
+function markPath(stateDir, ref) {
+    const ad = createHash("sha256").update(ref, "utf8").digest("hex").slice(0, 32);
+    return join(stateDir, KLASOR, `${ad}.start`);
+}
+/**
+ * Called before `inner` runs. A failure here must not block the call.
+ *
+ * The stamp is wall-clock time and not the proxy's injected `now`: a mark is
+ * not a ledger row, and taking a tick from a deterministic clock would shift
+ * every timestamp recorded after it — the golden ledger caught exactly that.
+ */
+export function markStarted(stateDir, ref, subject) {
+    try {
+        mkdirSync(join(stateDir, KLASOR), { recursive: true, mode: 0o700 });
+        // The body is for a human reading the directory after a crash; nothing parses it.
+        writeFileSync(markPath(stateDir, ref), `${JSON.stringify({ ref, subject, atMs: Date.now() })}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // A missing mark degrades to today's behaviour, it does not deny the call.
+    }
+}
+/** Called once the effect row is written, on success and on failure alike. */
+export function markEnded(stateDir, ref) {
+    try {
+        rmSync(markPath(stateDir, ref), { force: true });
+    }
+    catch {
+        // Leaving a stale mark makes the next retry cautious, never wrong.
+    }
+}
+/** True when a run started and no end was recorded: the outcome is unknown. */
+export function startedWithoutEnd(stateDir, ref) {
+    try {
+        return existsSync(markPath(stateDir, ref));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -14,3 +14,5 @@ export type { ApprovalRow, ApproveResult } from "./approvals.ts";
 export type { CardCsvOpts, ChannelRow, ReconcileReport } from "./reconcile.ts";
 export type { FileLedgerOpts, LedgerCounts } from "./ledger.ts";
 export type { EffectSigner, ExplainChain, ExplainPair, ExplainFinding, ExplainOpts, ExplainResult, ExplainTrustRoot, ExplainWarning, ExtractWindow, Ledger, LedgerEffect, Policy, PolicyDecision, Principal, ProxyDeps, RecordSigner, ToolCall, ToolResult, WitnessClass, } from "./types.ts";
+export { verifyLedger } from "./verify-ledger.ts";
+export type { VerifyResult, VerifyOptions, VerifyTrust } from "./verify-ledger.ts";

package/dist/index.js

@@ -16,3 +16,4 @@ export { diskProbe } from "./disk.js";
 export { checkpointsPath } from "./checkpoints.js";
 export { signEffectAttestation } from "./ledger.js";
 export { spokenReason } from "./spoken-reason.js";
+export { verifyLedger } from "./verify-ledger.js";

package/dist/proxy.js

@@ -4,6 +4,7 @@ import { signDecisionRecord } from "@cedulon/core";
 import { approvePending, approvalsLogFor, createApprovalBudgetGuard, drainApprovalCommands, spentTodayMinorOf, } from "./approvals.js";
 import { SerialQueue } from "./serial-queue.js";
 import { diskProbe } from "./disk.js";
+import { markEnded, markStarted, startedWithoutEnd } from "./in-flight-log.js";
 import { effectDescriptor, sha256Canonical } from "./hash.js";
 import { inputsLogFor } from "./inputs.js";
 import { countedWork, hasPrimaryEffect, lookupDecisionByRef, lookupReauthByHash, lookupResolvedBy, noteResolution, noteTenantRef, } from "./ledger.js";
@@ -64,6 +65,21 @@ function allowedReplay(ref) {
         isError: false,
     };
 }
+function threwReplay(ref) {
+    // The tool ran and exploded. That is not a deny — the gate allowed it.
+    // `allowed:` would teach a retry library the opposite of the ledger.
+    return {
+        content: [{ type: "text", text: `threw:${ref}` }],
+        isError: true,
+    };
+}
+async function replayAfterEffect(ledger, ref) {
+    const primary = (await ledger.effects()).find((e) => e.row.ref === ref && e.row.effectClass !== "duplicate-effect");
+    if (primary?.row.effectClass.endsWith(":threw")) {
+        return threwReplay(ref);
+    }
+    return allowedReplay(ref);
+}
 function deepFreeze(value) {
     if (value === null || typeof value !== "object")
         return value;
@@ -294,6 +310,11 @@ export function createProxy(deps) {
         };
     }
     function launchInner(dispatchedCall, principal, allowRef, flightKey) {
+        // Written before the tool runs, removed after the effect is recorded. A
+        // mark that survives the process is what tells a restarted body that this
+        // ref was already started (in-flight-log.ts).
+        if (stateDir !== null)
+            markStarted(stateDir, flightKey, dispatchedCall.name);
         const work = runInner(dispatchedCall, principal, allowRef);
         inFlight.set(flightKey, work);
         return { kind: "run", work, key: flightKey, replayRef: allowRef };
@@ -455,7 +476,7 @@ export function createProxy(deps) {
                                     await approvals.updateStatus(scopedRef, "approved", { allowRef: allow.ref });
                                 }
                                 if (await hasPrimaryEffect(deps.ledger, allow.ref)) {
-                                    return { kind: "done", result: allowedReplay(allow.ref) };
+                                    return { kind: "done", result: await replayAfterEffect(deps.ledger, allow.ref) };
                                 }
                                 if (allow.subject === "spend") {
                                     return {
@@ -469,6 +490,27 @@ export function createProxy(deps) {
                                 const flying = inFlight.get(scopedRef);
                                 if (flying)
                                     return { kind: "wait", work: flying, replayRef: allow.ref };
+                                // An approved allow means "the operator said yes", not "it ran",
+                                // so the first retry after an approval is the first run. Only a
+                                // mark left on disk says a run was already started and never
+                                // finished — that one cannot be run again.
+                                if (stateDir !== null && startedWithoutEnd(stateDir, scopedRef)) {
+                                    const unknownRef = deps.nonce();
+                                    await writeRecord({
+                                        decision: "deny",
+                                        reasonCode: "outcome-unknown",
+                                        ref: unknownRef,
+                                        requestHash,
+                                        inputs: {
+                                            ...resolved.inputs,
+                                            approver: { id: "verax-proxy", via: "proxy", resolves: scopedRef },
+                                        },
+                                        effectHash: null,
+                                        subject: call.name,
+                                        timestampMs,
+                                    });
+                                    return { kind: "done", result: denied("outcome-unknown", unknownRef) };
+                                }
                                 return launchInner(dispatched, principal, allow.ref, scopedRef);
                             }
                             return { kind: "done", result: deferred(given) };
@@ -478,7 +520,7 @@ export function createProxy(deps) {
                         }
                         if (existing.decision === "allow" && existing.ref) {
                             if (await hasPrimaryEffect(deps.ledger, existing.ref)) {
-                                return { kind: "done", result: allowedReplay(existing.ref) };
+                                return { kind: "done", result: await replayAfterEffect(deps.ledger, existing.ref) };
                             }
                             if (existing.subject === "spend") {
                                 return {
@@ -585,17 +627,23 @@ export function createProxy(deps) {
             if (plan.kind === "wait") {
                 try {
                     await plan.work;
+                    return allowedReplay(plan.replayRef);
                 }
                 catch {
-                    // The first call recorded the throw on its effect row.
+                    // The first call recorded the throw on its effect row. The
+                    // waiter must not call the tool again, and must not say allowed.
+                    return threwReplay(plan.replayRef);
                 }
-                return allowedReplay(plan.replayRef);
             }
             try {
                 return await plan.work;
             }
             finally {
                 inFlight.delete(plan.key);
+                // runInner has written its effect row by now — on the throw path too,
+                // as `<name>:threw`. The outcome is on the ledger, so the mark goes.
+                if (stateDir !== null)
+                    markEnded(stateDir, plan.key);
             }
         },
     };

package/dist/verify-ledger.d.ts

@@ -0,0 +1,25 @@
+export type VerifyTrust = {
+    /** `pinned`: the caller supplied the key. `in-ledger`: read from the records. */
+    source: "pinned" | "in-ledger" | "none";
+    publicKeyPem: string | null;
+    note: string;
+};
+export type VerifyResult = {
+    ok: boolean;
+    directory: string;
+    decisions: number;
+    effects: number;
+    signaturesValid: number;
+    signaturesInvalid: number;
+    /** Index of the first record whose `prevRecordHash` does not match, else null. */
+    chainBreakAt: number | null;
+    effectsBound: number;
+    effectsOrphaned: number;
+    trust: VerifyTrust;
+    problems: string[];
+};
+export type VerifyOptions = {
+    /** Verify against this key instead of the one the records carry. */
+    publicKeyPem?: string;
+};
+export declare function verifyLedger(dir: string, opts?: VerifyOptions): Promise<VerifyResult>;

package/dist/verify-ledger.js

@@ -0,0 +1,171 @@
+/**
+ * Reads a ledger directory and says whether it still holds together, with no
+ * body running and nothing on the network.
+ *
+ * This is the answer to a question a customer is right to ask: if we stopped
+ * using Verax tomorrow, would these files still mean anything? Evidence that
+ * can only be read by the vendor who sold it is a weak kind of evidence.
+ *
+ * Three things fail separately, so three things are stated separately:
+ *
+ *   signatures  each record verifies against a public key
+ *   chain       each record names the hash of the one before it
+ *   effects     each effect row is bound to a decision by `effectHash`
+ *
+ * And a fourth, which matters most and is the easiest to fudge: **which key**.
+ * A ledger checked against the key sitting next to it is internally
+ * consistent and nothing more — whatever could write the file could write
+ * that key too (the downstream audit showed exactly this: a stdio child runs
+ * as the same user and can read `keys/*.pem`). So the trust source is part of
+ * the answer rather than a footnote, and `publicKeyPem` lets a reader pin a
+ * copy they hold themselves.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findDecisionRecordChainBreak, verifyDecisionRecord } from "@cedulon/core";
+import { readLedgerManifest } from "./ledger-manifest.js";
+/** Every decisions file this directory holds, oldest piece first. */
+function decisionFiles(dir) {
+    const manifest = readLedgerManifest(dir);
+    if (manifest && Array.isArray(manifest.pieces) && manifest.pieces.length > 0) {
+        return manifest.pieces.map((p) => join(dir, p.decisions)).filter((p) => existsSync(p));
+    }
+    const tek = join(dir, "decisions.jsonl");
+    return existsSync(tek) ? [tek] : [];
+}
+function effectFiles(dir) {
+    const manifest = readLedgerManifest(dir);
+    if (manifest && Array.isArray(manifest.pieces) && manifest.pieces.length > 0) {
+        return manifest.pieces.map((p) => join(dir, p.effects)).filter((p) => existsSync(p));
+    }
+    const tek = join(dir, "effects.jsonl");
+    return existsSync(tek) ? [tek] : [];
+}
+/** Parses JSONL, reporting the line a bad row sits on rather than throwing. */
+function readJsonl(path, problems) {
+    const out = [];
+    const text = readFileSync(path, "utf8");
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line === "")
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            problems.push(`unreadable row: ${path}:${i + 1} is not JSON`);
+        }
+    }
+    return out;
+}
+export async function verifyLedger(dir, opts = {}) {
+    const problems = [];
+    const kararDosyalari = decisionFiles(dir);
+    const records = [];
+    for (const path of kararDosyalari) {
+        for (const row of readJsonl(path, problems)) {
+            records.push(row);
+        }
+    }
+    // An empty directory is not a clean ledger. Saying "valid" over no records
+    // would let a deleted ledger pass as a verified one.
+    if (records.length === 0) {
+        problems.push("no decisions found: this directory holds no ledger to verify");
+        return {
+            ok: false,
+            directory: dir,
+            decisions: 0,
+            effects: 0,
+            signaturesValid: 0,
+            signaturesInvalid: 0,
+            chainBreakAt: null,
+            effectsBound: 0,
+            effectsOrphaned: 0,
+            trust: { source: "none", publicKeyPem: null, note: "no records, so no key was used" },
+            problems,
+        };
+    }
+    const pinned = opts.publicKeyPem?.trim();
+    const icerden = typeof records[0]?.publicKeyPem === "string" ? records[0].publicKeyPem : null;
+    const anahtar = pinned && pinned !== "" ? pinned : icerden;
+    const trust = pinned && pinned !== ""
+        ? {
+            source: "pinned",
+            publicKeyPem: pinned,
+            note: "verified against a key the reader supplied, not one taken from these files",
+        }
+        : {
+            source: "in-ledger",
+            publicKeyPem: icerden,
+            note: "verified against the key carried in the records themselves: this shows the files are " +
+                "internally consistent, not that the key was ever trusted. Pin a key you hold to check that.",
+        };
+    let signaturesValid = 0;
+    let signaturesInvalid = 0;
+    for (let i = 0; i < records.length; i += 1) {
+        const rec = records[i];
+        let gecerli = false;
+        try {
+            gecerli = verifyDecisionRecord(rec, anahtar ?? undefined);
+        }
+        catch {
+            gecerli = false;
+        }
+        if (gecerli) {
+            signaturesValid += 1;
+        }
+        else {
+            signaturesInvalid += 1;
+            const ref = typeof rec.claims?.ref === "string" ? rec.claims.ref : "?";
+            problems.push(`signature does not verify: record ${i} (ref ${ref})`);
+        }
+    }
+    // Returns `{ index, reason }` or null. The reason is carried through: a
+    // broken link and a bad signature are different accidents, and a reader
+    // chasing one should not be told the other.
+    const brk = findDecisionRecordChainBreak(records, anahtar ? [anahtar] : undefined);
+    const chainBreakAt = brk ? brk.index : null;
+    if (brk) {
+        problems.push(`chain breaks at record ${brk.index} (${brk.reason}): a row was changed, removed or inserted`);
+    }
+    // Each effect names the decision it belongs to. An effect whose ref is on no
+    // record is an action with no decision behind it — the loudest thing this
+    // file can find, so it is counted rather than summarised away.
+    const refler = new Set();
+    for (const r of records) {
+        if (typeof r.claims?.ref === "string")
+            refler.add(r.claims.ref);
+    }
+    let effects = 0;
+    let effectsBound = 0;
+    let effectsOrphaned = 0;
+    for (const path of effectFiles(dir)) {
+        for (const row of readJsonl(path, problems)) {
+            effects += 1;
+            const e = row;
+            const ref = typeof e.row?.ref === "string" ? e.row.ref : null;
+            if (ref !== null && refler.has(ref)) {
+                effectsBound += 1;
+            }
+            else {
+                effectsOrphaned += 1;
+                problems.push(`effect with no decision: ref ${ref ?? "(missing)"}`);
+            }
+        }
+    }
+    const ok = problems.length === 0 && signaturesInvalid === 0 && chainBreakAt === null && effectsOrphaned === 0;
+    return {
+        ok,
+        directory: dir,
+        decisions: records.length,
+        effects,
+        signaturesValid,
+        signaturesInvalid,
+        chainBreakAt,
+        effectsBound,
+        effectsOrphaned,
+        trust,
+        problems,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verax-ai/proxy",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {