@peac/net-node 0.12.6

package/dist/ssrf.d.ts

@@ -0,0 +1,114 @@
+/**
+ * SSRF Policy Types and Validation
+ *
+ * Local definitions for SSRF protection configuration.
+ * These types are specific to @peac/net-node's SSRF protection.
+ *
+ * @internal
+ * @module @peac/net-node/ssrf
+ */
+/**
+ * Acknowledgment constant for allowing dangerous CIDR ranges
+ *
+ * When policy.allowCidrs contains private/dangerous ranges,
+ * this acknowledgment must be set to confirm intentional usage.
+ */
+export declare const ALLOW_DANGEROUS_CIDRS_ACK: "I_UNDERSTAND_ALLOWING_PRIVATE_CIDRS_IS_DANGEROUS";
+/**
+ * SSRF policy configuration
+ *
+ * Controls how SSRF protection handles URLs and IP addresses.
+ */
+export interface SSRFPolicy {
+    /**
+     * Additional CIDR ranges to ALLOW (bypass blocking).
+     * Use with extreme caution - only for trusted internal services.
+     * Requires ack_allow_dangerous_cidrs if ranges overlap with private/dangerous IPs.
+     */
+    allowCidrs?: string[];
+    /**
+     * Additional CIDR ranges to BLOCK (in addition to default private ranges).
+     * Applied after allowCidrs.
+     */
+    blockedCidrs?: string[];
+    /**
+     * Acknowledgment for allowing dangerous CIDR ranges.
+     * Required when allowCidrs contains private/dangerous ranges.
+     * Must be exactly ALLOW_DANGEROUS_CIDRS_ACK to be valid.
+     */
+    ack_allow_dangerous_cidrs?: string;
+    /**
+     * Allow CGNAT (Carrier-Grade NAT) range: 100.64.0.0/10
+     * Use with caution - requires explicit acknowledgment.
+     */
+    allowCgnat?: boolean;
+    /**
+     * Acknowledgment for allowing CGNAT range.
+     * Required when allowCgnat is true.
+     */
+    ack_allow_cgnat?: string;
+    /**
+     * Require HTTPS (default true). Set to false to allow HTTP URLs.
+     * @default true
+     */
+    requireHttps?: boolean;
+    /**
+     * Allow IP literals in URLs (default false).
+     * When false, only hostnames are allowed (not direct IP addresses).
+     * @default false
+     */
+    allowIPLiterals?: boolean;
+    /**
+     * Allowed ports (default [80, 443]).
+     * Only these ports are allowed in URLs. Other ports are blocked.
+     */
+    allowPorts?: number[];
+    /**
+     * Allow credentials in URLs (default false).
+     * When false, URLs with username:password are rejected.
+     * @default false
+     */
+    allowCredentials?: boolean;
+}
+/**
+ * Default SSRF policy - blocks all private IP ranges
+ */
+export declare const DEFAULT_SSRF_POLICY: SSRFPolicy;
+/**
+ * Result of URL validation for SSRF
+ */
+export type UrlValidationResult = {
+    ok: true;
+    value: URL;
+} | {
+    ok: false;
+    code: string;
+    error: string;
+};
+/**
+ * Validate a URL string for SSRF protection (string-level checks only)
+ *
+ * This performs URL parsing and basic string-level validation.
+ * NOTE: This is NOT sufficient for full SSRF protection - DNS resolution
+ * and IP validation must also be performed at connection time.
+ *
+ * @param urlString - The URL to validate
+ * @param policy - SSRF policy (affects which checks are applied)
+ * @returns Validation result with parsed URL or error
+ */
+export declare function validateUrlForSSRF(urlString: string, policy?: SSRFPolicy): UrlValidationResult;
+/**
+ * Error codes for trust boundary violations
+ *
+ * Used for SSRF-related errors in safeFetch operations.
+ */
+export declare const TRUST_ERROR_CODES: {
+    readonly SSRF_URL_REJECTED: "E_NET_SSRF_URL_REJECTED";
+    readonly SSRF_DNS_RESOLVED_PRIVATE: "E_NET_SSRF_DNS_RESOLVED_PRIVATE";
+    readonly SSRF_ALL_IPS_BLOCKED: "E_NET_SSRF_ALL_IPS_BLOCKED";
+    readonly SSRF_REDIRECT_BLOCKED: "E_NET_SSRF_REDIRECT_BLOCKED";
+    readonly SSRF_TOO_MANY_REDIRECTS: "E_NET_SSRF_TOO_MANY_REDIRECTS";
+    readonly SSRF_IPV6_ZONE_ID: "E_NET_SSRF_IPV6_ZONE_ID";
+    readonly SSRF_INVALID_HOST: "E_NET_SSRF_INVALID_HOST";
+};
+//# sourceMappingURL=ssrf.d.ts.map

