@peac/protocol 0.10.7 → 0.10.8

package/dist/ssrf-safe-fetch.d.ts

@@ -0,0 +1,205 @@
+/**
+ * SSRF-safe fetch utility for PEAC verifiers
+ *
+ * Implements SSRF protection per VERIFIER-SECURITY-MODEL.md:
+ * - HTTPS only
+ * - Block private IP ranges (RFC 1918)
+ * - Block link-local addresses
+ * - Block loopback addresses
+ * - Redirect limits and scheme downgrade protection
+ *
+ * ## Security Model: Best-Effort Protection
+ *
+ * **IMPORTANT**: SSRF protection is BEST-EFFORT, not a guarantee. The level of
+ * protection depends on the runtime environment's capabilities. In environments
+ * without DNS pre-resolution (browsers, edge workers), protection is limited to
+ * URL scheme validation and response limits. Defense-in-depth: combine with
+ * network-level controls (firewalls, egress filtering) in production.
+ *
+ * ## Hard Invariants (ALWAYS Enforced)
+ *
+ * These protections are enforced in ALL runtimes:
+ *
+ * | Invariant | Enforcement |
+ * |-----------|-------------|
+ * | HTTPS only | URL scheme validation before fetch |
+ * | No redirects (pointer fetch) | `redirect: 'manual'` + policy check |
+ * | Response size cap | Streaming with byte counter, abort on limit |
+ * | Timeout | AbortController with configurable timeout |
+ * | No scheme downgrade | Redirect target scheme validation |
+ *
+ * ## Runtime-Dependent Protections
+ *
+ * These protections require DNS pre-resolution capability:
+ *
+ * | Protection | Requires |
+ * |------------|----------|
+ * | Private IP blocking (RFC 1918) | DNS pre-resolution |
+ * | Loopback blocking (127.0.0.0/8) | DNS pre-resolution |
+ * | Link-local blocking (169.254.0.0/16) | DNS pre-resolution |
+ *
+ * ## Runtime Capability Model
+ *
+ * SSRF protection capabilities vary by runtime environment:
+ *
+ * | Runtime           | DNS Pre-Resolution | IP Blocking | Notes |
+ * |-------------------|-------------------|-------------|-------|
+ * | Node.js           | YES               | YES         | Full protection via dns module |
+ * | Browser           | NO                | NO          | Relies on server-side validation |
+ * | Cloudflare Workers| NO                | NO          | No DNS access, relies on CF network |
+ * | Deno              | NO                | NO          | dns module not available by default |
+ * | Bun               | YES               | YES         | Compatible with Node.js dns module |
+ *
+ * Use `getSSRFCapabilities()` to detect runtime capabilities.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Runtime environment where SSRF protection is running
+ */
+export type SSRFRuntime = 'node' | 'bun' | 'deno' | 'browser' | 'cloudflare-workers' | 'edge-generic' | 'unknown';
+/**
+ * SSRF protection capabilities available in the current runtime
+ *
+ * These capabilities determine what security measures can be applied:
+ * - `dnsPreResolution`: Can resolve hostnames to IPs before connecting
+ * - `ipBlocking`: Can inspect and block connections based on resolved IPs
+ * - `networkIsolation`: Runtime provides network-level isolation (e.g., CF Workers)
+ *
+ * When `dnsPreResolution` is false, SSRF protection is limited to:
+ * - URL scheme validation (HTTPS only)
+ * - Hostname pattern matching (if configured)
+ * - Response size limits
+ * - Timeout enforcement
+ *
+ * This is a defense-in-depth model: even without DNS pre-resolution,
+ * multiple layers of protection remain active.
+ */
+export interface SSRFCapabilities {
+    /** Detected runtime environment */
+    runtime: SSRFRuntime;
+    /** Can resolve DNS before making HTTP connection */
+    dnsPreResolution: boolean;
+    /** Can block connections based on resolved IP addresses */
+    ipBlocking: boolean;
+    /** Runtime provides network-level isolation */
+    networkIsolation: boolean;
+    /** Human-readable description of protection level */
+    protectionLevel: 'full' | 'partial' | 'minimal';
+    /** Advisory notes for operators */
+    notes: string[];
+}
+/**
+ * Detect SSRF protection capabilities for the current runtime
+ *
+ * This function performs runtime detection and returns a capability object
+ * that describes what SSRF protections are available.
+ *
+ * @returns SSRF capabilities for the current runtime
+ *
+ * @example
+ * ```typescript
+ * const caps = getSSRFCapabilities();
+ * if (!caps.dnsPreResolution) {
+ *   console.warn('Running without DNS pre-resolution; SSRF protection is limited');
+ * }
+ * ```
+ */
+export declare function getSSRFCapabilities(): SSRFCapabilities;
+/**
+ * Reset cached capabilities (for testing)
+ * @internal
+ */
+export declare function resetSSRFCapabilitiesCache(): void;
+/**
+ * SSRF fetch options
+ */
+export interface SSRFFetchOptions {
+    /** Timeout in milliseconds (default: VERIFIER_LIMITS.fetchTimeoutMs) */
+    timeoutMs?: number;
+    /** Maximum response size in bytes (default: VERIFIER_LIMITS.maxResponseBytes) */
+    maxBytes?: number;
+    /** Maximum redirects to follow (default: 0 for SSRF safety) */
+    maxRedirects?: number;
+    /** Allow redirects (default: VERIFIER_NETWORK.allowRedirects) */
+    allowRedirects?: boolean;
+    /**
+     * Allow cross-origin redirects (default: true for CDN compatibility).
+     * When true, redirects to different origins are allowed if the target passes SSRF checks.
+     * When false, redirects must stay within the same origin.
+     */
+    allowCrossOriginRedirects?: boolean;
+    /**
+     * How to handle DNS resolution failures (default: 'block' for fail-closed security).
+     * - 'block': Treat DNS failure as blocked (fail-closed, recommended)
+     * - 'fail': Return network_error and allow caller to decide
+     */
+    dnsFailureBehavior?: 'block' | 'fail';
+    /** Custom headers to include */
+    headers?: Record<string, string>;
+}
+/**
+ * SSRF fetch result
+ */
+export interface SSRFFetchResult {
+    /** Whether the fetch succeeded */
+    ok: true;
+    /** Response status code */
+    status: number;
+    /** Response body as string */
+    body: string;
+    /**
+     * Raw response bytes for digest computation.
+     * Use this for computing digests to avoid encoding round-trip issues.
+     */
+    rawBytes: Uint8Array;
+    /** Response content type */
+    contentType?: string;
+}
+/**
+ * SSRF fetch error
+ */
+export interface SSRFFetchError {
+    /** Fetch failed */
+    ok: false;
+    /** Error reason code */
+    reason: 'invalid_url' | 'not_https' | 'private_ip' | 'loopback' | 'link_local' | 'dns_failure' | 'too_many_redirects' | 'scheme_downgrade' | 'cross_origin_redirect' | 'timeout' | 'response_too_large' | 'jwks_too_many_keys' | 'network_error';
+    /** Human-readable error message */
+    message: string;
+    /** Blocked URL (if applicable) */
+    blockedUrl?: string;
+}
+/**
+ * Check if an IP address is private/blocked
+ */
+export declare function isBlockedIP(ip: string): {
+    blocked: true;
+    reason: 'private_ip' | 'loopback' | 'link_local';
+} | {
+    blocked: false;
+};
+/**
+ * Perform an SSRF-safe fetch
+ *
+ * This function implements the SSRF protection algorithm from VERIFIER-SECURITY-MODEL.md:
+ * 1. Parse URL; reject if not https://
+ * 2. Resolve hostname to IP(s)
+ * 3. For each IP: reject if private, link-local, or loopback
+ * 4. Perform fetch with timeout
+ * 5. On redirect: increment counter, reject if > max, apply checks to redirect URL
+ * 6. Validate response size
+ *
+ * @param url - URL to fetch (must be https://)
+ * @param options - Fetch options
+ * @returns Fetch result or error
+ */
+export declare function ssrfSafeFetch(url: string, options?: SSRFFetchOptions): Promise<SSRFFetchResult | SSRFFetchError>;
+/**
+ * Convenience function to fetch JWKS with SSRF protection
+ */
+export declare function fetchJWKSSafe(jwksUrl: string, options?: Omit<SSRFFetchOptions, 'maxBytes'>): Promise<SSRFFetchResult | SSRFFetchError>;
+/**
+ * Convenience function to fetch pointer target with SSRF protection
+ */
+export declare function fetchPointerSafe(pointerUrl: string, options?: Omit<SSRFFetchOptions, 'maxBytes'>): Promise<SSRFFetchResult | SSRFFetchError>;
+//# sourceMappingURL=ssrf-safe-fetch.d.ts.map

package/dist/ssrf-safe-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-safe-fetch.d.ts","sourceRoot":"","sources":["../src/ssrf-safe-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAQH;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,KAAK,GACL,MAAM,GACN,SAAS,GACT,oBAAoB,GACpB,cAAc,GACd,SAAS,CAAC;AAEd;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB,oDAAoD;IACpD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,UAAU,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAChD,mCAAmC;IACnC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAOtD;AA4GD;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACtC,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,UAAU,CAAC;IACrB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,EAAE,EAAE,KAAK,CAAC;IACV,wBAAwB;IACxB,MAAM,EACF,aAAa,GACb,WAAW,GACX,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,aAAa,GACb,oBAAoB,GACpB,kBAAkB,GAClB,uBAAuB,GACvB,SAAS,GACT,oBAAoB,GACpB,oBAAoB,GACpB,eAAe,CAAC;IACpB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqED;;GAEG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,GACT;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,YAAY,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAuC1F;AAwFD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,GAAG,cAAc,CAAC,CA+R3C;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GAC3C,OAAO,CAAC,eAAe,GAAG,cAAc,CAAC,CAS3C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GAC3C,OAAO,CAAC,eAAe,GAAG,cAAc,CAAC,CAS3C"}