@pseolint/core 0.3.2 → 0.4.0

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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"}

package/dist/types.d.ts

@@ -1,4 +1,10 @@
 export type Severity = "info" | "warning" | "error" | "critical";
+/** Verdict ladder — replaces the old numeric `score` field as the user-facing signal. */
+export type Verdict = "ready" | "caution" | "concerning" | "critical";
+/** Letter grade per category. */
+export type Grade = "A" | "B" | "C" | "D" | "F";
+/** Top-level v0.4 schema version. Bumps on every breaking output change. */
+export declare const SCHEMA_VERSION = "2026-04-v0.4";
 /** Options for `normalizeAuditUrl` (HTTP identity). */
 export interface NormalizeUrlOptions {
     /** When true (default), drop `?query` for URL identity. */
@@ -38,6 +44,12 @@ export interface RuleResult {
     fix?: string;
     /** Google documentation URL backing this finding. */
     ref?: string;
+    /**
+     * Marketing-page deeplink for this rule (v0.4+). Always populated by the
+     * auditor — points to https://pseolint.dev/rules/{slug} where slug is the
+     * rule-id segment after the namespace prefix.
+     */
+    docsUrl?: string;
     /** Primary page this finding refers to, when applicable. */
     pageUrl?: string;
     /** Other URLs involved (e.g. cluster members, related pairs). */
@@ -51,15 +63,47 @@ export interface RuleResult {
     /** Fix effort level assigned by the enrichment pipeline. */
     effort?: FixEffort;
 }
-export interface CategoryScores {
-    spam: number;
-    content: number;
-    aeo: number;
-    links: number;
-    tech: number;
-    data: number;
-    schema: number;
-    cannibal: number;
+/** v0.4 four-category bucket keys. */
+export type CategoryKey = "integrity" | "discoverability" | "citation" | "data" | "audit";
+/** Per-category grade + raw issue count. Audit category exists for completeness but is never weighted. */
+export interface CategoryGrade {
+    grade: Grade;
+    issues: number;
+}
+export type CategoryGrades = Record<CategoryKey, CategoryGrade>;
+/** Issues bucketed by severity — the v0.4 replacement for the flat `findings` array. */
+export interface IssueBuckets {
+    /** Severity = error or critical. Must be fixed before shipping. */
+    blockers: RuleResult[];
+    /** Severity = warning. Should be fixed before scaling. */
+    shouldFix: RuleResult[];
+    /** Severity = info. Tracked for trend analysis. */
+    informational: RuleResult[];
+}
+/** Crawl statistics surfaced under diagnostics. */
+export interface CrawlStats {
+    /** Total URLs the crawler considered (sitemap + discovered links). */
+    discovered: number;
+    /** URLs the crawler successfully fetched and audited. */
+    fetched: number;
+    /**
+     * URLs the crawler fetched but excluded from the rule pipeline (non-HTML
+     * content-type, dedup, robots-disallow, render budget, etc.).
+     */
+    skipped: number;
+}
+/** Engine-internal diagnostics — weight 0, never affects verdict. */
+export interface Diagnostics {
+    /** Origin readiness aggregate (median/p95/error ratio). Null when no live fetches occurred. */
+    originReadiness: import("./fetch-observer.js").ReadinessReport | null;
+    crawlStats: CrawlStats;
+    /**
+     * Engine-emitted `audit/*` findings (e.g. `audit/duplicate-url`,
+     * `audit/skipped-by-robots`). Always severity=info, never affect the
+     * verdict, never appear in `summary.issues`. Surfaced here so consumers
+     * (telemetry, debug UIs) can still see what was skipped or deduped.
+     */
+    auditFindings: RuleResult[];
 }
 /** Options for HTTP caching during audits. */
 export interface CacheOptions {
@@ -67,6 +111,13 @@ export interface CacheOptions {
     dir?: string;
     /** TTL for entries without ETag/Last-Modified validators. Default: 7 days. */
     ttlMs?: number;
+    /**
+     * Maximum total size of the cache directory in bytes. When exceeded after a
+     * run, oldest-mtime entries are evicted until under the cap. Also sweeps
+     * leftover `.tmp` files from crashed writes. `<= 0` disables size-based
+     * eviction. Default: 209_715_200 (200 MB).
+     */
+    maxBytes?: number;
 }
 /** Cache stats reported at end of audit. */
 export interface CacheStats {
@@ -117,12 +168,34 @@ export interface AiOptions {
     } | false;
 }
 export interface AuditSummary {
-    score: number;
-    categoryScores: CategoryScores;
+    /** Schema version. v0.4 = "2026-04-v0.4". Wave 2 / 3 consumers branch on this. */
+    schemaVersion: typeof SCHEMA_VERSION;
+    /** User-facing verdict ladder. */
+    verdict: Verdict;
+    /**
+     * Internal numeric risk score (0–100, low = good). Retained for CI thresholding,
+     * trend deltas, and alert-gate diff logic. NEVER displayed to humans.
+     */
+    risk: number;
+    /** One-liner summarising counts: e.g. "3 ship-blockers, 16 should-fix". */
+    headline: string;
+    /** Per-category grade + count. */
+    categories: CategoryGrades;
+    /** Findings bucketed by severity. */
+    issues: IssueBuckets;
+    /**
+     * v0.4 §4.11 — pre-flight site classification. Decides which rules apply
+     * based on URL count, template clustering, and framework signal. The
+     * `suppressedRules` list is what the rule dispatcher honours. Pass
+     * `strict: true` in AuditOptions to keep the classification but force all
+     * rules to run anyway.
+     */
+    siteClassification: import("./site-classifier.js").SiteClassification;
+    /** Engine-internal diagnostics (origin readiness, crawl stats). Weight 0. */
+    diagnostics: Diagnostics;
     groupScores?: Record<string, number>;
     groupPageCounts?: Record<string, number>;
     pageCount: number;
-    findings: RuleResult[];
     /** True when the enrichment pipeline detects template-generated content. */
     templateDetected?: boolean;
     /** Pre-enrichment finding count, for backward compatibility with CI scripts. */
@@ -160,12 +233,6 @@ export interface AuditOptions {
         uniqueValueMinWords?: number;
         metaUniquenessMinJaccard?: number;
         linkDepthMaxClicks?: number;
-        /** Minimum pages in one directory before hub/index coverage is required. */
-        hubPagesMinSiblings?: number;
-        /** Skip hub/index checks when a directory has more than this many pages (e.g. large blogs). */
-        hubPagesMaxSiblings?: number;
-        titleOverlapThreshold?: number;
-        keywordCollisionMinShared?: number;
         templateCoverageMinPages?: number;
         /** aeo/answer-first: max words in the first paragraph for extractable answer. */
         answerFirstMaxWords?: number;
@@ -188,7 +255,12 @@ export interface AuditOptions {
     timeout?: number;
     /** Audit a random subset of N pages. 0 means all pages (default: 0). */
     sampleSize?: number;
-    /** URL/path glob patterns to exclude from the audit. */
+    /**
+     * URL/path glob patterns to exclude from the audit. v0.4: globs match
+     * against the URL pathname only (e.g. "/api/foo"), not the full URL.
+     * The auditor logs a warning at the end of the audit for any pattern that
+     * matched zero discovered URLs (likely-typo signal).
+     */
     ignore?: string[];
     crawlDiscovery?: boolean;
     /**
@@ -243,7 +315,81 @@ export interface AuditOptions {
     ai?: AiOptions;
     /** Local-only telemetry (JSONL) options. When omitted or `enabled: false`, no records are written. */
     telemetry?: TelemetryOptions;
+    /**
+     * External abort signal. When aborted, in-flight fetches are cancelled and
+     * `auditSource` throws an `AbortError`. Host code can use this to kill an
+     * audit that exceeded a per-user budget or was cancelled by the user.
+     */
+    signal?: AbortSignal;
+    /**
+     * When true, every crawled URL's hostname is validated with
+     * `validateTargetHost` before fetch — resolves the hostname and rejects if
+     * any address is in a private / reserved / link-local / loopback / multicast
+     * range. Applies to the source URL, sitemap entries, redirect targets, and
+     * discovered links. Defends against SSRF / DNS-rebinding when the library is
+     * invoked against user-supplied URLs (e.g. from a hosted audit service).
+     * Default: false (CLI users auditing localhost / staging sites should not
+     * be broken silently).
+     */
+    guardSsrf?: boolean;
+    /**
+     * When true (default), sitemap URLs that match a `Disallow:` rule in the
+     * target's robots.txt are skipped at fetch time instead of crawled. Set to
+     * false to audit staging / internal sites that Disallow everything.
+     */
+    respectRobotsTxt?: boolean;
+    /**
+     * Preset that flips several safety options at once.
+     *   "saas" — intended for hosted services auditing user-submitted URLs:
+     *     guardSsrf=true, respectRobotsTxt=true, tighter maxFetchBytes cap,
+     *     followRedirects stays true (audits need final URL).
+     *   "cli"  — intended for local CLI / dev use:
+     *     guardSsrf=false (auditing localhost is OK), respectRobotsTxt=true,
+     *     default caps.
+     *   "dev"  — tiny crawl budget for localhost probing: concurrency=1,
+     *     sampleSize=25, maxCrawlDiscovered=50. Designed so a cache-cold
+     *     `pseolint http://localhost:3000` doesn't thundering-herd a dev DB.
+     *     Auto-selected on localhost sources unless `autoDevPreset: false`.
+     * Individual options on AuditOptions override the preset when set.
+     * Default: undefined (no preset applied, existing opt-in behaviour).
+     */
+    safeMode?: SafeMode;
+    /**
+     * When true (default), audit sources pointing at localhost / private
+     * networks are auto-promoted to the `dev` safeMode preset. Set to false
+     * to opt out (e.g. `--full` on the CLI). Explicit `safeMode` beats this.
+     */
+    autoDevPreset?: boolean;
+    /**
+     * Hard ceiling on URLs discovered via link-following before sampling.
+     * Protects against malicious sites with many self-links that could extend
+     * the crawl up to the byte budget. Default: 5000.
+     */
+    maxCrawlDiscovered?: number;
+    /**
+     * When false, 3xx responses are returned as-is (the audit will see the
+     * redirect location header and can report it) instead of followed. Useful
+     * for security-sensitive audits that must not leave the exact submitted
+     * URL. Default: true.
+     */
+    followRedirects?: boolean;
+    /**
+     * When false, disables the in-flight backpressure watchdog that aborts the
+     * audit when origin latency / 5xx rate spikes past thresholds during the
+     * crawl. On by default; the last line of defence against a cache-cold
+     * origin ballooning an audit into an expensive egress event.
+     */
+    backpressure?: boolean;
+    /**
+     * v0.4 §4.11 — when true, the site classifier still runs and `summary.siteClassification`
+     * is populated, but `suppressedRules` is forced to `[]` so every rule executes
+     * regardless of detected site type. Use this to inspect what the classifier
+     * sees on a site that would otherwise have pSEO-only rules suppressed.
+     * Default: false.
+     */
+    strict?: boolean;
 }
+export type SafeMode = "saas" | "cli" | "dev";
 export type SamplingStrategy = "stratified" | "random";
 /** A single page's source data for data-source comparison. */
 export interface PageDataRecord {
@@ -267,6 +413,12 @@ export interface HttpMeta {
     redirectChain: string[];
     xRobotsTag: string;
     linkHeader: string;
+    /**
+     * v0.4: lower-cased response headers. Populated for the source URL only
+     * (used by the dev-server framework detector). Other crawled pages can
+     * leave this undefined to keep the audit memory-bounded.
+     */
+    headers?: Record<string, string>;
 }
 export interface ParsedPage {
     url: string;