@peac/net-node 0.12.6

package/dist/index.d.ts

@@ -0,0 +1,772 @@
+/**
+ * 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 { type SSRFPolicy } from './ssrf.js';
+import { getAuditQueueStats, type RequestAuditContext } from './impl.js';
+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';
+export { getAuditQueueStats };
+export type { RequestAuditContext };
+export { SAFE_FETCH_ERROR_CODES };
+export { SAFE_FETCH_EVENT_SCHEMA_VERSION, SAFE_FETCH_EVIDENCE_SCHEMA_VERSION, MAX_PENDING_AUDIT_EVENTS, };
+/**
+ * Structured error with code, cause, and warnings
+ *
+ * NOTE: Error messages are intentionally generic to avoid leaking sensitive
+ * information (internal IPs, hostnames). Use `evidence` for audit details.
+ */
+export interface SafeFetchError {
+    error: string;
+    code: string;
+    cause_code?: string;
+    warnings?: string[];
+    /** Evidence object for audit trail (always present on error) */
+    evidence?: SafeFetchEvidence;
+}
+/**
+ * Result type for safeFetch operations
+ */
+export type SafeFetchResult<T> = {
+    ok: true;
+    response: Response;
+    data: T;
+    warnings?: string[];
+    evidence: SafeFetchEvidence;
+} | ({
+    ok: false;
+} & SafeFetchError);
+/**
+ * Result type for raw fetch (returns stream with cleanup)
+ */
+export type SafeFetchRawResult = {
+    ok: true;
+    response: Response;
+    close: () => Promise<void>;
+    warnings?: string[];
+    evidence: SafeFetchEvidence;
+} | ({
+    ok: false;
+} & SafeFetchError);
+/**
+ * DNS resolution result
+ */
+export interface DnsResolutionResult {
+    ok: true;
+    addresses: string[];
+    selectedAddress: string;
+    ipv4Addresses: string[];
+    ipv6Addresses: string[];
+}
+export interface DnsResolutionError {
+    ok: false;
+    error: string;
+    code: string;
+    /** Structured DNS answers for audit trail */
+    dns_answers?: DnsAnswer[];
+}
+/**
+ * DNS resolver interface for dependency injection
+ * Allows mocking in tests without network calls
+ */
+export interface DnsResolver {
+    /**
+     * Resolve a hostname to all available IP addresses
+     * @param hostname - The hostname to resolve
+     * @returns Array of IP addresses (both IPv4 and IPv6)
+     */
+    resolveAll(hostname: string): Promise<{
+        ipv4: string[];
+        ipv6: string[];
+    }>;
+}
+/**
+ * Phase-specific timeout options for HTTP client (P1.3)
+ *
+ * These map directly to undici's timeout options for precise control.
+ */
+export interface HttpClientTimeouts {
+    /** Total operation timeout (AbortController) */
+    totalMs?: number;
+    /** TCP/TLS connect timeout (undici Agent connect.timeout) */
+    connectMs?: number;
+    /** Time to receive headers after connection (undici headersTimeout) */
+    headersMs?: number;
+    /** Time to receive body after headers (undici bodyTimeout) */
+    bodyMs?: number;
+}
+/**
+ * HTTP client interface for dependency injection
+ * Pattern B: returns response + close function for proper lifecycle management
+ */
+export interface HttpClient {
+    /**
+     * Fetch a URL with optional pinned IP
+     * Returns response and close function to ensure proper agent cleanup
+     * @param url - The URL to fetch
+     * @param pinnedIp - The IP address to connect to (DNS pinning)
+     * @param options - Fetch options with phase-specific timeouts
+     */
+    fetch(url: string, pinnedIp: string | null, options?: RequestInit & {
+        timeouts?: HttpClientTimeouts;
+        timeoutMs?: number;
+    }): Promise<{
+        response: Response;
+        close: () => Promise<void>;
+    }>;
+}
+/**
+ * Redirect policy for cross-host redirects
+ */
+export type RedirectPolicy = 'none' | 'same-origin' | 'same-registrable-domain' | 'allowlist';
+/**
+ * Evidence redaction level for portable receipts
+ *
+ * - 'public': Safe for external sharing. Hashes IPs, removes raw addresses.
+ *   Use this for evidence that may be included in receipts, logs, or telemetry.
+ *
+ * - 'tenant': Internal correlation with HMAC-SHA256 keyed hashing.
+ *   Prevents cross-org linkage while allowing intra-org correlation.
+ *   Requires `redactionKey` option to be provided.
+ *
+ * - 'private': Full details for internal audit. Includes raw IPs and hostnames.
+ *   Only use for internal debugging or trusted audit systems.
+ *
+ * Default is 'public' for defense-in-depth (evidence may leak to external systems).
+ *
+ * @since v0.10.x
+ */
+export type EvidenceLevel = 'public' | 'tenant' | 'private';
+/**
+ * Redacted IP information for public evidence
+ *
+ * Raw IP addresses are replaced with family + SHA-256 hash.
+ * This allows correlation without exposing internal topology.
+ *
+ * For 'tenant' level, uses HMAC-SHA256 with tenant key to prevent
+ * cross-org correlation via rainbow tables.
+ */
+export interface RedactedIpInfo {
+    /** Address family (4 or 6) */
+    family: 4 | 6;
+    /** SHA-256 or HMAC-SHA256 hash of the IP address (lowercase hex, 0x prefixed) */
+    hash: string;
+    /** Key ID used for HMAC (only present in 'tenant' mode) */
+    key_id?: string;
+}
+/**
+ * Acknowledgment string for allowing mixed public/private DNS resolution
+ */
+export declare const ALLOW_MIXED_DNS_ACK: "I_UNDERSTAND_MIXED_DNS_SECURITY_RISKS";
+/**
+ * Evidence without digest fields (for computing the digest)
+ *
+ * The digest is computed over evidence with digest fields omitted
+ * to avoid self-referential circularity.
+ */
+export type SafeFetchEvidenceCore = Omit<SafeFetchEvidence, 'evidence_digest' | 'evidence_alg' | 'canonicalization'>;
+/**
+ * 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 declare function canonicalizeEvidence(evidence: SafeFetchEvidence | SafeFetchEvidenceCore): string;
+/**
+ * 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 declare function computeEvidenceDigest(evidence: SafeFetchEvidence | SafeFetchEvidenceCore): string;
+/**
+ * Event types emitted by safeFetch for audit logging
+ */
+export type SafeFetchEventType = 'dns_start' | 'dns_success' | 'dns_blocked' | 'dns_error' | 'connect_start' | 'connect_success' | 'connect_error' | 'request_start' | 'response_headers' | 'response_body_start' | 'response_body_complete' | 'redirect' | 'error' | 'audit_overflow' | 'audit_hook_error';
+/**
+ * Structured DNS answer for audit-clean logging
+ *
+ * Each answer includes the IP, address family, and blocked reason (if any).
+ * This allows downstream verifiers to replay "why blocked/allowed" decisions.
+ */
+export interface DnsAnswer {
+    /** Resolved IP address */
+    ip: string;
+    /** Address family (4 or 6) */
+    family: 4 | 6;
+    /** If blocked, the reason code; undefined if allowed */
+    blocked_reason?: string;
+}
+/**
+ * Policy decision for audit trail
+ */
+export type PolicyDecision = 'allow' | 'block';
+/**
+ * Audit event with timing and metadata
+ *
+ * This is a vendor-neutral structure that can be adapted to any logging system.
+ * Events are emitted at key points in the fetch lifecycle.
+ *
+ * IMPORTANT: This schema is versioned via `schema_version` for forward compatibility.
+ * @see SAFE_FETCH_EVENT_SCHEMA_VERSION
+ */
+export interface SafeFetchEvent {
+    /** Schema version for forward compatibility */
+    schema_version: typeof SAFE_FETCH_EVENT_SCHEMA_VERSION;
+    /** Event type */
+    type: SafeFetchEventType;
+    /** Timestamp (Date.now()) */
+    timestamp: number;
+    /** Original request URL (sanitized - no credentials) */
+    url: string;
+    /** Resolved hostname (after canonicalization) */
+    hostname?: string;
+    /** Selected IP address (only on success events) */
+    selected_ip?: string;
+    /** Error code if applicable */
+    code?: string;
+    /** Human-readable message (generic, non-sensitive) */
+    message?: string;
+    /** Policy decision (allow/block) for DNS events */
+    policy_decision?: PolicyDecision;
+    /** Additional metadata (vendor-neutral, may contain sensitive debug info) */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Audit hook callback type
+ *
+ * HOOK CONTRACT (for reliable integration):
+ *
+ * - Delivery: Asynchronous via queueMicrotask (non-blocking to fetch path)
+ * - Ordering: FIFO within a single request (events arrive in fetch order)
+ * - Guarantees: At-most-once delivery (events may be dropped under load)
+ * - Exceptions: MUST NOT throw (exceptions are swallowed silently)
+ * - Side effects: MUST NOT modify request/response or call safeFetch
+ *
+ * Special events:
+ * - `audit_overflow`: Emitted SYNCHRONOUSLY when queue is full (rate-limited 1/sec)
+ *   This event bypasses the queue to ensure observability of drops.
+ *
+ * For enterprise reliability, consume events idempotently and monitor
+ * `audit_overflow` events as a signal of capacity issues.
+ */
+export type SafeFetchAuditHook = (event: SafeFetchEvent) => void;
+/**
+ * Evidence object returned by safeFetch for PEAC-ready receipts
+ *
+ * This is a portable, signed-ready artifact that captures:
+ * - Request URL (normalized, no credentials)
+ * - Canonical host processing
+ * - DNS resolution decisions
+ * - Redirect chain (if any)
+ * - Timing summary
+ * - Budget enforcement
+ * - Final decision code
+ *
+ * Evidence is redacted based on `evidence_level`:
+ * - 'public': Raw IPs replaced with family + SHA-256 hash
+ * - 'private': Full details including raw IPs
+ *
+ * Designed for multi-agent workflow verification and dispute resolution.
+ */
+export interface SafeFetchEvidence {
+    /** Schema version for forward compatibility (evidence-specific) */
+    schema_version: typeof SAFE_FETCH_EVIDENCE_SCHEMA_VERSION;
+    /**
+     * Evidence redaction level
+     * - 'public': Safe for external sharing (default)
+     * - 'tenant': Internal correlation with HMAC (prevents cross-org linkage)
+     * - 'private': Full details for internal audit
+     */
+    evidence_level: EvidenceLevel;
+    /**
+     * SHA-256 digest of canonical evidence (0x-prefixed hex)
+     * Computed over evidence with this field omitted (self-referential exclusion)
+     */
+    evidence_digest: string;
+    /**
+     * Hash algorithm used for digest
+     * @default 'sha-256'
+     */
+    evidence_alg: 'sha-256';
+    /**
+     * Canonicalization scheme used before hashing
+     * @default 'RFC8785-JCS'
+     */
+    canonicalization: 'RFC8785-JCS';
+    /** Request timestamp (start of fetch) */
+    request_timestamp: number;
+    /** Response timestamp (headers received) */
+    response_timestamp?: number;
+    /** Normalized request URL (no credentials) */
+    request_url: string;
+    /** Canonical hostname after processing */
+    canonical_host: string;
+    /** Whether host was an IP literal */
+    is_ip_literal: boolean;
+    /**
+     * Selected IP info (public evidence - always present on success)
+     * Contains family and SHA-256 hash of the selected IP
+     */
+    selected_ip_info?: RedactedIpInfo;
+    /**
+     * DNS answer summary (public evidence)
+     * Count of answers by family, without raw IPs
+     */
+    dns_answer_count?: {
+        ipv4: number;
+        ipv6: number;
+    };
+    /**
+     * DNS answers with per-IP decisions (private evidence only)
+     * Only populated when evidence_level is 'private'
+     */
+    dns_answers?: DnsAnswer[];
+    /**
+     * Raw selected IP for connection (private evidence only)
+     * Only populated when evidence_level is 'private'
+     */
+    selected_ip?: string;
+    /** Policy decision */
+    policy_decision: PolicyDecision;
+    /** Final decision code */
+    decision_code: string;
+    /** Redirect chain (URLs) */
+    redirect_chain?: string[];
+    /** Response status code */
+    response_status?: number;
+    /** Actual response bytes received */
+    response_bytes?: number;
+    /** Max response bytes budget */
+    max_response_bytes: number;
+    /** Total elapsed time in milliseconds */
+    elapsed_ms?: number;
+    /** Dropped headers (security enforcement) */
+    dropped_headers?: string[];
+    /**
+     * Audit queue statistics at time of evidence creation (per-request)
+     *
+     * Provides visibility into audit event processing health for THIS request.
+     * All counters are request-scoped - they reset for each safeFetch call.
+     * If `dropped > 0`, some events were lost due to queue overflow.
+     * This is a signal that evidence quality may be degraded.
+     */
+    audit_stats?: {
+        /** Number of audit events pending at evidence creation */
+        pending: number;
+        /** Total number of dropped audit events for this request */
+        dropped: number;
+        /** Maximum allowed pending events */
+        max_pending: number;
+        /** Number of hook errors that occurred during this request */
+        hook_errors: number;
+        /** Number of hook errors suppressed by rate limiting for this request */
+        hook_suppressed: number;
+    };
+    /**
+     * Indicates audit data was truncated due to overflow
+     *
+     * NORMATIVE PRESENCE SEMANTICS:
+     * - Present and `true`: Evidence is incomplete, audit events were dropped
+     * - Absent (undefined): Evidence is complete, no truncation occurred
+     *
+     * Producers MUST omit this field when no truncation occurred.
+     * Producers MUST NOT emit `audit_truncated: false`.
+     *
+     * This field uses presence semantics to ensure digest compatibility:
+     * `{ ...core }` and `{ ...core, audit_truncated: false }` would produce
+     * different digests for logically identical evidence. By requiring omission
+     * when false, we guarantee cross-implementation digest parity.
+     *
+     * Set to `true` when `audit_stats.dropped > 0`.
+     */
+    audit_truncated?: true;
+}
+/**
+ * Granular timeout configuration for different phases
+ *
+ * All values are in milliseconds. If not specified, defaults apply.
+ */
+export interface TimeoutConfig {
+    /**
+     * Total request timeout (overall limit)
+     * @default 30000 (30 seconds)
+     */
+    totalMs?: number;
+    /**
+     * DNS resolution timeout
+     * @default 5000 (5 seconds)
+     */
+    dnsMs?: number;
+    /**
+     * TCP/TLS connection timeout
+     * @default 10000 (10 seconds)
+     */
+    connectMs?: number;
+    /**
+     * Time to receive response headers
+     * @default 15000 (15 seconds)
+     */
+    headersMs?: number;
+    /**
+     * Time to receive response body (after headers)
+     * @default 30000 (30 seconds)
+     */
+    bodyMs?: number;
+}
+/**
+ * Default timeout values
+ */
+export declare const DEFAULT_TIMEOUTS: Required<TimeoutConfig>;
+/**
+ * Options for safeFetch
+ */
+export interface SafeFetchOptions extends Omit<RequestInit, 'signal'> {
+    /**
+     * SSRF policy configuration
+     * @default DEFAULT_SSRF_POLICY
+     */
+    ssrfPolicy?: SSRFPolicy;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum number of redirects to follow
+     * Set to 0 to disable redirects
+     * @default 5
+     */
+    maxRedirects?: number;
+    /**
+     * Redirect policy for handling cross-host redirects
+     * @default 'same-origin'
+     */
+    redirectPolicy?: RedirectPolicy;
+    /**
+     * Allowed hosts for redirects when redirectPolicy is 'allowlist'
+     * Also used for 'same-registrable-domain' as additional allowed hosts
+     */
+    redirectAllowHosts?: string[];
+    /**
+     * @deprecated Use redirectPolicy instead
+     * Allow redirects to different hosts
+     */
+    allowCrossHostRedirects?: boolean;
+    /**
+     * Allowed HTTP methods (SSRF side-effect prevention)
+     * @default ['GET', 'HEAD']
+     */
+    allowedMethods?: string[];
+    /**
+     * Maximum response body size in bytes (DoS protection)
+     * @default 2097152 (2 MB)
+     */
+    maxResponseBytes?: number;
+    /**
+     * Disable Accept-Encoding: identity default.
+     *
+     * By default, we send Accept-Encoding: identity to prevent decompression bombs.
+     * Setting this to true allows compressed responses (gzip, deflate, br).
+     *
+     * WARNING: Only set this if you trust the server AND have streaming
+     * decompression with size limits in place.
+     *
+     * @default false
+     */
+    allowCompression?: boolean;
+    /**
+     * Allow DNS resolution that returns BOTH public and private IPs.
+     *
+     * By default, we REJECT requests where ANY resolved IP is private,
+     * even if there are also public IPs. This prevents attackers from
+     * hiding a private IP alongside public ones.
+     *
+     * In some corporate environments, split DNS legitimately returns
+     * both internal and external IPs. This escape hatch allows such
+     * configurations, but requires explicit acknowledgment.
+     *
+     * SECURITY WARNING: This weakens SSRF protection. Only use if:
+     * 1. You control the DNS infrastructure
+     * 2. You understand the risks of mixed DNS responses
+     * 3. You have other mitigations in place (network segmentation, etc.)
+     *
+     * @default false
+     */
+    allowMixedPublicAndPrivateDns?: boolean;
+    /**
+     * Required acknowledgment for allowMixedPublicAndPrivateDns.
+     * Set to ALLOW_MIXED_DNS_ACK ('I_UNDERSTAND_MIXED_DNS_SECURITY_RISKS').
+     */
+    ack_allow_mixed_dns?: typeof ALLOW_MIXED_DNS_ACK;
+    /**
+     * Allow connections to dangerous ports (admin, databases, service mesh).
+     *
+     * By default, we BLOCK connections to ports in DANGEROUS_PORTS set
+     * (SSH, databases, container orchestration, etc.) even on public IPs.
+     * This prevents SSRF attacks targeting internal services on non-standard ports.
+     *
+     * SECURITY WARNING: This weakens SSRF protection. Only use if:
+     * 1. You specifically need to connect to services on these ports
+     * 2. You understand the risks of allowing these connections
+     * 3. You have network-level controls in place
+     *
+     * @default false
+     */
+    allowDangerousPorts?: boolean;
+    /**
+     * Required acknowledgment for allowDangerousPorts.
+     * Set to ALLOW_DANGEROUS_PORTS_ACK ('I_UNDERSTAND_DANGEROUS_PORTS_RISK').
+     */
+    ack_allow_dangerous_ports?: typeof ALLOW_DANGEROUS_PORTS_ACK;
+    /**
+     * Granular timeout configuration for different phases.
+     * If provided, overrides timeoutMs for specific phases.
+     * @see TimeoutConfig
+     */
+    timeouts?: TimeoutConfig;
+    /**
+     * Audit hook for observing fetch lifecycle events.
+     *
+     * Called at key points (DNS, connect, request, response, error).
+     * Useful for logging, metrics, and debugging.
+     *
+     * MUST NOT throw or modify request/response.
+     * Hooks are invoked via queueMicrotask for performance isolation.
+     * @see SafeFetchAuditHook
+     */
+    onEvent?: SafeFetchAuditHook;
+    /**
+     * Custom sanitizer for hook error messages.
+     *
+     * By default, error messages are sanitized to:
+     * - Truncate to 200 characters
+     * - Redact Bearer tokens, passwords, keys, secrets
+     *
+     * Use this option to provide a custom sanitizer or disable sanitization:
+     * - Pass a function to customize: `(msg: string) => sanitizedMsg`
+     * - Pass `'off'` to disable sanitization entirely (NOT RECOMMENDED in production)
+     *
+     * @default Built-in sanitizer (truncate + redact secrets)
+     */
+    sanitizeHookError?: ((message: string) => string) | 'off';
+    /**
+     * Enable debug mode to include sensitive details in evidence and events.
+     *
+     * When false (default), error messages and evidence are generic to avoid
+     * leaking internal IPs or hostnames through logs/telemetry.
+     *
+     * When true:
+     * - Evidence includes detailed `dns_answers` with per-IP decisions
+     * - Event metadata includes blocked IPs and addresses
+     *
+     * WARNING: Only enable in trusted environments (local dev, internal logging).
+     * @default false
+     * @deprecated Use evidenceLevel: 'private' instead for evidence, keep debug for events
+     */
+    debug?: boolean;
+    /**
+     * Evidence redaction level for portable receipts.
+     *
+     * - 'public' (default): Raw IPs replaced with family + SHA-256 hash.
+     *   Safe for including in receipts, logs, or external telemetry.
+     *   Note: SHA-256 of IPv4 is rainbow-table vulnerable (only 2^32 inputs).
+     *
+     * - 'tenant': HMAC-SHA256 with tenant-specific key. Prevents cross-org
+     *   correlation via rainbow tables while allowing intra-org correlation.
+     *   Requires `redactionKey` and `redactionKeyId` options.
+     *
+     * - 'private': Full details including raw IPs and DNS answers.
+     *   Only use for internal audit systems you control.
+     *
+     * Defense-in-depth: default 'public' ensures evidence is safe even
+     * if accidentally exposed through logs or telemetry pipelines.
+     *
+     * @default 'public'
+     * @since v0.10.x
+     */
+    evidenceLevel?: EvidenceLevel;
+    /**
+     * Tenant-specific key for HMAC-based IP hashing (tenant mode only).
+     *
+     * Must be at least 32 bytes for security. Used with HMAC-SHA256 to
+     * prevent cross-tenant correlation via rainbow tables.
+     *
+     * Required when evidenceLevel is 'tenant'.
+     *
+     * @since v0.10.x
+     */
+    redactionKey?: Uint8Array;
+    /**
+     * Key identifier for tenant mode redaction.
+     *
+     * Included in evidence to identify which key was used for hashing.
+     * Allows key rotation while maintaining audit trails.
+     *
+     * Required when evidenceLevel is 'tenant'.
+     *
+     * @since v0.10.x
+     */
+    redactionKeyId?: string;
+    /**
+     * Custom DNS resolver for dependency injection (testing)
+     * @internal
+     */
+    _dnsResolver?: DnsResolver;
+    /**
+     * Custom HTTP client for dependency injection (testing)
+     * @internal
+     */
+    _httpClient?: HttpClient;
+}
+/**
+ * Default timeout for fetch requests (30 seconds)
+ */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Default maximum redirects
+ */
+export declare const DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * Default allowed HTTP methods (GET/HEAD only for SSRF safety)
+ */
+export declare const DEFAULT_ALLOWED_METHODS: string[];
+/**
+ * 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 declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * Whether maxResponseBytes measures wire or decoded bytes.
+ * Always 'decoded' - we measure after potential decompression.
+ */
+export declare const RESPONSE_BYTES_MEASUREMENT: "decoded";
+/**
+ * Maximum response size for JWKS/OIDC endpoints (512 KB)
+ */
+export declare const MAX_JWKS_RESPONSE_BYTES: number;
+/**
+ * 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 declare const DANGEROUS_PORTS: ReadonlySet<number>;
+/**
+ * Acknowledgment string for allowing dangerous ports
+ */
+export declare const ALLOW_DANGEROUS_PORTS_ACK: "I_UNDERSTAND_DANGEROUS_PORTS_RISK";
+/**
+ * Default DNS resolver using Node.js dns.promises module
+ * Resolves both A (IPv4) and AAAA (IPv6) records separately for Happy Eyeballs
+ */
+export declare const defaultDnsResolver: DnsResolver;
+/**
+ * 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 declare const defaultHttpClient: HttpClient;
+/**
+ * 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 declare function safeFetchRaw(url: string, options?: SafeFetchOptions): Promise<SafeFetchRawResult>;
+/**
+ * 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 declare function safeFetchJson<T = unknown>(url: string, options?: SafeFetchOptions): Promise<SafeFetchResult<T>>;
+/**
+ * SSRF-safe fetch with JSON parsing (legacy API, use safeFetchJson for new code)
+ *
+ * @deprecated Use safeFetchJson for better type safety and structured errors
+ */
+export declare function safeFetch<T = unknown>(url: string, options?: SafeFetchOptions): Promise<SafeFetchResult<T>>;
+/**
+ * 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 declare function safeFetchJWKS(url: string, options?: Omit<SafeFetchOptions, 'maxRedirects'>): Promise<SafeFetchResult<{
+    keys: unknown[];
+}>>;
+export { resolveReceiptUrl, verifyReceiptRef } from './receipt-resolver.js';
+export type { ResolveReceiptUrlOptions, ResolveReceiptUrlResult, ResolveReceiptUrlSuccess, ResolveReceiptUrlFailure, } from './receipt-resolver.js';
+export { createReceiptUrlResolver } from './receipt-url-middleware.js';
+export type { ReceiptUrlResolverOptions, RetrievalMetadata, ReceiptUrlMiddleware, } from './receipt-url-middleware.js';
+//# sourceMappingURL=index.d.ts.map