@verax-ai/proxy 0.1.0

package/dist/ledger.js

@@ -0,0 +1,683 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, open, readFile } from "node:fs/promises";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+/** I/O seam so append-cost tests can count rereads without mocking node:fs. */
+export const ledgerFs = {
+    readFile,
+    readFileSync,
+    open,
+};
+import { join } from "node:path";
+import { canonical, decisionRecordHash } from "@cedulon/core";
+import { coseToHex, signCoseSign1 } from "@cedulon/cose";
+import { signEffectExtract, } from "@cedulon/effect-extract";
+import { tenantKey } from "./tenant.js";
+import { sha256Canonical } from "./hash.js";
+const DEFAULT_WITNESS = "self";
+/** One async tail so read-then-append cannot fork the chain. */
+class SerialQueue {
+    tail = Promise.resolve();
+    enqueue(fn) {
+        const run = this.tail.then(fn, fn);
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+function lineOf(value) {
+    return `${canonical(value)}\n`;
+}
+function parseJsonl(text) {
+    const rows = [];
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        rows.push(JSON.parse(line));
+    }
+    return rows;
+}
+async function readJsonl(path) {
+    try {
+        return parseJsonl(await ledgerFs.readFile(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+function readJsonlSync(path) {
+    try {
+        return parseJsonl(ledgerFs.readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+/** Write then fsync so a crash cannot drop a committed line. */
+export async function appendDurable(path, line) {
+    const fh = await ledgerFs.open(path, "a");
+    try {
+        await fh.write(line);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+}
+function assertDirPrivate(dir) {
+    if (process.platform === "win32") {
+        // Stated, not a silent pass: Windows ACL is not measured here.
+        return "not checked on this platform";
+    }
+    const mode = statSync(dir).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`ledger-dir-not-private:${mode.toString(8)}`);
+    }
+    return "owner-only";
+}
+function ensureLedgerDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return assertDirPrivate(dir);
+}
+export function signEffectAttestation(row, witnessClass, resultHash, signer) {
+    return signedEffectFields(row, witnessClass, resultHash, signer);
+}
+function signedEffectFields(row, witnessClass, resultHash, signer) {
+    if (!signer)
+        return {};
+    const clean = asEffectRow(row);
+    const receipt = signEffectExtract({
+        deciderId: "verax-proxy",
+        channelId: "verax-body",
+        windowStartMs: clean.timestampMs,
+        windowEndMs: clean.timestampMs + 1,
+        effects: [clean],
+    }, signer.privateKeyPem, signer.publicKeyPem);
+    const payload = Buffer.from(canonical({
+        ref: clean.ref,
+        effectHash: clean.effectHash,
+        witnessClass,
+        resultHash: resultHash ?? null,
+    }), "utf8");
+    const attestation = {
+        coseHex: coseToHex(signCoseSign1(payload, signer.privateKeyPem, "application/json")),
+    };
+    return { receipt, attestation };
+}
+function asEffectRow(row) {
+    return {
+        ref: row.ref,
+        effectHash: row.effectHash,
+        effectClass: row.effectClass,
+        timestampMs: row.timestampMs,
+        ...(row.actor !== undefined ? { actor: row.actor } : {}),
+    };
+}
+function asStoredEffect(row, witnessClass, resultHash, signer) {
+    const stored = {
+        row: asEffectRow(row),
+        witnessClass,
+        ...signedEffectFields(row, witnessClass, resultHash, signer),
+    };
+    if (resultHash !== undefined)
+        stored.resultHash = resultHash;
+    return stored;
+}
+function indexRowOf(signed) {
+    if (typeof signed.claims.ref !== "string")
+        return null;
+    return {
+        ref: signed.claims.ref,
+        requestHash: signed.claims.requestHash,
+        decision: signed.claims.decision,
+        reasonCode: signed.claims.reasonCode,
+        subject: signed.claims.subject,
+        policyHash: signed.claims.policyHash,
+        timestampMs: signed.claims.timestampMs,
+    };
+}
+function resolutionKindOf(row) {
+    if (row.decision === "allow")
+        return "allow";
+    if (row.reasonCode === "expired")
+        return "expired";
+    return null;
+}
+function noteReauth(map, row) {
+    if (row.reasonCode !== "spend-reauth-required")
+        return;
+    if (!map.has(row.requestHash))
+        map.set(row.requestHash, row.ref);
+}
+function noteCounted(times, row) {
+    if (row.decision === "allow" || row.decision === "defer")
+        times.push(row.timestampMs);
+}
+export class MemoryLedger {
+    permissionCheck = "owner-only";
+    effectSigner;
+    _decisions = [];
+    _effects = [];
+    byRef = new Map();
+    resolvedBy = new Map();
+    reauthByHash = new Map();
+    countedAt = [];
+    countsReadable = true;
+    q = new SerialQueue();
+    lookupByRef(ref) {
+        return this.byRef.get(ref) ?? null;
+    }
+    noteTenantRef(key, ref) {
+        const row = this.byRef.get(ref);
+        if (row)
+            this.byRef.set(`${key}:${ref}`, row);
+    }
+    lookupResolvedBy(deferRef) {
+        return this.resolvedBy.get(deferRef) ?? null;
+    }
+    noteResolution(deferRef, hit) {
+        this.resolvedBy.set(deferRef, hit);
+    }
+    lookupReauthByHash(requestHash) {
+        return this.reauthByHash.get(requestHash) ?? null;
+    }
+    countedTimes() {
+        return this.countedAt;
+    }
+    hasPrimaryEffect(ref) {
+        return this._effects.some((e) => e.row.ref === ref && e.row.effectClass !== "duplicate-effect");
+    }
+    async appendDecision(signed) {
+        return this.q.enqueue(async () => {
+            this._decisions.push(signed);
+            const row = indexRowOf(signed);
+            if (row) {
+                this.byRef.set(row.ref, row);
+                noteReauth(this.reauthByHash, row);
+                noteCounted(this.countedAt, row);
+            }
+        });
+    }
+    async appendDecisionChained(build) {
+        return this.q.enqueue(async () => {
+            const last = this._decisions[this._decisions.length - 1];
+            const signed = build(last ? decisionRecordHash(last) : null);
+            this._decisions.push(signed);
+            const row = indexRowOf(signed);
+            if (row) {
+                this.byRef.set(row.ref, row);
+                noteReauth(this.reauthByHash, row);
+                noteCounted(this.countedAt, row);
+            }
+        });
+    }
+    async appendEffect(row, witnessClass = DEFAULT_WITNESS, resultHash) {
+        return this.q.enqueue(async () => this.appendEffectUnlocked(row, witnessClass, resultHash));
+    }
+    async appendEffectUnlocked(row, witnessClass, resultHash) {
+        const existing = this._effects.find((e) => e.row.ref === row.ref && e.row.effectClass !== "duplicate-effect");
+        if (existing && row.effectClass !== "duplicate-effect") {
+            this._effects.push(asStoredEffect({
+                ref: row.ref,
+                effectHash: sha256Canonical({ refused: "duplicate-effect", ref: row.ref }),
+                effectClass: "duplicate-effect",
+                timestampMs: row.timestampMs,
+                actor: row.actor,
+            }, DEFAULT_WITNESS, resultHash, undefined));
+            throw new Error(`duplicate-effect:${row.ref}`);
+        }
+        this._effects.push(asStoredEffect(row, witnessClass, resultHash, this.effectSigner));
+    }
+    async decisions() {
+        return [...this._decisions];
+    }
+    async effects() {
+        return [...this._effects];
+    }
+    async lastDecisionHash() {
+        const last = this._decisions[this._decisions.length - 1];
+        return last ? decisionRecordHash(last) : null;
+    }
+    async exportExtract(window, signer) {
+        return signWindow(this._effects, window, signer);
+    }
+}
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function readLock(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw.pid !== "number" || typeof raw.startedAt !== "number")
+            return null;
+        return {
+            pid: raw.pid,
+            startedAt: raw.startedAt,
+            ...(typeof raw.token === "string" ? { token: raw.token } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export class FileLedger {
+    permissionCheck;
+    dir;
+    effectSigner;
+    /** Optional signer in another process. Null means stay `self`. */
+    remoteWitness;
+    decisionsPath;
+    effectsPath;
+    lockPath;
+    q = new SerialQueue();
+    token = randomBytes(16).toString("hex");
+    closed = false;
+    lost = false;
+    tailHash = null;
+    effectRefs = new Set();
+    byRef = new Map();
+    resolvedBy = new Map();
+    reauthByHash = new Map();
+    countedAt = [];
+    countsReadable = true;
+    copyDir;
+    heartbeatPath;
+    decisionCount = 0;
+    effectCount = 0;
+    constructor(dir) {
+        this.dir = dir;
+        this.permissionCheck = ensureLedgerDir(dir);
+        this.decisionsPath = join(dir, "decisions.jsonl");
+        this.effectsPath = join(dir, "effects.jsonl");
+        this.lockPath = join(dir, "ledger.lock");
+        this.copyDir = join(dir, "evidence-copy");
+        this.heartbeatPath = join(dir, "heartbeat.json");
+        this.acquireLock();
+        this.loadCaches();
+    }
+    /** After lock handoff a new instance reloads; the lost owner cannot append. */
+    loadCaches() {
+        this.effectRefs.clear();
+        this.byRef.clear();
+        this.resolvedBy.clear();
+        this.reauthByHash.clear();
+        this.countedAt.length = 0;
+        this.countsReadable = true;
+        let decisions = [];
+        try {
+            decisions = readJsonlSync(this.decisionsPath);
+        }
+        catch {
+            this.countsReadable = false;
+        }
+        this.decisionCount = decisions.length;
+        const last = decisions[decisions.length - 1];
+        this.tailHash = last ? decisionRecordHash(last) : null;
+        const rowsByRef = new Map();
+        for (const rec of decisions) {
+            const row = indexRowOf(rec);
+            if (row) {
+                this.byRef.set(row.ref, row);
+                const list = rowsByRef.get(row.ref) ?? [];
+                list.push(row);
+                rowsByRef.set(row.ref, list);
+                noteReauth(this.reauthByHash, row);
+                noteCounted(this.countedAt, row);
+            }
+        }
+        this.loadTenantRefs(rowsByRef);
+        this.effectCount = 0;
+        for (const effect of readJsonlSync(this.effectsPath)) {
+            this.effectCount += 1;
+            if (effect.row.effectClass !== "duplicate-effect")
+                this.effectRefs.add(effect.row.ref);
+        }
+        this.loadResolvedBy();
+    }
+    /** Pair inputs.jsonl with decisions so a restart keeps per-tenant `_ref` keys. */
+    loadTenantRefs(rowsByRef) {
+        let text;
+        try {
+            text = ledgerFs.readFileSync(join(this.dir, "inputs.jsonl"), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        const seen = new Map();
+        for (const line of text.split("\n")) {
+            if (line === "")
+                continue;
+            const row = JSON.parse(line);
+            if (typeof row.ref !== "string")
+                continue;
+            const principal = row.inputs?.principal;
+            if (!principal || typeof principal.brain !== "string")
+                continue;
+            const idx = seen.get(row.ref) ?? 0;
+            seen.set(row.ref, idx + 1);
+            const indexed = rowsByRef.get(row.ref)?.[idx];
+            if (!indexed)
+                continue;
+            const key = tenantKey({
+                brain: principal.brain,
+                iss: principal.iss,
+                tenant: principal.tenant,
+                org: principal.org,
+            });
+            this.byRef.set(`${key}:${row.ref}`, indexed);
+        }
+    }
+    /** Single pass over inputs.jsonl. FileInputsLog itself stays cache-less. */
+    loadResolvedBy() {
+        let text;
+        try {
+            text = ledgerFs.readFileSync(join(this.dir, "inputs.jsonl"), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const line of text.split("\n")) {
+            if (line === "")
+                continue;
+            const row = JSON.parse(line);
+            if (typeof row.ref !== "string")
+                continue;
+            const resolves = row.inputs?.approver?.resolves;
+            if (typeof resolves !== "string")
+                continue;
+            const indexed = this.byRef.get(row.ref);
+            if (!indexed)
+                continue;
+            const kind = resolutionKindOf(indexed);
+            if (kind)
+                this.resolvedBy.set(resolves, { ref: row.ref, kind });
+        }
+    }
+    lockBody() {
+        return `${JSON.stringify({ pid: process.pid, startedAt: Date.now(), token: this.token })}\n`;
+    }
+    ownsLock() {
+        const existing = readLock(this.lockPath);
+        return existing?.token === this.token;
+    }
+    /** Lock file on disk, not a process counter. */
+    lockStatus() {
+        return this.ownsLock() ? "held" : "free";
+    }
+    markLost() {
+        this.lost = true;
+    }
+    assertOwned() {
+        if (this.lost || !this.ownsLock()) {
+            this.markLost();
+            throw new Error("ledger-lost-lock");
+        }
+    }
+    lockedError() {
+        const existing = readLock(this.lockPath);
+        const pid = existing?.pid ?? "unknown";
+        if (typeof existing?.pid === "number" && !pidAlive(existing.pid)) {
+            return new Error(`ledger-locked-stale:${pid}\nrun: verax unlock ${this.dir}`);
+        }
+        return new Error(`ledger-locked:${pid}`);
+    }
+    acquireLock() {
+        const body = this.lockBody();
+        try {
+            writeFileSync(this.lockPath, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                throw this.lockedError();
+            throw err;
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (!this.ownsLock()) {
+            this.lost = true;
+            return;
+        }
+        try {
+            unlinkSync(this.lockPath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    async appendDecision(signed) {
+        return this.q.enqueue(async () => {
+            this.assertOwned();
+            await mkdir(this.dir, { recursive: true, mode: 0o700 });
+            const line = lineOf(signed);
+            await appendDurable(this.decisionsPath, line);
+            await this.pulse("decisions.jsonl", line, "decision");
+            this.tailHash = decisionRecordHash(signed);
+            const row = indexRowOf(signed);
+            if (row) {
+                this.byRef.set(row.ref, row);
+                noteReauth(this.reauthByHash, row);
+                noteCounted(this.countedAt, row);
+            }
+        });
+    }
+    async appendDecisionChained(build) {
+        return this.q.enqueue(async () => {
+            this.assertOwned();
+            const prev = await this.lastDecisionHashUnlocked();
+            await mkdir(this.dir, { recursive: true, mode: 0o700 });
+            const signed = build(prev);
+            const line = lineOf(signed);
+            await appendDurable(this.decisionsPath, line);
+            await this.pulse("decisions.jsonl", line, "decision");
+            this.tailHash = decisionRecordHash(signed);
+            const row = indexRowOf(signed);
+            if (row) {
+                this.byRef.set(row.ref, row);
+                noteReauth(this.reauthByHash, row);
+                noteCounted(this.countedAt, row);
+            }
+        });
+    }
+    async appendEffect(row, witnessClass = DEFAULT_WITNESS, resultHash) {
+        return this.q.enqueue(async () => {
+            this.assertOwned();
+            return this.appendEffectUnlocked(row, witnessClass, resultHash);
+        });
+    }
+    async appendEffectUnlocked(row, witnessClass = DEFAULT_WITNESS, resultHash) {
+        if (row.effectClass !== "duplicate-effect" && this.effectRefs.has(row.ref)) {
+            const dup = lineOf(asStoredEffect({
+                ref: row.ref,
+                effectHash: sha256Canonical({ refused: "duplicate-effect", ref: row.ref }),
+                effectClass: "duplicate-effect",
+                timestampMs: row.timestampMs,
+                actor: row.actor,
+            }, DEFAULT_WITNESS, resultHash, undefined));
+            await appendDurable(this.effectsPath, dup);
+            await this.pulse("effects.jsonl", dup, "effect");
+            throw new Error(`duplicate-effect:${row.ref}`);
+        }
+        const line = lineOf(await this.storeEffect(row, witnessClass, resultHash));
+        await appendDurable(this.effectsPath, line);
+        await this.pulse("effects.jsonl", line, "effect");
+        if (row.effectClass !== "duplicate-effect")
+            this.effectRefs.add(row.ref);
+    }
+    async decisions() {
+        return readJsonl(this.decisionsPath);
+    }
+    async effects() {
+        return readJsonl(this.effectsPath);
+    }
+    async lastDecisionHash() {
+        return this.lastDecisionHashUnlocked();
+    }
+    async lastDecisionHashUnlocked() {
+        return this.tailHash;
+    }
+    async exportExtract(window, signer) {
+        return signWindow(await this.effects(), window, signer);
+    }
+    lookupByRef(ref) {
+        return this.byRef.get(ref) ?? null;
+    }
+    noteTenantRef(key, ref) {
+        const row = this.byRef.get(ref);
+        if (row)
+            this.byRef.set(`${key}:${ref}`, row);
+    }
+    lookupResolvedBy(deferRef) {
+        return this.resolvedBy.get(deferRef) ?? null;
+    }
+    noteResolution(deferRef, hit) {
+        this.resolvedBy.set(deferRef, hit);
+    }
+    lookupReauthByHash(requestHash) {
+        return this.reauthByHash.get(requestHash) ?? null;
+    }
+    countedTimes() {
+        return this.countedAt;
+    }
+    hasPrimaryEffect(ref) {
+        return this.effectRefs.has(ref);
+    }
+    async pulse(name, line, kind) {
+        mkdirSync(this.copyDir, { recursive: true, mode: 0o700 });
+        appendFileSync(join(this.copyDir, name), line, { encoding: "utf8" });
+        if (kind === "decision")
+            this.decisionCount += 1;
+        else
+            this.effectCount += 1;
+        writeFileSync(this.heartbeatPath, `${JSON.stringify({
+            atMs: Date.now(),
+            pid: process.pid,
+            lastDecisionN: this.decisionCount,
+            lastEffectN: this.effectCount,
+        })}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    async storeEffect(row, witnessClass, resultHash) {
+        if (this.remoteWitness && row.effectClass !== "duplicate-effect") {
+            const remote = await this.remoteWitness(row, resultHash);
+            if (remote?.attestation && remote.receipt && remote.witnessClass && remote.witnessClass !== "self") {
+                const stored = {
+                    row: asEffectRow(row),
+                    witnessClass: remote.witnessClass,
+                    receipt: remote.receipt,
+                    attestation: remote.attestation,
+                };
+                if (resultHash !== undefined)
+                    stored.resultHash = resultHash;
+                return stored;
+            }
+            return asStoredEffect(row, DEFAULT_WITNESS, resultHash, this.effectSigner);
+        }
+        return asStoredEffect(row, witnessClass, resultHash, this.effectSigner);
+    }
+}
+function signWindow(effects, window, signer) {
+    const rows = effects
+        .filter((e) => e.row.timestampMs >= window.startMs && e.row.timestampMs < window.endMs)
+        .map((e) => asEffectRow(e.row));
+    return signEffectExtract({
+        deciderId: "verax-proxy",
+        channelId: "verax-body",
+        windowStartMs: window.startMs,
+        windowEndMs: window.endMs,
+        effects: rows,
+    }, signer.privateKeyPem, signer.publicKeyPem);
+}
+export async function lookupDecisionByRef(ledger, ref, key) {
+    const extra = ledger;
+    if (typeof extra.lookupByRef === "function") {
+        if (key)
+            return extra.lookupByRef(`${key}:${ref}`);
+        return extra.lookupByRef(ref);
+    }
+    const found = (await ledger.decisions()).find((d) => d.claims.ref === ref);
+    return found ? indexRowOf(found) : null;
+}
+export function noteTenantRef(ledger, key, ref) {
+    const extra = ledger;
+    if (typeof extra.noteTenantRef === "function")
+        extra.noteTenantRef(key, ref);
+}
+export function lookupResolvedBy(ledger, deferRef) {
+    const extra = ledger;
+    if (typeof extra.lookupResolvedBy === "function")
+        return extra.lookupResolvedBy(deferRef);
+    return null;
+}
+export function noteResolution(ledger, deferRef, hit) {
+    const extra = ledger;
+    if (typeof extra.noteResolution === "function")
+        extra.noteResolution(deferRef, hit);
+}
+export function countedWork(ledger, nowMs) {
+    const extra = ledger;
+    if (extra.countsReadable === false)
+        return { ok: false };
+    if (typeof extra.countedTimes !== "function")
+        return { ok: false };
+    const times = extra.countedTimes();
+    const minuteStart = nowMs - 60_000;
+    const day = new Date(nowMs);
+    const dayStart = Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate());
+    let minute = 0;
+    let dayCount = 0;
+    for (const t of times) {
+        if (t >= minuteStart && t <= nowMs)
+            minute += 1;
+        if (t >= dayStart && t <= nowMs)
+            dayCount += 1;
+    }
+    return { ok: true, minute, day: dayCount };
+}
+export async function lookupReauthByHash(ledger, requestHash) {
+    const extra = ledger;
+    if (typeof extra.lookupReauthByHash === "function")
+        return extra.lookupReauthByHash(requestHash);
+    for (const d of await ledger.decisions()) {
+        if (d.claims.reasonCode === "spend-reauth-required" && d.claims.requestHash === requestHash && d.claims.ref) {
+            return d.claims.ref;
+        }
+    }
+    return null;
+}
+export async function hasPrimaryEffect(ledger, ref) {
+    const extra = ledger;
+    if (typeof extra.hasPrimaryEffect === "function")
+        return extra.hasPrimaryEffect(ref);
+    return (await ledger.effects()).some((e) => e.row.ref === ref && e.row.effectClass !== "duplicate-effect");
+}
+export function witnessClassSummary(effects) {
+    const out = {
+        self: 0,
+        "same-org": 0,
+        "third-party": 0,
+        regulated: 0,
+    };
+    for (const e of effects) {
+        out[e.witnessClass] += 1;
+    }
+    return out;
+}