package/dist/ssrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf.d.ts","sourceRoot":"","sources":["../src/ssrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EACpC,kDAA2D,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAGjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiE/C;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAqH9F;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;CAQpB,CAAC"}

package/dist/ssrf.js

@@ -0,0 +1,214 @@
+/**
+ * SSRF Policy Types and Validation
+ *
+ * Local definitions for SSRF protection configuration.
+ * These types are specific to @peac/net-node's SSRF protection.
+ *
+ * @internal
+ * @module @peac/net-node/ssrf
+ */
+/**
+ * Acknowledgment constant for allowing dangerous CIDR ranges
+ *
+ * When policy.allowCidrs contains private/dangerous ranges,
+ * this acknowledgment must be set to confirm intentional usage.
+ */
+export const ALLOW_DANGEROUS_CIDRS_ACK = 'I_UNDERSTAND_ALLOWING_PRIVATE_CIDRS_IS_DANGEROUS';
+/**
+ * Default SSRF policy - blocks all private IP ranges
+ */
+export const DEFAULT_SSRF_POLICY = {
+    allowCidrs: [],
+    blockedCidrs: [],
+};
+/**
+ * RFC 1918 private IPv4 ranges and localhost
+ */
+const PRIVATE_IPV4_PATTERNS = [
+    /^127\./, // Loopback
+    /^10\./, // Class A private
+    /^172\.(1[6-9]|2[0-9]|3[0-1])\./, // Class B private (172.16-31.x.x)
+    /^192\.168\./, // Class C private
+    /^0\./, // "This network"
+    /^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./, // CGNAT 100.64.0.0/10
+    /^169\.254\./, // Link-local
+    /^192\.0\.0\./, // IETF protocol assignments
+    /^192\.0\.2\./, // TEST-NET-1
+    /^198\.51\.100\./, // TEST-NET-2
+    /^203\.0\.113\./, // TEST-NET-3
+    /^192\.88\.99\./, // 6to4 relay anycast
+    /^198\.18\./, // Benchmark testing
+    /^224\./, // Multicast
+    /^240\./, // Reserved (future use)
+    /^255\.255\.255\.255$/, // Broadcast
+];
+/**
+ * Check if a hostname looks like a private IPv4 address
+ */
+function isPrivateIPv4Literal(hostname) {
+    // Check if it looks like an IPv4 address
+    if (!/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+        return false;
+    }
+    return PRIVATE_IPV4_PATTERNS.some((pattern) => pattern.test(hostname));
+}
+/**
+ * Check if a hostname is localhost or a loopback address
+ */
+function isLoopback(hostname) {
+    const lower = hostname.toLowerCase();
+    return (lower === 'localhost' ||
+        lower === 'localhost.' ||
+        lower.endsWith('.localhost') ||
+        lower === '127.0.0.1' ||
+        lower === '[::1]' ||
+        lower === '::1');
+}
+/**
+ * Check if a hostname is an IP literal (IPv4 or IPv6)
+ */
+function isIPLiteral(hostname) {
+    // IPv4 pattern
+    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+        return true;
+    }
+    // IPv6 pattern (bracketed or not)
+    if (hostname.startsWith('[') || hostname.includes(':')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Validate a URL string for SSRF protection (string-level checks only)
+ *
+ * This performs URL parsing and basic string-level validation.
+ * NOTE: This is NOT sufficient for full SSRF protection - DNS resolution
+ * and IP validation must also be performed at connection time.
+ *
+ * @param urlString - The URL to validate
+ * @param policy - SSRF policy (affects which checks are applied)
+ * @returns Validation result with parsed URL or error
+ */
+export function validateUrlForSSRF(urlString, policy) {
+    // Step 1: Parse URL
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(urlString);
+    }
+    catch {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_INVALID_URL',
+            error: 'Invalid URL format',
+        };
+    }
+    // Step 2: Protocol validation - only https allowed by default (http is risky)
+    if (parsedUrl.protocol !== 'https:' && parsedUrl.protocol !== 'http:') {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_INVALID_PROTOCOL',
+            error: `Protocol ${parsedUrl.protocol} not allowed`,
+        };
+    }
+    // Step 3: Block HTTP by default unless policy allows (requireHttps: false)
+    const requireHttps = policy?.requireHttps !== false; // default true
+    if (parsedUrl.protocol === 'http:' && requireHttps) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_HTTP_BLOCKED',
+            error: 'HTTP protocol blocked - use HTTPS',
+        };
+    }
+    // Step 4: Basic hostname validation
+    const hostname = parsedUrl.hostname;
+    if (!hostname || hostname.length === 0) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_INVALID_HOST',
+            error: 'Empty hostname',
+        };
+    }
+    // Step 5: Check for IPv6 zone IDs (security risk)
+    if (hostname.includes('%')) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_IPV6_ZONE_ID',
+            error: 'IPv6 zone IDs not allowed',
+        };
+    }
+    // Step 6: Block localhost/loopback
+    if (isLoopback(hostname)) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_LOCALHOST_BLOCKED',
+            error: 'Localhost/loopback addresses not allowed',
+        };
+    }
+    // Step 7: Block private IPv4 literals (unless policy allows)
+    if (isPrivateIPv4Literal(hostname)) {
+        // Check if policy explicitly allows this CIDR
+        const allowed = policy?.allowCidrs?.some((cidr) => {
+            // Simple check - if any allowCidr is set, we let DNS-level validation handle it
+            return cidr.length > 0;
+        });
+        if (!allowed) {
+            return {
+                ok: false,
+                code: 'E_NET_SSRF_PRIVATE_IP_BLOCKED',
+                error: 'Private IP addresses not allowed',
+            };
+        }
+    }
+    // Step 8: Block IP literals by default unless policy allows
+    const allowIPLiterals = policy?.allowIPLiterals === true;
+    if (isIPLiteral(hostname) && !allowIPLiterals) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_IP_LITERAL_BLOCKED',
+            error: 'IP literals not allowed - use hostnames',
+        };
+    }
+    // Step 9: Block credentials in URLs by default
+    const allowCredentials = policy?.allowCredentials === true;
+    if (!allowCredentials && (parsedUrl.username || parsedUrl.password)) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_CREDENTIALS_BLOCKED',
+            error: 'Credentials in URLs not allowed',
+        };
+    }
+    // Step 10: Port validation - only allow standard ports by default
+    // allowPorts is ADDITIVE to the default [80, 443]
+    const defaultPorts = [80, 443];
+    const additionalPorts = policy?.allowPorts ?? [];
+    const allowedPorts = [...new Set([...defaultPorts, ...additionalPorts])];
+    const portStr = parsedUrl.port;
+    const effectivePort = portStr
+        ? parseInt(portStr, 10)
+        : parsedUrl.protocol === 'https:'
+            ? 443
+            : 80;
+    if (!allowedPorts.includes(effectivePort)) {
+        return {
+            ok: false,
+            code: 'E_NET_SSRF_PORT_BLOCKED',
+            error: `Port ${effectivePort} not allowed`,
+        };
+    }
+    return { ok: true, value: parsedUrl };
+}
+/**
+ * Error codes for trust boundary violations
+ *
+ * Used for SSRF-related errors in safeFetch operations.
+ */
+export const TRUST_ERROR_CODES = {
+    SSRF_URL_REJECTED: 'E_NET_SSRF_URL_REJECTED',
+    SSRF_DNS_RESOLVED_PRIVATE: 'E_NET_SSRF_DNS_RESOLVED_PRIVATE',
+    SSRF_ALL_IPS_BLOCKED: 'E_NET_SSRF_ALL_IPS_BLOCKED',
+    SSRF_REDIRECT_BLOCKED: 'E_NET_SSRF_REDIRECT_BLOCKED',
+    SSRF_TOO_MANY_REDIRECTS: 'E_NET_SSRF_TOO_MANY_REDIRECTS',
+    SSRF_IPV6_ZONE_ID: 'E_NET_SSRF_IPV6_ZONE_ID',
+    SSRF_INVALID_HOST: 'E_NET_SSRF_INVALID_HOST',
+};
+//# sourceMappingURL=ssrf.js.map

