@forum-labs/payfetch 1.0.0

package/dist/src/core/fs.js

@@ -0,0 +1,104 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { dirname } from "node:path";
+function isEnoent(err) {
+    return err?.code === "ENOENT";
+}
+function isEexist(err) {
+    return err?.code === "EEXIST";
+}
+export const realFs = {
+    ensureDir(dir) {
+        mkdirSync(dir, { recursive: true });
+    },
+    readText(path) {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return null;
+            throw err;
+        }
+    },
+    writeText(path, data) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp.${process.pid}`;
+        const fd = openSync(tmp, "w");
+        try {
+            writeSync(fd, data);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    },
+    writeBytes(path, data) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp.${process.pid}`;
+        const fd = openSync(tmp, "w");
+        try {
+            writeSync(fd, data);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    },
+    appendLine(path, line, opts) {
+        mkdirSync(dirname(path), { recursive: true });
+        const fd = openSync(path, "a");
+        try {
+            writeSync(fd, line.endsWith("\n") ? line : `${line}\n`);
+            if (opts.fsync)
+                fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    },
+    statMtimeMs(path) {
+        try {
+            return statSync(path).mtimeMs;
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return null;
+            throw err;
+        }
+    },
+    listDir(dir) {
+        try {
+            return readdirSync(dir);
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return [];
+            throw err;
+        }
+    },
+    tryCreateExclusive(path, contents, mode) {
+        mkdirSync(dirname(path), { recursive: true });
+        let fd;
+        try {
+            fd = openSync(path, "wx", mode ?? 0o666);
+        }
+        catch (err) {
+            if (isEexist(err))
+                return false;
+            throw err;
+        }
+        try {
+            writeSync(fd, contents);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+};

package/dist/src/core/integrity.d.ts

@@ -0,0 +1,23 @@
+import type { PayfetchFs } from "./fs.js";
+export declare const INTEGRITY_KEY_BYTES = 32;
+export declare const INTEGRITY_KEY_MODE = 384;
+export type SidecarRecord = {
+    seq: number;
+    receiptId: string;
+    sha256: string;
+    mac: string;
+};
+export type MonthIntegrity = {
+    ok: boolean;
+    checked: number;
+    issues: string[];
+};
+export declare function integrityKeyPath(dataDir: string): string;
+export declare function sidecarPath(monthFile: string): string;
+export declare function lineHash(lineString: string): string;
+export declare function genesisMac(key: Uint8Array, monthKey: string): string;
+export declare function nextMac(key: Uint8Array, prevMacHex: string, lineSha256Hex: string): string;
+export declare function loadOrCreateKey(fs: PayfetchFs, dataDir: string, random: () => Uint8Array): Uint8Array;
+export declare function defaultRandom(): Uint8Array;
+export declare function readSidecarRecords(fs: PayfetchFs, sidecar: string): SidecarRecord[];
+export declare function verifyMonth(fs: PayfetchFs, _dataDir: string, key: Uint8Array, monthFile: string): MonthIntegrity;

package/dist/src/core/integrity.js

@@ -0,0 +1,150 @@
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import { basename, join } from "node:path";
+const GENESIS_PREFIX = "p3f-integrity-genesis:";
+export const INTEGRITY_KEY_BYTES = 32;
+export const INTEGRITY_KEY_MODE = 0o600;
+const JSONL_SUFFIX = ".jsonl";
+const SIDECAR_SUFFIX = ".integrity";
+export function integrityKeyPath(dataDir) {
+    return join(dataDir, "integrity.key");
+}
+export function sidecarPath(monthFile) {
+    return `${monthFile}${SIDECAR_SUFFIX}`;
+}
+function monthKeyOfFile(monthFile) {
+    const base = basename(monthFile);
+    return base.endsWith(JSONL_SUFFIX) ? base.slice(0, -JSONL_SUFFIX.length) : base;
+}
+function bytesToHex(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++)
+        s += bytes[i].toString(16).padStart(2, "0");
+    return s;
+}
+function hexToBytes(hex) {
+    const h = hex.trim();
+    if (h.length === 0 || h.length % 2 !== 0)
+        return null;
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(h.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte))
+            return null;
+        out[i] = byte;
+    }
+    return out;
+}
+export function lineHash(lineString) {
+    return createHash("sha256").update(lineString).digest("hex");
+}
+export function genesisMac(key, monthKey) {
+    return createHmac("sha256", key).update(GENESIS_PREFIX + monthKey).digest("hex");
+}
+export function nextMac(key, prevMacHex, lineSha256Hex) {
+    return createHmac("sha256", key)
+        .update(`${prevMacHex}:${lineSha256Hex}`)
+        .digest("hex");
+}
+export function loadOrCreateKey(fs, dataDir, random) {
+    const path = integrityKeyPath(dataDir);
+    const existing = fs.readText(path);
+    if (existing !== null) {
+        const bytes = hexToBytes(existing);
+        if (bytes !== null)
+            return bytes;
+    }
+    const fresh = random();
+    const hex = bytesToHex(fresh);
+    if (fs.tryCreateExclusive(path, hex, INTEGRITY_KEY_MODE))
+        return fresh;
+    const raced = fs.readText(path);
+    const bytes = raced !== null ? hexToBytes(raced) : null;
+    return bytes ?? fresh;
+}
+export function defaultRandom() {
+    return new Uint8Array(randomBytes(INTEGRITY_KEY_BYTES));
+}
+function isSidecarRecord(o) {
+    if (o == null || typeof o !== "object")
+        return false;
+    const r = o;
+    return (typeof r.seq === "number" &&
+        typeof r.receiptId === "string" &&
+        typeof r.sha256 === "string" &&
+        typeof r.mac === "string");
+}
+export function readSidecarRecords(fs, sidecar) {
+    const raw = fs.readText(sidecar);
+    if (raw === null)
+        return [];
+    const out = [];
+    for (const seg of raw.split("\n")) {
+        if (seg.trim().length === 0)
+            continue;
+        try {
+            const o = JSON.parse(seg);
+            if (isSidecarRecord(o))
+                out.push(o);
+        }
+        catch {
+        }
+    }
+    return out;
+}
+function readLedgerLines(fs, monthFile) {
+    const raw = fs.readText(monthFile);
+    if (raw === null)
+        return [];
+    const out = [];
+    for (const seg of raw.split("\n")) {
+        if (seg.trim().length === 0)
+            continue;
+        out.push(seg);
+    }
+    return out;
+}
+function lineReceiptId(line) {
+    try {
+        const o = JSON.parse(line);
+        return typeof o.receiptId === "string" ? o.receiptId : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function verifyMonth(fs, _dataDir, key, monthFile) {
+    const issues = [];
+    const monthKey = monthKeyOfFile(monthFile);
+    const lines = readLedgerLines(fs, monthFile);
+    const records = readSidecarRecords(fs, sidecarPath(monthFile));
+    let prev = genesisMac(key, monthKey);
+    const n = Math.max(lines.length, records.length);
+    for (let i = 0; i < n; i++) {
+        const line = i < lines.length ? lines[i] : null;
+        const rec = i < records.length ? records[i] : null;
+        if (line === null && rec !== null) {
+            issues.push(`seq ${i} (receiptId ${rec.receiptId}): sidecar record has no matching ledger line (extra sidecar record / deleted ledger line)`);
+            prev = rec.mac;
+            continue;
+        }
+        if (line !== null && rec === null) {
+            issues.push(`seq ${i} (receiptId ${lineReceiptId(line) ?? "?"}): ledger line has no sidecar record (missing sidecar record)`);
+            prev = nextMac(key, prev, lineHash(line));
+            continue;
+        }
+        const sha = lineHash(line);
+        const expectedMac = nextMac(key, prev, sha);
+        const rid = lineReceiptId(line) ?? rec.receiptId;
+        if (rec.sha256 !== sha) {
+            issues.push(`seq ${i} (receiptId ${rid}): ledger line hash mismatch — line was edited or corrupted`);
+        }
+        if (rec.mac !== expectedMac) {
+            issues.push(`seq ${i} (receiptId ${rid}): MAC mismatch — broken hash-chain (tampered, reordered, or deleted line)`);
+        }
+        if (rec.seq !== i) {
+            issues.push(`seq ${i} (receiptId ${rid}): sidecar record has out-of-order seq ${rec.seq}`);
+        }
+        prev = rec.mac;
+    }
+    return { ok: issues.length === 0, checked: lines.length, issues };
+}

package/dist/src/core/ledger.d.ts

@@ -0,0 +1,149 @@
+import type { PayfetchFs } from "./fs.js";
+import { type MonthIntegrity } from "./integrity.js";
+import type { PaymentQuote } from "../payer/types.js";
+import type { GuardResult } from "../guards/types.js";
+export type GuardBlockReason = "danger" | "degraded" | "timeout" | "unavailable";
+export type Outcome = "free" | "dry_run" | "policy_denied" | "guard_blocked" | "approval_denied" | "approval_queued" | "approval_timeout" | "paid_delivered" | "paid_not_delivered" | "payment_rejected" | "unknown_settlement" | "fetch_error";
+export type Receipt = {
+    schema: "p3f.receipt.v1";
+    receiptId: string;
+    ts: number;
+    clientVersion: string;
+    policyVersion: "p3f-policy-1.5.0";
+    test: boolean;
+    url: string;
+    method: string;
+    host: string;
+    outcome: Outcome;
+    denyCode: string | null;
+    guardBlockReason?: GuardBlockReason | null;
+    verdictPath: string[];
+    quote: PaymentQuote | null;
+    rejectedQuotes: Record<string, number> | null;
+    guards: GuardResult[];
+    approval: {
+        mode: string;
+        approvedBy: "elicit" | "queue" | "config" | null;
+    } | null;
+    payment: {
+        payerAddress: string;
+        nonce: string;
+        validBeforeTs: number;
+        settledAmountUsd: number | null;
+        txRef: string | null;
+        settlementConfirmed: boolean;
+    } | null;
+    budgets: {
+        dayRemainingUsd: number;
+        hostRemainingUsd: number;
+        totalRemainingUsd: number | null;
+    };
+    http: {
+        status: number | null;
+        contentType: string | null;
+        bodyBytes: number | null;
+        bodySha256: string | null;
+        truncated: boolean;
+        totalMs: number;
+    } | null;
+    notes: string[];
+};
+export type AdjustKind = "hold_released_expiry" | "hold_settled_expiry" | "autodeny_set" | "autodeny_cleared" | "manual_note";
+export type Adjust = {
+    schema: "p3f.adjust.v1";
+    receiptId: string;
+    ts: number;
+    kind: AdjustKind;
+    detail: Record<string, unknown>;
+};
+export type LedgerEntry = Receipt | Adjust;
+export declare function isReceipt(e: LedgerEntry): e is Receipt;
+export declare function isAdjust(e: LedgerEntry): e is Adjust;
+export type StrikeClass = "confirmed" | "soft";
+export type StrikeRecord = {
+    ts: number;
+    class: StrikeClass;
+};
+export type HostAutoDeny = {
+    strikes: StrikeRecord[];
+    deniedUntilTs: number | null;
+};
+export type Hold = {
+    holdId: string;
+    amountUsd: number;
+    host: string;
+    validBeforeTs: number;
+    createdTs: number;
+    counterKeys: string[];
+    signed?: boolean;
+};
+export type ApprovalGrant = {
+    approvalId: string;
+    host: string;
+    amountUsd: number;
+    createdTs: number;
+    resource: string | null;
+    status: "pending" | "granted";
+};
+export type State = {
+    schema: "p3f.state.v1";
+    installId: string;
+    counters: Record<string, number>;
+    holds: Hold[];
+    autoDeny: Record<string, HostAutoDeny>;
+    approvals: ApprovalGrant[];
+};
+export declare function utcDate(ms: number): string;
+export declare function monthKey(ms: number): string;
+export declare const TOTAL_KEY = "total";
+export declare function dayKey(date: string): string;
+export declare function hostDayKey(host: string, date: string): string;
+export declare function guardDayKey(guardId: string, date: string): string;
+export declare function mainCounterKeys(host: string, ms: number): string[];
+export declare function isSettledOutcome(o: Outcome): boolean;
+export declare function isHoldKeptOutcome(o: Outcome): boolean;
+export declare function strikeClassForOutcome(o: Outcome): StrikeClass | null;
+export type LedgerOptions = {
+    isPidAlive?: (pid: number) => boolean;
+    random?: () => Uint8Array;
+};
+export declare class LedgerLockedError extends Error {
+    constructor(pid: number);
+}
+export declare class LedgerAppendConflictError extends Error {
+    constructor(receiptId: string);
+}
+export declare class Ledger {
+    #private;
+    constructor(fs: PayfetchFs, dataDir: string, now: () => number, opts?: LedgerOptions);
+    private ledgerDir;
+    private monthFile;
+    private statePath;
+    private lockPath;
+    downloadPath(receiptId: string): string;
+    acquireLock(pid?: number): void;
+    private parseLock;
+    private refreshLock;
+    releaseLock(): void;
+    append(receipt: Receipt): void;
+    appendAdjust(adjust: Adjust): void;
+    private recordIntegrity;
+    private integrityKey;
+    verifyIntegrity(): {
+        ok: boolean;
+        months: Array<{
+            month: string;
+        } & MonthIntegrity>;
+    };
+    private readMonth;
+    readEntries(): LedgerEntry[];
+    readAllReceipts(): Receipt[];
+    loadStateRaw(): State | null;
+    saveState(state: State): void;
+    rebuildState(installId: string): State;
+}
+export declare function applyStrike(autoDeny: Record<string, HostAutoDeny>, host: string, ts: number, cls: StrikeClass): {
+    strikeCount: number;
+    engaged: boolean;
+};
+export declare function isHostAutoDenied(autoDeny: Record<string, HostAutoDeny>, host: string, now: number): boolean;