@pseolint/core 0.3.2 → 0.4.1

package/dist/site-classifier.js

@@ -0,0 +1,205 @@
+/**
+ * v0.4 Site Classifier — runs BEFORE rules to gate which rule set applies.
+ *
+ * Today the engine runs every rule against every audited site regardless of
+ * whether the site is actually programmatic-SEO. A 23-page marketing site
+ * gets pSEO-targeted findings that don't apply; a 50,000-page directory
+ * gets the same audit shape as a small blog. This pre-flight classifier
+ * decides which "kind" of site we're auditing and emits a list of ruleIds
+ * that the dispatcher will skip when site type is small-marketing/blog.
+ *
+ * Heuristics (v1, ships in v0.4):
+ *   - Sitemap URL count: <50 = bias small/blog; ≥1000 = bias programmatic.
+ *   - URL-pattern clustering: normalize numeric/slug segments; if top-3
+ *     templates cover ≥60% of URLs → strong programmatic signal.
+ *   - Framework signal: pass-through from dev-server detection.
+ *
+ * Deferred to v0.4.1+ (per spec §4.11):
+ *   - DOM-skeleton hashing across pages.
+ *   - Per-cluster classification (mixed pSEO + marketing).
+ *   - Per-page applicability tagging on findings.
+ */
+/** Rules suppressed for non-pSEO sites (small-marketing / blog). */
+export const PSEO_ONLY_RULE_IDS = [
+    "spam/template-coverage",
+    "spam/template-diversity",
+    "spam/entity-swap",
+    "cannibal/url-pattern",
+];
+/**
+ * Normalize a pathname into a hashable template by replacing path segments
+ * that look like values with type placeholders.
+ *
+ * Examples:
+ *   /california/los-angeles/plumbers   → /:slug/:slug/:slug
+ *   /blog/hello-world                  → /blog/:slug
+ *   /post/12345                        → /post/:n
+ *   /                                  → /
+ */
+export function normalizePathToTemplate(pathname) {
+    // Drop trailing slash for consistency, but keep "/" itself.
+    let p = pathname || "/";
+    if (p.length > 1 && p.endsWith("/"))
+        p = p.slice(0, -1);
+    if (!p.startsWith("/"))
+        p = "/" + p;
+    const segments = p.split("/").slice(1); // drop leading empty
+    if (segments.length === 0 || (segments.length === 1 && segments[0] === "")) {
+        return "/";
+    }
+    const out = segments.map((seg) => {
+        if (seg === "")
+            return "";
+        // Pure numeric segment.
+        if (/^\d+$/.test(seg))
+            return ":n";
+        // Slug-like: lowercase letters/digits/hyphens with at least one
+        // hyphen-separated multi-word structure (e.g. "los-angeles",
+        // "hello-world"). Pure single-word segments like "about", "blog",
+        // "tools" are kept as literals so collection roots don't collide
+        // with their detail-page templates.
+        if (/^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(seg)) {
+            return ":slug";
+        }
+        // Long lowercase letter-only segments (>= 12 chars) are treated as
+        // slugs even without hyphens — covers concatenated-word URLs like
+        // /chicagoplumbers without hyphens.
+        if (seg.length >= 12 && /^[a-z]+$/.test(seg)) {
+            return ":slug";
+        }
+        return seg;
+    });
+    return "/" + out.join("/");
+}
+/** Convert a URL string to its template path (no host, no query). */
+function urlToTemplate(url) {
+    try {
+        const u = new URL(url);
+        return normalizePathToTemplate(u.pathname);
+    }
+    catch {
+        // Treat as a raw path.
+        if (typeof url === "string" && url.length > 0) {
+            const path = url.split("?")[0].split("#")[0];
+            return normalizePathToTemplate(path);
+        }
+        return null;
+    }
+}
+/** Compute template-cluster ratios from a URL list. Returns top entries first. */
+export function clusterUrlTemplates(urls) {
+    const counts = new Map();
+    let total = 0;
+    for (const url of urls) {
+        const t = urlToTemplate(url);
+        if (t === null)
+            continue;
+        counts.set(t, (counts.get(t) ?? 0) + 1);
+        total += 1;
+    }
+    if (total === 0)
+        return [];
+    const entries = Array.from(counts.entries()).map(([template, count]) => ({
+        template,
+        count,
+        ratio: count / total,
+    }));
+    entries.sort((a, b) => b.count - a.count || a.template.localeCompare(b.template));
+    return entries;
+}
+/**
+ * Classify a site from its URL list + framework signal. Pure function.
+ *
+ * Contract: callers must pass the FULL discovered URL list (sitemap +
+ * crawl), not the post-sample list. The classifier needs the raw size
+ * signal to distinguish a 5000-page directory from a 25-page sample of one.
+ */
+export function classifySite(input) {
+    const urls = Array.isArray(input.urls) ? input.urls : [];
+    const framework = input.framework ?? "unknown";
+    const signals = [];
+    signals.push({ kind: "sitemap-url-count", value: urls.length });
+    const clusters = clusterUrlTemplates(urls);
+    const top = clusters[0];
+    const top3Ratio = clusters.slice(0, 3).reduce((sum, c) => sum + c.ratio, 0);
+    if (top) {
+        signals.push({
+            kind: "url-pattern-cluster-coverage",
+            topTemplate: top.template,
+            pages: top.count,
+            ratio: top.ratio,
+        });
+    }
+    signals.push({ kind: "framework-detected", value: framework });
+    // Empty list → unclear (no signal to act on).
+    if (urls.length === 0) {
+        return { type: "unclear", confidence: 0, signals, suppressedRules: [] };
+    }
+    // Step 4: synthesize.
+    let type = "unclear";
+    let confidence = 0;
+    if (urls.length >= 1000) {
+        if (top3Ratio >= 0.6) {
+            type = "programmatic-directory";
+            confidence = 0.9;
+        }
+        else {
+            // Lots of pages but no clear template clustering — likely ecommerce
+            // (varied product URLs) or a sprawling content site.
+            type = "ecommerce";
+            confidence = 0.6;
+        }
+    }
+    else if (urls.length < 50) {
+        // Small site. Detect blog separately from generic small-marketing.
+        //
+        // Note on clustering for tiny sites: in our normalization, top-level
+        // pages like /about, /pricing, /contact all collapse to /:slug, so
+        // ratio-based clustering misfires below ~10 URLs. We require the top
+        // template to be deeper than one segment (so /:slug doesn't trigger)
+        // before treating clustering as a programmatic signal at small scale.
+        const blogTemplate = clusters.find((c) => c.template.startsWith("/blog/") || c.template === "/blog" || c.template === "/blog/:slug");
+        const topIsDeepCluster = top !== undefined &&
+            top.template.split("/").filter(Boolean).length >= 2 &&
+            top.ratio >= 0.6;
+        if (blogTemplate && blogTemplate.ratio >= 0.4) {
+            type = "blog";
+            confidence = 0.85;
+        }
+        else if (!topIsDeepCluster) {
+            // Tiny site without a deep dominant template — marketing pages.
+            type = "small-marketing";
+            confidence = 0.85;
+        }
+        else {
+            // Tiny site WITH a deep dominant template — likely a templated
+            // micro-site (rare, but possible). Don't claim it's pSEO from such a
+            // tiny sample. Keep `unclear` so all rules run; the rules themselves
+            // will decide.
+            type = "unclear";
+            confidence = 0.5;
+        }
+    }
+    else {
+        // Medium tier (50–999 URLs). Use clustering to decide.
+        if (top3Ratio >= 0.6) {
+            type = "programmatic-directory";
+            confidence = 0.7;
+        }
+        else {
+            // No clear pattern in the medium tier. Could be marketing site or
+            // mid-sized content. Default to unclear so we don't over-suppress.
+            type = "unclear";
+            confidence = 0.5;
+        }
+    }
+    // Framework-aware nudge: a small Next.js site is almost certainly a
+    // marketing or blog site, not a pSEO directory. We've already excluded
+    // pSEO via the size check, so this is mostly a confidence bump.
+    if (framework === "nextjs" && urls.length < 50 && (type === "small-marketing" || type === "blog")) {
+        confidence = Math.min(0.95, confidence + 0.05);
+    }
+    const suppressedRules = type === "small-marketing" || type === "blog" ? [...PSEO_ONLY_RULE_IDS] : [];
+    return { type, confidence, signals, suppressedRules };
+}
+//# sourceMappingURL=site-classifier.js.map

