@forum-labs/payfetch 1.0.0

package/dist/src/core/transport.js

@@ -0,0 +1,364 @@
+import { createHash } from "node:crypto";
+import { FETCH_TIMEOUT_MS, INTEGRATION_HEADER, MAX_REDIRECTS, RESPONSE_INLINE_MAX_BYTES, RESPONSE_MAX_BYTES, X_PAYMENT_HEADER, X_PAYMENT_RESPONSE_HEADER, } from "./constants.js";
+export function parseIpv4(s) {
+    const m = s.split(".");
+    if (m.length !== 4)
+        return null;
+    const out = [];
+    for (const part of m) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const n = Number(part);
+        if (n > 255)
+            return null;
+        out.push(n);
+    }
+    return out;
+}
+export function parseIpv6(input) {
+    let s = input;
+    if (s.startsWith("[") && s.endsWith("]"))
+        s = s.slice(1, -1);
+    const pct = s.indexOf("%");
+    if (pct >= 0)
+        s = s.slice(0, pct);
+    if (!s.includes(":"))
+        return null;
+    let tailHextets = [];
+    const lastColon = s.lastIndexOf(":");
+    const tail = s.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const v4 = parseIpv4(tail);
+        if (!v4)
+            return null;
+        tailHextets = [(v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]];
+        s = s.slice(0, lastColon + 1);
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null;
+    const toHextets = (part) => {
+        if (part === "")
+            return [];
+        const groups = part.split(":").filter((g) => g.length > 0);
+        const out = [];
+        for (const g of groups) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    if (halves.length === 2) {
+        const head = toHextets(halves[0]);
+        const rest = toHextets(halves[1]);
+        if (head === null || rest === null)
+            return null;
+        const full = [...head, ...rest, ...tailHextets];
+        if (full.length > 8)
+            return null;
+        const zeros = new Array(8 - full.length).fill(0);
+        return [...head, ...zeros, ...rest, ...tailHextets];
+    }
+    const head = toHextets(halves[0]);
+    if (head === null)
+        return null;
+    const full = [...head, ...tailHextets];
+    return full.length === 8 ? full : null;
+}
+function isBlockedIpv4(o) {
+    const [a, b] = o;
+    if (a === 0)
+        return true;
+    if (a === 10)
+        return true;
+    if (a === 127)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    return false;
+}
+function isBlockedIpv6(h) {
+    if (h.every((x) => x === 0))
+        return true;
+    if (h.slice(0, 7).every((x) => x === 0) && h[7] === 1)
+        return true;
+    if ((h[0] & 0xffc0) === 0xfe80)
+        return true;
+    if ((h[0] & 0xfe00) === 0xfc00)
+        return true;
+    if (h.slice(0, 5).every((x) => x === 0) && h[5] === 0xffff) {
+        const v4 = [(h[6] >> 8) & 0xff, h[6] & 0xff, (h[7] >> 8) & 0xff, h[7] & 0xff];
+        return isBlockedIpv4(v4);
+    }
+    return false;
+}
+export function isBlockedIp(ip) {
+    const v4 = parseIpv4(ip);
+    if (v4)
+        return isBlockedIpv4(v4);
+    const v6 = parseIpv6(ip);
+    if (v6)
+        return isBlockedIpv6(v6);
+    return true;
+}
+export function evaluateTarget(url, resolvedIps, policy) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: "invalid_url" };
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:") {
+        return { ok: false, reason: "scheme" };
+    }
+    if (policy.allowPrivateTargets)
+        return { ok: true, host: u.hostname };
+    if (resolvedIps.length === 0)
+        return { ok: false, reason: "unresolved" };
+    for (const ip of resolvedIps) {
+        if (isBlockedIp(ip))
+            return { ok: false, reason: "private_target" };
+    }
+    return { ok: true, host: u.hostname };
+}
+export function createPinnedLookup(resolve, policy) {
+    return (hostname, options, callback) => {
+        const fail = (err) => {
+            if (options?.all)
+                callback(err, []);
+            else
+                callback(err, "", 0);
+        };
+        const deliver = (ips) => {
+            if (options?.all) {
+                callback(null, ips.map((ip) => ({ address: ip, family: parseIpv4(ip) ? 4 : 6 })));
+                return;
+            }
+            const ip = ips[0];
+            callback(null, ip, parseIpv4(ip) ? 4 : 6);
+        };
+        resolve(hostname)
+            .then((ips) => {
+            if (ips.length === 0) {
+                fail(new Error(`payfetch: DNS resolution failed for ${hostname}`));
+                return;
+            }
+            if (policy.allowPrivateTargets) {
+                deliver(ips);
+                return;
+            }
+            if (ips.some((ip) => isBlockedIp(ip))) {
+                fail(new Error(`payfetch: refusing to dial ${hostname} — resolves to a blocked address`));
+                return;
+            }
+            deliver(ips);
+        })
+            .catch((err) => fail(err));
+    };
+}
+export function adaptFetch(fetchFn) {
+    return async (url, init) => {
+        const resp = await fetchFn(url, {
+            method: init.method,
+            headers: init.headers,
+            body: init.body ?? undefined,
+            redirect: "manual",
+            signal: init.signal,
+        });
+        return { status: resp.status, headers: resp.headers, body: resp.body };
+    };
+}
+export async function readCapped(body, maxBytes) {
+    if (body === null)
+        return { bytes: new Uint8Array(0), hardCapped: false };
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    let hardCapped = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        if (total + value.length > maxBytes) {
+            chunks.push(value.subarray(0, maxBytes - total));
+            total = maxBytes;
+            hardCapped = true;
+            await reader.cancel().catch(() => { });
+            break;
+        }
+        chunks.push(value);
+        total += value.length;
+    }
+    const bytes = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        bytes.set(c, off);
+        off += c.length;
+    }
+    return { bytes, hardCapped };
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const SENSITIVE_REDIRECT_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    X_PAYMENT_HEADER.toLowerCase(),
+    X_PAYMENT_RESPONSE_HEADER.toLowerCase(),
+    INTEGRATION_HEADER.toLowerCase(),
+]);
+function stripSensitiveHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (!SENSITIVE_REDIRECT_HEADERS.has(k.toLowerCase()))
+            out[k] = v;
+    }
+    return out;
+}
+function defaultTimer(fn, ms) {
+    const t = setTimeout(fn, ms);
+    return { clear: () => clearTimeout(t) };
+}
+export async function transportFetch(url, init, policy, io, opts = {}) {
+    const startMs = io.now();
+    const timer = io.setTimer ?? defaultTimer;
+    const followRedirects = opts.followRedirects ?? true;
+    const hopChain = [];
+    const notes = [];
+    let current = url;
+    let method = init.method;
+    let body = init.body;
+    let headers = init.headers;
+    let redirectCount = 0;
+    const base = (finalUrl) => ({
+        ok: false,
+        error: null,
+        finalUrl,
+        finalHost: safeHost(finalUrl),
+        status: null,
+        headers: null,
+        contentType: null,
+        rawBody: null,
+        bodyBytes: null,
+        bodySha256: null,
+        hardCapped: false,
+        hopChain,
+        redirectCount,
+        notes,
+        totalMs: io.now() - startMs,
+    });
+    for (;;) {
+        let host;
+        let ips;
+        try {
+            host = new URL(current).hostname;
+        }
+        catch {
+            return { ...base(current), error: "fetch_error" };
+        }
+        try {
+            ips = await io.resolve(host);
+        }
+        catch {
+            ips = [];
+        }
+        const verdict = evaluateTarget(current, ips, policy);
+        if (!verdict.ok) {
+            if (verdict.reason === "scheme" || verdict.reason === "private_target") {
+                notes.push("private_target_blocked");
+                return { ...base(current), error: "private_target_blocked" };
+            }
+            return { ...base(current), error: "fetch_error" };
+        }
+        hopChain.push(current);
+        const controller = new AbortController();
+        const t = timer(() => controller.abort(), FETCH_TIMEOUT_MS);
+        let resp;
+        try {
+            resp = await io.request(current, { method, headers, body, signal: controller.signal });
+        }
+        catch (err) {
+            io.log("transport.fetch_error", { host, message: err.message });
+            return { ...base(current), error: "fetch_error" };
+        }
+        finally {
+            t.clear();
+        }
+        if (followRedirects && REDIRECT_STATUSES.has(resp.status) && redirectCount < MAX_REDIRECTS) {
+            const location = resp.headers.get("location");
+            if (location) {
+                await resp.body?.cancel().catch(() => { });
+                let next;
+                try {
+                    next = new URL(location, current);
+                }
+                catch {
+                    return { ...base(current), error: "fetch_error" };
+                }
+                if (new URL(current).protocol === "https:" && next.protocol === "http:") {
+                    notes.push("insecure_redirect");
+                    return { ...base(current), error: "insecure_redirect" };
+                }
+                redirectCount += 1;
+                if (new URL(current).origin !== next.origin) {
+                    headers = stripSensitiveHeaders(headers);
+                }
+                if (resp.status === 303 || (method !== "GET" && method !== "HEAD" && resp.status !== 307 && resp.status !== 308)) {
+                    method = "GET";
+                    body = null;
+                }
+                current = next.toString();
+                continue;
+            }
+        }
+        const { bytes, hardCapped } = await readCapped(resp.body, RESPONSE_MAX_BYTES);
+        if (redirectCount > 0)
+            notes.push(`redirected:${redirectCount}`);
+        return {
+            ok: true,
+            error: null,
+            finalUrl: current,
+            finalHost: safeHost(current),
+            status: resp.status,
+            headers: resp.headers,
+            contentType: resp.headers.get("content-type"),
+            rawBody: bytes,
+            bodyBytes: bytes.length,
+            bodySha256: sha256(bytes),
+            hardCapped,
+            hopChain,
+            redirectCount,
+            notes,
+            totalMs: io.now() - startMs,
+        };
+    }
+}
+function safeHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return "";
+    }
+}
+export function deliverBody(bytes, responseMode, ctx) {
+    if (responseMode === "file") {
+        ctx.fs.writeBytes(ctx.downloadPath, bytes);
+        return { mode: "file", path: ctx.downloadPath, truncated: false };
+    }
+    const truncated = bytes.length > RESPONSE_INLINE_MAX_BYTES;
+    const slice = truncated ? bytes.subarray(0, RESPONSE_INLINE_MAX_BYTES) : bytes;
+    return { mode: "inline", text: new TextDecoder("utf-8", { fatal: false }).decode(slice), truncated };
+}

