@forum-labs/payfetch 1.0.0

package/dist/src/config.js

@@ -0,0 +1,170 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { homedir as osHomedir } from "node:os";
+import { join } from "node:path";
+import { NONCE_BYTES } from "./core/constants.js";
+import { CdpServerWalletSigner } from "./payer/signer_cdp.js";
+import { LocalKeySigner } from "./payer/signer_local.js";
+export const ENV = {
+    PRIVATE_KEY: "PAYFETCH_PRIVATE_KEY",
+    KEY_FILE: "PAYFETCH_KEY_FILE",
+    CDP_API_KEY_ID: "PAYFETCH_CDP_API_KEY_ID",
+    CDP_API_KEY_SECRET: "PAYFETCH_CDP_API_KEY_SECRET",
+    CDP_WALLET_SECRET: "PAYFETCH_CDP_WALLET_SECRET",
+    CDP_ACCOUNT_NAME: "PAYFETCH_CDP_ACCOUNT_NAME",
+    DATA_DIR: "PAYFETCH_DATA_DIR",
+    TEST_MODE: "PAYFETCH_TEST_MODE",
+    APPROVER: "PAYFETCH_APPROVER",
+    VIA: "PAYFETCH_VIA",
+};
+export const DEFAULT_DATA_DIR_NAME = ".payfetch";
+export const APPROVER_ENABLED_VALUE = "1";
+const GROUP_WORLD_PERMS_MASK = 0o077;
+const MIN_SCRUB_SECRET_LEN = 6;
+export function realConfigIo() {
+    return {
+        readText: (path) => readFileSync(path, "utf8"),
+        statMode: (path) => {
+            try {
+                return statSync(path).mode;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return null;
+                throw err;
+            }
+        },
+        homedir: () => osHomedir(),
+        fetch: (...args) => fetch(...args),
+        now: () => Date.now(),
+        random: () => Uint8Array.from(randomBytes(NONCE_BYTES)),
+        log: (msg, fields) => {
+            process.stderr.write(`${JSON.stringify({ ts: Date.now(), msg, ...(fields ?? {}) })}\n`);
+        },
+    };
+}
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export function scrubSecrets(text, secrets) {
+    let out = text;
+    for (const s of secrets) {
+        if (s && s.length >= MIN_SCRUB_SECRET_LEN)
+            out = out.split(s).join("[redacted]");
+    }
+    out = out.replace(/0x[0-9a-fA-F]{16,}/g, "0x[redacted]");
+    out = out.replace(/\b[0-9a-fA-F]{32,}\b/g, "[redacted]");
+    out = out.replace(/\b[A-Za-z0-9_-]{40,}\b/g, "[redacted]");
+    return out;
+}
+function nonEmpty(v) {
+    return typeof v === "string" && v.trim().length > 0;
+}
+const NO_SIGNER_MSG = "payfetch: no wallet signer configured. Set EXACTLY ONE of: " +
+    "(1) PAYFETCH_PRIVATE_KEY (0x-hex private key), " +
+    "(2) PAYFETCH_KEY_FILE (path to a mode-600 key file), or " +
+    "(3) PAYFETCH_CDP_API_KEY_ID + PAYFETCH_CDP_API_KEY_SECRET + PAYFETCH_CDP_WALLET_SECRET " +
+    "(Coinbase CDP server wallet). (SPEC §12)";
+export function selectSignerSource(env) {
+    const hasPk = nonEmpty(env[ENV.PRIVATE_KEY]);
+    const hasKf = nonEmpty(env[ENV.KEY_FILE]);
+    const cdpParts = [
+        [ENV.CDP_API_KEY_ID, nonEmpty(env[ENV.CDP_API_KEY_ID])],
+        [ENV.CDP_API_KEY_SECRET, nonEmpty(env[ENV.CDP_API_KEY_SECRET])],
+        [ENV.CDP_WALLET_SECRET, nonEmpty(env[ENV.CDP_WALLET_SECRET])],
+    ];
+    const cdpAny = cdpParts.some(([, present]) => present);
+    const cdpAll = cdpParts.every(([, present]) => present);
+    const present = [];
+    if (hasPk)
+        present.push("private_key");
+    if (hasKf)
+        present.push("key_file");
+    if (cdpAny)
+        present.push("cdp");
+    if (present.length === 0)
+        throw new ConfigError(NO_SIGNER_MSG);
+    if (present.length > 1) {
+        throw new ConfigError(`payfetch: multiple wallet signer sources set (${present.join(", ")}). ` +
+            "Set EXACTLY ONE — payfetch never guesses which wallet to spend from. " +
+            "Options: PAYFETCH_PRIVATE_KEY | PAYFETCH_KEY_FILE | PAYFETCH_CDP_* . (SPEC §12)");
+    }
+    if (present[0] === "cdp" && !cdpAll) {
+        const missing = cdpParts.filter(([, p]) => !p).map(([name]) => name);
+        throw new ConfigError(`payfetch: CDP signer selected but incomplete — missing ${missing.join(", ")}. ` +
+            "All of PAYFETCH_CDP_API_KEY_ID, PAYFETCH_CDP_API_KEY_SECRET, " +
+            "PAYFETCH_CDP_WALLET_SECRET are required. (SPEC §12)");
+    }
+    return present[0];
+}
+function newLocalSigner(key, secrets) {
+    try {
+        return new LocalKeySigner(key);
+    }
+    catch (err) {
+        const scrubbed = scrubSecrets(`${err.message}`, secrets);
+        throw new ConfigError(`payfetch: invalid private key — ${scrubbed} (SPEC §12)`);
+    }
+}
+function buildSigner(source, env, io) {
+    if (source === "private_key") {
+        const key = env[ENV.PRIVATE_KEY].trim();
+        return newLocalSigner(key, [key]);
+    }
+    if (source === "key_file") {
+        const path = env[ENV.KEY_FILE];
+        const mode = io.statMode(path);
+        if (mode === null) {
+            throw new ConfigError(`payfetch: PAYFETCH_KEY_FILE not found at "${path}". (SPEC §12)`);
+        }
+        if ((mode & GROUP_WORLD_PERMS_MASK) !== 0) {
+            throw new ConfigError(`payfetch: refusing to start — PAYFETCH_KEY_FILE "${path}" is group/world-readable ` +
+                `(mode ${(mode & 0o777).toString(8).padStart(3, "0")}). ` +
+                "Run: chmod 600 <file>. (SPEC §12)");
+        }
+        let contents;
+        try {
+            contents = io.readText(path);
+        }
+        catch (err) {
+            throw new ConfigError(`payfetch: could not read PAYFETCH_KEY_FILE "${path}": ${err.message}. (SPEC §12)`);
+        }
+        const key = contents.trim();
+        return newLocalSigner(key, [key, contents]);
+    }
+    return new CdpServerWalletSigner({
+        apiKeyId: env[ENV.CDP_API_KEY_ID],
+        apiKeySecret: env[ENV.CDP_API_KEY_SECRET],
+        walletSecret: env[ENV.CDP_WALLET_SECRET],
+        accountName: nonEmpty(env[ENV.CDP_ACCOUNT_NAME]) ? env[ENV.CDP_ACCOUNT_NAME].trim() : undefined,
+    });
+}
+export function resolveDataDir(env, homedir = osHomedir) {
+    const d = env[ENV.DATA_DIR];
+    return nonEmpty(d) ? d.trim() : join(homedir(), DEFAULT_DATA_DIR_NAME);
+}
+export function buildFromEnv(env, io = realConfigIo()) {
+    const source = selectSignerSource(env);
+    const signer = buildSigner(source, env, io);
+    const dataDir = resolveDataDir(env, io.homedir);
+    const viaRaw = env[ENV.VIA];
+    const via = nonEmpty(viaRaw) ? viaRaw.trim() : null;
+    const deps = {
+        fetch: io.fetch,
+        signer,
+        now: io.now,
+        random: io.random,
+        dataDir,
+        log: io.log,
+        elicit: null,
+    };
+    return {
+        deps,
+        testMode: env[ENV.TEST_MODE] != null,
+        approver: env[ENV.APPROVER] === APPROVER_ENABLED_VALUE,
+        via,
+    };
+}

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

