@forum-labs/payfetch 1.0.0

package/dist/src/core/ledger.js

@@ -0,0 +1,357 @@
+import { join } from "node:path";
+import { AUTO_DENY_STRIKES, AUTO_DENY_TTL_DAYS, AUTO_DENY_UNKNOWN_ONLY_STRIKES, AUTO_DENY_WINDOW_DAYS, LOCK_STALE_S, } from "./constants.js";
+import { defaultRandom, genesisMac, lineHash, loadOrCreateKey, nextMac, readSidecarRecords, sidecarPath, verifyMonth, } from "./integrity.js";
+export function isReceipt(e) {
+    return e.schema === "p3f.receipt.v1";
+}
+export function isAdjust(e) {
+    return e.schema === "p3f.adjust.v1";
+}
+export function utcDate(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+export function monthKey(ms) {
+    return new Date(ms).toISOString().slice(0, 7);
+}
+export const TOTAL_KEY = "total";
+export function dayKey(date) {
+    return `day:${date}`;
+}
+export function hostDayKey(host, date) {
+    return `host:${host}:${date}`;
+}
+export function guardDayKey(guardId, date) {
+    return `guard:${guardId}:${date}`;
+}
+export function mainCounterKeys(host, ms) {
+    const d = utcDate(ms);
+    return [dayKey(d), hostDayKey(host, d), TOTAL_KEY];
+}
+const FSYNC_OUTCOMES = new Set([
+    "paid_delivered",
+    "paid_not_delivered",
+    "payment_rejected",
+    "unknown_settlement",
+]);
+export function isSettledOutcome(o) {
+    return o === "paid_delivered" || o === "paid_not_delivered";
+}
+export function isHoldKeptOutcome(o) {
+    return (o === "payment_rejected" || o === "unknown_settlement" || o === "fetch_error");
+}
+export function strikeClassForOutcome(o) {
+    if (o === "paid_not_delivered" || o === "payment_rejected")
+        return "confirmed";
+    if (o === "unknown_settlement")
+        return "soft";
+    return null;
+}
+export class LedgerLockedError extends Error {
+    constructor(pid) {
+        super(`payfetch: another live instance holds the ledger lock (pid ${pid}); refusing to start (SPEC §8.1).`);
+        this.name = "LedgerLockedError";
+    }
+}
+export class LedgerAppendConflictError extends Error {
+    constructor(receiptId) {
+        super(`payfetch: refusing to re-append receiptId ${receiptId} — the ledger is append-only (SPEC §8/§14).`);
+        this.name = "LedgerAppendConflictError";
+    }
+}
+export class Ledger {
+    #fs;
+    #dataDir;
+    #now;
+    #isPidAlive;
+    #random;
+    #seenReceiptIds = new Set();
+    #holdsLock = false;
+    #integrityKey = null;
+    #integrityByMonth = new Map();
+    constructor(fs, dataDir, now, opts = {}) {
+        this.#fs = fs;
+        this.#dataDir = dataDir;
+        this.#now = now;
+        this.#random = opts.random ?? defaultRandom;
+        this.#isPidAlive =
+            opts.isPidAlive ??
+                ((pid) => {
+                    try {
+                        process.kill(pid, 0);
+                        return true;
+                    }
+                    catch (err) {
+                        return err.code === "EPERM";
+                    }
+                });
+    }
+    ledgerDir() {
+        return join(this.#dataDir, "ledger");
+    }
+    monthFile(ms) {
+        return join(this.ledgerDir(), `${monthKey(ms)}.jsonl`);
+    }
+    statePath() {
+        return join(this.#dataDir, "state.json");
+    }
+    lockPath() {
+        return join(this.#dataDir, "lock");
+    }
+    downloadPath(receiptId) {
+        return join(this.#dataDir, "downloads", receiptId);
+    }
+    acquireLock(pid = process.pid) {
+        this.#fs.ensureDir(this.#dataDir);
+        const path = this.lockPath();
+        const contents = JSON.stringify({ pid, ts: this.#now() });
+        if (this.#fs.tryCreateExclusive(path, contents)) {
+            this.#holdsLock = true;
+            return;
+        }
+        const raw = this.#fs.readText(path);
+        const holder = this.parseLock(raw);
+        const stale = holder === null ||
+            this.#now() - holder.ts > LOCK_STALE_S * 1000 ||
+            !this.#isPidAlive(holder.pid);
+        if (!stale)
+            throw new LedgerLockedError(holder.pid);
+        this.#fs.remove(path);
+        if (!this.#fs.tryCreateExclusive(path, contents)) {
+            const now2 = this.parseLock(this.#fs.readText(path));
+            throw new LedgerLockedError(now2?.pid ?? -1);
+        }
+        this.#holdsLock = true;
+    }
+    parseLock(raw) {
+        if (raw === null)
+            return null;
+        try {
+            const o = JSON.parse(raw);
+            if (typeof o.pid === "number" && typeof o.ts === "number") {
+                return { pid: o.pid, ts: o.ts };
+            }
+        }
+        catch {
+        }
+        return null;
+    }
+    refreshLock(pid = process.pid) {
+        if (!this.#holdsLock)
+            return;
+        this.#fs.writeText(this.lockPath(), JSON.stringify({ pid, ts: this.#now() }));
+    }
+    releaseLock() {
+        if (!this.#holdsLock)
+            return;
+        this.#fs.remove(this.lockPath());
+        this.#holdsLock = false;
+    }
+    append(receipt) {
+        if (this.#seenReceiptIds.has(receipt.receiptId)) {
+            throw new LedgerAppendConflictError(receipt.receiptId);
+        }
+        const fsync = FSYNC_OUTCOMES.has(receipt.outcome) || receipt.payment !== null;
+        const json = JSON.stringify(receipt);
+        this.#fs.appendLine(this.monthFile(receipt.ts), json, { fsync });
+        this.#seenReceiptIds.add(receipt.receiptId);
+        this.recordIntegrity(receipt.ts, json, receipt.receiptId, fsync);
+        this.refreshLock();
+    }
+    appendAdjust(adjust) {
+        const json = JSON.stringify(adjust);
+        this.#fs.appendLine(this.monthFile(adjust.ts), json, { fsync: true });
+        this.recordIntegrity(adjust.ts, json, adjust.receiptId, true);
+        this.refreshLock();
+    }
+    recordIntegrity(ts, json, receiptId, fsync) {
+        try {
+            const key = this.integrityKey();
+            const mk = monthKey(ts);
+            const mf = this.monthFile(ts);
+            let st = this.#integrityByMonth.get(mf);
+            if (st === undefined) {
+                const records = readSidecarRecords(this.#fs, sidecarPath(mf));
+                const prevMac = records.length > 0 ? records[records.length - 1].mac : genesisMac(key, mk);
+                st = { prevMac, nextSeq: records.length };
+                this.#integrityByMonth.set(mf, st);
+            }
+            const sha256 = lineHash(json);
+            const mac = nextMac(key, st.prevMac, sha256);
+            const record = { seq: st.nextSeq, receiptId, sha256, mac };
+            this.#fs.appendLine(sidecarPath(mf), JSON.stringify(record), { fsync });
+            st.prevMac = mac;
+            st.nextSeq += 1;
+        }
+        catch {
+        }
+    }
+    integrityKey() {
+        if (this.#integrityKey === null) {
+            this.#integrityKey = loadOrCreateKey(this.#fs, this.#dataDir, this.#random);
+        }
+        return this.#integrityKey;
+    }
+    verifyIntegrity() {
+        const key = this.integrityKey();
+        const files = this.#fs
+            .listDir(this.ledgerDir())
+            .filter((f) => f.endsWith(".jsonl"));
+        files.sort();
+        const months = files.map((f) => {
+            const res = verifyMonth(this.#fs, this.#dataDir, key, join(this.ledgerDir(), f));
+            return { month: f.replace(/\.jsonl$/, ""), ...res };
+        });
+        return { ok: months.every((m) => m.ok), months };
+    }
+    readMonth(ms) {
+        const raw = this.#fs.readText(this.monthFile(ms));
+        if (raw === null)
+            return [];
+        const out = [];
+        for (const line of raw.split("\n")) {
+            const s = line.trim();
+            if (s.length === 0)
+                continue;
+            try {
+                const o = JSON.parse(s);
+                if (o && (o.schema === "p3f.receipt.v1" || o.schema === "p3f.adjust.v1")) {
+                    out.push(o);
+                }
+            }
+            catch {
+            }
+        }
+        return out;
+    }
+    readEntries() {
+        const now = this.#now();
+        const prevMs = new Date(now);
+        prevMs.setUTCDate(0);
+        const cur = this.monthFile(now);
+        const prev = this.monthFile(prevMs.getTime());
+        if (cur === prev)
+            return this.readMonth(now);
+        return [...this.readMonth(prevMs.getTime()), ...this.readMonth(now)];
+    }
+    readAllReceipts() {
+        const files = this.#fs.listDir(this.ledgerDir()).filter((f) => f.endsWith(".jsonl"));
+        files.sort();
+        const out = [];
+        for (const f of files) {
+            const raw = this.#fs.readText(join(this.ledgerDir(), f));
+            if (raw === null)
+                continue;
+            for (const line of raw.split("\n")) {
+                const s = line.trim();
+                if (s.length === 0)
+                    continue;
+                try {
+                    const o = JSON.parse(s);
+                    if (o && o.schema === "p3f.receipt.v1")
+                        out.push(o);
+                }
+                catch {
+                }
+            }
+        }
+        return out;
+    }
+    loadStateRaw() {
+        const raw = this.#fs.readText(this.statePath());
+        if (raw === null)
+            return null;
+        try {
+            const o = JSON.parse(raw);
+            if (o &&
+                o.schema === "p3f.state.v1" &&
+                typeof o.installId === "string" &&
+                o.counters &&
+                Array.isArray(o.holds) &&
+                o.autoDeny &&
+                Array.isArray(o.approvals)) {
+                return o;
+            }
+        }
+        catch {
+        }
+        return null;
+    }
+    saveState(state) {
+        this.#fs.writeText(this.statePath(), JSON.stringify(state));
+        this.refreshLock();
+    }
+    rebuildState(installId) {
+        const entries = this.readEntries();
+        const released = new Set();
+        const settledOnExpiry = new Set();
+        for (const e of entries) {
+            if (!isAdjust(e))
+                continue;
+            if (e.kind === "hold_released_expiry")
+                released.add(e.receiptId);
+            else if (e.kind === "hold_settled_expiry")
+                settledOnExpiry.add(e.receiptId);
+        }
+        const counters = {};
+        const holds = [];
+        const autoDeny = {};
+        const receipts = entries.filter(isReceipt).sort((a, b) => a.ts - b.ts);
+        for (const r of receipts) {
+            if (r.payment !== null) {
+                const keys = mainCounterKeys(r.host, r.ts);
+                if (isSettledOutcome(r.outcome)) {
+                    const amt = r.payment.settledAmountUsd ?? r.quote?.amountUsd ?? 0;
+                    for (const k of keys)
+                        counters[k] = (counters[k] ?? 0) + amt;
+                }
+                else if (isHoldKeptOutcome(r.outcome)) {
+                    if (settledOnExpiry.has(r.receiptId)) {
+                        const amt = r.payment.settledAmountUsd ?? r.quote?.amountUsd ?? 0;
+                        for (const k of keys)
+                            counters[k] = (counters[k] ?? 0) + amt;
+                    }
+                    else if (released.has(r.receiptId)) {
+                    }
+                    else {
+                        holds.push({
+                            holdId: r.receiptId,
+                            amountUsd: r.quote?.amountUsd ?? 0,
+                            host: r.host,
+                            validBeforeTs: r.payment.validBeforeTs,
+                            createdTs: r.ts,
+                            counterKeys: keys,
+                            signed: true,
+                        });
+                    }
+                }
+            }
+            const cls = strikeClassForOutcome(r.outcome);
+            if (cls !== null)
+                applyStrike(autoDeny, r.host, r.ts, cls);
+        }
+        return { schema: "p3f.state.v1", installId, counters, holds, autoDeny, approvals: [] };
+    }
+}
+const DAY_MS = 86_400_000;
+export function applyStrike(autoDeny, host, ts, cls) {
+    const entry = autoDeny[host] ?? { strikes: [], deniedUntilTs: null };
+    const windowStart = ts - AUTO_DENY_WINDOW_DAYS * DAY_MS;
+    entry.strikes = entry.strikes.filter((s) => s.ts >= windowStart);
+    entry.strikes.push({ ts, class: cls });
+    entry.strikes.sort((a, b) => a.ts - b.ts);
+    const total = entry.strikes.length;
+    const confirmed = entry.strikes.filter((s) => s.class === "confirmed").length;
+    const soft = total - confirmed;
+    const engage = (total >= AUTO_DENY_STRIKES && confirmed >= 1) ||
+        soft >= AUTO_DENY_UNKNOWN_ONLY_STRIKES;
+    if (engage) {
+        const lastTs = entry.strikes[entry.strikes.length - 1].ts;
+        entry.deniedUntilTs = lastTs + AUTO_DENY_TTL_DAYS * DAY_MS;
+    }
+    autoDeny[host] = entry;
+    return { strikeCount: total, engaged: engage };
+}
+export function isHostAutoDenied(autoDeny, host, now) {
+    const e = autoDeny[host];
+    return e != null && e.deniedUntilTs != null && now < e.deniedUntilTs;
+}

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

@@ -0,0 +1,22 @@
+import type { GuardId } from "../guards/types.js";
+export type FixedNoteCode = "malformed_402" | "unsupported_terms" | "unsupported_scheme_upto" | "unknown_asset" | "unsupported_network" | "host_denied" | "host_not_allowlisted" | "host_auto_denied" | "per_call_cap_exceeded" | "guard_unrated" | "approval_mode_deny" | "approval_timeout" | "approval_queue_expired" | "elicit_unsupported" | "elicit_cancelled" | "settlement_unconfirmed" | "body_truncated" | "insecure_redirect" | "private_target_blocked" | "hold_released_expiry" | "test_mode";
+export type BudgetWhich = "day" | "host" | "total";
+export type ElicitFallback = "queue" | "deny";
+export type PreapprovedWhich = "host" | "cap";
+export type BudgetExhaustedNote = `budget_exhausted:${BudgetWhich}`;
+export type PreapprovedNote = `preapproved:${PreapprovedWhich}`;
+export type GuardBlockedNote = `guard_blocked:${GuardId}`;
+export type GuardUnavailableNote = `guard_unavailable:${GuardId}`;
+export type GuardWarnNote = `guard_warn:${GuardId}`;
+export type RedirectedNote = `redirected:${number}`;
+export type AutodenyStrikeNote = `autodeny_strike:${number}`;
+export type ElicitFallbackNote = `elicit_unsupported_fallback:${ElicitFallback}`;
+export type NoteCode = FixedNoteCode | BudgetExhaustedNote | PreapprovedNote | GuardBlockedNote | GuardUnavailableNote | GuardWarnNote | RedirectedNote | AutodenyStrikeNote | ElicitFallbackNote;
+export declare function budgetExhausted(which: BudgetWhich): BudgetExhaustedNote;
+export declare function preapproved(which: PreapprovedWhich): PreapprovedNote;
+export declare function guardBlocked(id: GuardId): GuardBlockedNote;
+export declare function guardUnavailable(id: GuardId): GuardUnavailableNote;
+export declare function guardWarn(id: GuardId): GuardWarnNote;
+export declare function redirected(n: number): RedirectedNote;
+export declare function autodenyStrike(n: number): AutodenyStrikeNote;
+export declare function elicitUnsupportedFallback(mode: ElicitFallback): ElicitFallbackNote;

package/dist/src/core/notes.js

@@ -0,0 +1,24 @@
+export function budgetExhausted(which) {
+    return `budget_exhausted:${which}`;
+}
+export function preapproved(which) {
+    return `preapproved:${which}`;
+}
+export function guardBlocked(id) {
+    return `guard_blocked:${id}`;
+}
+export function guardUnavailable(id) {
+    return `guard_unavailable:${id}`;
+}
+export function guardWarn(id) {
+    return `guard_warn:${id}`;
+}
+export function redirected(n) {
+    return `redirected:${n}`;
+}
+export function autodenyStrike(n) {
+    return `autodeny_strike:${n}`;
+}
+export function elicitUnsupportedFallback(mode) {
+    return `elicit_unsupported_fallback:${mode}`;
+}

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

@@ -0,0 +1,143 @@
+import type { Budget, RemainingBudgets } from "./budget.js";
+import type { PayfetchFs } from "./fs.js";
+import { Ledger, type Outcome, type Receipt } from "./ledger.js";
+import { type Policy } from "./policy.js";
+import { type TransportIo, type TransportResult } from "./transport.js";
+import type { PayfetchDeps, PaymentPayer, PaymentQuote } from "../payer/types.js";
+import type { GuardId, GuardResult, GuardRuntime, PrePayGuard } from "../guards/types.js";
+export type FetchOpts = {
+    maxAmountUsd?: number;
+    dryRun?: boolean;
+    tokenAddress?: string;
+    chain?: string;
+    responseMode?: "inline" | "file";
+};
+export type PayfetchFetchResult = {
+    response: Response | null;
+    receipt: Receipt;
+};
+export type Decision = {
+    outcome: Outcome;
+    denyCode: string | null;
+    decision: "would_pay" | "would_deny" | "free";
+    quote: PaymentQuote | null;
+    rejectedQuotes: Record<string, number> | null;
+    guards: GuardResult[];
+    remainingBudgets: RemainingBudgets;
+    notes: string[];
+};
+export type SpendStatus = {
+    date: string;
+    day: {
+        spentUsd: number;
+        remainingUsd: number;
+    };
+    total: {
+        spentUsd: number;
+        remainingUsd: number | null;
+    };
+    perHost: Record<string, {
+        spentUsd: number;
+        remainingUsd: number;
+    }>;
+    holds: {
+        holdId: string;
+        amountUsd: number;
+        host: string;
+        validBeforeTs: number;
+    }[];
+    autoDenied: {
+        host: string;
+        untilTs: number;
+    }[];
+    recentPayments: {
+        receiptId: string;
+        host: string;
+        amountUsd: number | null;
+        outcome: Outcome;
+        ts: number;
+    }[];
+};
+export type { GuardRuntime } from "../guards/types.js";
+export type EngineConfig = {
+    deps: PayfetchDeps;
+    fs: PayfetchFs;
+    ledger: Ledger;
+    budget: Budget;
+    payers: PaymentPayer[];
+    policyProvider: () => {
+        ok: true;
+        policy: Policy;
+    } | {
+        ok: false;
+        error: string;
+    };
+    transportIo: Omit<TransportIo, "now" | "log" | "fs">;
+    testMode: boolean;
+    approverEnabled: boolean;
+    delay?: (ms: number) => Promise<void>;
+    guardBaseUrls: {
+        trust: string | null;
+        safety: string | null;
+    };
+    via: string | null;
+};
+export declare class PayfetchEngine {
+    #private;
+    guards: PrePayGuard[];
+    constructor(cfg: EngineConfig);
+    private newReceiptId;
+    private capsOf;
+    private transportIo;
+    fetch(url: string, init?: RequestInit, opts?: FetchOpts): Promise<PayfetchFetchResult>;
+    quote(url: string, init?: RequestInit): Promise<{
+        decision: Decision;
+        receipt: Receipt;
+    }>;
+    status(): Promise<SpendStatus>;
+    receipts(q: {
+        sinceTs?: number;
+        host?: string;
+        outcome?: Outcome;
+        limit?: number;
+    }): Receipt[];
+    listApprovals(): ReturnType<Budget["listApprovals"]>;
+    queueCapableNow(): boolean;
+    resolveApproval(approvalId: string, approve: boolean): {
+        ok: boolean;
+        error?: string;
+    };
+    private run;
+    private executePayment;
+    private runGuard;
+    private guardUnavailableResult;
+    private runApproval;
+    private elicitUnavailable;
+    private queueApproval;
+    liveGuardBudgetUsd(id: GuardId): number;
+    makeGuardFetch(id: GuardId, budgetUsd: number | (() => number), baseUrl: string | null): GuardRuntime["guardFetch"];
+    private payGuardFetch;
+    private detectPayer;
+    private quoteAndReject;
+    private httpBlock;
+    private materialize;
+    private deny;
+    private denyGuardBlocked;
+    private baseReceipt;
+    private finish;
+    private decisionFromReceipt;
+}
+export type TerminalClass = {
+    outcome: Outcome;
+    holdDisposition: "settle" | "keep";
+    settlementConfirmed: boolean;
+    settledAmountUsd: number | null;
+    txRef: string | null;
+    note: string | null;
+};
+export declare function classifyTerminal(retry: TransportResult, quote: PaymentQuote): TerminalClass;
+export declare function classifyFromParts(status: number, settlement: {
+    success: boolean;
+    transaction?: string;
+} | null, _quote: PaymentQuote): TerminalClass;
+export declare function stripReservedHeaders(headers: RequestInit["headers"]): Record<string, string>;