package/dist/ssrf.js.map

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

package/dist/testing.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @peac/net-node Testing Utilities
+ *
+ * This module exports internal utilities for testing purposes only.
+ * These APIs are NOT part of the public contract and may change without notice.
+ *
+ * Import via:
+ *   import { _internals } from '@peac/net-node/testing';
+ *
+ * DO NOT use these in production code.
+ *
+ * @module @peac/net-node/testing
+ */
+import { isPrivateIP, resolveDnsSecure, createPinnedAgent, parseCidr, matchesAnyCidr, validateAllowCidrsAck, cidrOverlapsDangerousRanges, getRegistrableDomain, isRedirectAllowed, normalizeHostname, sanitizeUrl, readBodyWithLimit, attemptWithFallback, hasHeaderCaseInsensitive, stripHopByHopHeaders, hasIPv6ZoneId, normalizeIPv4MappedIPv6, canonicalizeHost, emitAuditEvent, createRequestAuditContext, hashIpAddress, redactIp, resetAuditQueueStats } from './impl.js';
+import { jcsCanonicalizeValue } from './evidence-utils.js';
+import { finalizeEvidence } from './internal.js';
+export type { DnsResolver, HttpClient, HttpClientTimeouts, SafeFetchAuditHook, SafeFetchEvent, DnsAnswer, SafeFetchEvidence, SafeFetchEvidenceCore, EvidenceLevel, RedactedIpInfo, RequestAuditContext, } from './index.js';
+export { canonicalizeEvidence, computeEvidenceDigest, getAuditQueueStats, MAX_PENDING_AUDIT_EVENTS, DANGEROUS_PORTS, ALLOW_DANGEROUS_PORTS_ACK, SAFE_FETCH_ERROR_CODES, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_REDIRECTS, DEFAULT_ALLOWED_METHODS, DEFAULT_MAX_RESPONSE_BYTES, MAX_JWKS_RESPONSE_BYTES, RESPONSE_BYTES_MEASUREMENT, DEFAULT_TIMEOUTS, ALLOW_MIXED_DNS_ACK, SAFE_FETCH_EVENT_SCHEMA_VERSION, SAFE_FETCH_EVIDENCE_SCHEMA_VERSION, } from './index.js';
+/**
+ * Internal utilities for testing.
+ *
+ * These utilities provide access to internal implementation details
+ * for testing purposes only. They are NOT stable APIs.
+ *
+ * @example
+ * import { _internals } from '@peac/net-node/testing';
+ *
+ * // Access internal functions
+ * const isPrivate = _internals.isPrivateIP('10.0.0.1');
+ */
+export declare const _internals: {
+    readonly isPrivateIP: typeof isPrivateIP;
+    readonly resolveDnsSecure: typeof resolveDnsSecure;
+    readonly createPinnedAgent: typeof createPinnedAgent;
+    readonly parseCidr: typeof parseCidr;
+    readonly matchesAnyCidr: typeof matchesAnyCidr;
+    readonly validateAllowCidrsAck: typeof validateAllowCidrsAck;
+    readonly cidrOverlapsDangerousRanges: typeof cidrOverlapsDangerousRanges;
+    readonly getRegistrableDomain: typeof getRegistrableDomain;
+    readonly isRedirectAllowed: typeof isRedirectAllowed;
+    readonly normalizeHostname: typeof normalizeHostname;
+    readonly sanitizeUrl: typeof sanitizeUrl;
+    readonly readBodyWithLimit: typeof readBodyWithLimit;
+    readonly attemptWithFallback: typeof attemptWithFallback;
+    readonly hasHeaderCaseInsensitive: typeof hasHeaderCaseInsensitive;
+    readonly stripHopByHopHeaders: typeof stripHopByHopHeaders;
+    readonly hasIPv6ZoneId: typeof hasIPv6ZoneId;
+    readonly normalizeIPv4MappedIPv6: typeof normalizeIPv4MappedIPv6;
+    readonly canonicalizeHost: typeof canonicalizeHost;
+    readonly emitAuditEvent: typeof emitAuditEvent;
+    readonly createRequestAuditContext: typeof createRequestAuditContext;
+    readonly hashIpAddress: typeof hashIpAddress;
+    readonly redactIp: typeof redactIp;
+    readonly jcsCanonicalizeValue: typeof jcsCanonicalizeValue;
+    readonly resetAuditQueueStats: typeof resetAuditQueueStats;
+    readonly finalizeEvidence: typeof finalizeEvidence;
+    readonly BLOCKED_IPV4_RANGES: Set<string>;
+    readonly BLOCKED_IPV6_RANGES: Set<string>;
+    readonly ADDITIONAL_BLOCKED_CIDRS_V4: [import("ipaddr.js").IPv4, number][];
+    readonly ADDITIONAL_BLOCKED_CIDRS_V6: [import("ipaddr.js").IPv6, number][];
+    readonly HOP_BY_HOP_HEADERS: Set<string>;
+    readonly SAFE_FETCH_EVENT_SCHEMA_VERSION: "peac-safe-fetch-event/0.1";
+    readonly SAFE_FETCH_EVIDENCE_SCHEMA_VERSION: "peac-safe-fetch-evidence/0.1";
+};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAEL,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EAEjB,SAAS,EACT,cAAc,EACd,qBAAqB,EACrB,2BAA2B,EAE3B,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EAEX,iBAAiB,EACjB,mBAAmB,EAEnB,wBAAwB,EACxB,oBAAoB,EAEpB,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EAEhB,cAAc,EACd,yBAAyB,EAEzB,aAAa,EACb,QAAQ,EAER,oBAAoB,EAOrB,MAAM,WAAW,CAAC;AAMnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,YAAY,EACV,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,yBAAyB,EACzB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,+BAA+B,EAC/B,kCAAkC,GACnC,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8Cb,CAAC"}

