@peac/net-node 0.12.6

package/dist/impl.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Internal Implementation for @peac/net-node
+ *
+ * This module contains internal helper functions that are NOT part of the public API.
+ * These functions are used internally by index.ts and exposed ONLY via the testing subpath.
+ *
+ * IMPORTANT: This module is NOT listed in package.json exports, so it cannot be
+ * directly imported by consumers. Only the testing subpath re-exports from here.
+ *
+ * @internal
+ * @module @peac/net-node/impl
+ */
+import ipaddr from 'ipaddr.js';
+import { Agent } from 'undici';
+import { type SSRFPolicy } from './ssrf.js';
+import { SAFE_FETCH_ERROR_CODES } from './codes.js';
+import { MAX_PENDING_AUDIT_EVENTS } from './constants.js';
+export { MAX_PENDING_AUDIT_EVENTS };
+import type { SafeFetchOptions, SafeFetchAuditHook, SafeFetchEvent, DnsResolutionResult, DnsResolutionError, DnsAnswer, DnsResolver, HttpClient, RedactedIpInfo, RedirectPolicy } from './index.js';
+export type { DnsAnswer, RedactedIpInfo };
+/**
+ * Happy Eyeballs connection timeout for first attempt (250ms)
+ */
+export declare const HAPPY_EYEBALLS_FIRST_TIMEOUT_MS = 250;
+/**
+ * Hop-by-hop headers that MUST NOT be forwarded (RFC 7230 Section 6.1)
+ * These are stripped from requests to prevent proxy confusion and smuggling
+ */
+export declare const HOP_BY_HOP_HEADERS: Set<string>;
+/**
+ * Blocked IPv4 range names from ipaddr.js
+ * These are always blocked (fail-closed security)
+ */
+export declare const BLOCKED_IPV4_RANGES: Set<string>;
+/**
+ * Additional IPv4 CIDR ranges to block (RFC 6890 compliance)
+ * Not covered by ipaddr.js range() but should be blocked
+ */
+export declare const ADDITIONAL_BLOCKED_CIDRS_V4: Array<[ipaddr.IPv4, number]>;
+/**
+ * Blocked IPv6 range names from ipaddr.js
+ */
+export declare const BLOCKED_IPV6_RANGES: Set<string>;
+/**
+ * Additional IPv6 CIDR ranges to block
+ */
+export declare const ADDITIONAL_BLOCKED_CIDRS_V6: Array<[ipaddr.IPv6, number]>;
+export { SAFE_FETCH_ERROR_CODES };
+/**
+ * Hash an IP address for public evidence using SHA-256
+ *
+ * Returns a 0x-prefixed lowercase hex string for consistency with
+ * other PEAC cryptographic identifiers (e.g., EAS anchors).
+ *
+ * @param ip - Raw IP address string
+ * @returns SHA-256 hash as 0x-prefixed lowercase hex
+ * @internal
+ */
+export declare function hashIpAddress(ip: string): string;
+/**
+ * Create redacted IP info for public evidence
+ *
+ * @param ip - Raw IP address string
+ * @param options - Optional HMAC key for tenant mode
+ * @returns Redacted info with family and hash
+ * @internal
+ */
+export declare function redactIp(ip: string, options?: {
+    key?: Uint8Array;
+    keyId?: string;
+}): RedactedIpInfo;
+/**
+ * Header input type (compatible with RequestInit.headers)
+ * Using a type alias to avoid dependency on DOM types
+ */
+type HeaderInput = Headers | Record<string, string> | Array<[string, string]> | undefined;
+/**
+ * Case-insensitive header presence check
+ *
+ * Works with any header input type (Headers, array, object).
+ * The Fetch API's Headers object is case-insensitive by spec, but this helper
+ * provides explicit case-insensitive checking for any input format.
+ *
+ * @param headers - Headers, array of [name, value] pairs, or plain object
+ * @param name - Header name to check (case-insensitive)
+ * @returns true if header exists (any casing)
+ * @internal
+ */
+export declare function hasHeaderCaseInsensitive(headers: HeaderInput, name: string): boolean;
+/**
+ * Parse a CIDR string into an ipaddr.js address and prefix length
+ * @internal
+ */
+export declare function parseCidr(cidrStr: string): [ipaddr.IPv4 | ipaddr.IPv6, number] | null;
+/**
+ * Check if an IP address matches any CIDR in a list
+ * @internal
+ */
+export declare function matchesAnyCidr(addr: ipaddr.IPv4 | ipaddr.IPv6, cidrStrings: string[]): boolean;
+/**
+ * Check if a CIDR string overlaps with any dangerous/private ranges
+ * Uses robust range-based overlap detection (conservative - false positives OK)
+ * @internal
+ */
+export declare function cidrOverlapsDangerousRanges(cidrStr: string): boolean;
+/**
+ * Check if an IP address is private/reserved using RFC 6890-grade classification
+ * @internal
+ */
+export declare function isPrivateIP(ip: string, policy?: SSRFPolicy): boolean;
+/**
+ * Validate that allowCidrs has proper acknowledgment if it contains dangerous ranges
+ * @internal
+ */
+export declare function validateAllowCidrsAck(policy?: SSRFPolicy): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Check if a hostname contains an IPv6 zone identifier
+ *
+ * Zone identifiers (e.g., %eth0, %25eth0) are used for link-local addresses
+ * and MUST be rejected to prevent SSRF bypasses via interface binding.
+ *
+ * @param hostname - Raw hostname from URL
+ * @returns true if zone ID is present
+ * @internal
+ */
+export declare function hasIPv6ZoneId(hostname: string): boolean;
+/**
+ * Normalize IPv4-mapped IPv6 address to IPv4
+ *
+ * IPv4-mapped IPv6 addresses (::ffff:a.b.c.d) can bypass IPv4 blocklists
+ * if not normalized. We convert them to plain IPv4 for consistent blocking.
+ *
+ * @param ip - IP address string
+ * @returns Normalized IP (IPv4 if it was IPv4-mapped, otherwise unchanged)
+ * @internal
+ */
+export declare function normalizeIPv4MappedIPv6(ip: string): string;
+/**
+ * Canonical host result
+ */
+interface CanonicalHostResult {
+    ok: true;
+    hostname: string;
+    isIP: boolean;
+    originalHostname: string;
+}
+interface CanonicalHostError {
+    ok: false;
+    error: string;
+    code: string;
+}
+/**
+ * Canonicalize a hostname with full security validation
+ *
+ * This is the single source of truth for hostname processing:
+ * 1. Reject IPv6 zone identifiers (SSRF bypass prevention)
+ * 2. Lowercase and strip trailing dot
+ * 3. Normalize IDNs to ASCII (punycode)
+ * 4. Normalize IPv4-mapped IPv6 to IPv4
+ *
+ * @param hostname - Raw hostname from URL
+ * @returns Canonicalized hostname or error
+ * @internal
+ */
+export declare function canonicalizeHost(hostname: string): CanonicalHostResult | CanonicalHostError;
+/**
+ * Strip hop-by-hop headers from request headers
+ *
+ * RFC 7230 Section 6.1 defines hop-by-hop headers that MUST NOT be forwarded.
+ * Stripping these prevents proxy confusion and request smuggling attacks.
+ *
+ * @param headers - Headers object to sanitize (mutated in place)
+ * @internal
+ */
+export declare function stripHopByHopHeaders(headers: Headers): void;
+/**
+ * Normalize hostname for comparison:
+ * - Lowercase
+ * - Strip trailing dot
+ * - Convert to ASCII (punycode)
+ * - Normalize IPv4-mapped IPv6
+ * @internal
+ */
+export declare function normalizeHostname(hostname: string): string;
+/**
+ * Extract registrable domain (eTLD+1) from hostname using proper PSL
+ * Uses tldts library for accurate Public Suffix List matching
+ *
+ * IMPORTANT: This function accepts a hostname (from URL.hostname), NOT a host:port string.
+ * IPv6 addresses are returned as-is (they don't have registrable domains).
+ *
+ * @param hostname - A hostname (e.g., "example.com", "2001:db8::1"), NOT "host:port"
+ * @internal
+ */
+export declare function getRegistrableDomain(hostname: string): string;
+/**
+ * Check if redirect target is allowed by policy
+ * @internal
+ */
+export declare function isRedirectAllowed(originalUrl: URL, redirectUrl: URL, policy: RedirectPolicy, allowHosts?: string[]): boolean;
+/**
+ * Options for creating a pinned agent
+ * @internal
+ */
+interface PinnedAgentOptions {
+    /** TCP/TLS connect timeout in milliseconds */
+    connectTimeoutMs?: number;
+}
+/**
+ * Create an undici Agent with DNS pinning and optional connect timeout
+ * @internal
+ */
+export declare function createPinnedAgent(pinnedIp: string, _hostname: string, options?: PinnedAgentOptions): Agent;
+/**
+ * Options for DNS resolution
+ * @internal
+ */
+interface DnsResolveOptions {
+    policy: SSRFPolicy;
+    allowMixedPublicAndPrivate?: boolean;
+}
+/**
+ * P1.3: Wrap a promise with a timeout
+ * Returns a discriminated union to distinguish timeout from actual result
+ * @internal
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutCode: string): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    code: string;
+}>;
+/**
+ * Resolve DNS and validate ALL resolved IPs, returning only safe ones
+ * Implements RFC 8305-style address family ordering
+ *
+ * SECURITY NOTES:
+ * - Error messages are intentionally generic to avoid leaking internal IPs
+ * - Structured dns_answers are returned for audit trail (debug mode only reveals in events)
+ * - Mixed DNS (public + private) requires explicit opt-in
+ *
+ * @internal
+ */
+export declare function resolveDnsSecure(hostname: string, policy: SSRFPolicy, resolver: DnsResolver, dnsOptions?: DnsResolveOptions): Promise<DnsResolutionResult | DnsResolutionError>;
+/**
+ * Attempt connection with Happy Eyeballs-style fallback (RFC 8305)
+ * Properly cancels and cleans up the losing attempt
+ * @internal
+ */
+export declare function attemptWithFallback(url: string, dnsResult: DnsResolutionResult, httpClient: HttpClient, options: SafeFetchOptions): Promise<{
+    response: Response;
+    close: () => Promise<void>;
+}>;
+/**
+ * Read response body with size limit enforcement
+ * @internal
+ */
+export declare function readBodyWithLimit(response: Response, maxBytes: number): Promise<{
+    ok: true;
+    body: ArrayBuffer;
+} | {
+    ok: false;
+    error: string;
+    code: string;
+}>;
+/**
+ * Per-request audit context for tracking request-scoped counters
+ *
+ * All counters in this context are specific to a single safeFetch invocation.
+ * This ensures evidence accurately reflects the state of that specific request,
+ * not global process state.
+ *
+ * @internal
+ */
+export interface RequestAuditContext {
+    /** Number of events currently pending for this request */
+    pending: number;
+    /** Number of events dropped for this request */
+    dropped: number;
+    /** Number of hook errors for this request */
+    hookErrors: number;
+    /** Number of hook errors suppressed for this request */
+    hookSuppressed: number;
+}
+/**
+ * Create a new request-scoped audit context
+ * @internal
+ */
+export declare function createRequestAuditContext(): RequestAuditContext;
+/**
+ * Reset audit queue statistics (for testing)
+ * @internal
+ */
+export declare function resetAuditQueueStats(): void;
+/**
+ * Get global audit queue statistics for monitoring (process-level)
+ *
+ * NOTE: For per-request stats, use the RequestAuditContext.
+ * This function returns process-level totals for operational monitoring.
+ *
+ * @returns Object with global pending count
+ */
+export declare function getAuditQueueStats(): {
+    pending: number;
+    dropped: number;
+};
+/**
+ * Safely emit an audit event via microtask for performance isolation
+ *
+ * Events are queued via queueMicrotask to prevent slow hooks from blocking
+ * the request path. Ordering is guaranteed within a request but may
+ * interleave with other async operations.
+ *
+ * P1.4: Implements bounded queue to prevent microtask blowup.
+ * Events are dropped (not queued) if MAX_PENDING_AUDIT_EVENTS is exceeded.
+ * When drops occur, a rate-limited `audit_overflow` event is emitted.
+ *
+ * @param ctx - Request-scoped audit context for tracking per-request counters
+ * @internal
+ */
+export declare function emitAuditEvent(ctx: RequestAuditContext, hook: SafeFetchAuditHook | undefined, sanitizer: ((message: string) => string) | 'off' | undefined, hookName: string, event: Omit<SafeFetchEvent, 'schema_version'>): void;
+/**
+ * Sanitize URL for logging (remove credentials)
+ * @internal
+ */
+export declare function sanitizeUrl(url: string): string;
+//# sourceMappingURL=impl.d.ts.map

package/dist/impl.d.ts.map

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