@@ -0,0 +1,62 @@
+import { Ledger, type ApprovalGrant, type Hold, type State, type StrikeClass } from "./ledger.js";
+export type ReserveCaps = {
+    dailyUsd: number;
+    perHostDailyUsd: number;
+    totalUsd: number | null;
+};
+export type ExtraCap = {
+    key: string;
+    cap: number;
+    which: string;
+};
+export type ReserveRequest = {
+    holdId: string;
+    amountUsd: number;
+    host: string;
+    caps: ReserveCaps;
+    extra?: ExtraCap[];
+};
+export type ReserveResult = {
+    ok: true;
+    holdId: string;
+} | {
+    ok: false;
+    which: string;
+};
+export type RemainingBudgets = {
+    dayRemainingUsd: number;
+    hostRemainingUsd: number;
+    totalRemainingUsd: number | null;
+};
+export declare class Budget {
+    #private;
+    constructor(state: State, ledger: Ledger, now: () => number);
+    get state(): State;
+    private persist;
+    private spentMicro;
+    private heldMicro;
+    private usedMicro;
+    remaining(caps: ReserveCaps, host: string): RemainingBudgets;
+    sweepExpired(): string[];
+    reserve(req: ReserveRequest): ReserveResult;
+    setHoldValidBefore(holdId: string, validBeforeTs: number): void;
+    settle(holdId: string, actualUsd: number): void;
+    release(holdId: string): void;
+    getHold(holdId: string): Hold | undefined;
+    isAutoDenied(host: string): boolean;
+    recordStrike(host: string, cls: StrikeClass): {
+        strikeCount: number;
+        engaged: boolean;
+    };
+    clearAutoDeny(host: string): boolean;
+    autoDeniedHosts(): {
+        host: string;
+        untilTs: number;
+    }[];
+    findGrant(host: string, amountUsd: number): ApprovalGrant | null;
+    consumeGrant(approvalId: string): void;
+    addPendingApproval(entry: Omit<ApprovalGrant, "status">): ApprovalGrant;
+    listApprovals(): ApprovalGrant[];
+    resolvePending(approvalId: string, approve: boolean): ApprovalGrant | null;
+    private pruneExpiredApprovals;
+}

