@peac/net-node 0.12.6

package/dist/index.js

@@ -0,0 +1,1121 @@
+/**
+ * PEAC Net (Node.js) - SSRF-Safe Network Utilities with DNS Pinning
+ *
+ * This module provides a reference implementation of network-layer SSRF protection
+ * with proper DNS resolution pinning using undici's custom dispatcher.
+ *
+ * SECURITY NOTES:
+ * - String-level URL checks alone are NOT sufficient for SSRF protection
+ * - DNS rebinding attacks require connection-time IP pinning
+ * - This implementation resolves DNS, validates ALL candidate IPs, and PINS
+ *   the chosen IP at the connection layer (not just pre-check)
+ *
+ * RUNTIME: Node.js only (requires dns module and undici)
+ *
+ * @since v0.10.x
+ * @module @peac/net-node
+ */
+import { createHash } from 'crypto';
+import * as dns from 'dns/promises';
+import { fetch as undiciFetch } from 'undici';
+// Local SSRF types (not from @peac/schema to keep package self-contained)
+import { validateUrlForSSRF, DEFAULT_SSRF_POLICY } from './ssrf.js';
+// Import finalizeEvidence from internal module (not exported from main entry)
+import { finalizeEvidence } from './internal.js';
+// Import internal helpers from impl.ts (for internal use only - NOT re-exported)
+import { isPrivateIP, resolveDnsSecure, createPinnedAgent, validateAllowCidrsAck, isRedirectAllowed, sanitizeUrl, readBodyWithLimit, attemptWithFallback, stripHopByHopHeaders, canonicalizeHost, emitAuditEvent, createRequestAuditContext, redactIp, getAuditQueueStats, withTimeout, } from './impl.js';
+// Import from single source of truth modules
+import { SAFE_FETCH_ERROR_CODES } from './codes.js';
+import { SAFE_FETCH_EVENT_SCHEMA_VERSION, SAFE_FETCH_EVIDENCE_SCHEMA_VERSION, MAX_PENDING_AUDIT_EVENTS, } from './constants.js';
+// Re-export public API items
+export { getAuditQueueStats };
+// Re-export error codes and constants
+export { SAFE_FETCH_ERROR_CODES };
+export { SAFE_FETCH_EVENT_SCHEMA_VERSION, SAFE_FETCH_EVIDENCE_SCHEMA_VERSION, MAX_PENDING_AUDIT_EVENTS, };
+/**
+ * Acknowledgment string for allowing mixed public/private DNS resolution
+ */
+export const ALLOW_MIXED_DNS_ACK = 'I_UNDERSTAND_MIXED_DNS_SECURITY_RISKS';
+// -----------------------------------------------------------------------------
+// P1.1: Vendor-neutral Audit Hook (Protocol-Grade)
+// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// P1.2: JCS Canonicalization + SHA-256 Digest
+// -----------------------------------------------------------------------------
+/**
+ * Check if a value is a plain object (prototype is Object.prototype or null)
+ *
+ * This excludes Date, RegExp, Map, Set, and other non-JSON-serializable objects.
+ * @internal
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Canonicalize a JSON value per RFC 8785 (JSON Canonicalization Scheme)
+ *
+ * This ensures deterministic serialization for cross-implementation parity:
+ * - Object keys sorted lexicographically (Unicode code points)
+ * - No whitespace between tokens
+ * - Numbers serialized per ES2015
+ * - Strings with minimal escaping
+ *
+ * @param value - Any JSON-serializable value
+ * @returns Canonical JSON string
+ * @internal
+ */
+function jcsCanonicalizeValue(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        // Handle special cases per ES2015 spec
+        if (Object.is(value, -0))
+            return '0';
+        if (!Number.isFinite(value)) {
+            throw new Error('JCS does not support Infinity or NaN');
+        }
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        // Use JSON.stringify for proper escaping
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        const elements = value.map(jcsCanonicalizeValue);
+        return '[' + elements.join(',') + ']';
+    }
+    if (isPlainObject(value)) {
+        // Sort keys lexicographically (Unicode code point order)
+        const keys = Object.keys(value).sort();
+        const pairs = keys
+            .filter((k) => value[k] !== undefined)
+            .map((k) => JSON.stringify(k) + ':' + jcsCanonicalizeValue(value[k]));
+        return '{' + pairs.join(',') + '}';
+    }
+    throw new Error(`Cannot canonicalize value of type ${typeof value}`);
+}
+/**
+ * Canonicalize evidence per RFC 8785 (JCS)
+ *
+ * Returns the canonical JSON string representation of the evidence object.
+ * This is deterministic across implementations and can be used for:
+ * - Computing digests for signing
+ * - Cross-implementation verification
+ * - Deduplication
+ *
+ * IMPORTANT: For digest computation, pass evidence WITHOUT digest fields
+ * to avoid self-referential circularity.
+ *
+ * @param evidence - SafeFetchEvidence or SafeFetchEvidenceCore object
+ * @returns Canonical JSON string
+ */
+export function canonicalizeEvidence(evidence) {
+    return jcsCanonicalizeValue(evidence);
+}
+/**
+ * Compute SHA-256 digest of evidence using JCS canonicalization
+ *
+ * Returns a 0x-prefixed lowercase hex string, consistent with other
+ * PEAC cryptographic identifiers (EAS anchors, IP hashes).
+ *
+ * Self-omission rule: If the evidence includes digest fields, they are
+ * stripped before computing the digest to avoid circularity.
+ *
+ * @param evidence - SafeFetchEvidence or SafeFetchEvidenceCore object
+ * @returns 0x-prefixed SHA-256 hex digest
+ */
+export function computeEvidenceDigest(evidence) {
+    // Strip digest fields if present (self-omission rule)
+    const { evidence_digest, evidence_alg, canonicalization, ...core } = evidence;
+    const canonical = canonicalizeEvidence(core);
+    const hash = createHash('sha256').update(canonical, 'utf8').digest('hex');
+    return `0x${hash}`;
+}
+/**
+ * Default timeout values
+ */
+export const DEFAULT_TIMEOUTS = {
+    totalMs: 30000,
+    dnsMs: 5000,
+    connectMs: 10000,
+    headersMs: 15000,
+    bodyMs: 30000,
+};
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+/**
+ * Default timeout for fetch requests (30 seconds)
+ */
+export const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Default maximum redirects
+ */
+export const DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * Default allowed HTTP methods (GET/HEAD only for SSRF safety)
+ */
+export const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD'];
+/**
+ * Default maximum response size (2 MB)
+ *
+ * COMPRESSION SEMANTICS (P0.4 - Protocol-Grade Evidence):
+ *
+ * This limit measures DECODED bytes (after decompression), NOT wire bytes.
+ * The limit applies to what `response.body.getReader().read()` returns.
+ *
+ * By default, we request `Accept-Encoding: identity` to prevent compression.
+ * This means:
+ * - Wire bytes === Decoded bytes (no compression)
+ * - Content-Length matches actual body size
+ * - No decompression bomb risk
+ *
+ * If `allowCompression: true`, compression is allowed, and:
+ * - Wire bytes may be smaller than decoded bytes
+ * - Content-Length reflects compressed size (if set)
+ * - We measure DECODED bytes (after browser/runtime decompresses)
+ * - Decompression bombs are possible (1KB compressed -> 1GB decoded)
+ *
+ * WARNING: Only use `allowCompression: true` if you trust the server AND have
+ * additional decoded size limits in place.
+ *
+ * For evidence purposes, `response_bytes` in SafeFetchEvidence reflects
+ * decoded bytes (what we actually read), not wire bytes.
+ */
+export const DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+/**
+ * Whether maxResponseBytes measures wire or decoded bytes.
+ * Always 'decoded' - we measure after potential decompression.
+ */
+export const RESPONSE_BYTES_MEASUREMENT = 'decoded';
+/**
+ * Maximum response size for JWKS/OIDC endpoints (512 KB)
+ */
+export const MAX_JWKS_RESPONSE_BYTES = 512 * 1024;
+/**
+ * Dangerous ports that are ALWAYS blocked regardless of configuration.
+ *
+ * These ports commonly host:
+ * - SSH (22), SMTP (25), DNS (53), FTP (21)
+ * - Database services (3306 MySQL, 5432 PostgreSQL, 6379 Redis, 27017 MongoDB)
+ * - Kubernetes (6443, 10250), Envoy (15000), Prometheus (9090)
+ * - Internal admin panels, debug ports
+ *
+ * Blocking these prevents SSRF to internal services even on attacker-controlled hosts.
+ * To allow these ports, you MUST provide explicit acknowledgment.
+ */
+export const DANGEROUS_PORTS = new Set([
+    // Remote access
+    21, // FTP control
+    22, // SSH
+    23, // Telnet
+    25, // SMTP
+    53, // DNS
+    110, // POP3
+    143, // IMAP
+    445, // SMB
+    513, // rlogin
+    514, // rsh/syslog
+    587, // SMTP submission
+    // Databases
+    1433, // MSSQL
+    1521, // Oracle
+    3306, // MySQL
+    5432, // PostgreSQL
+    5984, // CouchDB
+    6379, // Redis
+    9042, // Cassandra
+    27017, // MongoDB
+    // Container/orchestration
+    2375, // Docker daemon (unencrypted)
+    2376, // Docker daemon (TLS)
+    2379, // etcd client
+    2380, // etcd peer
+    6443, // Kubernetes API
+    10250, // Kubelet
+    10255, // Kubelet read-only
+    // Service mesh/proxy
+    9090, // Prometheus
+    15000, // Envoy admin
+    15001, // Istio proxy
+    15004, // Istio debug
+]);
+/**
+ * Acknowledgment string for allowing dangerous ports
+ */
+export const ALLOW_DANGEROUS_PORTS_ACK = 'I_UNDERSTAND_DANGEROUS_PORTS_RISK';
+// Internal constants are now imported from impl.ts
+// Internal helper functions are now imported from impl.ts
+// -----------------------------------------------------------------------------
+// Default Implementations
+// -----------------------------------------------------------------------------
+/**
+ * Default DNS resolver using Node.js dns.promises module
+ * Resolves both A (IPv4) and AAAA (IPv6) records separately for Happy Eyeballs
+ */
+export const defaultDnsResolver = {
+    async resolveAll(hostname) {
+        const ipv4 = [];
+        const ipv6 = [];
+        // Try to get all A records (IPv4)
+        try {
+            const ipv4Addresses = await dns.resolve4(hostname);
+            ipv4.push(...ipv4Addresses);
+        }
+        catch {
+            // IPv4 resolution failed, continue with IPv6
+        }
+        // Try to get all AAAA records (IPv6)
+        try {
+            const ipv6Addresses = await dns.resolve6(hostname);
+            ipv6.push(...ipv6Addresses);
+        }
+        catch {
+            // IPv6 resolution failed
+        }
+        // If both failed, fall back to dns.lookup for /etc/hosts entries
+        if (ipv4.length === 0 && ipv6.length === 0) {
+            const result = await dns.lookup(hostname, { all: true });
+            if (Array.isArray(result)) {
+                for (const r of result) {
+                    if (r.family === 4) {
+                        ipv4.push(r.address);
+                    }
+                    else if (r.family === 6) {
+                        ipv6.push(r.address);
+                    }
+                }
+            }
+        }
+        return { ipv4, ipv6 };
+    },
+};
+/**
+ * Default HTTP client using undici with DNS pinning
+ * Returns close function for proper agent lifecycle management
+ * P1.3: Supports phase-specific timeouts via undici options
+ */
+export const defaultHttpClient = {
+    async fetch(url, pinnedIp, options) {
+        const parsedUrl = new URL(url);
+        // P1.3: Extract phase-specific timeouts
+        const timeouts = options?.timeouts;
+        const totalMs = timeouts?.totalMs ?? options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const connectMs = timeouts?.connectMs ?? DEFAULT_TIMEOUTS.connectMs;
+        const headersMs = timeouts?.headersMs ?? DEFAULT_TIMEOUTS.headersMs;
+        const bodyMs = timeouts?.bodyMs ?? DEFAULT_TIMEOUTS.bodyMs;
+        // Create abort controller for total timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), totalMs);
+        let agent = null;
+        try {
+            if (pinnedIp) {
+                // Use pinned agent for DNS rebinding protection
+                // P1.3: Pass connect timeout to agent
+                agent = createPinnedAgent(pinnedIp, parsedUrl.hostname, {
+                    connectTimeoutMs: connectMs,
+                });
+                // P1.3: Pass phase-specific timeouts to undici
+                const response = await undiciFetch(url, {
+                    ...options,
+                    signal: controller.signal,
+                    dispatcher: agent,
+                    redirect: 'manual', // Handle redirects manually
+                    // undici-specific timeout options
+                    headersTimeout: headersMs,
+                    bodyTimeout: bodyMs,
+                });
+                clearTimeout(timeoutId);
+                // Return response and close function
+                // IMPORTANT: Agent must be closed AFTER body is consumed
+                return {
+                    response: response,
+                    close: async () => {
+                        if (agent) {
+                            await agent.close();
+                        }
+                    },
+                };
+            }
+            else {
+                // No pinning needed (IP literal already validated)
+                // P1.3: Pass phase-specific timeouts to undici
+                const response = await undiciFetch(url, {
+                    ...options,
+                    signal: controller.signal,
+                    redirect: 'manual',
+                    headersTimeout: headersMs,
+                    bodyTimeout: bodyMs,
+                });
+                clearTimeout(timeoutId);
+                return {
+                    response: response,
+                    close: async () => {
+                        // No agent to close
+                    },
+                };
+            }
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            // Clean up agent on error
+            if (agent) {
+                await agent.close();
+            }
+            throw err;
+        }
+    },
+};
+// -----------------------------------------------------------------------------
+// Main API
+// -----------------------------------------------------------------------------
+/**
+ * SSRF-safe raw fetch with proper DNS resolution pinning
+ * Returns response stream with close function for proper lifecycle management
+ *
+ * Use this when you need to process the response stream directly.
+ * IMPORTANT: You MUST call the close() function after consuming the response.
+ *
+ * Security features:
+ * - DNS resolution pinning (prevents rebinding attacks)
+ * - Private IP blocking (RFC 6890 compliant)
+ * - Host header enforcement (prevents SSRF via Host manipulation)
+ * - Hop-by-hop header stripping (RFC 7230)
+ * - Response size enforcement
+ * - Redirect chain validation
+ *
+ * Returns an evidence object for PEAC-ready receipts and audit trails.
+ */
+export async function safeFetchRaw(url, options) {
+    // Create request-scoped audit context for per-request counters
+    const auditCtx = createRequestAuditContext();
+    const requestTimestamp = Date.now();
+    const internalOptions = {
+        ...options,
+        _redirectCount: options?._redirectCount ?? 0,
+        _originalHost: options?._originalHost,
+        _originalOrigin: options?._originalOrigin,
+    };
+    // P1.3: Extract phase-specific timeouts from TimeoutConfig
+    // If timeouts option is provided, it overrides the legacy timeoutMs option
+    const phaseTimeouts = options?.timeouts ?? {
+        totalMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        dnsMs: DEFAULT_TIMEOUTS.dnsMs,
+        connectMs: DEFAULT_TIMEOUTS.connectMs,
+        headersMs: DEFAULT_TIMEOUTS.headersMs,
+        bodyMs: DEFAULT_TIMEOUTS.bodyMs,
+    };
+    const totalTimeoutMs = phaseTimeouts.totalMs ?? DEFAULT_TIMEOUT_MS;
+    const dnsTimeoutMs = phaseTimeouts.dnsMs ?? DEFAULT_TIMEOUTS.dnsMs;
+    // connectMs, headersMs, bodyMs are passed to httpClient
+    const maxRedirects = options?.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const maxResponseBytes = options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const ssrfPolicy = options?.ssrfPolicy ?? DEFAULT_SSRF_POLICY;
+    const allowedMethods = options?.allowedMethods ?? DEFAULT_ALLOWED_METHODS;
+    const debug = options?.debug ?? false;
+    // P0.3: Evidence level (default 'public' for defense-in-depth)
+    const evidenceLevel = options?.evidenceLevel ?? 'public';
+    const isPrivateEvidence = evidenceLevel === 'private';
+    const warnings = [];
+    const droppedHeaders = [];
+    // Validate tenant mode configuration (fail-fast)
+    if (evidenceLevel === 'tenant') {
+        if (!options?.redactionKey || options.redactionKey.length < 32) {
+            // Build minimal error evidence before we have hostname info
+            const errorCore = {
+                schema_version: SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+                evidence_level: 'public', // Fallback to public for error evidence
+                request_timestamp: requestTimestamp,
+                request_url: sanitizeUrl(url),
+                canonical_host: '[unknown]',
+                is_ip_literal: false,
+                policy_decision: 'block',
+                decision_code: SAFE_FETCH_ERROR_CODES.E_TENANT_KEY_MISSING,
+                max_response_bytes: options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
+            };
+            return {
+                ok: false,
+                error: 'Tenant mode requires redactionKey (>= 32 bytes)',
+                code: SAFE_FETCH_ERROR_CODES.E_TENANT_KEY_MISSING,
+                evidence: finalizeEvidence(errorCore, auditCtx),
+            };
+        }
+        if (!options?.redactionKeyId) {
+            const errorCore = {
+                schema_version: SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+                evidence_level: 'public',
+                request_timestamp: requestTimestamp,
+                request_url: sanitizeUrl(url),
+                canonical_host: '[unknown]',
+                is_ip_literal: false,
+                policy_decision: 'block',
+                decision_code: SAFE_FETCH_ERROR_CODES.E_TENANT_KEY_MISSING,
+                max_response_bytes: options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
+            };
+            return {
+                ok: false,
+                error: 'Tenant mode requires redactionKeyId for key rotation audit',
+                code: SAFE_FETCH_ERROR_CODES.E_TENANT_KEY_MISSING,
+                evidence: finalizeEvidence(errorCore, auditCtx),
+            };
+        }
+    }
+    // Sanitize URL for logging (remove credentials)
+    const sanitizedUrl = sanitizeUrl(url);
+    // Handle deprecated allowCrossHostRedirects
+    let redirectPolicy = options?.redirectPolicy ?? 'same-origin';
+    if (options?.allowCrossHostRedirects && !options?.redirectPolicy) {
+        redirectPolicy = 'same-registrable-domain';
+        warnings.push('allowCrossHostRedirects is deprecated, use redirectPolicy instead');
+    }
+    // Use injected dependencies or defaults
+    const dnsResolver = options?._dnsResolver ?? defaultDnsResolver;
+    const httpClient = options?._httpClient ?? defaultHttpClient;
+    // Helper to build error evidence (partial, before hostname resolution)
+    // P0.3: Respects evidenceLevel for redaction
+    const buildErrorEvidence = (code, canonicalHost = '[unknown]', isIpLiteral = false, dnsAnswers, selectedIp) => {
+        // Build redaction options for tenant mode
+        const redactOpts = evidenceLevel === 'tenant' && options?.redactionKey
+            ? { key: options.redactionKey, keyId: options?.redactionKeyId }
+            : undefined;
+        // Build base evidence (without digest - will be added by finalizeEvidence)
+        const core = {
+            schema_version: SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+            evidence_level: evidenceLevel,
+            request_timestamp: requestTimestamp,
+            request_url: sanitizedUrl,
+            canonical_host: canonicalHost,
+            is_ip_literal: isIpLiteral,
+            policy_decision: 'block',
+            decision_code: code,
+            max_response_bytes: maxResponseBytes,
+            dropped_headers: droppedHeaders.length > 0 ? droppedHeaders : undefined,
+        };
+        // Add IP-related fields based on evidence level
+        if (selectedIp) {
+            if (isPrivateEvidence) {
+                core.selected_ip = selectedIp;
+            }
+            else {
+                core.selected_ip_info = redactIp(selectedIp, redactOpts);
+            }
+        }
+        // Add DNS answers based on evidence level
+        if (dnsAnswers && dnsAnswers.length > 0) {
+            if (isPrivateEvidence) {
+                core.dns_answers = dnsAnswers;
+            }
+            else {
+                // Public/tenant: only include counts
+                const ipv4Count = dnsAnswers.filter((a) => a.family === 4).length;
+                const ipv6Count = dnsAnswers.filter((a) => a.family === 6).length;
+                core.dns_answer_count = { ipv4: ipv4Count, ipv6: ipv6Count };
+            }
+        }
+        // Finalize with digest (pass auditCtx for request-scoped counters)
+        return finalizeEvidence(core, auditCtx);
+    };
+    // Step 0: Validate HTTP method (SSRF side-effect prevention)
+    const method = (options?.method ?? 'GET').toUpperCase();
+    if (!allowedMethods.map((m) => m.toUpperCase()).includes(method)) {
+        return {
+            ok: false,
+            error: `HTTP method '${method}' not allowed`,
+            code: SAFE_FETCH_ERROR_CODES.E_METHOD_NOT_ALLOWED,
+            evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_METHOD_NOT_ALLOWED),
+        };
+    }
+    // Step 1: Validate allowCidrs acknowledgment at DNS-time
+    const ackValidation = validateAllowCidrsAck(ssrfPolicy);
+    if (!ackValidation.valid) {
+        return {
+            ok: false,
+            error: 'SSRF policy configuration error',
+            code: SAFE_FETCH_ERROR_CODES.E_SSRF_ALLOWCIDRS_ACK_REQUIRED,
+            evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_ALLOWCIDRS_ACK_REQUIRED),
+        };
+    }
+    // Validate allowMixedPublicAndPrivateDns acknowledgment
+    const allowMixedDns = options?.allowMixedPublicAndPrivateDns ?? false;
+    if (allowMixedDns && options?.ack_allow_mixed_dns !== ALLOW_MIXED_DNS_ACK) {
+        return {
+            ok: false,
+            error: 'Mixed DNS requires explicit acknowledgment',
+            code: SAFE_FETCH_ERROR_CODES.E_SSRF_MIXED_DNS_ACK_MISSING,
+            evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_MIXED_DNS_ACK_MISSING),
+        };
+    }
+    // Step 2: String-level URL validation
+    const urlCheck = validateUrlForSSRF(url, ssrfPolicy);
+    if (!urlCheck.ok) {
+        return {
+            ok: false,
+            error: 'URL rejected by SSRF policy',
+            code: SAFE_FETCH_ERROR_CODES.E_SSRF_URL_REJECTED,
+            cause_code: urlCheck.code,
+            evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_URL_REJECTED),
+        };
+    }
+    const parsedUrl = urlCheck.value;
+    const rawHostname = parsedUrl.hostname;
+    // Step 2.1: Dangerous port validation
+    // Get port number (default 443 for https, 80 for http)
+    const portStr = parsedUrl.port;
+    const effectivePort = portStr
+        ? parseInt(portStr, 10)
+        : parsedUrl.protocol === 'https:'
+            ? 443
+            : 80;
+    // Check if port is in dangerous ports list
+    if (DANGEROUS_PORTS.has(effectivePort)) {
+        const allowDangerous = options?.allowDangerousPorts ?? false;
+        if (allowDangerous && options?.ack_allow_dangerous_ports !== ALLOW_DANGEROUS_PORTS_ACK) {
+            return {
+                ok: false,
+                error: 'Dangerous port requires explicit acknowledgment',
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_DANGEROUS_PORT_ACK_MISSING,
+                evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_DANGEROUS_PORT_ACK_MISSING),
+            };
+        }
+        if (!allowDangerous) {
+            return {
+                ok: false,
+                error: 'Port blocked by security policy',
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_DANGEROUS_PORT,
+                evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_DANGEROUS_PORT),
+            };
+        }
+        // User explicitly acknowledged - allow through
+        warnings.push(`Dangerous port ${effectivePort} allowed via explicit acknowledgment`);
+    }
+    // Step 2.5: Canonical host validation (zone IDs, IDN, IPv4-mapped IPv6)
+    const hostResult = canonicalizeHost(rawHostname);
+    if (!hostResult.ok) {
+        return {
+            ...hostResult,
+            evidence: buildErrorEvidence(hostResult.code),
+        };
+    }
+    const hostname = hostResult.hostname;
+    // Track original host/origin for redirect validation
+    if (!internalOptions._originalHost) {
+        internalOptions._originalHost = hostname;
+        internalOptions._originalOrigin = parsedUrl.origin;
+    }
+    // Get the audit hook for event emission and optional sanitizer
+    const onEvent = options?.onEvent;
+    const hookSanitizer = options?.sanitizeHookError;
+    // Track DNS answers for evidence
+    let dnsAnswers;
+    // Step 3: DNS resolution with validation and pinning
+    let pinnedIp = null;
+    let dnsResult = null;
+    if (hostResult.isIP) {
+        // URL contains IP literal (may have been normalized from IPv4-mapped IPv6)
+        // No DNS resolution needed, but we still validate the IP
+        const isBlocked = isPrivateIP(hostname, ssrfPolicy);
+        dnsAnswers = [
+            {
+                ip: hostname,
+                family: hostname.includes(':') ? 6 : 4,
+                blocked_reason: isBlocked ? 'private_ip' : undefined,
+            },
+        ];
+        if (isBlocked) {
+            emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+                type: 'dns_blocked',
+                timestamp: Date.now(),
+                url: sanitizedUrl,
+                hostname,
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_DNS_RESOLVED_PRIVATE,
+                message: 'IP literal blocked by policy',
+                policy_decision: 'block',
+                meta: debug ? { dns_answers: dnsAnswers } : undefined,
+            });
+            return {
+                ok: false,
+                error: 'IP literal blocked by policy',
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_DNS_RESOLVED_PRIVATE,
+                evidence: buildErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_DNS_RESOLVED_PRIVATE, hostname, true, dnsAnswers),
+            };
+        }
+        pinnedIp = null; // No pinning needed for IP literals
+    }
+    else {
+        // Emit DNS start event
+        emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+            type: 'dns_start',
+            timestamp: Date.now(),
+            url: sanitizedUrl,
+            hostname,
+        });
+        // DNS resolution with validation and P1.3 phase timeout
+        const dnsPromise = resolveDnsSecure(hostname, ssrfPolicy, dnsResolver, {
+            policy: ssrfPolicy,
+            allowMixedPublicAndPrivate: allowMixedDns,
+        });
+        const dnsWithTimeout = await withTimeout(dnsPromise, dnsTimeoutMs, SAFE_FETCH_ERROR_CODES.E_DNS_TIMEOUT);
+        // Handle DNS timeout
+        if (!dnsWithTimeout.ok) {
+            emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+                type: 'dns_error',
+                timestamp: Date.now(),
+                url: sanitizedUrl,
+                hostname,
+                code: dnsWithTimeout.code,
+                message: 'DNS resolution timed out',
+                policy_decision: 'block',
+            });
+            return {
+                ok: false,
+                error: 'DNS resolution timed out',
+                code: dnsWithTimeout.code,
+                evidence: buildErrorEvidence(dnsWithTimeout.code, hostname, false),
+            };
+        }
+        const result = dnsWithTimeout.value;
+        if (!result.ok) {
+            dnsAnswers = result.dns_answers;
+            const eventType = result.code === SAFE_FETCH_ERROR_CODES.E_DNS_RESOLUTION_FAILED
+                ? 'dns_error'
+                : 'dns_blocked';
+            emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+                type: eventType,
+                timestamp: Date.now(),
+                url: sanitizedUrl,
+                hostname,
+                code: result.code,
+                message: result.error,
+                policy_decision: 'block',
+                meta: debug ? { dns_answers: dnsAnswers } : undefined,
+            });
+            return {
+                ...result,
+                evidence: buildErrorEvidence(result.code, hostname, false, dnsAnswers),
+            };
+        }
+        dnsResult = result;
+        pinnedIp = result.selectedAddress;
+        // Build dns_answers for successful resolution (all allowed)
+        dnsAnswers = [
+            ...result.ipv4Addresses.map((ip) => ({ ip, family: 4 })),
+            ...result.ipv6Addresses.map((ip) => ({ ip, family: 6 })),
+        ];
+        // Emit DNS success event
+        emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+            type: 'dns_success',
+            timestamp: Date.now(),
+            url: sanitizedUrl,
+            hostname,
+            selected_ip: pinnedIp,
+            policy_decision: 'allow',
+            meta: debug
+                ? {
+                    dns_answers: dnsAnswers,
+                    ipv4_count: result.ipv4Addresses.length,
+                    ipv6_count: result.ipv6Addresses.length,
+                }
+                : {
+                    ipv4_count: result.ipv4Addresses.length,
+                    ipv6_count: result.ipv6Addresses.length,
+                },
+        });
+    }
+    // Step 4: Build request options with security defaults
+    const allowCompression = options?.allowCompression ?? false;
+    const fetchHeaders = new Headers(options?.headers);
+    // P0.3: Strip hop-by-hop headers (RFC 7230 Section 6.1)
+    // This prevents proxy confusion and request smuggling attacks
+    stripHopByHopHeaders(fetchHeaders);
+    // SECURITY: Drop user-provided Host header to prevent SSRF via Host manipulation
+    // The Host header must match the URL, not be controlled by the caller.
+    // This prevents attacks where attacker controls Host to redirect internal requests.
+    if (fetchHeaders.has('host')) {
+        droppedHeaders.push('host');
+        fetchHeaders.delete('host');
+    }
+    // P0.5: Prevent decompression bombs by requesting identity encoding by default
+    // Only applies if Accept-Encoding is not already set and compression is not explicitly allowed
+    //
+    // SECURITY NOTE: Headers.has() is case-insensitive per Fetch API spec.
+    // The Headers object normalizes all header names to lowercase internally.
+    // We check for 'accept-encoding' (lowercase) to be explicit about this behavior.
+    // This prevents bypass via 'Accept-Encoding', 'ACCEPT-ENCODING', or mixed case.
+    //
+    // NOTE: maxResponseBytes measures WIRE bytes (after identity encoding).
+    // If compression is enabled, the actual decoded size could exceed the budget.
+    // Only enable compression if you trust the server AND have additional decoded size limits.
+    if (!allowCompression && !fetchHeaders.has('accept-encoding')) {
+        fetchHeaders.set('Accept-Encoding', 'identity');
+    }
+    const fetchOptions = {
+        ...options,
+        headers: fetchHeaders,
+        timeoutMs: totalTimeoutMs,
+    };
+    // Step 5: Make the request with DNS pinning
+    // Emit request start event with dropped headers info
+    emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+        type: 'request_start',
+        timestamp: Date.now(),
+        url: sanitizedUrl,
+        hostname,
+        selected_ip: pinnedIp ?? hostname,
+        meta: {
+            method,
+            dropped_headers: droppedHeaders.length > 0 ? droppedHeaders : undefined,
+        },
+    });
+    let fetchResult;
+    try {
+        if (dnsResult) {
+            // Use Happy Eyeballs for dual-stack hosts
+            fetchResult = await attemptWithFallback(url, dnsResult, httpClient, fetchOptions);
+        }
+        else {
+            // IP literal - direct fetch
+            fetchResult = await httpClient.fetch(url, pinnedIp, fetchOptions);
+        }
+    }
+    catch (err) {
+        const isTimeout = err instanceof Error && err.name === 'AbortError';
+        const code = isTimeout
+            ? SAFE_FETCH_ERROR_CODES.E_REQUEST_TIMEOUT
+            : SAFE_FETCH_ERROR_CODES.E_NETWORK_ERROR;
+        emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+            type: 'error',
+            timestamp: Date.now(),
+            url: sanitizedUrl,
+            hostname,
+            selected_ip: pinnedIp ?? undefined,
+            code,
+            // Generic error messages - no internal details
+            message: isTimeout ? 'Request timed out' : 'Network error',
+        });
+        const elapsedMs = Date.now() - requestTimestamp;
+        // Build redaction options for tenant mode
+        const redactOpts = evidenceLevel === 'tenant' && options?.redactionKey
+            ? { key: options.redactionKey, keyId: options?.redactionKeyId }
+            : undefined;
+        // P0.3: Build network error evidence with proper redaction
+        const errorCore = {
+            schema_version: SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+            evidence_level: evidenceLevel,
+            request_timestamp: requestTimestamp,
+            request_url: sanitizedUrl,
+            canonical_host: hostname,
+            is_ip_literal: hostResult.isIP,
+            // Public/tenant evidence: include redacted IP info
+            ...(pinnedIp && !isPrivateEvidence
+                ? { selected_ip_info: redactIp(pinnedIp, redactOpts) }
+                : {}),
+            // Private evidence: include raw details
+            ...(isPrivateEvidence ? { dns_answers: dnsAnswers } : {}),
+            ...(isPrivateEvidence && pinnedIp ? { selected_ip: pinnedIp } : {}),
+            // Public/tenant evidence: include DNS answer counts
+            ...(!isPrivateEvidence && dnsAnswers.length > 0
+                ? {
+                    dns_answer_count: {
+                        ipv4: dnsAnswers.filter((a) => a.family === 4).length,
+                        ipv6: dnsAnswers.filter((a) => a.family === 6).length,
+                    },
+                }
+                : {}),
+            policy_decision: 'block',
+            decision_code: code,
+            max_response_bytes: maxResponseBytes,
+            elapsed_ms: elapsedMs,
+            dropped_headers: droppedHeaders.length > 0 ? droppedHeaders : undefined,
+        };
+        const errorEvidence = finalizeEvidence(errorCore, auditCtx);
+        if (isTimeout) {
+            return {
+                ok: false,
+                error: 'Request timed out',
+                code: SAFE_FETCH_ERROR_CODES.E_REQUEST_TIMEOUT,
+                evidence: errorEvidence,
+            };
+        }
+        return {
+            ok: false,
+            error: 'Network error',
+            code: SAFE_FETCH_ERROR_CODES.E_NETWORK_ERROR,
+            evidence: errorEvidence,
+        };
+    }
+    const { response, close } = fetchResult;
+    const responseTimestamp = Date.now();
+    // Emit response headers event
+    emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+        type: 'response_headers',
+        timestamp: responseTimestamp,
+        url: sanitizedUrl,
+        hostname,
+        selected_ip: pinnedIp ?? undefined,
+        meta: {
+            status: response.status,
+            statusText: response.statusText,
+        },
+    });
+    // Helper to build redirect error evidence
+    // P0.3: Respects evidenceLevel for redaction
+    const buildRedirectErrorEvidence = (code) => {
+        // Build redaction options for tenant mode
+        const redactOpts = evidenceLevel === 'tenant' && options?.redactionKey
+            ? { key: options.redactionKey, keyId: options?.redactionKeyId }
+            : undefined;
+        const core = {
+            schema_version: SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+            evidence_level: evidenceLevel,
+            request_timestamp: requestTimestamp,
+            response_timestamp: responseTimestamp,
+            request_url: sanitizedUrl,
+            canonical_host: hostname,
+            is_ip_literal: hostResult.isIP,
+            policy_decision: 'block',
+            decision_code: code,
+            response_status: response.status,
+            max_response_bytes: maxResponseBytes,
+            elapsed_ms: responseTimestamp - requestTimestamp,
+            dropped_headers: droppedHeaders.length > 0 ? droppedHeaders : undefined,
+        };
+        // Add IP-related fields based on evidence level
+        if (pinnedIp) {
+            if (isPrivateEvidence) {
+                core.selected_ip = pinnedIp;
+            }
+            else {
+                core.selected_ip_info = redactIp(pinnedIp, redactOpts);
+            }
+        }
+        // Add DNS answers based on evidence level
+        if (dnsAnswers && dnsAnswers.length > 0) {
+            if (isPrivateEvidence) {
+                core.dns_answers = dnsAnswers;
+            }
+            else {
+                core.dns_answer_count = {
+                    ipv4: dnsAnswers.filter((a) => a.family === 4).length,
+                    ipv6: dnsAnswers.filter((a) => a.family === 6).length,
+                };
+            }
+        }
+        return finalizeEvidence(core, auditCtx);
+    };
+    // Step 6: Handle redirects
+    if (response.status >= 300 && response.status < 400) {
+        // Close current response before following redirect
+        await close();
+        const location = response.headers.get('location');
+        if (!location) {
+            return {
+                ok: false,
+                error: 'Redirect response missing Location header',
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_REDIRECT_BLOCKED,
+                evidence: buildRedirectErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_REDIRECT_BLOCKED),
+            };
+        }
+        // Check redirect count
+        if (internalOptions._redirectCount >= maxRedirects) {
+            return {
+                ok: false,
+                error: 'Too many redirects',
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_TOO_MANY_REDIRECTS,
+                evidence: buildRedirectErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_TOO_MANY_REDIRECTS),
+            };
+        }
+        // Resolve redirect URL
+        const redirectUrl = new URL(location, url);
+        const originalUrl = new URL(internalOptions._originalOrigin);
+        // Emit redirect event
+        emitAuditEvent(auditCtx, onEvent, hookSanitizer, 'onEvent', {
+            type: 'redirect',
+            timestamp: Date.now(),
+            url: sanitizedUrl,
+            hostname,
+            selected_ip: pinnedIp ?? undefined,
+            meta: {
+                redirect_to: sanitizeUrl(redirectUrl.toString()),
+                redirect_count: internalOptions._redirectCount + 1,
+            },
+        });
+        // Check redirect policy
+        if (!isRedirectAllowed(originalUrl, redirectUrl, redirectPolicy, options?.redirectAllowHosts)) {
+            return {
+                ok: false,
+                error: 'Redirect blocked by policy',
+                code: SAFE_FETCH_ERROR_CODES.E_SSRF_REDIRECT_BLOCKED,
+                evidence: buildRedirectErrorEvidence(SAFE_FETCH_ERROR_CODES.E_SSRF_REDIRECT_BLOCKED),
+            };
+        }
+        // Recursive call with incremented redirect count
+        // IMPORTANT: Full re-validation occurs for redirects
+        return safeFetchRaw(redirectUrl.toString(), {
+            ...options,
+            _redirectCount: internalOptions._redirectCount + 1,
+            _originalHost: internalOptions._originalHost,
+            _originalOrigin: internalOptions._originalOrigin,
+        });
+    }
+    // Build success evidence with P0.3 redaction
+    const effectiveIp = pinnedIp ?? (hostResult.isIP ? hostname : undefined);
+    // Build redaction options for tenant mode
+    const redactOptsSuccess = evidenceLevel === 'tenant' && options?.redactionKey
+        ? { key: options.redactionKey, keyId: options?.redactionKeyId }
+        : undefined;
+    const successCore = {
+        schema_version: SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+        evidence_level: evidenceLevel,
+        request_timestamp: requestTimestamp,
+        response_timestamp: responseTimestamp,
+        request_url: sanitizedUrl,
+        canonical_host: hostname,
+        is_ip_literal: hostResult.isIP,
+        // Public/tenant evidence: include redacted IP info
+        ...(effectiveIp && !isPrivateEvidence
+            ? { selected_ip_info: redactIp(effectiveIp, redactOptsSuccess) }
+            : {}),
+        // Private evidence: include raw details
+        ...(isPrivateEvidence ? { dns_answers: dnsAnswers } : {}),
+        ...(isPrivateEvidence && effectiveIp ? { selected_ip: effectiveIp } : {}),
+        // Public/tenant evidence: include DNS answer counts
+        ...(!isPrivateEvidence && dnsAnswers.length > 0
+            ? {
+                dns_answer_count: {
+                    ipv4: dnsAnswers.filter((a) => a.family === 4).length,
+                    ipv6: dnsAnswers.filter((a) => a.family === 6).length,
+                },
+            }
+            : {}),
+        policy_decision: 'allow',
+        decision_code: 'OK',
+        response_status: response.status,
+        max_response_bytes: maxResponseBytes,
+        elapsed_ms: responseTimestamp - requestTimestamp,
+        dropped_headers: droppedHeaders.length > 0 ? droppedHeaders : undefined,
+    };
+    const successEvidence = finalizeEvidence(successCore, auditCtx);
+    return {
+        ok: true,
+        response,
+        close,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        evidence: successEvidence,
+    };
+}
+/**
+ * SSRF-safe JSON fetch with proper DNS resolution pinning and size limits
+ *
+ * This is the recommended function for fetching JSON APIs (JWKS, OIDC, etc.)
+ */
+export async function safeFetchJson(url, options) {
+    const maxResponseBytes = options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const rawResult = await safeFetchRaw(url, options);
+    if (!rawResult.ok) {
+        return rawResult;
+    }
+    const { response, close, warnings, evidence } = rawResult;
+    try {
+        // Read body with size limit
+        const bodyResult = await readBodyWithLimit(response, maxResponseBytes);
+        if (!bodyResult.ok) {
+            // Add evidence to body read errors (recompute digest)
+            const { evidence_digest, evidence_alg, canonicalization, ...baseEvidence } = evidence;
+            const errorCore = {
+                ...baseEvidence,
+                policy_decision: 'block',
+                decision_code: bodyResult.code,
+            };
+            return {
+                ...bodyResult,
+                evidence: finalizeEvidence(errorCore),
+            };
+        }
+        // Parse JSON
+        const text = new TextDecoder().decode(bodyResult.body);
+        const data = JSON.parse(text);
+        // Update evidence with actual response bytes (recompute digest)
+        const { evidence_digest, evidence_alg, canonicalization, ...baseEvidence } = evidence;
+        const finalCore = {
+            ...baseEvidence,
+            response_bytes: bodyResult.body.byteLength,
+        };
+        const finalEvidence = finalizeEvidence(finalCore);
+        return {
+            ok: true,
+            response,
+            data,
+            warnings,
+            evidence: finalEvidence,
+        };
+    }
+    catch (err) {
+        // Strip digest fields before modifying
+        const { evidence_digest, evidence_alg, canonicalization, ...baseEvidence } = evidence;
+        if (err instanceof SyntaxError) {
+            const errorCore = {
+                ...baseEvidence,
+                policy_decision: 'block',
+                decision_code: SAFE_FETCH_ERROR_CODES.E_PARSE_ERROR,
+            };
+            return {
+                ok: false,
+                error: 'Failed to parse JSON response',
+                code: SAFE_FETCH_ERROR_CODES.E_PARSE_ERROR,
+                evidence: finalizeEvidence(errorCore),
+            };
+        }
+        const errorCore = {
+            ...baseEvidence,
+            policy_decision: 'block',
+            decision_code: SAFE_FETCH_ERROR_CODES.E_NETWORK_ERROR,
+        };
+        return {
+            ok: false,
+            error: 'Failed to read response body',
+            code: SAFE_FETCH_ERROR_CODES.E_NETWORK_ERROR,
+            evidence: finalizeEvidence(errorCore),
+        };
+    }
+    finally {
+        // IMPORTANT: Always close the agent after body consumption
+        await close();
+    }
+}
+/**
+ * SSRF-safe fetch with JSON parsing (legacy API, use safeFetchJson for new code)
+ *
+ * @deprecated Use safeFetchJson for better type safety and structured errors
+ */
+export async function safeFetch(url, options) {
+    return safeFetchJson(url, options);
+}
+/**
+ * SSRF-safe fetch for JWKS endpoints
+ *
+ * Convenience wrapper around safeFetchJson with JWKS-specific defaults:
+ * - Shorter timeout (10 seconds)
+ * - No redirects by default
+ * - Smaller response size limit (512 KB)
+ * - Type-safe JWKS response
+ */
+export async function safeFetchJWKS(url, options) {
+    return safeFetchJson(url, {
+        ...options,
+        timeoutMs: options?.timeoutMs ?? 10000,
+        maxRedirects: 0, // JWKS endpoints should not redirect
+        maxResponseBytes: options?.maxResponseBytes ?? MAX_JWKS_RESPONSE_BYTES,
+    });
+}
+// Receipt URL resolver (v0.11.2+)
+export { resolveReceiptUrl, verifyReceiptRef } from './receipt-resolver.js';
+// Receipt URL resolution middleware (v0.12.6+, DD-207)
+export { createReceiptUrlResolver } from './receipt-url-middleware.js';
+// NOTE: Internal functions are now in impl.ts and NOT exported from main entry.
+// Access internal utilities via '@peac/net-node/testing' subpath only.
+//# sourceMappingURL=index.js.map