package/dist/site-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-classifier.js","sourceRoot":"","sources":["../src/site-classifier.ts"],"names":[],"mappings":"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"}

package/dist/ssrf-guard.d.ts

@@ -0,0 +1,96 @@
+/**
+ * SSRF guard for audit targets.
+ *
+ * Two layers:
+ *   1. `isPrivateOrReservedHost(hostname)` — fast, synchronous string check.
+ *      Catches literal private IPs ("10.0.0.5"), loopback names ("localhost"),
+ *      link-local suffixes (".local"), and internal/metadata hostnames.
+ *   2. `validateTargetHost(hostname)` — async. Resolves the hostname via DNS
+ *      and rejects if the resulting address (v4 or v6) falls into a private /
+ *      reserved / link-local / multicast range. Mitigates DNS rebinding where
+ *      a public hostname returns 127.0.0.1.
+ *
+ * Usage:
+ *   const hostname = new URL(userSuppliedUrl).hostname;
+ *   await validateTargetHost(hostname); // throws SSRFError on blocked targets
+ *
+ * Library consumers should call this BEFORE enqueuing a crawl. The audit
+ * engine itself wraps its own fetches with this check when `guardSsrf` is
+ * enabled in AuditOptions, but defense-in-depth at the API boundary is the
+ * primary mitigation.
+ */
+export declare class SSRFError extends Error {
+    readonly hostname: string;
+    readonly reason: string;
+    constructor(hostname: string, reason: string);
+}
+/**
+ * Thrown when a hostname legitimately fails DNS resolution (NXDOMAIN / SERVFAIL
+ * / no A / AAAA records). Distinct from `SSRFError`: resolution failure
+ * is a "try again later / fix your typo" condition, not an attack. Callers
+ * in SaaS contexts should not log these as security events.
+ */
+export declare class DnsResolutionError extends Error {
+    readonly hostname: string;
+    constructor(hostname: string);
+}
+/**
+ * IPv4 range predicate — true if the address is private / reserved /
+ * link-local / loopback / multicast / broadcast / CGNAT. Expects a valid
+ * dotted-quad; caller must ensure that (e.g. via `net.isIP`).
+ */
+export declare function isPrivateIPv4(addr: string): boolean;
+/**
+ * IPv6 range predicate — true for loopback, ULA, link-local, unspecified,
+ * multicast, and IPv4-mapped addresses (after unwrapping to the v4 check).
+ */
+export declare function isPrivateIPv6(addr: string): boolean;
+/**
+ * Decode an integer-packed (`2130706433` = `127.0.0.1`) or hex-encoded
+ * (`0x7f000001`) hostname into dotted-quad form. Returns `null` if the
+ * input isn't a numeric hostname. Needed because some fetch stacks accept
+ * these encodings and resolve them to private IPs, bypassing a naive
+ * string-only dotted-quad check.
+ */
+export declare function decodeNumericIPv4(hostname: string): string | null;
+/**
+ * Synchronous string-only check. Rejects:
+ *   - literal private / reserved IP addresses (dotted-quad OR numeric/hex encoding)
+ *   - exact blocked hostnames (localhost, 0, etc.)
+ *   - suffix-blocked hostnames (.local, .internal, .arpa, ...)
+ *
+ * Returns `null` if the host is acceptable, or a human-readable reason
+ * string if it should be blocked.
+ */
+export declare function isPrivateOrReservedHost(hostname: string): string | null;
+export interface ValidateTargetHostOptions {
+    /** Override the DNS resolver — useful for tests or custom resolvers. */
+    resolver?: {
+        resolve4: (hostname: string) => Promise<string[]>;
+        resolve6: (hostname: string) => Promise<string[]>;
+    };
+}
+/**
+ * Full SSRF check: the string check above PLUS a DNS lookup to guarantee the
+ * resolved address isn't in a private range. Throws `SSRFError` on failure.
+ *
+ * Time-of-check-vs-time-of-use: an attacker-controlled DNS server can return
+ * a public IP on first lookup and a private IP on the subsequent fetch ("DNS
+ * rebinding"). Mitigations: cache the resolved IP and dial to THAT IP (host
+ * header preserved), or use a resolver that refuses re-resolution within a
+ * TTL window. This function validates; it does not pin. For the audit
+ * engine's own fetches, the pinning layer is layered on top via `safeFetch`.
+ */
+export declare function validateTargetHost(hostname: string, options?: ValidateTargetHostOptions): Promise<void>;
+/**
+ * Convenience check for "is this URL pointing at localhost or a private
+ * network?". Used by the CLI to auto-apply a conservative crawl preset when
+ * a developer runs `pseolint http://localhost:3000` — a cache-cold local
+ * server can amplify every fetch into a thundering herd of DB queries.
+ *
+ * Returns false for anything that isn't a parseable URL with a hostname
+ * (paths, `file://`, empty strings). Delegates the actual decision to
+ * `isPrivateOrReservedHost` so the two stay in sync.
+ */
+export declare function isLocalhostUrl(url: string): boolean;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../src/ssrf-guard.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7C;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAwBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAqBnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAWnD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4BvE;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE;QACT,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;KACnD,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD"}