package/dist/src/guards/index.d.ts

@@ -0,0 +1,4 @@
+export { createTrustGuard } from "./trust.js";
+export { createSafetyGuard } from "./safety.js";
+export type { PrePayGuard, GuardId, GuardInput, GuardResult, TrustGuardConfig, SafetyGuardConfig, GuardRuntime, } from "./types.js";
+export { DEFAULT_TRUST_GUARD_CONFIG, DEFAULT_SAFETY_GUARD_CONFIG } from "./types.js";

package/dist/src/guards/index.js

@@ -0,0 +1,3 @@
+export { createTrustGuard } from "./trust.js";
+export { createSafetyGuard } from "./safety.js";
+export { DEFAULT_TRUST_GUARD_CONFIG, DEFAULT_SAFETY_GUARD_CONFIG } from "./types.js";

package/dist/src/guards/internal.d.ts

@@ -0,0 +1,17 @@
+import type { NoteCode } from "../core/notes.js";
+import type { GuardId, GuardResult, GuardRuntime } from "./types.js";
+export declare const GUARD_UNRATED_NOTE: NoteCode;
+export declare function integrationHeaderValue(installId8: string, via: string | null): string;
+export declare function guardHeaders(rt: GuardRuntime): Record<string, string>;
+export declare function stripTarget(url: string): string;
+export declare function trustScoreUrl(base: string, target: string): string;
+export declare function safetyScreenUrl(base: string, mint: string, chain: string, deep: boolean): string;
+export declare function guardFetchWithTimeout(rt: GuardRuntime, url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}, budgetMs: number, dryRun?: boolean): Promise<Response>;
+export declare function unwrapEnvelope(body: unknown): Record<string, unknown> | null;
+export declare function blockOrWarn(mode: "advisory" | "enforce"): "block" | "warn";
+export declare function guardResult(id: GuardId, verdict: GuardResult["verdict"], detail: Record<string, unknown>, startMs: number, rt: GuardRuntime): GuardResult;
+export declare function unavailable(id: GuardId, reason: string, startMs: number, rt: GuardRuntime): GuardResult;

