securl 1.4.1

package/dist/infrastructure.d.ts

@@ -0,0 +1,9 @@
+import type { InfrastructureInfo, TechnologyResult } from "./types.js";
+interface InfrastructureResolver {
+    resolveCname(host: string): Promise<string[]>;
+    resolve4(host: string): Promise<string[]>;
+    resolve6(host: string): Promise<string[]>;
+    reverse(address: string): Promise<string[]>;
+}
+export declare function analyzeInfrastructure(finalUrl: URL, headers: Record<string, string | string[] | undefined>, technologies: TechnologyResult[], resolver?: InfrastructureResolver): Promise<InfrastructureInfo>;
+export {};

package/dist/infrastructure.js

@@ -0,0 +1,149 @@
+import dns from "node:dns/promises";
+import { DNS_LOOKUP_TIMEOUT_MS } from "./scannerConfig.js";
+import { headerValue, mapWithConcurrency, safeResolveWithTimeout, unique } from "./utils.js";
+const defaultResolver = {
+    resolveCname: (host) => dns.resolveCname(host),
+    resolve4: (host) => dns.resolve4(host),
+    resolve6: (host) => dns.resolve6(host),
+    reverse: (address) => dns.reverse(address),
+};
+const PROVIDER_SIGNATURES = [
+    { provider: "Cloudflare", category: "edge", pattern: /cloudflare|cf-ray|cf-cache-status/i },
+    { provider: "AWS / CloudFront", category: "cloud", pattern: /amazonaws|aws|cloudfront|awsglobalaccelerator|elb\.amazonaws/i },
+    { provider: "Microsoft Azure", category: "cloud", pattern: /azure|trafficmanager\.net|cloudapp\.net|azurefd\.net|windows\.net/i },
+    { provider: "Google Cloud", category: "cloud", pattern: /googleusercontent|googlehosted|googleapis|gcp|appspot\.com|goog/i },
+    { provider: "Fastly", category: "cdn", pattern: /fastly|fastlylb/i },
+    { provider: "Akamai", category: "cdn", pattern: /akamai|edgesuite|edgekey/i },
+    { provider: "Bunny.net", category: "cdn", pattern: /bunnycdn|bunny\.net|b-cdn\.net/i },
+    { provider: "Vercel", category: "paas", pattern: /vercel|now\.sh/i },
+    { provider: "Netlify", category: "paas", pattern: /netlify/i },
+    { provider: "Cloudflare Pages", category: "paas", pattern: /pages\.dev/i },
+    { provider: "Railway", category: "paas", pattern: /railway\.app|up\.railway\.app/i },
+    { provider: "Render", category: "paas", pattern: /render\.com|onrender\.com/i },
+    { provider: "Fly.io", category: "paas", pattern: /fly\.dev|fly\.io/i },
+    { provider: "DigitalOcean", category: "hosting", pattern: /digitalocean|do-static|ondigitalocean/i },
+    { provider: "Hostinger", category: "hosting", pattern: /hostinger|hstgr\.io/i },
+    { provider: "OVHcloud", category: "hosting", pattern: /ovh|ovhcloud/i },
+    { provider: "Hetzner", category: "hosting", pattern: /hetzner|your-server\.de/i },
+    { provider: "Heroku", category: "paas", pattern: /herokuapp|herokudns|heroku/i },
+    { provider: "GitHub Pages", category: "paas", pattern: /github\.io|githubusercontent|github\.com/i },
+];
+const signalFromEvidence = (evidence, source) => {
+    for (const signature of PROVIDER_SIGNATURES) {
+        if (signature.pattern.test(evidence)) {
+            return {
+                provider: signature.provider,
+                category: signature.category,
+                confidence: source === "headers" || source === "technology" ? "high" : "medium",
+                source,
+                evidence,
+            };
+        }
+    }
+    return null;
+};
+const addSignals = (signals, values, source) => {
+    for (const value of values.filter(Boolean)) {
+        const signal = signalFromEvidence(value, source);
+        if (signal) {
+            signals.push(signal);
+        }
+    }
+};
+const detectProtocol = (headers) => {
+    const altSvc = headerValue(headers, "alt-svc");
+    const http3Advertised = Boolean(altSvc && /\bh3(?:-|=|")/i.test(altSvc));
+    // Node's fetch API does not expose the protocol version directly from response headers alone.
+    // Default to "unknown" rather than asserting HTTP/1.1 incorrectly for HTTP/2+ sites.
+    return {
+        http: "unknown",
+        http3Advertised,
+        altSvc,
+    };
+};
+const detectWaf = (headers) => {
+    const server = headerValue(headers, "server") || "";
+    const xCdn = headerValue(headers, "x-cdn") || "";
+    const setCookie = headerValue(headers, "set-cookie") || "";
+    const detectors = [
+        { provider: "Cloudflare", confidence: "high", evidence: "Observed Cloudflare edge headers.", matched: Boolean(headerValue(headers, "cf-ray") || headerValue(headers, "cf-cache-status") || /cloudflare/i.test(server)) },
+        { provider: "Akamai", confidence: "high", evidence: "Observed Akamai cache/request headers.", matched: Boolean(headerValue(headers, "x-check-cacheable") || headerValue(headers, "x-akamai-request-id") || headerValue(headers, "akamai-cache-status")) },
+        { provider: "AWS WAF / CloudFront", confidence: "medium", evidence: "Observed AWS CloudFront edge headers.", matched: Boolean(headerValue(headers, "x-amz-cf-id") || headerValue(headers, "x-amz-cf-pop")) },
+        { provider: "Imperva", confidence: "high", evidence: "Observed Imperva / Incapsula headers.", matched: Boolean(headerValue(headers, "x-iinfo") || /imperva/i.test(xCdn)) },
+        { provider: "Fastly", confidence: "medium", evidence: "Observed Fastly request/cache headers.", matched: Boolean(headerValue(headers, "x-fastly-request-id") || headerValue(headers, "fastly-restarts")) },
+        { provider: "Vercel Edge", confidence: "high", evidence: "Observed Vercel edge headers.", matched: Boolean(headerValue(headers, "x-vercel-cache") || headerValue(headers, "x-vercel-id")) },
+        { provider: "Sucuri", confidence: "high", evidence: "Observed Sucuri edge headers.", matched: Boolean(headerValue(headers, "x-sucuri-id") || headerValue(headers, "x-sucuri-cache")) },
+        { provider: "Azure Front Door", confidence: "high", evidence: "Observed Azure Front Door headers.", matched: Boolean(headerValue(headers, "x-azure-ref") || headerValue(headers, "x-fd-healthprobe")) },
+        { provider: "F5 / BIG-IP", confidence: "medium", evidence: "Observed F5 / BIG-IP headers or cookie markers.", matched: Boolean(headerValue(headers, "x-wa-info") || /bigipserver/i.test(setCookie)) },
+    ];
+    const match = detectors.find((detector) => detector.matched);
+    return match
+        ? { detected: true, provider: match.provider, confidence: match.confidence, evidence: match.evidence }
+        : { detected: false, provider: null, confidence: "low", evidence: "No passive WAF signature headers were observed." };
+};
+export async function analyzeInfrastructure(finalUrl, headers, technologies, resolver = defaultResolver) {
+    const host = finalUrl.hostname;
+    const resolveDns = (operation) => safeResolveWithTimeout(operation, DNS_LOOKUP_TIMEOUT_MS);
+    const [cnameTargetsRaw, ipv4Raw, ipv6Raw] = await Promise.all([
+        resolveDns(() => resolver.resolveCname(host)),
+        resolveDns(() => resolver.resolve4(host)),
+        resolveDns(() => resolver.resolve6(host)),
+    ]);
+    const cnameTargets = cnameTargetsRaw || [];
+    const addresses = unique([...(ipv4Raw || []), ...(ipv6Raw || [])]);
+    const reverseDns = unique((await mapWithConcurrency(addresses.slice(0, 4), 2, async (address) => (await resolveDns(() => resolver.reverse(address))) || [])).flat());
+    const signals = [];
+    addSignals(signals, [host, ...cnameTargets], "dns");
+    addSignals(signals, reverseDns, "reverse_dns");
+    addSignals(signals, [
+        headerValue(headers, "server") || "",
+        headerValue(headers, "via") || "",
+        headerValue(headers, "x-served-by") || "",
+        headerValue(headers, "x-cache") || "",
+        headerValue(headers, "cf-ray") || "",
+        headerValue(headers, "x-amz-cf-id") || "",
+        headerValue(headers, "x-vercel-id") || "",
+        headerValue(headers, "x-nf-request-id") || "",
+        headerValue(headers, "x-render-origin-server") || "",
+        headerValue(headers, "x-railway-edge") || "",
+        headerValue(headers, "platform") || "",
+        headerValue(headers, "panel") || "",
+    ], "headers");
+    addSignals(signals, technologies.map((technology) => `${technology.name} ${technology.evidence}`), "technology");
+    const providers = unique(signals.map((signal) => `${signal.provider}|${signal.category}|${signal.source}`))
+        .map((key) => signals.find((signal) => `${signal.provider}|${signal.category}|${signal.source}` === key))
+        .filter((signal) => Boolean(signal));
+    const providerNames = unique(providers.map((signal) => signal.provider));
+    const protocol = detectProtocol(headers);
+    const waf = detectWaf(headers);
+    const issues = [];
+    const strengths = [];
+    if (protocol.http3Advertised) {
+        strengths.push("HTTP/3 support is advertised via Alt-Svc.");
+    }
+    else {
+        issues.push("No HTTP/3 Alt-Svc advertisement was visible on the main response.");
+    }
+    if (waf.detected && waf.provider) {
+        strengths.push(`Passive WAF or edge-protection headers indicate ${waf.provider}.`);
+    }
+    return {
+        host,
+        addresses,
+        cnameTargets,
+        reverseDns,
+        providers,
+        protocol,
+        waf,
+        issues,
+        strengths: [
+            ...strengths,
+            ...(providerNames.length
+                ? [`Passive DNS, header, or stack evidence identified ${providerNames.join(", ")}.`]
+                : []),
+        ],
+        summary: providerNames.length
+            ? `Passive infrastructure evidence points to ${providerNames.join(", ")}.`
+            : "No obvious cloud, CDN, or hosting provider was inferred from passive evidence.",
+    };
+}

package/dist/libraryRisk.d.ts

@@ -0,0 +1,3 @@
+import type { LibraryFingerprint, LibraryRiskSignal } from "./types.js";
+export declare const collectLibraryFingerprints: (externalScriptUrls: string[]) => LibraryFingerprint[];
+export declare const fetchLibraryRiskSignals: (fingerprints: LibraryFingerprint[]) => Promise<LibraryRiskSignal[]>;

package/dist/libraryRisk.js

@@ -0,0 +1,164 @@
+import { LIBRARY_RISK_LOOKUP_LIMIT, OSV_DETAIL_CONCURRENCY_LIMIT, OSV_DETAIL_LOOKUP_LIMIT, OSV_QUERY_TIMEOUT_MS, } from "./scannerConfig.js";
+import { mapWithConcurrency, unique } from "./utils.js";
+const OSV_QUERYBATCH_URL = "https://api.osv.dev/v1/querybatch";
+const OSV_VULN_URL = "https://api.osv.dev/v1/vulns/";
+const LIBRARY_PATTERNS = [
+    { packageName: "jquery", pattern: /(?:^|[/_-])jquery(?:[-_.](?:slim|ui))?[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned jQuery script URL" },
+    { packageName: "bootstrap", pattern: /(?:^|[/_-])bootstrap(?:\.bundle)?[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned Bootstrap script URL" },
+    { packageName: "react", pattern: /(?:^|[/_-])react[-@/_]?v?(\d+\.\d+\.\d+)(?:\.production\.min|\.development|\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned React script URL" },
+    { packageName: "react-dom", pattern: /(?:^|[/_-])react-dom[-@/_]?v?(\d+\.\d+\.\d+)(?:\.production\.min|\.development|\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned React DOM script URL" },
+    { packageName: "vue", pattern: /(?:^|[/_-])vue(?:\.runtime|\.global|\.esm-browser|\.esm-bundler|\.cjs)?(?:\.prod)?[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned Vue script URL" },
+    { packageName: "angular", pattern: /(?:^|[/_-])angular(?:\.min)?[-@/_]?v?(\d+\.\d+\.\d+)\.js(?:[?#]|$)/i, evidence: "Detected from a versioned AngularJS script URL" },
+    { packageName: "lodash", pattern: /(?:^|[/_-])lodash[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned Lodash script URL" },
+    { packageName: "moment", pattern: /(?:^|[/_-])moment[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned Moment.js script URL" },
+    { packageName: "axios", pattern: /(?:^|[/_-])axios[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned Axios script URL" },
+    { packageName: "chart.js", pattern: /(?:^|[/_-])chart(?:\.umd)?[-@/_]?v?(\d+\.\d+\.\d+)(?:\.min)?\.js(?:[?#]|$)/i, evidence: "Detected from a versioned Chart.js script URL" },
+];
+const riskCache = new Map();
+const abortableJsonFetch = async (url, init) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), OSV_QUERY_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            ...init,
+            signal: controller.signal,
+            headers: {
+                "content-type": "application/json",
+                ...(init?.headers || {}),
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`OSV request failed with status ${response.status}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+const toSeverity = (value) => {
+    const normalized = typeof value === "string" ? value.toLowerCase() : "";
+    if (normalized === "low" || normalized === "moderate" || normalized === "high" || normalized === "critical") {
+        return normalized;
+    }
+    return "unknown";
+};
+const pickReferenceUrl = (references) => {
+    if (!Array.isArray(references)) {
+        return null;
+    }
+    const preferred = references.find((item) => typeof item === "object" && item && "url" in item && typeof item.url === "string");
+    return preferred && typeof preferred === "object" && preferred && "url" in preferred && typeof preferred.url === "string" ? preferred.url : null;
+};
+const toVulnerability = (payload) => ({
+    id: typeof payload.id === "string" ? payload.id : "unknown",
+    summary: typeof payload.summary === "string" && payload.summary.trim() ? payload.summary.trim() : "Known advisory recorded in OSV.",
+    severity: payload.database_specific && typeof payload.database_specific === "object"
+        ? toSeverity(payload.database_specific.severity)
+        : "unknown",
+    aliases: Array.isArray(payload.aliases) ? payload.aliases.filter((item) => typeof item === "string").slice(0, 4) : [],
+    referenceUrl: pickReferenceUrl(payload.references),
+});
+export const collectLibraryFingerprints = (externalScriptUrls) => {
+    const fingerprints = [];
+    const seen = new Set();
+    for (const sourceUrl of externalScriptUrls) {
+        // Skip pathologically long URLs to guard against ReDoS
+        if (sourceUrl.length > 1024)
+            continue;
+        for (const matcher of LIBRARY_PATTERNS) {
+            const match = sourceUrl.match(matcher.pattern);
+            if (!match?.[1]) {
+                continue;
+            }
+            const version = match[1];
+            const key = `${matcher.packageName}@${version}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            fingerprints.push({
+                packageName: matcher.packageName,
+                version,
+                sourceUrl,
+                confidence: "high",
+                evidence: matcher.evidence,
+            });
+            break;
+        }
+    }
+    return fingerprints.slice(0, LIBRARY_RISK_LOOKUP_LIMIT);
+};
+export const fetchLibraryRiskSignals = async (fingerprints) => {
+    const queryableFingerprints = fingerprints.filter((item) => item.confidence === "high").slice(0, LIBRARY_RISK_LOOKUP_LIMIT);
+    if (!queryableFingerprints.length) {
+        return [];
+    }
+    const cacheKey = unique(queryableFingerprints.map((item) => `${item.packageName}@${item.version}`)).sort().join("|");
+    const cached = riskCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const queryResponse = await abortableJsonFetch(OSV_QUERYBATCH_URL, {
+            method: "POST",
+            body: JSON.stringify({
+                queries: queryableFingerprints.map((item) => ({
+                    package: {
+                        ecosystem: "npm",
+                        name: item.packageName,
+                    },
+                    version: item.version,
+                })),
+            }),
+        });
+        const results = Array.isArray(queryResponse.results) ? queryResponse.results : [];
+        const vulnerabilityIds = unique(results.flatMap((result) => result && typeof result === "object" && Array.isArray(result.vulns)
+            ? result.vulns
+                .map((item) => (typeof item.id === "string" ? item.id : null))
+                .filter((item) => Boolean(item))
+            : [])).slice(0, OSV_DETAIL_LOOKUP_LIMIT);
+        const vulnerabilityDetails = await mapWithConcurrency(vulnerabilityIds, OSV_DETAIL_CONCURRENCY_LIMIT, async (id) => {
+            try {
+                const payload = await abortableJsonFetch(`${OSV_VULN_URL}${encodeURIComponent(id)}`);
+                return [id, toVulnerability(payload)];
+            }
+            catch {
+                return [id, null];
+            }
+        });
+        const vulnerabilityMap = new Map(vulnerabilityDetails.filter((entry) => Boolean(entry[1])));
+        const signals = queryableFingerprints.flatMap((fingerprint, index) => {
+            const result = results[index];
+            const ids = result && typeof result === "object" && Array.isArray(result.vulns)
+                ? result.vulns
+                    .map((item) => (typeof item.id === "string" ? item.id : null))
+                    .filter((item) => Boolean(item))
+                : [];
+            const vulnerabilities = ids
+                .map((id) => vulnerabilityMap.get(id))
+                .filter((item) => Boolean(item))
+                .slice(0, 4);
+            if (!vulnerabilities.length) {
+                return [];
+            }
+            return [
+                {
+                    packageName: fingerprint.packageName,
+                    version: fingerprint.version,
+                    confidence: fingerprint.confidence,
+                    sourceUrl: fingerprint.sourceUrl,
+                    evidence: fingerprint.evidence,
+                    vulnerabilities,
+                },
+            ];
+        });
+        if (riskCache.size > 500)
+            riskCache.clear();
+        riskCache.set(cacheKey, signals);
+        return signals;
+    }
+    catch {
+        return [];
+    }
+};

package/dist/network-validation.d.ts

@@ -0,0 +1,30 @@
+export interface ValidatedAddress {
+    address: string;
+    family: number;
+}
+interface PinnedLookupOptions {
+    family?: number | "IPv4" | "IPv6";
+    all?: boolean;
+}
+type PinnedLookupCallback = (err: NodeJS.ErrnoException | null, address: string | ValidatedAddress[], family?: number) => void;
+/** Node's lookup callback used by http/https request `lookup` option. */
+export type PinnedLookup = (hostname: string, options: PinnedLookupOptions | PinnedLookupCallback, callback?: PinnedLookupCallback) => void;
+export declare function isPrivateIpv4(value: string): boolean;
+export declare function isPrivateIpv6(value: string): boolean;
+export declare function isLocalHostname(hostname: string): boolean;
+export declare function isPrivateAddress(value: string): boolean;
+/**
+ * Validate that `targetUrl` is a public destination and return the exact set of
+ * IP addresses it resolved to. Callers MUST connect using {@link createPinnedLookup}
+ * with the returned addresses so the socket cannot be re-pointed at a private IP
+ * between validation and connection (DNS-rebinding / TOCTOU SSRF).
+ */
+export declare function assertPublicRequestTarget(targetUrl: URL): Promise<ValidatedAddress[]>;
+export declare function assertPublicRedirectTarget(targetUrl: URL): Promise<ValidatedAddress[]>;
+/**
+ * Build a `lookup` function for http/https requests that only ever yields the
+ * pre-validated public addresses, closing the gap between validation and the
+ * connection's own DNS resolution.
+ */
+export declare function createPinnedLookup(addresses: ValidatedAddress[]): PinnedLookup;
+export {};

package/dist/network-validation.js

@@ -0,0 +1,161 @@
+import dns from "node:dns/promises";
+import net from "node:net";
+import { DNS_LOOKUP_TIMEOUT_MS } from "./scannerConfig.js";
+import { withTimeout } from "./utils.js";
+function stripBrackets(value) {
+    return value.replace(/^\[(.*)\]$/, "$1");
+}
+export function isPrivateIpv4(value) {
+    const [first, second] = value.split(".").map((part) => Number(part));
+    if ([first, second].some((part) => Number.isNaN(part))) {
+        return false;
+    }
+    return (first === 10 ||
+        first === 127 ||
+        first === 0 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        (first === 198 && (second === 18 || second === 19)));
+}
+// Decode the IPv4 address embedded in IPv4-mapped (::ffff:a.b.c.d / ::ffff:HHHH:HHHH),
+// 6to4 (2002:HHHH:HHHH::) and NAT64 (64:ff9b::a.b.c.d) IPv6 forms.
+function extractEmbeddedIpv4(normalized) {
+    // Dotted-quad already present in the address (e.g. ::ffff:127.0.0.1, 64:ff9b::127.0.0.1).
+    const dotted = normalized.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (dotted) {
+        return dotted[1];
+    }
+    const hexPairToIpv4 = (high, low) => {
+        const h = Number.parseInt(high, 16);
+        const l = Number.parseInt(low, 16);
+        if (Number.isNaN(h) || Number.isNaN(l)) {
+            return null;
+        }
+        return `${(h >> 8) & 0xff}.${h & 0xff}.${(l >> 8) & 0xff}.${l & 0xff}`;
+    };
+    // IPv4-mapped in hextet form: ::ffff:7f00:1
+    const mapped = normalized.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (mapped) {
+        return hexPairToIpv4(mapped[1], mapped[2]);
+    }
+    // 6to4: 2002:HHHH:HHHH::/16 carries the IPv4 gateway in the next 32 bits.
+    const sixToFour = normalized.match(/^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4})/);
+    if (sixToFour) {
+        return hexPairToIpv4(sixToFour[1], sixToFour[2]);
+    }
+    return null;
+}
+export function isPrivateIpv6(value) {
+    const normalized = stripBrackets(value.toLowerCase());
+    if (normalized === "::1" || normalized === "::") {
+        return true;
+    }
+    // Unique local (fc00::/7) and link-local (fe80::/10, i.e. fe80–febf).
+    const firstHextet = Number.parseInt(normalized.split(":")[0] || "", 16);
+    if (!Number.isNaN(firstHextet)) {
+        if ((firstHextet & 0xfe00) === 0xfc00) {
+            return true; // fc00::/7
+        }
+        if ((firstHextet & 0xffc0) === 0xfe80) {
+            return true; // fe80::/10
+        }
+        if (firstHextet === 0xfec0) {
+            return true; // deprecated site-local
+        }
+    }
+    // IPv4-mapped (::ffff:*) is never a routable IPv6 destination; block and, when
+    // possible, also classify the embedded IPv4 so the message is accurate.
+    if (normalized.startsWith("::ffff:")) {
+        return true;
+    }
+    // 6to4 and NAT64 tunnels can smuggle a private IPv4 destination.
+    if (normalized.startsWith("2002:") || normalized.startsWith("64:ff9b:")) {
+        const embedded = extractEmbeddedIpv4(normalized);
+        if (embedded && isPrivateIpv4(embedded)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function isLocalHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return (normalized === "localhost" ||
+        normalized.endsWith(".localhost") ||
+        normalized.endsWith(".local") ||
+        normalized.endsWith(".internal"));
+}
+export function isPrivateAddress(value) {
+    const normalized = stripBrackets(value);
+    const ipVersion = net.isIP(normalized);
+    if (ipVersion === 4) {
+        return isPrivateIpv4(normalized);
+    }
+    if (ipVersion === 6) {
+        return isPrivateIpv6(normalized);
+    }
+    return false;
+}
+async function resolveValidatedAddresses(hostname, blockedMessage, unresolvedMessage) {
+    const literal = stripBrackets(hostname);
+    const literalVersion = net.isIP(literal);
+    if (literalVersion !== 0) {
+        if (isPrivateAddress(literal)) {
+            throw new Error(blockedMessage);
+        }
+        return [{ address: literal, family: literalVersion }];
+    }
+    const lookups = await withTimeout(dns.lookup(hostname, { all: true }), DNS_LOOKUP_TIMEOUT_MS, `DNS lookup for ${hostname} timed out.`);
+    if (!lookups.length || lookups.some((entry) => isPrivateAddress(entry.address))) {
+        throw new Error(unresolvedMessage);
+    }
+    return lookups.map((entry) => ({ address: entry.address, family: entry.family }));
+}
+/**
+ * Validate that `targetUrl` is a public destination and return the exact set of
+ * IP addresses it resolved to. Callers MUST connect using {@link createPinnedLookup}
+ * with the returned addresses so the socket cannot be re-pointed at a private IP
+ * between validation and connection (DNS-rebinding / TOCTOU SSRF).
+ */
+export async function assertPublicRequestTarget(targetUrl) {
+    if (isLocalHostname(targetUrl.hostname) || isPrivateAddress(targetUrl.hostname)) {
+        throw new Error(`Target ${targetUrl.hostname} is not public and was blocked.`);
+    }
+    return resolveValidatedAddresses(targetUrl.hostname, `Target ${targetUrl.hostname} is not public and was blocked.`, `Target ${targetUrl.hostname} did not resolve exclusively to public IP addresses.`);
+}
+export async function assertPublicRedirectTarget(targetUrl) {
+    if (isLocalHostname(targetUrl.hostname) || isPrivateAddress(targetUrl.hostname)) {
+        throw new Error(`Redirect target ${targetUrl.hostname} is not public and was blocked.`);
+    }
+    return resolveValidatedAddresses(targetUrl.hostname, `Redirect target ${targetUrl.hostname} is not public and was blocked.`, `Redirect target ${targetUrl.hostname} did not resolve exclusively to public IP addresses.`);
+}
+/**
+ * Build a `lookup` function for http/https requests that only ever yields the
+ * pre-validated public addresses, closing the gap between validation and the
+ * connection's own DNS resolution.
+ */
+export function createPinnedLookup(addresses) {
+    return function pinnedLookup(_hostname, options, callback) {
+        const cb = (typeof options === "function" ? options : callback);
+        const opts = typeof options === "function" ? {} : options || {};
+        if (!addresses.length) {
+            cb(new Error("No validated address available for pinned lookup."), "", 0);
+            return;
+        }
+        const requestedFamily = opts.family === 4 || opts.family === "IPv4"
+            ? 4
+            : opts.family === 6 || opts.family === "IPv6"
+                ? 6
+                : 0;
+        const matching = requestedFamily
+            ? addresses.filter((entry) => entry.family === requestedFamily)
+            : addresses;
+        const selected = matching.length ? matching : addresses;
+        if (opts.all) {
+            cb(null, selected.map((entry) => ({ address: entry.address, family: entry.family })));
+            return;
+        }
+        cb(null, selected[0].address, selected[0].family);
+    };
+}

package/dist/network.d.ts

@@ -0,0 +1,34 @@
+import http from "node:http";
+import type { RedirectHop } from "./types.js";
+export declare const SCANNER_USER_AGENT = "ExternalPostureInsight/1.0";
+export interface RequestHeadResult {
+    statusCode: number;
+    headers: http.IncomingHttpHeaders;
+    elapsedMs: number;
+}
+export interface RequestTextResult {
+    statusCode: number;
+    headers: http.IncomingHttpHeaders;
+    body: string;
+}
+export interface RequestJsonResult<T = unknown> {
+    statusCode: number;
+    headers: http.IncomingHttpHeaders;
+    body: string;
+    json: T | null;
+}
+export type RequestTextFn = (targetUrl: URL, extraHeaders?: Record<string, string>) => Promise<RequestTextResult>;
+export type RequestJsonFn = (targetUrl: URL, extraHeaders?: Record<string, string>) => Promise<RequestJsonResult>;
+interface RequestOptions {
+    timeoutMs?: number;
+}
+export declare function requestOnce(targetUrl: URL, method?: string, options?: RequestOptions): Promise<RequestHeadResult>;
+export declare function requestWithHeaders(targetUrl: URL, method?: string, extraHeaders?: Record<string, string>, options?: RequestOptions): Promise<RequestHeadResult>;
+export declare function requestText(targetUrl: URL, extraHeaders?: Record<string, string>, options?: RequestOptions): Promise<RequestTextResult>;
+export declare function requestJson(targetUrl: URL, extraHeaders?: Record<string, string>, options?: RequestOptions): Promise<RequestJsonResult>;
+export declare function fetchWithRedirects(initialUrl: URL, redirectLimit?: number, options?: RequestOptions): Promise<{
+    finalUrl: URL;
+    redirects: RedirectHop[];
+    response: RequestHeadResult;
+}>;
+export {};