@forum-labs/payfetch 1.0.0

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

@@ -0,0 +1,57 @@
+import type { PayfetchFs } from "./fs.js";
+import type { SafetyGuardConfig, TrustGuardConfig } from "../guards/types.js";
+export type { TrustGuardConfig, SafetyGuardConfig };
+export type HostPattern = string;
+export type Policy = {
+    schema: "p3f.policy.v1";
+    mode: "open" | "allowlist";
+    allow: HostPattern[];
+    deny: HostPattern[];
+    caps: {
+        perCallUsd: number;
+        dailyUsd: number;
+        perHostDailyUsd: number;
+        totalUsd: number | null;
+    };
+    approval: {
+        thresholdUsd: number;
+        mode: "elicit" | "queue" | "deny";
+        elicitFallback: "queue" | "deny";
+        preApprovedUpToUsd: number | null;
+        preApprovedHosts: HostPattern[];
+    };
+    guards: {
+        trust: TrustGuardConfig;
+        safety: SafetyGuardConfig;
+    };
+    allowPrivateTargets: boolean;
+    autoDeny: {
+        enabled: boolean;
+    };
+};
+export declare function defaultPolicy(): Policy;
+export declare function matchHostPattern(host: string, pattern: string): boolean;
+export declare function matchesAnyHost(host: string, patterns: readonly HostPattern[]): boolean;
+export declare function mergePolicy(base: Policy, over?: DeepPartial<Policy>): Policy;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends readonly (infer U)[] ? U[] : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+export declare class PolicyLoadError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export type PolicyLoad = {
+    ok: true;
+    policy: Policy;
+    mtimeMs: number | null;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateConfig(parsed: unknown, base: Policy, warn?: (msg: string) => void): Policy;
+export declare function configPath(dataDir: string): string;
+export type PolicyIo = {
+    fs: PayfetchFs;
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+};
+export declare function loadPolicy(dataDir: string, io: PolicyIo, base: Policy): PolicyLoad;

package/dist/src/core/policy.js

@@ -0,0 +1,224 @@
+import { join } from "node:path";
+import { APPROVAL_PREAPPROVED_UP_TO_DEFAULT_USD, APPROVAL_THRESHOLD_DEFAULT_USD, DAILY_CAP_DEFAULT_USD, PER_CALL_CAP_DEFAULT_USD, PER_HOST_DAILY_CAP_DEFAULT_USD, TOTAL_CAP_DEFAULT_USD, } from "./constants.js";
+import { DEFAULT_SAFETY_GUARD_CONFIG, DEFAULT_TRUST_GUARD_CONFIG, } from "../guards/types.js";
+export function defaultPolicy() {
+    return Object.freeze({
+        schema: "p3f.policy.v1",
+        mode: "open",
+        allow: [],
+        deny: [],
+        caps: Object.freeze({
+            perCallUsd: PER_CALL_CAP_DEFAULT_USD,
+            dailyUsd: DAILY_CAP_DEFAULT_USD,
+            perHostDailyUsd: PER_HOST_DAILY_CAP_DEFAULT_USD,
+            totalUsd: TOTAL_CAP_DEFAULT_USD,
+        }),
+        approval: Object.freeze({
+            thresholdUsd: APPROVAL_THRESHOLD_DEFAULT_USD,
+            mode: "elicit",
+            elicitFallback: "deny",
+            preApprovedUpToUsd: APPROVAL_PREAPPROVED_UP_TO_DEFAULT_USD,
+            preApprovedHosts: [],
+        }),
+        guards: Object.freeze({
+            trust: {
+                ...DEFAULT_TRUST_GUARD_CONFIG,
+                blockVerdicts: [...DEFAULT_TRUST_GUARD_CONFIG.blockVerdicts],
+            },
+            safety: {
+                ...DEFAULT_SAFETY_GUARD_CONFIG,
+                blockVerdicts: [...DEFAULT_SAFETY_GUARD_CONFIG.blockVerdicts],
+                blockDeployerVerdicts: [...DEFAULT_SAFETY_GUARD_CONFIG.blockDeployerVerdicts],
+            },
+        }),
+        allowPrivateTargets: false,
+        autoDeny: { enabled: true },
+    });
+}
+export function matchHostPattern(host, pattern) {
+    const h = host.toLowerCase();
+    const p = pattern.toLowerCase();
+    if (p.startsWith("*.")) {
+        const suffix = p.slice(1);
+        return h.endsWith(suffix) && h.length > suffix.length;
+    }
+    return h === p;
+}
+export function matchesAnyHost(host, patterns) {
+    return patterns.some((p) => matchHostPattern(host, p));
+}
+export function mergePolicy(base, over) {
+    if (!over)
+        return base;
+    return {
+        schema: "p3f.policy.v1",
+        mode: over.mode ?? base.mode,
+        allow: over.allow ? [...over.allow] : [...base.allow],
+        deny: over.deny ? [...over.deny] : [...base.deny],
+        caps: { ...base.caps, ...(over.caps ?? {}) },
+        approval: {
+            ...base.approval,
+            ...(over.approval ?? {}),
+            preApprovedHosts: over.approval?.preApprovedHosts
+                ? [...over.approval.preApprovedHosts]
+                : [...base.approval.preApprovedHosts],
+        },
+        guards: {
+            trust: { ...base.guards.trust, ...(over.guards?.trust ?? {}) },
+            safety: { ...base.guards.safety, ...(over.guards?.safety ?? {}) },
+        },
+        allowPrivateTargets: over.allowPrivateTargets ?? base.allowPrivateTargets,
+        autoDeny: { ...base.autoDeny, ...(over.autoDeny ?? {}) },
+    };
+}
+export class PolicyLoadError extends Error {
+    reason;
+    constructor(reason) {
+        super(`payfetch: invalid ${"config.json"} — ${reason} (SPEC §4.1: fail closed).`);
+        this.reason = reason;
+        this.name = "PolicyLoadError";
+    }
+}
+function isPlainObject(v) {
+    return v != null && typeof v === "object" && !Array.isArray(v);
+}
+function fail(reason) {
+    throw new PolicyLoadError(reason);
+}
+function reqEnum(v, allowed, base, field) {
+    if (v === undefined)
+        return base;
+    if (typeof v === "string" && allowed.includes(v))
+        return v;
+    fail(`${field} must be one of ${allowed.join("|")}`);
+}
+function reqNumber(v, base, field) {
+    if (v === undefined)
+        return base;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+        return v;
+    fail(`${field} must be a non-negative number`);
+}
+function reqNumberOrNull(v, base, field) {
+    if (v === undefined)
+        return base;
+    if (v === null)
+        return null;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+        return v;
+    fail(`${field} must be a non-negative number or null`);
+}
+function reqBool(v, base, field) {
+    if (v === undefined)
+        return base;
+    if (typeof v === "boolean")
+        return v;
+    fail(`${field} must be a boolean`);
+}
+function reqStringArray(v, base, field) {
+    if (v === undefined)
+        return [...base];
+    if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+        return [...v];
+    fail(`${field} must be an array of strings`);
+}
+export function validateConfig(parsed, base, warn) {
+    if (!isPlainObject(parsed))
+        fail("root must be a JSON object");
+    const root = parsed;
+    if (root.schema !== undefined && root.schema !== "p3f.policy.v1") {
+        fail(`schema must be "p3f.policy.v1"`);
+    }
+    const caps = root.caps === undefined ? {} : isPlainObject(root.caps) ? root.caps : fail("caps must be an object");
+    const approval = root.approval === undefined ? {} : isPlainObject(root.approval) ? root.approval : fail("approval must be an object");
+    const guards = root.guards === undefined ? {} : isPlainObject(root.guards) ? root.guards : fail("guards must be an object");
+    const trust = guards.trust === undefined
+        ? {}
+        : isPlainObject(guards.trust)
+            ? guards.trust
+            : fail("guards.trust must be an object");
+    const safety = guards.safety === undefined
+        ? {}
+        : isPlainObject(guards.safety)
+            ? guards.safety
+            : fail("guards.safety must be an object");
+    const autoDeny = root.autoDeny === undefined ? {} : isPlainObject(root.autoDeny) ? root.autoDeny : fail("autoDeny must be an object");
+    const policy = {
+        schema: "p3f.policy.v1",
+        mode: reqEnum(root.mode, ["open", "allowlist"], base.mode, "mode"),
+        allow: reqStringArray(root.allow, base.allow, "allow"),
+        deny: reqStringArray(root.deny, base.deny, "deny"),
+        caps: {
+            perCallUsd: reqNumber(caps.perCallUsd, base.caps.perCallUsd, "caps.perCallUsd"),
+            dailyUsd: reqNumber(caps.dailyUsd, base.caps.dailyUsd, "caps.dailyUsd"),
+            perHostDailyUsd: reqNumber(caps.perHostDailyUsd, base.caps.perHostDailyUsd, "caps.perHostDailyUsd"),
+            totalUsd: reqNumberOrNull(caps.totalUsd, base.caps.totalUsd, "caps.totalUsd"),
+        },
+        approval: {
+            thresholdUsd: reqNumber(approval.thresholdUsd, base.approval.thresholdUsd, "approval.thresholdUsd"),
+            mode: reqEnum(approval.mode, ["elicit", "queue", "deny"], base.approval.mode, "approval.mode"),
+            elicitFallback: reqEnum(approval.elicitFallback, ["queue", "deny"], base.approval.elicitFallback, "approval.elicitFallback"),
+            preApprovedUpToUsd: reqNumberOrNull(approval.preApprovedUpToUsd, base.approval.preApprovedUpToUsd, "approval.preApprovedUpToUsd"),
+            preApprovedHosts: reqStringArray(approval.preApprovedHosts, base.approval.preApprovedHosts, "approval.preApprovedHosts"),
+        },
+        guards: {
+            trust: {
+                enabled: reqBool(trust.enabled, base.guards.trust.enabled, "guards.trust.enabled"),
+                mode: reqEnum(trust.mode, ["advisory", "enforce"], base.guards.trust.mode, "guards.trust.mode"),
+                minScore: reqNumberOrNull(trust.minScore, base.guards.trust.minScore, "guards.trust.minScore"),
+                blockVerdicts: reqStringArray(trust.blockVerdicts, base.guards.trust.blockVerdicts, "guards.trust.blockVerdicts"),
+                blockUnrated: reqBool(trust.blockUnrated, base.guards.trust.blockUnrated, "guards.trust.blockUnrated"),
+                onUnavailable: reqEnum(trust.onUnavailable, ["proceed", "block"], base.guards.trust.onUnavailable, "guards.trust.onUnavailable"),
+                dailyBudgetUsd: reqNumber(trust.dailyBudgetUsd, base.guards.trust.dailyBudgetUsd, "guards.trust.dailyBudgetUsd"),
+            },
+            safety: {
+                enabled: reqBool(safety.enabled, base.guards.safety.enabled, "guards.safety.enabled"),
+                mode: reqEnum(safety.mode, ["advisory", "enforce"], base.guards.safety.mode, "guards.safety.mode"),
+                depth: reqEnum(safety.depth, ["basic", "deep"], base.guards.safety.depth, "guards.safety.depth"),
+                blockVerdicts: reqStringArray(safety.blockVerdicts, base.guards.safety.blockVerdicts, "guards.safety.blockVerdicts"),
+                blockDeployerVerdicts: reqStringArray(safety.blockDeployerVerdicts, base.guards.safety.blockDeployerVerdicts, "guards.safety.blockDeployerVerdicts"),
+                onUnavailable: reqEnum(safety.onUnavailable, ["proceed", "block"], base.guards.safety.onUnavailable, "guards.safety.onUnavailable"),
+                onDegraded: reqEnum(safety.onDegraded, ["block", "warn", "proceed"], base.guards.safety.onDegraded, "guards.safety.onDegraded"),
+                dailyBudgetUsd: reqNumber(safety.dailyBudgetUsd, base.guards.safety.dailyBudgetUsd, "guards.safety.dailyBudgetUsd"),
+            },
+        },
+        allowPrivateTargets: reqBool(root.allowPrivateTargets, base.allowPrivateTargets, "allowPrivateTargets"),
+        autoDeny: {
+            enabled: reqBool(autoDeny.enabled, base.autoDeny.enabled, "autoDeny.enabled"),
+        },
+    };
+    if (policy.approval.preApprovedUpToUsd !== null &&
+        policy.approval.preApprovedUpToUsd > policy.caps.perCallUsd) {
+        warn?.(`approval.preApprovedUpToUsd (${policy.approval.preApprovedUpToUsd}) exceeds ` +
+            `caps.perCallUsd (${policy.caps.perCallUsd}); the per-call cap clips every payment ` +
+            `first, so the excess pre-approval ceiling has no effect.`);
+    }
+    return policy;
+}
+export function configPath(dataDir) {
+    return join(dataDir, "config.json");
+}
+export function loadPolicy(dataDir, io, base) {
+    const path = configPath(dataDir);
+    const raw = io.fs.readText(path);
+    if (raw === null) {
+        io.fs.writeText(path, JSON.stringify(base, null, 2));
+        return { ok: true, policy: base, mtimeMs: io.fs.statMtimeMs(path) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, error: `config.json is not valid JSON: ${err.message}` };
+    }
+    try {
+        const policy = validateConfig(parsed, base, (msg) => io.log?.("policy.config_warning", { message: msg }));
+        return { ok: true, policy, mtimeMs: io.fs.statMtimeMs(path) };
+    }
+    catch (err) {
+        if (err instanceof PolicyLoadError)
+            return { ok: false, error: err.reason };
+        return { ok: false, error: err.message };
+    }
+}

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

@@ -0,0 +1,93 @@
+import type { PayfetchFs } from "./fs.js";
+import type { Policy } from "./policy.js";
+export declare function parseIpv4(s: string): number[] | null;
+export declare function parseIpv6(input: string): number[] | null;
+export declare function isBlockedIp(ip: string): boolean;
+export type TargetReason = "scheme" | "private_target" | "invalid_url" | "unresolved";
+export type TargetVerdict = {
+    ok: true;
+    host: string;
+} | {
+    ok: false;
+    reason: TargetReason;
+};
+export declare function evaluateTarget(url: string, resolvedIps: readonly string[], policy: Pick<Policy, "allowPrivateTargets">): TargetVerdict;
+export type LookupAddress = {
+    address: string;
+    family: number;
+};
+export type NetLookupOptions = {
+    all?: boolean;
+    family?: number;
+};
+type NetLookupCb = (err: Error | null, address: string | LookupAddress[], family?: number) => void;
+type NetLookup = (hostname: string, options: NetLookupOptions | undefined, callback: NetLookupCb) => void;
+export declare function createPinnedLookup(resolve: (host: string) => Promise<string[]>, policy: Pick<Policy, "allowPrivateTargets">): NetLookup;
+export type HttpResponse = {
+    status: number;
+    headers: Headers;
+    body: ReadableStream<Uint8Array> | null;
+};
+export type HttpRequestInit = {
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    signal?: AbortSignal;
+};
+export type HttpClient = (url: string, init: HttpRequestInit) => Promise<HttpResponse>;
+export declare function adaptFetch(fetchFn: typeof fetch): HttpClient;
+export type CappedBody = {
+    bytes: Uint8Array;
+    hardCapped: boolean;
+};
+export declare function readCapped(body: ReadableStream<Uint8Array> | null, maxBytes: number): Promise<CappedBody>;
+export type TransportIo = {
+    request: HttpClient;
+    resolve: (host: string) => Promise<string[]>;
+    fs: PayfetchFs;
+    now: () => number;
+    log: (msg: string, fields?: Record<string, unknown>) => void;
+    setTimer?: (fn: () => void, ms: number) => {
+        clear: () => void;
+    };
+};
+export type TransportError = "private_target_blocked" | "insecure_redirect" | "fetch_error";
+export type TransportOpts = {
+    followRedirects?: boolean;
+};
+export type TransportResult = {
+    ok: boolean;
+    error: TransportError | null;
+    finalUrl: string;
+    finalHost: string;
+    status: number | null;
+    headers: Headers | null;
+    contentType: string | null;
+    rawBody: Uint8Array | null;
+    bodyBytes: number | null;
+    bodySha256: string | null;
+    hardCapped: boolean;
+    hopChain: string[];
+    redirectCount: number;
+    notes: string[];
+    totalMs: number;
+};
+export declare function transportFetch(url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+}, policy: Pick<Policy, "allowPrivateTargets">, io: TransportIo, opts?: TransportOpts): Promise<TransportResult>;
+export type DeliveredBody = {
+    mode: "inline";
+    text: string;
+    truncated: boolean;
+} | {
+    mode: "file";
+    path: string;
+    truncated: false;
+};
+export declare function deliverBody(bytes: Uint8Array, responseMode: "inline" | "file", ctx: {
+    fs: PayfetchFs;
+    downloadPath: string;
+}): DeliveredBody;
+export {};