package/dist/testing.js

@@ -0,0 +1,103 @@
+/**
+ * @peac/net-node Testing Utilities
+ *
+ * This module exports internal utilities for testing purposes only.
+ * These APIs are NOT part of the public contract and may change without notice.
+ *
+ * Import via:
+ *   import { _internals } from '@peac/net-node/testing';
+ *
+ * DO NOT use these in production code.
+ *
+ * @module @peac/net-node/testing
+ */
+// Import internal functions from impl.ts (the internal implementation module)
+import { 
+// Core validation
+isPrivateIP, resolveDnsSecure, createPinnedAgent, 
+// CIDR utilities
+parseCidr, matchesAnyCidr, validateAllowCidrsAck, cidrOverlapsDangerousRanges, 
+// URL/hostname utilities
+getRegistrableDomain, isRedirectAllowed, normalizeHostname, sanitizeUrl, 
+// Response handling
+readBodyWithLimit, attemptWithFallback, 
+// Header utilities
+hasHeaderCaseInsensitive, stripHopByHopHeaders, 
+// Canonical host pipeline
+hasIPv6ZoneId, normalizeIPv4MappedIPv6, canonicalizeHost, 
+// Audit helpers
+emitAuditEvent, createRequestAuditContext, 
+// Evidence redaction helpers
+hashIpAddress, redactIp, 
+// Audit queue helpers (for testing)
+resetAuditQueueStats, 
+// Constants (read-only references)
+BLOCKED_IPV4_RANGES, BLOCKED_IPV6_RANGES, ADDITIONAL_BLOCKED_CIDRS_V4, ADDITIONAL_BLOCKED_CIDRS_V6, HOP_BY_HOP_HEADERS, } from './impl.js';
+// Import schema version constants from index.ts (public API)
+import { SAFE_FETCH_EVENT_SCHEMA_VERSION, SAFE_FETCH_EVIDENCE_SCHEMA_VERSION } from './index.js';
+// Import JCS canonicalization helper from evidence-utils
+import { jcsCanonicalizeValue } from './evidence-utils.js';
+// Import finalizeEvidence from internal module (NOT in main entry)
+import { finalizeEvidence } from './internal.js';
+// Re-export public utilities that are useful for testing
+export { canonicalizeEvidence, computeEvidenceDigest, getAuditQueueStats, MAX_PENDING_AUDIT_EVENTS, DANGEROUS_PORTS, ALLOW_DANGEROUS_PORTS_ACK, SAFE_FETCH_ERROR_CODES, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_REDIRECTS, DEFAULT_ALLOWED_METHODS, DEFAULT_MAX_RESPONSE_BYTES, MAX_JWKS_RESPONSE_BYTES, RESPONSE_BYTES_MEASUREMENT, DEFAULT_TIMEOUTS, ALLOW_MIXED_DNS_ACK, SAFE_FETCH_EVENT_SCHEMA_VERSION, SAFE_FETCH_EVIDENCE_SCHEMA_VERSION, } from './index.js';
+/**
+ * Internal utilities for testing.
+ *
+ * These utilities provide access to internal implementation details
+ * for testing purposes only. They are NOT stable APIs.
+ *
+ * @example
+ * import { _internals } from '@peac/net-node/testing';
+ *
+ * // Access internal functions
+ * const isPrivate = _internals.isPrivateIP('10.0.0.1');
+ */
+export const _internals = {
+    // Core validation
+    isPrivateIP,
+    resolveDnsSecure,
+    createPinnedAgent,
+    // CIDR utilities
+    parseCidr,
+    matchesAnyCidr,
+    validateAllowCidrsAck,
+    cidrOverlapsDangerousRanges,
+    // URL/hostname utilities
+    getRegistrableDomain,
+    isRedirectAllowed,
+    normalizeHostname,
+    sanitizeUrl,
+    // Response handling
+    readBodyWithLimit,
+    attemptWithFallback,
+    // Header utilities
+    hasHeaderCaseInsensitive,
+    stripHopByHopHeaders,
+    // Canonical host pipeline
+    hasIPv6ZoneId,
+    normalizeIPv4MappedIPv6,
+    canonicalizeHost,
+    // Audit helpers
+    emitAuditEvent,
+    createRequestAuditContext,
+    // Evidence redaction helpers
+    hashIpAddress,
+    redactIp,
+    // JCS canonicalization helpers
+    jcsCanonicalizeValue,
+    // Audit queue helpers (for testing)
+    resetAuditQueueStats,
+    // Evidence finalization (from internal.ts - NOT in main entry)
+    finalizeEvidence,
+    // Constants (read-only references)
+    BLOCKED_IPV4_RANGES,
+    BLOCKED_IPV6_RANGES,
+    ADDITIONAL_BLOCKED_CIDRS_V4,
+    ADDITIONAL_BLOCKED_CIDRS_V6,
+    HOP_BY_HOP_HEADERS,
+    // Schema version constants
+    SAFE_FETCH_EVENT_SCHEMA_VERSION,
+    SAFE_FETCH_EVIDENCE_SCHEMA_VERSION,
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8EAA8E;AAC9E,OAAO;AACL,kBAAkB;AAClB,WAAW,EACX,gBAAgB,EAChB,iBAAiB;AACjB,iBAAiB;AACjB,SAAS,EACT,cAAc,EACd,qBAAqB,EACrB,2BAA2B;AAC3B,yBAAyB;AACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,WAAW;AACX,oBAAoB;AACpB,iBAAiB,EACjB,mBAAmB;AACnB,mBAAmB;AACnB,wBAAwB,EACxB,oBAAoB;AACpB,0BAA0B;AAC1B,aAAa,EACb,uBAAuB,EACvB,gBAAgB;AAChB,gBAAgB;AAChB,cAAc,EACd,yBAAyB;AACzB,6BAA6B;AAC7B,aAAa,EACb,QAAQ;AACR,oCAAoC;AACpC,oBAAoB;AACpB,mCAAmC;AACnC,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,kBAAkB,GACnB,MAAM,WAAW,CAAC;AAEnB,6DAA6D;AAC7D,OAAO,EAAE,+BAA+B,EAAE,kCAAkC,EAAE,MAAM,YAAY,CAAC;AAEjG,yDAAyD;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,mEAAmE;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiBjD,yDAAyD;AACzD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,yBAAyB,EACzB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,+BAA+B,EAC/B,kCAAkC,GACnC,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,kBAAkB;IAClB,WAAW;IACX,gBAAgB;IAChB,iBAAiB;IACjB,iBAAiB;IACjB,SAAS;IACT,cAAc;IACd,qBAAqB;IACrB,2BAA2B;IAC3B,yBAAyB;IACzB,oBAAoB;IACpB,iBAAiB;IACjB,iBAAiB;IACjB,WAAW;IACX,oBAAoB;IACpB,iBAAiB;IACjB,mBAAmB;IACnB,mBAAmB;IACnB,wBAAwB;IACxB,oBAAoB;IACpB,0BAA0B;IAC1B,aAAa;IACb,uBAAuB;IACvB,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,yBAAyB;IACzB,6BAA6B;IAC7B,aAAa;IACb,QAAQ;IACR,+BAA+B;IAC/B,oBAAoB;IACpB,oCAAoC;IACpC,oBAAoB;IACpB,+DAA+D;IAC/D,gBAAgB;IAChB,mCAAmC;IACnC,mBAAmB;IACnB,mBAAmB;IACnB,2BAA2B;IAC3B,2BAA2B;IAC3B,kBAAkB;IAClB,2BAA2B;IAC3B,+BAA+B;IAC/B,kCAAkC;CAC1B,CAAC"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@peac/net-node",
+  "version": "0.12.6",
+  "description": "SSRF-safe network utilities for PEAC Protocol with DNS resolution pinning (Node.js only)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./*": null
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
+    "directory": "packages/net/node"
+  },
+  "author": "PEAC Protocol Contributors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/peacprotocol/peac/issues"
+  },
+  "homepage": "https://github.com/peacprotocol/peac#readme",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ipaddr.js": "^2.3.0",
+    "tldts": "^6.1.86",
+    "undici": "^6.24.0",
+    "@peac/schema": "0.12.6"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@types/node": "^22.19.11",
+    "publint": "^0.3.17",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.0"
+  },
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "network",
+    "node",
+    "jwks-resolution",
+    "ssrf-safe"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "echo 'Run pnpm lint from repo root'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "verify:jcs-vectors": "node scripts/verify-jcs-vectors.mjs",
+    "regen:jcs-vectors": "node scripts/verify-jcs-vectors.mjs --regenerate",
+    "test:pack-install": "node scripts/test-pack-install.mjs",
+    "lint:pkg": "publint && attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution",
+    "lint:publint": "publint",
+    "lint:attw": "attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution"
+  }
+}