package/dist/src/guards/internal.js

@@ -0,0 +1,74 @@
+import { GUARD_SEND_QUERY, INTEGRATION_HEADER, } from "../core/constants.js";
+export const GUARD_UNRATED_NOTE = "guard_unrated";
+export function integrationHeaderValue(installId8, via) {
+    const value = `payfetch/1;i=${installId8}`;
+    return via != null && via !== "" ? `${value};via=${via}` : value;
+}
+export function guardHeaders(rt) {
+    return {
+        [INTEGRATION_HEADER]: integrationHeaderValue(rt.installId8, rt.via),
+        Accept: "application/json",
+    };
+}
+export function stripTarget(url) {
+    try {
+        const u = new URL(url);
+        u.hash = "";
+        if (!GUARD_SEND_QUERY)
+            u.search = "";
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+function trimSlash(base) {
+    return base.replace(/\/+$/, "");
+}
+export function trustScoreUrl(base, target) {
+    const u = new URL(`${trimSlash(base)}/v1/trust/score`);
+    u.searchParams.set("url", target);
+    return u.toString();
+}
+export function safetyScreenUrl(base, mint, chain, deep) {
+    const path = deep ? "/v1/safety/screen/deep" : "/v1/safety/screen";
+    const u = new URL(`${trimSlash(base)}${path}`);
+    u.searchParams.set("mint", mint);
+    u.searchParams.set("chain", chain);
+    return u.toString();
+}
+export async function guardFetchWithTimeout(rt, url, init, budgetMs, dryRun) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), budgetMs);
+    try {
+        return await rt.guardFetch(url, { ...init, signal: controller.signal }, { dryRun });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function unwrapEnvelope(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    const data = b.data;
+    if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+        return data;
+    }
+    return b;
+}
+export function blockOrWarn(mode) {
+    return mode === "enforce" ? "block" : "warn";
+}
+export function guardResult(id, verdict, detail, startMs, rt) {
+    return {
+        id,
+        verdict,
+        detail,
+        latencyMs: Math.max(0, rt.now() - startMs),
+        costUsd: 0,
+    };
+}
+export function unavailable(id, reason, startMs, rt) {
+    return guardResult(id, "unavailable", { reason }, startMs, rt);
+}

