@zudojs/security 0.0.1 → 1.0.0

package/dist/types/index.d.ts

@@ -3,6 +3,6 @@
  *
  * Re-exports all security configuration and result types.
  */
-export type { HeaderSecurityConfig, HeaderValidationResult, BodyLimitConfig, BodyLimitPresets, UrlValidationConfig, UrlValidationResult, CookieSecurityConfig, ParsedCookie, CorsConfig, CsrfConfig, RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitResult, SecurityHeadersConfig, RequestValidationConfig, InputSanitizationConfig, } from "./security.type.js";
+export type { HeaderSecurityConfig, HeaderValidationResult, BodyLimitConfig, BodyLimitPresets, UrlValidationConfig, UrlValidationResult, CookieSecurityConfig, ParsedCookie, CorsConfig, CsrfConfig, RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitResult, SecurityHeadersConfig, InputSanitizationConfig, } from "./security.type.js";
 export { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from "./security.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/security.type.d.ts

@@ -13,6 +13,15 @@ export interface HeaderSecurityConfig {
     readonly maxTotalSize?: number;
     /** Headers that should be rejected entirely. */
     readonly blockedHeaders?: readonly string[];
+    /**
+     * Reject hop-by-hop headers (default: false).
+     *
+     * `isHopByHopHeader` was exported and consulted by nothing. Set this when
+     * validating a request that has crossed a proxy: `Transfer-Encoding`,
+     * `Connection` and friends are per-hop and a forwarded one is a
+     * request-smuggling primitive.
+     */
+    readonly blockHopByHop?: boolean;
 }
 /** Result of header validation. */
 export interface HeaderValidationResult {
@@ -116,8 +125,14 @@ export interface RateLimitConfig {
     readonly windowMs: number;
     /** Key generator function (defaults to IP). */
     readonly keyGenerator?: (request: RateLimitRequest) => string;
-    /** Custom handler when rate limit is exceeded. */
-    readonly handler?: (request: RateLimitRequest, response: RateLimitResponse) => void;
+    /**
+     * Custom handler when rate limit is exceeded.
+     *
+     * Receives the decision that produced the rejection, so a handler can set an
+     * accurate `Retry-After` instead of guessing. A two-parameter handler is
+     * still assignable — the third argument is simply ignored.
+     */
+    readonly handler?: (request: RateLimitRequest, response: RateLimitResponse, result: RateLimitResult) => void;
     /** Skip certain requests. */
     readonly skip?: (request: RateLimitRequest) => boolean;
     /** Message returned when rate limited. */
@@ -166,21 +181,6 @@ export interface SecurityHeadersConfig {
     /** Cross-Origin-Resource-Policy value. */
     readonly resourcePolicy?: string;
 }
-/** Configuration for request validation. */
-export interface RequestValidationConfig {
-    /** Allowed HTTP methods. */
-    readonly allowedMethods?: readonly string[];
-    /** Maximum request line size in bytes. */
-    readonly maxRequestLineSize?: number;
-    /** Allowed hosts (empty = allow all). */
-    readonly allowedHosts?: readonly string[];
-    /** Whether to validate the Host header. */
-    readonly validateHost?: boolean;
-    /** Whether to validate Content-Length. */
-    readonly validateContentLength?: boolean;
-    /** Maximum Content-Length value. */
-    readonly maxContentLength?: number;
-}
 /** Configuration for input sanitization. */
 export interface InputSanitizationConfig {
     /** Whether to strip null bytes. */
@@ -191,13 +191,30 @@ export interface InputSanitizationConfig {
     readonly maxStringLength?: number;
     /** Whether to prevent prototype pollution. */
     readonly preventPrototypePollution?: boolean;
+    /** Maximum nesting depth to recurse into (default: 32). */
+    readonly maxDepth?: number;
     /** Custom sanitizer function. */
     readonly customSanitizer?: (value: string) => string;
 }
 /** Keys that indicate prototype pollution attempts. */
 export declare const PROTOTYPE_POLLUTION_KEYS: readonly ["__proto__", "constructor", "prototype"];
-/** Common SQL injection patterns. */
+/**
+ * Common SQL injection patterns.
+ *
+ * Heuristics, not a parser: they carry a high false-positive rate on ordinary
+ * prose (the word "update", a `#` in a hashtag) and must never be the only
+ * defence. Parameterise queries; use these for logging and alerting.
+ *
+ * Like {@link XSS_PATTERNS}, none carries the `g` flag — see the note there.
+ */
 export declare const SQL_INJECTION_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
-/** Common XSS patterns. */
+/**
+ * Common XSS patterns.
+ *
+ * These are matched with {@link RegExp.test}, so none of them carries the `g`
+ * flag: a global regex advances `lastIndex` on every `test` call and resumes
+ * from there on the next one, which makes a shared pattern report `false` for
+ * a payload it matched a moment earlier.
+ */
 export declare const XSS_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
 //# sourceMappingURL=security.type.d.ts.map

package/dist/types/security.type.js

@@ -9,23 +9,38 @@ export const PROTOTYPE_POLLUTION_KEYS = [
     "constructor",
     "prototype",
 ];
-/** Common SQL injection patterns. */
+/**
+ * Common SQL injection patterns.
+ *
+ * Heuristics, not a parser: they carry a high false-positive rate on ordinary
+ * prose (the word "update", a `#` in a hashtag) and must never be the only
+ * defence. Parameterise queries; use these for logging and alerting.
+ *
+ * Like {@link XSS_PATTERNS}, none carries the `g` flag — see the note there.
+ */
 export const SQL_INJECTION_PATTERNS = [
     /(\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|EXEC|EXECUTE|UNION|FETCH|DECLARE|TRUNCATE|COMMENT|ALTER)\b)/i,
     /(--|#|\/\*|\*\/)/,
     /('\s*(OR|AND)\s*')/i,
     /(;\s*(DROP|DELETE|INSERT|UPDATE))/i,
 ];
-/** Common XSS patterns. */
+/**
+ * Common XSS patterns.
+ *
+ * These are matched with {@link RegExp.test}, so none of them carries the `g`
+ * flag: a global regex advances `lastIndex` on every `test` call and resumes
+ * from there on the next one, which makes a shared pattern report `false` for
+ * a payload it matched a moment earlier.
+ */
 export const XSS_PATTERNS = [
-    /<script\b[^>]*>[\s\S]*?<\/script[^>]*>/gi,
-    /<script\b[^>]*>/gi,
-    /<\/script[^>]*>/gi,
-    /javascript:/gi,
-    /on\w+\s*=/gi,
-    /data:text\/html/gi,
-    /<iframe\b[^>]*>/gi,
-    /<object\b[^>]*>/gi,
-    /<embed\b[^>]*>/gi,
+    /<script\b[^>]*>[\s\S]*?<\/script[^>]*>/i,
+    /<script\b[^>]*>/i,
+    /<\/script[^>]*>/i,
+    /javascript:/i,
+    /on\w+\s*=/i,
+    /data:text\/html/i,
+    /<iframe\b[^>]*>/i,
+    /<object\b[^>]*>/i,
+    /<embed\b[^>]*>/i,
 ];
 //# sourceMappingURL=security.type.js.map

package/dist/url/index.d.ts

@@ -1,5 +1,6 @@
 /**
  * @zudojs/security — URL Validation Barrel
  */
-export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, } from "./url.core.js";
+export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url.core.js";
+export type { RequestTargetConfig } from "./url.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/url/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — URL Validation Barrel
  */
-export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, } from "./url.core.js";
+export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url.core.js";
 //# sourceMappingURL=index.js.map

package/dist/url/url.core.d.ts

@@ -5,6 +5,32 @@
  * and ensures request targets are safe.
  */
 import type { UrlValidationConfig, UrlValidationResult } from "../types/security.type.js";
+/**
+ * Fully percent-decodes a string, up to {@link MAX_DECODE_ROUNDS} times.
+ *
+ * Traversal sequences cannot be recognised reliably by pattern-matching an
+ * encoded string: `..`, `%2e%2e`, `.%2e`, `%2e.` and their double-encoded
+ * forms are all the same path, and the variant space grows with every round of
+ * encoding. Decoding to a fixed point first collapses them into one shape.
+ *
+ * @param value - The string to decode.
+ * @returns The decoded string and whether decoding terminated cleanly.
+ */
+export declare function fullyDecodeUri(value: string): {
+    decoded: string;
+    truncated: boolean;
+    malformed: boolean;
+};
+/**
+ * Checks whether a path contains a traversal segment.
+ *
+ * Operates on the fully decoded form, and treats a backslash as a separator
+ * because Windows and some proxies do.
+ *
+ * @param path - The path to inspect.
+ * @returns True when a `..` segment is present.
+ */
+export declare function containsTraversal(path: string): boolean;
 /**
  * Validates a URL against security configuration.
  *
@@ -16,10 +42,21 @@ export declare function validateUrl(url: string, config?: UrlValidationConfig):
 /**
  * Normalizes a URL path by resolving . and .. segments.
  *
+ * `..` never escapes the root: at depth zero it is discarded rather than
+ * popping into the parent.
+ *
  * @param pathname - The path to normalize.
  * @returns The normalized path.
  */
 export declare function normalizePath(pathname: string): string;
+/**
+ * Options accepted by {@link validateRequestTarget}.
+ *
+ * A request target is origin-form (`/users?page=1`) and carries no scheme, so
+ * `allowedProtocols` can never apply to it. Declaring the full
+ * {@link UrlValidationConfig} advertised a knob this function cannot honour.
+ */
+export type RequestTargetConfig = Omit<UrlValidationConfig, "allowedProtocols">;
 /**
  * Validates a request target (URI path + query).
  *
@@ -27,12 +64,31 @@ export declare function normalizePath(pathname: string): string;
  * @param config - Optional validation configuration.
  * @returns Validation result.
  */
-export declare function validateRequestTarget(target: string, config?: UrlValidationConfig): UrlValidationResult;
+export declare function validateRequestTarget(target: string, config?: RequestTargetConfig): UrlValidationResult;
+/**
+ * Checks whether a hostname points at a private, loopback, link-local or
+ * otherwise internal destination.
+ *
+ * @param hostname - The hostname to check (as produced by `URL.hostname`).
+ * @returns True when the hostname is not safe to reach outward.
+ */
+export declare function isPrivateHostname(hostname: string): boolean;
 /**
  * Checks if a URL is safe to follow (not pointing to internal resources).
  *
+ * Only `http:` and `https:` are allowed by default — every other scheme,
+ * including `file:`, `gopher:`, `data:` and `blob:`, is rejected rather than
+ * denied one at a time.
+ *
+ * **This cannot stop DNS rebinding.** A public hostname may resolve to a
+ * private address, and may resolve differently between this check and the
+ * connection. For outbound requests that must be safe, resolve the hostname
+ * yourself, run {@link isPrivateHostname} against the resolved address, and
+ * connect to that address directly.
+ *
  * @param url - The URL to check.
+ * @param allowedProtocols - Protocols to permit (default: http and https).
  * @returns True if the URL appears safe.
  */
-export declare function isSafeUrl(url: string): boolean;
+export declare function isSafeUrl(url: string, allowedProtocols?: readonly string[]): boolean;
 //# sourceMappingURL=url.core.d.ts.map

package/dist/url/url.core.js

@@ -8,18 +8,13 @@
 const DEFAULT_MAX_URL_LENGTH = 2048;
 /** Default allowed protocols. */
 const DEFAULT_ALLOWED_PROTOCOLS = ["http:", "https:"];
-/**
- * Path traversal patterns that indicate directory traversal attacks.
- */
-const TRAVERSAL_PATTERNS = [
-    /\.\./, // Simple ..
-    /%2e%2e/i, // URL-encoded ..
-    /%252e%252e/i, // Double-encoded ..
-    /\.\.%2f/i, // Mixed encoding
-    /\.\.%5c/i, // Mixed encoding with backslash
-];
+/** Maximum percent-decoding rounds before input is considered hostile. */
+const MAX_DECODE_ROUNDS = 8;
 /**
  * Null byte patterns.
+ *
+ * Kept alongside full decoding because a caller may pass a target that is not
+ * decodable (invalid escapes) and still contains a literal or encoded NUL.
  */
 const NULL_BYTE_PATTERNS = [
     /\x00/, // Actual null byte
@@ -27,9 +22,91 @@ const NULL_BYTE_PATTERNS = [
     /%2500/i, // Double-encoded null byte
 ];
 /**
- * Invalid percent-encoding patterns.
+ * Invalid percent-encoding.
+ *
+ * A `%` must be followed by exactly two hex digits. The lookahead also catches
+ * a truncated escape at the very end of the string, which a "`%` plus one
+ * character" pattern silently accepts.
+ */
+const INVALID_PERCENT_ENCODING = /%(?![0-9a-fA-F]{2})/;
+/**
+ * Control characters that must never appear in a request target.
+ *
+ * Tab is tolerated; CR and LF are not. Leaving those two out of the class —
+ * as an "everything except tab" range easily does — is what allows a target to
+ * be reflected into a header and split the response.
+ */
+const TARGET_CONTROL_CHARS = /[\x00-\x08\x0A-\x1F\x7F]/;
+/**
+ * Fully percent-decodes a string, up to {@link MAX_DECODE_ROUNDS} times.
+ *
+ * Traversal sequences cannot be recognised reliably by pattern-matching an
+ * encoded string: `..`, `%2e%2e`, `.%2e`, `%2e.` and their double-encoded
+ * forms are all the same path, and the variant space grows with every round of
+ * encoding. Decoding to a fixed point first collapses them into one shape.
+ *
+ * @param value - The string to decode.
+ * @returns The decoded string and whether decoding terminated cleanly.
+ */
+export function fullyDecodeUri(value) {
+    let current = value;
+    let malformed = INVALID_PERCENT_ENCODING.test(value);
+    for (let round = 0; round < MAX_DECODE_ROUNDS; round++) {
+        const { decoded: next, malformed: roundMalformed } = decodeOnce(current);
+        if (roundMalformed)
+            malformed = true;
+        if (next === current) {
+            return { decoded: current, truncated: false, malformed };
+        }
+        current = next;
+    }
+    // Still changing after the cap: treat as hostile rather than looping.
+    return { decoded: current, truncated: true, malformed };
+}
+/**
+ * One decoding round that survives a malformed escape.
+ *
+ * `decodeURIComponent` throws for the *whole* string if any escape in it is
+ * bad, so a single stray `%` anywhere used to abort decoding entirely and
+ * return the still-encoded input with `truncated: false`. Every downstream
+ * check then ran against the encoded form: `/a/%2e%2e/etc/passwd%` was
+ * reported valid, and so was `/a%0d%0aX-Evil:1%`. That is a fail-open guard.
+ *
+ * Decoding run-by-run instead keeps multi-byte sequences intact (a run of
+ * valid triplets is a complete UTF-8 character) while leaving an invalid run
+ * as literal text, so the rest of the string still collapses to its true
+ * shape and `malformed` records that something was wrong.
+ */
+function decodeOnce(value) {
+    let malformed = false;
+    const decoded = value.replace(/(?:%[0-9a-fA-F]{2})+/g, (run) => {
+        try {
+            return decodeURIComponent(run);
+        }
+        catch {
+            malformed = true;
+            return run;
+        }
+    });
+    return { decoded, malformed };
+}
+/**
+ * Checks whether a path contains a traversal segment.
+ *
+ * Operates on the fully decoded form, and treats a backslash as a separator
+ * because Windows and some proxies do.
+ *
+ * @param path - The path to inspect.
+ * @returns True when a `..` segment is present.
  */
-const INVALID_PERCENT_ENCODING = /%[^0-9a-fA-F]|%(?:[0-9a-fA-F][^0-9a-fA-F])/;
+export function containsTraversal(path) {
+    const { decoded, truncated } = fullyDecodeUri(path);
+    if (truncated)
+        return true;
+    return decoded
+        .split(/[/\\]/)
+        .some((segment) => segment === ".." || segment === "...");
+}
 /**
  * Validates a URL against security configuration.
  *
@@ -69,25 +146,35 @@ export function validateUrl(url, config) {
     if (!allowedProtocols.includes(parsed.protocol)) {
         errors.push(`Protocol "${parsed.protocol}" is not allowed (allowed: ${allowedProtocols.join(", ")})`);
     }
-    // Check for path traversal (check raw URL, not normalized pathname)
+    // Check for path traversal against the raw path, decoded to a fixed point.
     if (config?.blockTraversal !== false) {
-        // Extract raw path from URL before normalization
         const rawPath = url.split("?")[0]?.split("#")[0] ?? "";
-        for (const pattern of TRAVERSAL_PATTERNS) {
-            if (pattern.test(rawPath)) {
-                errors.push("URL contains path traversal attempts");
-                break;
-            }
+        if (containsTraversal(rawPath)) {
+            errors.push("URL contains path traversal attempts");
         }
     }
+    // `normalizePaths` was declared on UrlValidationConfig and read only by
+    // validateRequestTarget, so `UrlValidationResult.normalized` was never once
+    // populated by this function — the field looked optional-by-chance rather
+    // than opt-in.
+    let normalized;
+    if (config?.normalizePaths === true) {
+        const rebuilt = new URL(parsed.href);
+        rebuilt.pathname = normalizePath(parsed.pathname);
+        normalized = rebuilt.href;
+    }
     return {
         valid: errors.length === 0,
+        normalized,
         errors,
     };
 }
 /**
  * Normalizes a URL path by resolving . and .. segments.
  *
+ * `..` never escapes the root: at depth zero it is discarded rather than
+ * popping into the parent.
+ *
  * @param pathname - The path to normalize.
  * @returns The normalized path.
  */
@@ -119,6 +206,13 @@ export function normalizePath(pathname) {
  */
 export function validateRequestTarget(target, config) {
     const errors = [];
+    // `maxLength` was accepted and discarded here, leaving the request target —
+    // the one input that arrives straight off the wire — with no length bound
+    // at all.
+    const maxLength = config?.maxLength ?? DEFAULT_MAX_URL_LENGTH;
+    if (target.length > maxLength) {
+        errors.push(`Request target length ${target.length} exceeds maximum ${maxLength}`);
+    }
     // Check for null bytes
     for (const pattern of NULL_BYTE_PATTERNS) {
         if (pattern.test(target)) {
@@ -128,17 +222,28 @@ export function validateRequestTarget(target, config) {
     }
     // Check for path traversal
     if (config?.blockTraversal !== false) {
-        for (const pattern of TRAVERSAL_PATTERNS) {
-            if (pattern.test(target)) {
-                errors.push("Request target contains path traversal attempts");
-                break;
-            }
+        if (containsTraversal(target.split("?")[0] ?? "")) {
+            errors.push("Request target contains path traversal attempts");
         }
     }
-    // Check for control characters (except tab)
-    if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(target)) {
+    // Check for control characters (tab is tolerated; CR and LF are not)
+    if (TARGET_CONTROL_CHARS.test(target)) {
         errors.push("Request target contains control characters");
     }
+    // `validateUrl` has always rejected a malformed escape; the request-target
+    // path did not, which is how a single trailing `%` used to disable both the
+    // traversal and the encoded-CRLF checks below.
+    if (INVALID_PERCENT_ENCODING.test(target)) {
+        errors.push("Request target contains invalid percent encoding (a % must be followed by two hex digits)");
+    }
+    // A decoded CR/LF is just as dangerous as a literal one. Run this whenever
+    // decoding produced anything, rather than only when the whole string
+    // changed.
+    const { decoded } = fullyDecodeUri(target);
+    if (!TARGET_CONTROL_CHARS.test(target) &&
+        TARGET_CONTROL_CHARS.test(decoded)) {
+        errors.push("Request target contains encoded control characters");
+    }
     // Normalize if requested
     let normalized;
     if (config?.normalizePaths) {
@@ -155,33 +260,155 @@ export function validateRequestTarget(target, config) {
         errors,
     };
 }
+/* ─── Private network detection ──────────────────────────────────────────── */
+/**
+ * Parses a dotted-quad IPv4 address into its four octets.
+ *
+ * Returns undefined for anything that is not already in canonical form —
+ * decimal (`2130706433`) and octal (`0177.0.0.1`) hosts are normalised to
+ * dotted-quad by the WHATWG URL parser before this is reached.
+ */
+function parseIpv4(hostname) {
+    const parts = hostname.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return undefined;
+        const n = Number(part);
+        if (n > 255)
+            return undefined;
+        octets.push(n);
+    }
+    return octets;
+}
+/** True when the dotted-quad address falls in a private or special-use range. */
+function isPrivateIpv4(octets) {
+    const [a = 0, b = 0] = octets;
+    return (a === 0 || // 0.0.0.0/8 "this network" — resolves to localhost on Linux
+        a === 10 || // 10.0.0.0/8 private
+        a === 127 || // 127.0.0.0/8 loopback (all of it, not just 127.0.0.1)
+        (a === 100 && b >= 64 && b <= 127) || // 100.64.0.0/10 CGNAT
+        (a === 169 && b === 254) || // 169.254.0.0/16 link-local + cloud metadata
+        (a === 172 && b >= 16 && b <= 31) || // 172.16.0.0/12 private
+        (a === 192 && b === 168) || // 192.168.0.0/16 private
+        (a === 192 && b === 0) || // 192.0.0.0/24 + 192.0.2.0/24 special-use
+        (a === 198 && (b === 18 || b === 19)) || // 198.18.0.0/15 benchmarking
+        a >= 224 // 224/4 multicast, 240/4 reserved, 255.255.255.255 broadcast
+    );
+}
+/**
+ * True when an IPv6 hostname (already stripped of brackets) is private.
+ *
+ * Also unwraps IPv4-mapped and IPv4-compatible forms, so `::ffff:127.0.0.1`
+ * is recognised as loopback rather than treated as an opaque v6 address.
+ */
+function isPrivateIpv6(hostname) {
+    const host = hostname.toLowerCase();
+    if (host === "::1" || host === "::" || host === "::0")
+        return true;
+    // IPv4-mapped (::ffff:127.0.0.1) and IPv4-compatible (::127.0.0.1)
+    const mapped = /^::(?:ffff:)?(\d{1,3}(?:\.\d{1,3}){3})$/.exec(host);
+    if (mapped?.[1]) {
+        const octets = parseIpv4(mapped[1]);
+        return octets ? isPrivateIpv4(octets) : true;
+    }
+    // Hex-form IPv4-mapped: ::ffff:7f00:1
+    const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+    if (hexMapped?.[1] && hexMapped[2]) {
+        const high = parseInt(hexMapped[1], 16);
+        const low = parseInt(hexMapped[2], 16);
+        const octets = [high >> 8, high & 0xff, low >> 8, low & 0xff];
+        return isPrivateIpv4(octets);
+    }
+    const firstGroup = host.split(":")[0] ?? "";
+    const leading = parseInt(firstGroup.padEnd(4, "0"), 16);
+    // fc00::/7 unique local
+    if ((leading & 0xfe00) === 0xfc00)
+        return true;
+    // fe80::/10 link-local
+    if ((leading & 0xffc0) === 0xfe80)
+        return true;
+    return false;
+}
+/**
+ * Hostnames that resolve inside the local network or to a metadata service.
+ */
+const BLOCKED_HOSTNAMES = new Set([
+    "localhost",
+    "metadata.google.internal",
+    "metadata",
+    "instance-data",
+]);
+/** Hostname suffixes reserved for local or internal resolution. */
+const BLOCKED_HOST_SUFFIXES = [
+    ".localhost",
+    ".local",
+    ".internal",
+    ".localdomain",
+];
+/**
+ * Checks whether a hostname points at a private, loopback, link-local or
+ * otherwise internal destination.
+ *
+ * @param hostname - The hostname to check (as produced by `URL.hostname`).
+ * @returns True when the hostname is not safe to reach outward.
+ */
+export function isPrivateHostname(hostname) {
+    const host = hostname.toLowerCase().replace(/\.$/, "");
+    if (host.length === 0)
+        return true;
+    if (BLOCKED_HOSTNAMES.has(host))
+        return true;
+    if (BLOCKED_HOST_SUFFIXES.some((suffix) => host.endsWith(suffix)))
+        return true;
+    // URL.hostname keeps IPv6 literals in brackets.
+    if (host.startsWith("[") && host.endsWith("]")) {
+        return isPrivateIpv6(host.slice(1, -1));
+    }
+    if (host.includes(":")) {
+        return isPrivateIpv6(host);
+    }
+    const octets = parseIpv4(host);
+    if (octets) {
+        return isPrivateIpv4(octets);
+    }
+    return false;
+}
 /**
  * Checks if a URL is safe to follow (not pointing to internal resources).
  *
+ * Only `http:` and `https:` are allowed by default — every other scheme,
+ * including `file:`, `gopher:`, `data:` and `blob:`, is rejected rather than
+ * denied one at a time.
+ *
+ * **This cannot stop DNS rebinding.** A public hostname may resolve to a
+ * private address, and may resolve differently between this check and the
+ * connection. For outbound requests that must be safe, resolve the hostname
+ * yourself, run {@link isPrivateHostname} against the resolved address, and
+ * connect to that address directly.
+ *
  * @param url - The URL to check.
+ * @param allowedProtocols - Protocols to permit (default: http and https).
  * @returns True if the URL appears safe.
  */
-export function isSafeUrl(url) {
+export function isSafeUrl(url, allowedProtocols = DEFAULT_ALLOWED_PROTOCOLS) {
+    let parsed;
     try {
-        const parsed = new URL(url);
-        // Block file:// protocol
-        if (parsed.protocol === "file:") {
-            return false;
-        }
-        // Block internal network ranges (basic check)
-        const hostname = parsed.hostname;
-        if (hostname === "localhost" ||
-            hostname === "127.0.0.1" ||
-            hostname === "::1" ||
-            hostname.startsWith("192.168.") ||
-            hostname.startsWith("10.") ||
-            hostname.startsWith("172.")) {
-            return false;
-        }
-        return true;
+        parsed = new URL(url);
     }
     catch {
         return false;
     }
+    if (!allowedProtocols.includes(parsed.protocol)) {
+        return false;
+    }
+    // Credentials in a URL are a redirect-laundering vector and never needed
+    // for a target this function is asked to vouch for.
+    if (parsed.username || parsed.password) {
+        return false;
+    }
+    return !isPrivateHostname(parsed.hostname);
 }
 //# sourceMappingURL=url.core.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/security",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
   "license": "MIT",
   "type": "module",
@@ -14,11 +14,14 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "0.0.1",
-    "@zudojs/constants": "0.0.1"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
@@ -39,14 +42,18 @@
     "rate-limiting"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/security"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   }