@zudojs/security 0.0.1

package/dist/url/url.core.js

@@ -0,0 +1,187 @@
+/**
+ * @zudojs/security — URL Validation
+ *
+ * Validates and normalizes URLs, prevents path traversal attacks,
+ * and ensures request targets are safe.
+ */
+/** Default maximum URL length. */
+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
+];
+/**
+ * Null byte patterns.
+ */
+const NULL_BYTE_PATTERNS = [
+    /\x00/, // Actual null byte
+    /%00/i, // URL-encoded null byte
+    /%2500/i, // Double-encoded null byte
+];
+/**
+ * Invalid percent-encoding patterns.
+ */
+const INVALID_PERCENT_ENCODING = /%[^0-9a-fA-F]|%(?:[0-9a-fA-F][^0-9a-fA-F])/;
+/**
+ * Validates a URL against security configuration.
+ *
+ * @param url - The URL string to validate.
+ * @param config - Optional validation configuration.
+ * @returns Validation result.
+ */
+export function validateUrl(url, config) {
+    const errors = [];
+    const allowedProtocols = config?.allowedProtocols ?? DEFAULT_ALLOWED_PROTOCOLS;
+    const maxLength = config?.maxLength ?? DEFAULT_MAX_URL_LENGTH;
+    // Check length
+    if (url.length > maxLength) {
+        errors.push(`URL length ${url.length} exceeds maximum ${maxLength}`);
+    }
+    // Check for null bytes
+    for (const pattern of NULL_BYTE_PATTERNS) {
+        if (pattern.test(url)) {
+            errors.push("URL contains null bytes");
+            break;
+        }
+    }
+    // Check for invalid percent encoding
+    if (INVALID_PERCENT_ENCODING.test(url)) {
+        errors.push("URL contains invalid percent encoding");
+    }
+    // Try to parse as URL
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        errors.push("URL is malformed");
+        return { valid: false, errors };
+    }
+    // Check protocol
+    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)
+    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;
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Normalizes a URL path by resolving . and .. segments.
+ *
+ * @param pathname - The path to normalize.
+ * @returns The normalized path.
+ */
+export function normalizePath(pathname) {
+    // Split into segments
+    const segments = pathname.split("/");
+    const normalized = [];
+    for (const segment of segments) {
+        if (segment === "." || segment === "") {
+            // Skip current directory references and empty segments
+            continue;
+        }
+        if (segment === "..") {
+            // Go up one level if possible
+            normalized.pop();
+        }
+        else {
+            normalized.push(segment);
+        }
+    }
+    return "/" + normalized.join("/");
+}
+/**
+ * Validates a request target (URI path + query).
+ *
+ * @param target - The request target (e.g., "/users?page=1").
+ * @param config - Optional validation configuration.
+ * @returns Validation result.
+ */
+export function validateRequestTarget(target, config) {
+    const errors = [];
+    // Check for null bytes
+    for (const pattern of NULL_BYTE_PATTERNS) {
+        if (pattern.test(target)) {
+            errors.push("Request target contains null bytes");
+            break;
+        }
+    }
+    // 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;
+            }
+        }
+    }
+    // Check for control characters (except tab)
+    if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(target)) {
+        errors.push("Request target contains control characters");
+    }
+    // Normalize if requested
+    let normalized;
+    if (config?.normalizePaths) {
+        const [path, ...queryParts] = target.split("?");
+        const query = queryParts.join("?");
+        normalized = normalizePath(path ?? "");
+        if (query) {
+            normalized += "?" + query;
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        normalized,
+        errors,
+    };
+}
+/**
+ * Checks if a URL is safe to follow (not pointing to internal resources).
+ *
+ * @param url - The URL to check.
+ * @returns True if the URL appears safe.
+ */
+export function isSafeUrl(url) {
+    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;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=url.core.js.map

package/dist/url/url.core.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zudojs/security",
+  "version": "0.0.1",
+  "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@zudojs/errors": "0.0.1",
+    "@zudojs/constants": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11",
+    "@types/node": "^26.4.1"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zudojs",
+    "security",
+    "cors",
+    "csrf",
+    "rate-limiting"
+  ],
+  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oyinlola-tech/zudo"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}