package/dist/src/guards/safety.d.ts

@@ -0,0 +1,2 @@
+import type { PrePayGuard, GuardRuntime, SafetyGuardConfig } from "./types.js";
+export declare function createSafetyGuard(cfg: SafetyGuardConfig, rt: GuardRuntime): PrePayGuard;

package/dist/src/guards/safety.js

@@ -0,0 +1,94 @@
+import { guardBudgetMs } from "../core/constants.js";
+import { GUARD_UNRATED_NOTE, blockOrWarn, guardFetchWithTimeout, guardHeaders, guardResult, safetyScreenUrl, unavailable, unwrapEnvelope, } from "./internal.js";
+const DANGER_INCONCLUSIVE_VERDICTS = new Set(["unknown", "caution"]);
+function parseScreen(body) {
+    const b = unwrapEnvelope(body);
+    if (b === null)
+        return null;
+    if (typeof b.verdict !== "string")
+        return null;
+    const score = typeof b.score === "number" ? b.score : null;
+    const degraded = b.degraded === true;
+    let deployer = null;
+    let deployerVerdict = null;
+    if (typeof b.deployer === "object" && b.deployer !== null) {
+        deployer = b.deployer;
+        const dv = deployer.verdict;
+        deployerVerdict = typeof dv === "string" ? dv : null;
+    }
+    return { verdict: b.verdict, score, deployer, deployerVerdict, degraded };
+}
+function mapSafety(cfg, parsed, startMs, rt) {
+    const { verdict, score, deployer, deployerVerdict, degraded } = parsed;
+    const detail = { verdict, score, deployer, degraded };
+    if (cfg.blockVerdicts.includes(verdict)) {
+        return guardResult("safety", blockOrWarn(cfg.mode), detail, startMs, rt);
+    }
+    if (cfg.depth === "deep" &&
+        deployerVerdict !== null &&
+        cfg.blockDeployerVerdicts.includes(deployerVerdict)) {
+        return guardResult("safety", blockOrWarn(cfg.mode), detail, startMs, rt);
+    }
+    if (cfg.mode === "enforce" && degraded && DANGER_INCONCLUSIVE_VERDICTS.has(verdict)) {
+        return unavailable("safety", "degraded_screen", startMs, rt);
+    }
+    const inconclusive = verdict === "unknown" ||
+        (cfg.depth === "deep" && deployerVerdict === "insufficient_history");
+    if (inconclusive) {
+        detail.notes = [GUARD_UNRATED_NOTE];
+    }
+    return guardResult("safety", "pass", detail, startMs, rt);
+}
+export function createSafetyGuard(cfg, rt) {
+    return {
+        id: "safety",
+        applies(req) {
+            const token = req.context.tokenAddress;
+            return typeof token === "string" && token.length > 0;
+        },
+        async check(req) {
+            const start = rt.now();
+            const activeCfg = req.config ?? cfg;
+            try {
+                const base = rt.baseUrls.safety;
+                if (base === null) {
+                    return unavailable("safety", "base_url_unset", start, rt);
+                }
+                const token = req.context.tokenAddress;
+                if (token == null || token === "") {
+                    return unavailable("safety", "no_token", start, rt);
+                }
+                const chain = req.context.chain ?? "solana";
+                const url = safetyScreenUrl(base, token, chain, activeCfg.depth === "deep");
+                let res;
+                try {
+                    res = await guardFetchWithTimeout(rt, url, {
+                        method: "GET",
+                        headers: guardHeaders(rt),
+                    }, guardBudgetMs(activeCfg.mode), req.dryRun);
+                }
+                catch {
+                    return unavailable("safety", "fetch_failed", start, rt);
+                }
+                if (!res.ok) {
+                    return unavailable("safety", `http_${res.status}`, start, rt);
+                }
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    return unavailable("safety", "malformed_json", start, rt);
+                }
+                const parsed = parseScreen(body);
+                if (parsed === null) {
+                    return unavailable("safety", "malformed_body", start, rt);
+                }
+                return mapSafety(activeCfg, parsed, start, rt);
+            }
+            catch {
+                return unavailable("safety", "crash", start, rt);
+            }
+        },
+    };
+}