package/dist/src/core/budget.js

@@ -0,0 +1,236 @@
+import { APPROVAL_QUEUE_TTL_S, HOLD_RELEASE_MARGIN_S, PAYMENT_VALIDITY_MAX_S, } from "./constants.js";
+import { TOTAL_KEY, applyStrike, dayKey, hostDayKey, isHostAutoDenied, utcDate, } from "./ledger.js";
+function micro(usd) {
+    return Math.round(usd * 1_000_000);
+}
+export class Budget {
+    #state;
+    #ledger;
+    #now;
+    constructor(state, ledger, now) {
+        this.#state = state;
+        this.#ledger = ledger;
+        this.#now = now;
+    }
+    get state() {
+        return this.#state;
+    }
+    persist() {
+        this.#ledger.saveState(this.#state);
+    }
+    spentMicro(key) {
+        return micro(this.#state.counters[key] ?? 0);
+    }
+    heldMicro(key) {
+        let sum = 0;
+        for (const h of this.#state.holds) {
+            if (h.counterKeys.includes(key))
+                sum += micro(h.amountUsd);
+        }
+        return sum;
+    }
+    usedMicro(key) {
+        return this.spentMicro(key) + this.heldMicro(key);
+    }
+    remaining(caps, host) {
+        const d = utcDate(this.#now());
+        const dayRem = (micro(caps.dailyUsd) - this.usedMicro(dayKey(d))) / 1_000_000;
+        const hostRem = (micro(caps.perHostDailyUsd) - this.usedMicro(hostDayKey(host, d))) / 1_000_000;
+        const totalRem = caps.totalUsd == null
+            ? null
+            : (micro(caps.totalUsd) - this.usedMicro(TOTAL_KEY)) / 1_000_000;
+        return {
+            dayRemainingUsd: dayRem,
+            hostRemainingUsd: hostRem,
+            totalRemainingUsd: totalRem,
+        };
+    }
+    sweepExpired() {
+        const now = this.#now();
+        const swept = [];
+        const kept = [];
+        for (const h of this.#state.holds) {
+            const expireAtMs = (h.validBeforeTs + HOLD_RELEASE_MARGIN_S) * 1000;
+            if (now < expireAtMs) {
+                kept.push(h);
+                continue;
+            }
+            swept.push(h.holdId);
+            if (h.signed !== false) {
+                for (const k of h.counterKeys) {
+                    this.#state.counters[k] = (this.#state.counters[k] ?? 0) + h.amountUsd;
+                }
+                this.#ledger.appendAdjust({
+                    schema: "p3f.adjust.v1",
+                    receiptId: h.holdId,
+                    ts: now,
+                    kind: "hold_settled_expiry",
+                    detail: { amountUsd: h.amountUsd, host: h.host, validBeforeTs: h.validBeforeTs },
+                });
+            }
+            else {
+                this.#ledger.appendAdjust({
+                    schema: "p3f.adjust.v1",
+                    receiptId: h.holdId,
+                    ts: now,
+                    kind: "hold_released_expiry",
+                    detail: { amountUsd: h.amountUsd, host: h.host, validBeforeTs: h.validBeforeTs },
+                });
+            }
+        }
+        if (swept.length > 0) {
+            this.#state.holds = kept;
+            this.persist();
+        }
+        return swept;
+    }
+    reserve(req) {
+        const now = this.#now();
+        const d = utcDate(now);
+        const amt = micro(req.amountUsd);
+        const checks = [
+            { key: dayKey(d), capMicro: micro(req.caps.dailyUsd), which: "day" },
+            { key: hostDayKey(req.host, d), capMicro: micro(req.caps.perHostDailyUsd), which: "host" },
+        ];
+        if (req.caps.totalUsd != null) {
+            checks.push({ key: TOTAL_KEY, capMicro: micro(req.caps.totalUsd), which: "total" });
+        }
+        for (const e of req.extra ?? []) {
+            checks.push({ key: e.key, capMicro: micro(e.cap), which: e.which });
+        }
+        for (const c of checks) {
+            if (this.usedMicro(c.key) + amt > c.capMicro) {
+                return { ok: false, which: c.which };
+            }
+        }
+        const counterKeys = [
+            dayKey(d),
+            hostDayKey(req.host, d),
+            TOTAL_KEY,
+            ...(req.extra ?? []).map((e) => e.key),
+        ];
+        this.#state.holds.push({
+            holdId: req.holdId,
+            amountUsd: req.amountUsd,
+            host: req.host,
+            validBeforeTs: Math.floor(now / 1000) + PAYMENT_VALIDITY_MAX_S,
+            createdTs: now,
+            counterKeys,
+            signed: false,
+        });
+        this.persist();
+        return { ok: true, holdId: req.holdId };
+    }
+    setHoldValidBefore(holdId, validBeforeTs) {
+        const h = this.#state.holds.find((x) => x.holdId === holdId);
+        if (h) {
+            h.validBeforeTs = validBeforeTs;
+            h.signed = true;
+            this.persist();
+        }
+    }
+    settle(holdId, actualUsd) {
+        const h = this.#state.holds.find((x) => x.holdId === holdId);
+        if (!h)
+            return;
+        for (const k of h.counterKeys) {
+            this.#state.counters[k] = (this.#state.counters[k] ?? 0) + actualUsd;
+        }
+        this.#state.holds = this.#state.holds.filter((x) => x.holdId !== holdId);
+        this.persist();
+    }
+    release(holdId) {
+        const before = this.#state.holds.length;
+        this.#state.holds = this.#state.holds.filter((x) => x.holdId !== holdId);
+        if (this.#state.holds.length !== before)
+            this.persist();
+    }
+    getHold(holdId) {
+        return this.#state.holds.find((x) => x.holdId === holdId);
+    }
+    isAutoDenied(host) {
+        return isHostAutoDenied(this.#state.autoDeny, host, this.#now());
+    }
+    recordStrike(host, cls) {
+        const res = applyStrike(this.#state.autoDeny, host, this.#now(), cls);
+        if (res.engaged) {
+            this.#ledger.appendAdjust({
+                schema: "p3f.adjust.v1",
+                receiptId: host,
+                ts: this.#now(),
+                kind: "autodeny_set",
+                detail: {
+                    host,
+                    strikeCount: res.strikeCount,
+                    deniedUntilTs: this.#state.autoDeny[host]?.deniedUntilTs ?? null,
+                },
+            });
+        }
+        this.persist();
+        return res;
+    }
+    clearAutoDeny(host) {
+        if (!(host in this.#state.autoDeny))
+            return false;
+        delete this.#state.autoDeny[host];
+        this.#ledger.appendAdjust({
+            schema: "p3f.adjust.v1",
+            receiptId: host,
+            ts: this.#now(),
+            kind: "autodeny_cleared",
+            detail: { host },
+        });
+        this.persist();
+        return true;
+    }
+    autoDeniedHosts() {
+        const now = this.#now();
+        const out = [];
+        for (const [host, e] of Object.entries(this.#state.autoDeny)) {
+            if (e.deniedUntilTs != null && now < e.deniedUntilTs) {
+                out.push({ host, untilTs: e.deniedUntilTs });
+            }
+        }
+        return out;
+    }
+    findGrant(host, amountUsd) {
+        this.pruneExpiredApprovals();
+        const amt = micro(amountUsd);
+        return (this.#state.approvals.find((g) => g.status === "granted" && g.host === host && micro(g.amountUsd) === amt) ?? null);
+    }
+    consumeGrant(approvalId) {
+        this.#state.approvals = this.#state.approvals.filter((g) => g.approvalId !== approvalId);
+        this.persist();
+    }
+    addPendingApproval(entry) {
+        const grant = { ...entry, status: "pending" };
+        this.#state.approvals.push(grant);
+        this.persist();
+        return grant;
+    }
+    listApprovals() {
+        this.pruneExpiredApprovals();
+        return [...this.#state.approvals];
+    }
+    resolvePending(approvalId, approve) {
+        this.pruneExpiredApprovals();
+        const g = this.#state.approvals.find((x) => x.approvalId === approvalId);
+        if (!g)
+            return null;
+        if (approve) {
+            g.status = "granted";
+        }
+        else {
+            this.#state.approvals = this.#state.approvals.filter((x) => x.approvalId !== approvalId);
+        }
+        this.persist();
+        return g;
+    }
+    pruneExpiredApprovals() {
+        const cutoff = this.#now() - APPROVAL_QUEUE_TTL_S * 1000;
+        const before = this.#state.approvals.length;
+        this.#state.approvals = this.#state.approvals.filter((g) => g.createdTs >= cutoff);
+        if (this.#state.approvals.length !== before)
+            this.persist();
+    }
+}

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

@@ -0,0 +1,66 @@
+export declare const CLIENT_VERSION = "p3f-1.0.0";
+export declare const POLICY_VERSION = "p3f-policy-1.5.0";
+export declare const PER_CALL_CAP_DEFAULT_USD = 1;
+export declare const DAILY_CAP_DEFAULT_USD = 2;
+export declare const PER_HOST_DAILY_CAP_DEFAULT_USD = 1;
+export declare const TOTAL_CAP_DEFAULT_USD: number | null;
+export declare const APPROVAL_THRESHOLD_DEFAULT_USD = 0.1;
+export declare const APPROVAL_PREAPPROVED_UP_TO_DEFAULT_USD: number | null;
+export declare const APPROVAL_ELICIT_TIMEOUT_S = 120;
+export declare const APPROVAL_QUEUE_TTL_S = 3600;
+export declare const MAX_PAYMENT_ATTEMPTS_PER_REQUEST = 1;
+export declare const CLOCK_SKEW_S = 600;
+export declare const PAYMENT_VALIDITY_DEFAULT_S = 300;
+export declare const PAYMENT_VALIDITY_MAX_S = 600;
+export declare const HOLD_RELEASE_MARGIN_S = 60;
+export declare const AUTO_DENY_STRIKES = 2;
+export declare const AUTO_DENY_UNKNOWN_ONLY_STRIKES = 4;
+export declare const AUTO_DENY_WINDOW_DAYS = 7;
+export declare const AUTO_DENY_TTL_DAYS = 7;
+export declare const GUARD_SCREEN_BUDGET_MS = 13000;
+export declare const GUARD_ADVISORY_BUDGET_MS = 2000;
+export declare function guardBudgetMs(mode: "advisory" | "enforce"): number;
+export declare const GUARD_RECURSION_DEPTH = 0;
+export declare const GUARD_DAILY_BUDGET_DEFAULT_USD = 0;
+export declare const GUARD_SEND_QUERY = false;
+export declare const TRUST_BLOCK_VERDICTS_DEFAULT: readonly string[];
+export declare const SAFETY_BLOCK_VERDICTS_DEFAULT: readonly string[];
+export declare const SAFETY_BLOCK_DEPLOYER_VERDICTS_DEFAULT: readonly string[];
+export declare const SAFETY_GUARD_DEPTH_DEFAULT: "basic";
+export declare const SAFETY_ON_DEGRADED_DEFAULT: "block";
+export declare const RAILS_ENABLED: readonly ["x402"];
+export declare const SUPPORTED_SCHEMES: readonly ["exact"];
+export declare const SUPPORTED_NETWORKS: readonly ["base", "base-sepolia"];
+export type SupportedNetwork = (typeof SUPPORTED_NETWORKS)[number];
+export declare const SUPPORTED_X402_VERSIONS: readonly number[];
+export declare function isSupportedX402Version(v: number | null | undefined): boolean;
+export declare const NETWORK_ALIASES: Readonly<Record<string, SupportedNetwork>>;
+export declare function canonicalNetwork(declared: string | null | undefined): string | null;
+export declare function chainIdForNetwork(canonical: string | null | undefined): number | null;
+export declare const FETCH_TIMEOUT_MS = 30000;
+export declare const MAX_REDIRECTS = 2;
+export declare const RESPONSE_MAX_BYTES = 10485760;
+export declare const RESPONSE_INLINE_MAX_BYTES = 102400;
+export declare const LOCK_STALE_S = 300;
+export declare const SCAFFOLD_BASE_URL = "https://api.forum-labs.com";
+export declare const P2_TRUST_BASE_URL: string;
+export declare const P1_SAFETY_BASE_URL: string;
+export declare const INTEGRATION_HEADER = "X-P2-Integration";
+export declare const NONCE_BYTES = 32;
+export declare const X_PAYMENT_HEADER = "X-PAYMENT";
+export declare const PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED";
+export declare const PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+export declare const X_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+export declare const DEFAULT_CDP_ACCOUNT_NAME = "payfetch";
+export declare const USDC_DECIMALS = 6;
+export type KnownAsset = {
+    readonly address: string;
+    readonly decimals: number;
+    readonly network: SupportedNetwork;
+    readonly label: string;
+};
+export declare const KNOWN_ASSETS: readonly KnownAsset[];
+export declare function isKnownAsset(asset: string | null | undefined): boolean;
+export declare function knownAssetDecimals(asset: string | null | undefined): number | null;
+export declare function knownAssetNetwork(asset: string | null | undefined): SupportedNetwork | null;
+export declare function deriveAmountUsd(amountAtomic: string | null | undefined, asset: string | null | undefined): number | null;

package/dist/src/core/constants.js

@@ -0,0 +1,115 @@
+export const CLIENT_VERSION = "p3f-1.0.0";
+export const POLICY_VERSION = "p3f-policy-1.5.0";
+export const PER_CALL_CAP_DEFAULT_USD = 1.0;
+export const DAILY_CAP_DEFAULT_USD = 2.0;
+export const PER_HOST_DAILY_CAP_DEFAULT_USD = 1.0;
+export const TOTAL_CAP_DEFAULT_USD = null;
+export const APPROVAL_THRESHOLD_DEFAULT_USD = 0.1;
+export const APPROVAL_PREAPPROVED_UP_TO_DEFAULT_USD = null;
+export const APPROVAL_ELICIT_TIMEOUT_S = 120;
+export const APPROVAL_QUEUE_TTL_S = 3_600;
+export const MAX_PAYMENT_ATTEMPTS_PER_REQUEST = 1;
+export const CLOCK_SKEW_S = 600;
+export const PAYMENT_VALIDITY_DEFAULT_S = 300;
+export const PAYMENT_VALIDITY_MAX_S = 600;
+export const HOLD_RELEASE_MARGIN_S = 60;
+export const AUTO_DENY_STRIKES = 2;
+export const AUTO_DENY_UNKNOWN_ONLY_STRIKES = 4;
+export const AUTO_DENY_WINDOW_DAYS = 7;
+export const AUTO_DENY_TTL_DAYS = 7;
+export const GUARD_SCREEN_BUDGET_MS = 13_000;
+export const GUARD_ADVISORY_BUDGET_MS = 2_000;
+export function guardBudgetMs(mode) {
+    return mode === "enforce" ? GUARD_SCREEN_BUDGET_MS : GUARD_ADVISORY_BUDGET_MS;
+}
+export const GUARD_RECURSION_DEPTH = 0;
+export const GUARD_DAILY_BUDGET_DEFAULT_USD = 0;
+export const GUARD_SEND_QUERY = false;
+export const TRUST_BLOCK_VERDICTS_DEFAULT = Object.freeze(["unreliable"]);
+export const SAFETY_BLOCK_VERDICTS_DEFAULT = Object.freeze(["danger"]);
+export const SAFETY_BLOCK_DEPLOYER_VERDICTS_DEFAULT = Object.freeze([
+    "serial_rugger",
+]);
+export const SAFETY_GUARD_DEPTH_DEFAULT = "basic";
+export const SAFETY_ON_DEGRADED_DEFAULT = "block";
+export const RAILS_ENABLED = Object.freeze(["x402"]);
+export const SUPPORTED_SCHEMES = Object.freeze(["exact"]);
+export const SUPPORTED_NETWORKS = Object.freeze([
+    "base",
+    "base-sepolia",
+]);
+export const SUPPORTED_X402_VERSIONS = Object.freeze([1, 2]);
+export function isSupportedX402Version(v) {
+    return v != null && SUPPORTED_X402_VERSIONS.includes(v);
+}
+export const NETWORK_ALIASES = Object.freeze({
+    "eip155:8453": "base",
+    "eip155:84532": "base-sepolia",
+});
+const CHAIN_ID_BY_CANONICAL = Object.freeze({
+    base: 8453,
+    "base-sepolia": 84532,
+});
+export function canonicalNetwork(declared) {
+    if (declared == null)
+        return null;
+    return NETWORK_ALIASES[declared] ?? declared;
+}
+export function chainIdForNetwork(canonical) {
+    if (canonical == null)
+        return null;
+    return CHAIN_ID_BY_CANONICAL[canonical] ?? null;
+}
+export const FETCH_TIMEOUT_MS = 30_000;
+export const MAX_REDIRECTS = 2;
+export const RESPONSE_MAX_BYTES = 10_485_760;
+export const RESPONSE_INLINE_MAX_BYTES = 102_400;
+export const LOCK_STALE_S = 300;
+export const SCAFFOLD_BASE_URL = "https://api.forum-labs.com";
+export const P2_TRUST_BASE_URL = SCAFFOLD_BASE_URL;
+export const P1_SAFETY_BASE_URL = SCAFFOLD_BASE_URL;
+export const INTEGRATION_HEADER = "X-P2-Integration";
+export const NONCE_BYTES = 32;
+export const X_PAYMENT_HEADER = "X-PAYMENT";
+export const PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED";
+export const PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+export const X_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+export const DEFAULT_CDP_ACCOUNT_NAME = "payfetch";
+export const USDC_DECIMALS = 6;
+export const KNOWN_ASSETS = Object.freeze([
+    Object.freeze({
+        address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        decimals: USDC_DECIMALS,
+        network: "base",
+        label: "USDC (Base)",
+    }),
+    Object.freeze({
+        address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        decimals: USDC_DECIMALS,
+        network: "base-sepolia",
+        label: "USDC (Base Sepolia)",
+    }),
+]);
+const KNOWN_ASSET_DECIMALS_BY_LOWER = new Map(KNOWN_ASSETS.map((a) => [a.address.toLowerCase(), a.decimals]));
+const KNOWN_ASSET_NETWORK_BY_LOWER = new Map(KNOWN_ASSETS.map((a) => [a.address.toLowerCase(), a.network]));
+export function isKnownAsset(asset) {
+    return asset != null && KNOWN_ASSET_DECIMALS_BY_LOWER.has(asset.toLowerCase());
+}
+export function knownAssetDecimals(asset) {
+    if (asset == null)
+        return null;
+    return KNOWN_ASSET_DECIMALS_BY_LOWER.get(asset.toLowerCase()) ?? null;
+}
+export function knownAssetNetwork(asset) {
+    if (asset == null)
+        return null;
+    return KNOWN_ASSET_NETWORK_BY_LOWER.get(asset.toLowerCase()) ?? null;
+}
+export function deriveAmountUsd(amountAtomic, asset) {
+    if (amountAtomic == null || !/^\d+$/.test(amountAtomic))
+        return null;
+    const decimals = knownAssetDecimals(asset);
+    if (decimals == null)
+        return null;
+    return Number(amountAtomic) / 10 ** decimals;
+}

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

@@ -0,0 +1,14 @@
+export interface PayfetchFs {
+    ensureDir(dir: string): void;
+    readText(path: string): string | null;
+    writeText(path: string, data: string): void;
+    writeBytes(path: string, data: Uint8Array): void;
+    appendLine(path: string, line: string, opts: {
+        fsync: boolean;
+    }): void;
+    statMtimeMs(path: string): number | null;
+    listDir(dir: string): string[];
+    tryCreateExclusive(path: string, contents: string, mode?: number): boolean;
+    remove(path: string): void;
+}
+export declare const realFs: PayfetchFs;