package/dist/ssrf-guard.js

@@ -0,0 +1,268 @@
+import { promises as dns } from "node:dns";
+import { isIP } from "node:net";
+/**
+ * SSRF guard for audit targets.
+ *
+ * Two layers:
+ *   1. `isPrivateOrReservedHost(hostname)` — fast, synchronous string check.
+ *      Catches literal private IPs ("10.0.0.5"), loopback names ("localhost"),
+ *      link-local suffixes (".local"), and internal/metadata hostnames.
+ *   2. `validateTargetHost(hostname)` — async. Resolves the hostname via DNS
+ *      and rejects if the resulting address (v4 or v6) falls into a private /
+ *      reserved / link-local / multicast range. Mitigates DNS rebinding where
+ *      a public hostname returns 127.0.0.1.
+ *
+ * Usage:
+ *   const hostname = new URL(userSuppliedUrl).hostname;
+ *   await validateTargetHost(hostname); // throws SSRFError on blocked targets
+ *
+ * Library consumers should call this BEFORE enqueuing a crawl. The audit
+ * engine itself wraps its own fetches with this check when `guardSsrf` is
+ * enabled in AuditOptions, but defense-in-depth at the API boundary is the
+ * primary mitigation.
+ */
+export class SSRFError extends Error {
+    hostname;
+    reason;
+    constructor(hostname, reason) {
+        super(`Target host "${hostname}" is not permitted: ${reason}`);
+        this.name = "SSRFError";
+        this.hostname = hostname;
+        this.reason = reason;
+    }
+}
+/**
+ * Thrown when a hostname legitimately fails DNS resolution (NXDOMAIN / SERVFAIL
+ * / no A / AAAA records). Distinct from `SSRFError`: resolution failure
+ * is a "try again later / fix your typo" condition, not an attack. Callers
+ * in SaaS contexts should not log these as security events.
+ */
+export class DnsResolutionError extends Error {
+    hostname;
+    constructor(hostname) {
+        super(`DNS resolution failed for "${hostname}"`);
+        this.name = "DnsResolutionError";
+        this.hostname = hostname;
+    }
+}
+const BLOCKED_HOSTNAME_EXACT = new Set([
+    "localhost",
+    "broadcasthost",
+    "ip6-localhost",
+    "ip6-loopback",
+    "0",
+]);
+const BLOCKED_HOSTNAME_SUFFIXES = [
+    ".local",
+    ".localhost",
+    ".internal",
+    ".arpa",
+    ".intranet",
+    ".lan",
+    ".home",
+    ".private",
+    ".corp",
+];
+const IPV4_MAPPED_IPV6 = /^::ffff:(?:0:)?(\d+\.\d+\.\d+\.\d+)$/i;
+/**
+ * IPv4 range predicate — true if the address is private / reserved /
+ * link-local / loopback / multicast / broadcast / CGNAT. Expects a valid
+ * dotted-quad; caller must ensure that (e.g. via `net.isIP`).
+ */
+export function isPrivateIPv4(addr) {
+    const parts = addr.split(".").map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === 0)
+        return true; // 0.0.0.0/8 — "this network"
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 127)
+        return true; // 127.0.0.0/8 — loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 — link-local + cloud metadata
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 — CGNAT
+    if (a === 192 && b === 0 && parts[2] === 0)
+        return true; // 192.0.0.0/24 — IETF
+    if (a === 192 && b === 0 && parts[2] === 2)
+        return true; // 192.0.2.0/24 — TEST-NET-1
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 — benchmark
+    if (a === 198 && b === 51 && parts[2] === 100)
+        return true; // 198.51.100.0/24 — TEST-NET-2
+    if (a === 203 && b === 0 && parts[2] === 113)
+        return true; // 203.0.113.0/24 — TEST-NET-3
+    if (a >= 224 && a <= 239)
+        return true; // 224.0.0.0/4 — multicast
+    if (a >= 240)
+        return true; // 240.0.0.0/4 — reserved + 255.255.255.255 broadcast
+    return false;
+}
+/**
+ * IPv6 range predicate — true for loopback, ULA, link-local, unspecified,
+ * multicast, and IPv4-mapped addresses (after unwrapping to the v4 check).
+ */
+export function isPrivateIPv6(addr) {
+    const normalized = addr.toLowerCase();
+    if (normalized === "::" || normalized === "::1")
+        return true;
+    if (normalized.startsWith("fe8") || normalized.startsWith("fe9") ||
+        normalized.startsWith("fea") || normalized.startsWith("feb"))
+        return true; // fe80::/10
+    if (normalized.startsWith("fc") || normalized.startsWith("fd"))
+        return true; // fc00::/7 ULA
+    if (normalized.startsWith("ff"))
+        return true; // ff00::/8 multicast
+    // IPv4-mapped IPv6 (::ffff:a.b.c.d or ::ffff:0:a.b.c.d) — unwrap and delegate
+    const mapped = normalized.match(IPV4_MAPPED_IPV6);
+    if (mapped)
+        return isPrivateIPv4(mapped[1]);
+    return false;
+}
+/**
+ * Decode an integer-packed (`2130706433` = `127.0.0.1`) or hex-encoded
+ * (`0x7f000001`) hostname into dotted-quad form. Returns `null` if the
+ * input isn't a numeric hostname. Needed because some fetch stacks accept
+ * these encodings and resolve them to private IPs, bypassing a naive
+ * string-only dotted-quad check.
+ */
+export function decodeNumericIPv4(hostname) {
+    const s = hostname.toLowerCase().trim();
+    if (!s)
+        return null;
+    let n = null;
+    if (/^[0-9]+$/.test(s)) {
+        // Pure decimal (also catches single-number IPv4 form "2130706433").
+        const parsed = Number(s);
+        if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 0xffffffff)
+            n = parsed;
+    }
+    else if (/^0x[0-9a-f]+$/.test(s)) {
+        // Hex — "0x7f000001".
+        const parsed = Number(s);
+        if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 0xffffffff)
+            n = parsed;
+    }
+    if (n === null)
+        return null;
+    return [
+        (n >>> 24) & 0xff,
+        (n >>> 16) & 0xff,
+        (n >>> 8) & 0xff,
+        n & 0xff,
+    ].join(".");
+}
+/**
+ * Synchronous string-only check. Rejects:
+ *   - literal private / reserved IP addresses (dotted-quad OR numeric/hex encoding)
+ *   - exact blocked hostnames (localhost, 0, etc.)
+ *   - suffix-blocked hostnames (.local, .internal, .arpa, ...)
+ *
+ * Returns `null` if the host is acceptable, or a human-readable reason
+ * string if it should be blocked.
+ */
+export function isPrivateOrReservedHost(hostname) {
+    if (!hostname)
+        return "empty hostname";
+    const lower = hostname.toLowerCase();
+    if (BLOCKED_HOSTNAME_EXACT.has(lower)) {
+        return `reserved hostname (${lower})`;
+    }
+    for (const suffix of BLOCKED_HOSTNAME_SUFFIXES) {
+        if (lower.endsWith(suffix))
+            return `reserved TLD / suffix (${suffix})`;
+    }
+    // Numeric / hex encoding of IPv4 — decode and test.
+    const decoded = decodeNumericIPv4(hostname);
+    if (decoded) {
+        if (isPrivateIPv4(decoded))
+            return `private / reserved IPv4 (${decoded}, encoded as ${hostname})`;
+        // Also reject all numeric hostnames that decode to public IPs — they're a
+        // deniability smell. Callers who intentionally audit a literal IP will
+        // pass it in dotted-quad form.
+        return `ambiguous numeric-encoded IPv4 (${hostname} decodes to ${decoded}); pass dotted-quad form explicitly`;
+    }
+    const version = isIP(hostname); // 4 | 6 | 0
+    if (version === 4 && isPrivateIPv4(hostname))
+        return "private / reserved IPv4 range";
+    if (version === 6) {
+        const bare = hostname.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+        if (isPrivateIPv6(bare))
+            return "private / reserved IPv6 range";
+    }
+    return null;
+}
+/**
+ * Full SSRF check: the string check above PLUS a DNS lookup to guarantee the
+ * resolved address isn't in a private range. Throws `SSRFError` on failure.
+ *
+ * Time-of-check-vs-time-of-use: an attacker-controlled DNS server can return
+ * a public IP on first lookup and a private IP on the subsequent fetch ("DNS
+ * rebinding"). Mitigations: cache the resolved IP and dial to THAT IP (host
+ * header preserved), or use a resolver that refuses re-resolution within a
+ * TTL window. This function validates; it does not pin. For the audit
+ * engine's own fetches, the pinning layer is layered on top via `safeFetch`.
+ */
+export async function validateTargetHost(hostname, options = {}) {
+    const stringReason = isPrivateOrReservedHost(hostname);
+    if (stringReason)
+        throw new SSRFError(hostname, stringReason);
+    // Literal IPs pass the DNS step trivially (isIP > 0 ⇒ not a name to resolve).
+    if (isIP(hostname) !== 0)
+        return;
+    const resolver = options.resolver ?? {
+        resolve4: (h) => dns.resolve4(h),
+        resolve6: (h) => dns.resolve6(h),
+    };
+    const [v4, v6] = await Promise.allSettled([
+        resolver.resolve4(hostname),
+        resolver.resolve6(hostname),
+    ]);
+    const addrs = [];
+    if (v4.status === "fulfilled")
+        for (const a of v4.value)
+            addrs.push({ kind: "v4", addr: a });
+    if (v6.status === "fulfilled")
+        for (const a of v6.value)
+            addrs.push({ kind: "v6", addr: a });
+    if (addrs.length === 0) {
+        throw new DnsResolutionError(hostname);
+    }
+    for (const { kind, addr } of addrs) {
+        const isPrivate = kind === "v4" ? isPrivateIPv4(addr) : isPrivateIPv6(addr);
+        if (isPrivate) {
+            throw new SSRFError(hostname, `resolves to private ${kind} address ${addr}`);
+        }
+    }
+}
+/**
+ * Convenience check for "is this URL pointing at localhost or a private
+ * network?". Used by the CLI to auto-apply a conservative crawl preset when
+ * a developer runs `pseolint http://localhost:3000` — a cache-cold local
+ * server can amplify every fetch into a thundering herd of DB queries.
+ *
+ * Returns false for anything that isn't a parseable URL with a hostname
+ * (paths, `file://`, empty strings). Delegates the actual decision to
+ * `isPrivateOrReservedHost` so the two stay in sync.
+ */
+export function isLocalhostUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (!parsed.hostname)
+        return false;
+    const host = parsed.hostname.replace(/^\[|\]$/g, "");
+    return isPrivateOrReservedHost(host) !== null;
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/ssrf-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.js","sourceRoot":"","sources":["../src/ssrf-guard.ts"],"names":[],"mappings":"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"}