package/dist/src/guards/trust.d.ts

@@ -0,0 +1,2 @@
+import type { PrePayGuard, GuardRuntime, TrustGuardConfig } from "./types.js";
+export declare function createTrustGuard(cfg: TrustGuardConfig, rt: GuardRuntime): PrePayGuard;

package/dist/src/guards/trust.js

@@ -0,0 +1,79 @@
+import { guardBudgetMs } from "../core/constants.js";
+import { GUARD_UNRATED_NOTE, blockOrWarn, guardFetchWithTimeout, guardHeaders, guardResult, stripTarget, trustScoreUrl, unavailable, unwrapEnvelope, } from "./internal.js";
+function parseTrustScore(body) {
+    const b = unwrapEnvelope(body);
+    if (b === null)
+        return null;
+    if (typeof b.verdict !== "string")
+        return null;
+    const score = b.score;
+    if (typeof score !== "number" && score !== null)
+        return null;
+    return { score, verdict: b.verdict, counts: b.counts ?? null };
+}
+function mapTrust(cfg, parsed, startMs, rt) {
+    const { score, verdict, counts } = parsed;
+    const detail = { score, verdict, counts };
+    if (cfg.blockVerdicts.includes(verdict)) {
+        return guardResult("trust", blockOrWarn(cfg.mode), detail, startMs, rt);
+    }
+    if (score !== null && cfg.minScore !== null && score < cfg.minScore) {
+        return guardResult("trust", blockOrWarn(cfg.mode), detail, startMs, rt);
+    }
+    if (verdict === "unrated") {
+        if (cfg.blockUnrated) {
+            return guardResult("trust", blockOrWarn(cfg.mode), detail, startMs, rt);
+        }
+        detail.notes = [GUARD_UNRATED_NOTE];
+        return guardResult("trust", "pass", detail, startMs, rt);
+    }
+    return guardResult("trust", "pass", detail, startMs, rt);
+}
+export function createTrustGuard(cfg, rt) {
+    return {
+        id: "trust",
+        applies() {
+            return true;
+        },
+        async check(req) {
+            const start = rt.now();
+            const activeCfg = req.config ?? cfg;
+            try {
+                const base = rt.baseUrls.trust;
+                if (base === null) {
+                    return unavailable("trust", "base_url_unset", start, rt);
+                }
+                const target = stripTarget(req.url);
+                const url = trustScoreUrl(base, target);
+                let res;
+                try {
+                    res = await guardFetchWithTimeout(rt, url, {
+                        method: "GET",
+                        headers: guardHeaders(rt),
+                    }, guardBudgetMs(activeCfg.mode), req.dryRun);
+                }
+                catch {
+                    return unavailable("trust", "fetch_failed", start, rt);
+                }
+                if (!res.ok) {
+                    return unavailable("trust", `http_${res.status}`, start, rt);
+                }
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    return unavailable("trust", "malformed_json", start, rt);
+                }
+                const parsed = parseTrustScore(body);
+                if (parsed === null) {
+                    return unavailable("trust", "malformed_body", start, rt);
+                }
+                return mapTrust(activeCfg, parsed, start, rt);
+            }
+            catch {
+                return unavailable("trust", "crash", start, rt);
+            }
+        },
+    };
+}