tezx 3.0.14-beta → 3.0.14-beta2

package/middleware/secure-headers copy.js

@@ -0,0 +1,136 @@
+import crypto from "crypto";
+const joinSrc = (v) => typeof v === "string" ? v : v.join(" ");
+const buildCSPString = (cspObj) => {
+    const parts = [];
+    for (const key in cspObj) {
+        parts.push(`${key} ${joinSrc(cspObj[key])}`);
+    }
+    return parts.join("; ");
+};
+const defaultPresets = {
+    strict: {
+        preset: "strict",
+        hsts: true,
+        hstsMaxAge: 63072000,
+        frameGuard: "DENY",
+        noSniff: true,
+        xssProtection: true,
+        referrerPolicy: "strict-origin-when-cross-origin",
+        permissionsPolicy: "geolocation=(), microphone=(), camera=(), usb=()",
+        csp: {
+            "default-src": ["'self'"],
+            "script-src": ["'self'"],
+            "style-src": ["'self'", "'unsafe-inline'"],
+            "img-src": ["'self'", "data:", "blob:"],
+            "font-src": ["'self'"],
+            "connect-src": ["'self'"],
+            "object-src": ["'none'"],
+            "frame-ancestors": ["'none'"],
+        },
+        cspReportOnly: false,
+    },
+    balanced: {
+        preset: "balanced",
+        hsts: true,
+        hstsMaxAge: 31536000,
+        frameGuard: "SAMEORIGIN",
+        noSniff: true,
+        xssProtection: true,
+        referrerPolicy: "no-referrer-when-downgrade",
+        permissionsPolicy: "geolocation=(), microphone=()",
+        csp: {
+            "default-src": ["'self'"],
+            "script-src": ["'self'", "https://cdn.jsdelivr.net"],
+            "style-src": [
+                "'self'",
+                "'unsafe-inline'",
+                "https://fonts.googleapis.com",
+            ],
+            "img-src": ["'self'", "data:", "https://images.example.com"],
+            "connect-src": ["'self'", "https://api.example.com"],
+        },
+        cspReportOnly: true,
+    },
+    dev: {
+        preset: "dev",
+        hsts: false,
+        frameGuard: "SAMEORIGIN",
+        noSniff: false,
+        xssProtection: false,
+        referrerPolicy: "no-referrer",
+        permissionsPolicy: "",
+        csp: {
+            "default-src": [
+                "'self'",
+                "'unsafe-inline'",
+                "'unsafe-eval'",
+                "http://localhost:3000",
+            ],
+            "img-src": ["'self'", "data:", "blob:"],
+        },
+        cspReportOnly: true,
+    },
+};
+const setHeader = (ctx, name, value) => {
+    if (typeof ctx.setHeader === "function")
+        ctx.setHeader(name, value);
+    else if (ctx.response?.setHeader)
+        ctx.response.setHeader(name, value);
+    else if (ctx.headersOut)
+        ctx.headersOut[name] = value;
+};
+export const secureHeaders = (userOpts = {}) => {
+    const preset = userOpts.preset ?? "balanced";
+    const base = {
+        ...(defaultPresets[preset] || defaultPresets.balanced),
+        ...userOpts,
+    };
+    const hstsHeader = base.hsts
+        ? `max-age=${base.hstsMaxAge || 31536000}; includeSubDomains; preload`
+        : "";
+    const frameHeader = base.frameGuard || "SAMEORIGIN";
+    const noSniffHeader = base.noSniff ? "nosniff" : "";
+    const xssHeader = base.xssProtection ? "1; mode=block" : "0";
+    const referrerHeader = base.referrerPolicy || "no-referrer";
+    const permissionsHeader = base.permissionsPolicy || "";
+    let cspStatic = null;
+    let cspNeedsNonce = !!base.cspUseNonce;
+    if (typeof base.csp === "string")
+        cspStatic = base.csp;
+    else if (base.csp && typeof base.csp === "object")
+        cspStatic = buildCSPString(base.csp);
+    if (base.ultraFastMode)
+        cspNeedsNonce = false;
+    const cspReportOnly = !!base.cspReportOnly;
+    return async (ctx, next) => {
+        try {
+            if (base.hsts)
+                setHeader(ctx, "Strict-Transport-Security", hstsHeader);
+            setHeader(ctx, "X-Frame-Options", frameHeader);
+            setHeader(ctx, "X-Content-Type-Options", noSniffHeader);
+            setHeader(ctx, "X-XSS-Protection", xssHeader);
+            setHeader(ctx, "Referrer-Policy", referrerHeader);
+            if (permissionsHeader)
+                setHeader(ctx, "Permissions-Policy", permissionsHeader);
+            if (cspNeedsNonce) {
+                const nonce = crypto.randomBytes(12).toString("base64");
+                let cspHeader = cspStatic || `default-src 'self'; script-src 'self' 'nonce-${nonce}'`;
+                if (cspReportOnly)
+                    setHeader(ctx, "Content-Security-Policy-Report-Only", cspHeader);
+                else
+                    setHeader(ctx, "Content-Security-Policy", cspHeader);
+                ctx.cspNonce = nonce;
+            }
+            else if (cspStatic) {
+                if (cspReportOnly)
+                    setHeader(ctx, "Content-Security-Policy-Report-Only", cspStatic);
+                else
+                    setHeader(ctx, "Content-Security-Policy", cspStatic);
+            }
+            return await next();
+        }
+        catch {
+            return await next();
+        }
+    };
+};

package/middleware/secure-headers.d.ts

@@ -0,0 +1,132 @@
+import { Middleware } from "../types/index.js";
+/**
+ * Options for HTTP Strict Transport Security (HSTS) header.
+ */
+export interface HstsOptions {
+    /**
+     * Max age in seconds for the `Strict-Transport-Security` header.
+     * Example: 31536000 (1 year)
+     */
+    maxAge?: number;
+    /**
+     * Apply HSTS to subdomains by adding `includeSubDomains` directive.
+     * Default: false
+     */
+    includeSubDomains?: boolean;
+    /**
+     * Add `preload` directive for browser preload lists.
+     * Default: false
+     */
+    preload?: boolean;
+    /**
+     * Only apply HSTS on HTTPS requests.
+     * If true, HTTP requests will not receive the HSTS header.
+     * Default: false
+     */
+    hstsOnlyOnHttps?: boolean;
+}
+/**
+ * Options for the secureHeaders middleware.
+ */
+export type SecureHeadersOptions = {
+    /**
+     * Built-in preset to use.
+     * - "strict": strongest defaults for production.
+     * - "balanced": reasonable defaults for most apps (report-only CSP by default).
+     * - "dev": permissive settings useful for local development.
+     *
+     * @default "balanced"
+     */
+    preset?: "strict" | "balanced" | "dev";
+    /**
+     * HSTS (HTTP Strict Transport Security) options.
+     * If provided, the middleware will set the `Strict-Transport-Security` header.
+     *
+     * @example
+     * { maxAge: 31536000, includeSubDomains: true, preload: true }
+     */
+    hsts?: HstsOptions;
+    /**
+     * Value for `X-Frame-Options` header.
+     * Common values: "DENY", "SAMEORIGIN".
+     *
+     * @default "SAMEORIGIN"
+     */
+    frameGuard?: "DENY" | "SAMEORIGIN" | string;
+    /**
+     * If true, sets `X-Content-Type-Options: nosniff`.
+     *
+     * @default true (depends on preset)
+     */
+    noSniff?: boolean;
+    /**
+     * If true, sets `X-XSS-Protection: 1; mode=block`.
+     * Note: modern browsers use CSP; this header is legacy but harmless.
+     *
+     * @default true (depends on preset)
+     */
+    xssProtection?: boolean;
+    /**
+     * Value for `Referrer-Policy` header.
+     * Examples: "no-referrer", "strict-origin-when-cross-origin".
+     *
+     * @default "no-referrer" (depends on preset)
+     */
+    referrerPolicy?: string;
+    /**
+     * Value for `Permissions-Policy` (formerly Feature-Policy).
+     * Example: 'geolocation=(), microphone=()'
+     *
+     * @default '' (empty string = not set)
+     */
+    permissionsPolicy?: string;
+    /**
+     * Content Security Policy (CSP).
+     * - Pass a raw header string to use it unchanged.
+     * - Or pass an object mapping directives to sources (object will be prebuilt at init).
+     *
+     * Example object:
+     * {
+     *   "default-src": ["'self'"],
+     *   "script-src": ["'self'", "https://cdn.example.com"]
+     * }
+     */
+    csp?: string | Record<string, string | string[]>;
+    /**
+     * If true, send `Content-Security-Policy-Report-Only` instead of enforcement header.
+     * Useful when first testing policies.
+     *
+     * @default false
+     */
+    cspReportOnly?: boolean;
+    /**
+     * If true, middleware will generate a per-request nonce (string) and inject it
+     * into the `script-src` directive so inline scripts with that nonce are allowed.
+     * Note: nonce generation allocates a small string per-request unless `ultraFastMode` is enabled.
+     *
+     * @default false
+     */
+    cspUseNonce?: boolean;
+    /**
+     * Ultra-fast mode disables per-request allocations (e.g., nonce generation).
+     * Use this in high-QPS environments where inline scripts are not required.
+     *
+     * @default false
+     */
+    ultraFastMode?: boolean;
+};
+/**
+ * secureHeaders middleware
+ *
+ * Precomputes static headers (HSTS, static CSP, X-Frame-Options, etc.) at
+ * middleware creation time. Optionally supports per-request CSP nonces
+ * (disabled in ultraFastMode).
+ *
+ * @template T,Path
+ * @param {SecureHeadersOptions} [userOpts={}] - configuration overrides
+ * @returns {Middleware<T,Path>} TezX-compatible middleware
+ *
+ * @example
+ * app.use(secureHeaders({ preset: 'strict', cspUseNonce: true }));
+ */
+export declare const secureHeaders: <T extends Record<string, any> = {}, Path extends string = any>(userOpts?: SecureHeadersOptions) => Middleware<T, Path>;

package/middleware/secure-headers.js

@@ -0,0 +1,153 @@
+import { generateRandomBase64, GlobalConfig } from "../helper/index.js";
+const joinSrc = (v) => typeof v === "string" ? v : v.join(" ");
+const buildCSPString = (cspObj) => {
+    const parts = [];
+    for (const key in cspObj)
+        parts.push(`${key} ${joinSrc(cspObj[key])}`);
+    return parts.join("; ");
+};
+export const secureHeaders = (userOpts = {}) => {
+    const defaultPresets = {
+        strict: {
+            preset: "strict",
+            hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
+            frameGuard: "DENY",
+            noSniff: true,
+            xssProtection: true,
+            referrerPolicy: "strict-origin-when-cross-origin",
+            permissionsPolicy: "geolocation=(), microphone=(), camera=(), usb=()",
+            csp: {
+                "default-src": ["'self'"],
+                "script-src": ["'self'"],
+                "style-src": ["'self'", "'unsafe-inline'"],
+                "img-src": ["'self'", "data:", "blob:"],
+                "font-src": ["'self'"],
+                "connect-src": ["'self'"],
+                "object-src": ["'none'"],
+                "frame-ancestors": ["'none'"],
+            },
+            cspReportOnly: false,
+        },
+        balanced: {
+            preset: "balanced",
+            hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+            frameGuard: "SAMEORIGIN",
+            noSniff: true,
+            xssProtection: true,
+            referrerPolicy: "no-referrer-when-downgrade",
+            permissionsPolicy: "geolocation=(), microphone=()",
+            csp: {
+                "default-src": ["'self'"],
+                "script-src": ["'self'", "https://cdn.jsdelivr.net"],
+                "style-src": [
+                    "'self'",
+                    "'unsafe-inline'",
+                    "https://fonts.googleapis.com",
+                ],
+                "img-src": ["'self'", "data:", "https://images.example.com"],
+                "connect-src": ["'self'", "https://api.example.com"],
+            },
+            cspReportOnly: true,
+        },
+        dev: {
+            preset: "dev",
+            hsts: undefined,
+            frameGuard: "SAMEORIGIN",
+            noSniff: false,
+            xssProtection: false,
+            referrerPolicy: "no-referrer",
+            permissionsPolicy: "",
+            csp: {
+                "default-src": [
+                    "'self'",
+                    "'unsafe-inline'",
+                    "'unsafe-eval'",
+                    "http://localhost:3000",
+                ],
+                "img-src": ["'self'", "data:", "blob:"],
+            },
+            cspReportOnly: true,
+        },
+    };
+    const preset = userOpts.preset ?? "balanced";
+    const base = {
+        ...(defaultPresets[preset] || defaultPresets.balanced),
+        ...userOpts,
+    };
+    const frameHeader = base.frameGuard || "SAMEORIGIN";
+    const xssHeader = base.xssProtection ? "1; mode=block" : "0";
+    const noSniffHeader = base.noSniff ? "nosniff" : "";
+    const permissionsHeader = base.permissionsPolicy || "";
+    const referrerHeader = base.referrerPolicy || "no-referrer";
+    const hstsParts = [`max-age=${base.hsts?.maxAge || 31536000}`];
+    if (base.hsts?.includeSubDomains)
+        hstsParts.push("includeSubDomains");
+    if (base.hsts?.preload)
+        hstsParts.push("preload");
+    const hstsHeader = hstsParts.join("; ");
+    let cspStatic = null;
+    let cspNeedsNonce = !!base.cspUseNonce;
+    if (typeof base.csp === "string")
+        cspStatic = base.csp;
+    else if (base.csp)
+        cspStatic = buildCSPString(base.csp);
+    const cspReportOnly = !!base.cspReportOnly;
+    const ultraFast = !!base.ultraFastMode;
+    if (cspNeedsNonce && ultraFast) {
+        GlobalConfig.debugging.warn("secureHeaders: ultraFastMode disables CSP nonce support. Nonce will not be used.");
+    }
+    if (ultraFast)
+        cspNeedsNonce = false;
+    return async (ctx, next) => {
+        try {
+            if (base.hsts) {
+                const proto = (ctx.req?.header("x-forwarded-proto") || "").toString();
+                if (!base.hsts.hstsOnlyOnHttps || proto.includes("https")) {
+                    ctx.headers.set("Strict-Transport-Security", hstsHeader);
+                }
+            }
+            ctx.headers.set("X-Frame-Options", frameHeader);
+            ctx.headers.set("X-Content-Type-Options", noSniffHeader);
+            ctx.headers.set("X-XSS-Protection", xssHeader);
+            ctx.headers.set("Referrer-Policy", referrerHeader);
+            if (permissionsHeader)
+                ctx.headers.set("Permissions-Policy", permissionsHeader);
+            if (cspNeedsNonce) {
+                const nonce = generateRandomBase64();
+                let cspHeader = cspStatic;
+                if (!cspHeader) {
+                    cspHeader = `default-src 'self'; script-src 'self' 'nonce-${nonce}'`;
+                }
+                if (typeof base.csp === "object") {
+                    const idx = cspHeader.indexOf("script-src");
+                    if (idx >= 0) {
+                        const parts = [];
+                        parts.push(cspHeader.slice(0, idx + 10));
+                        parts.push(" 'nonce-" + nonce + "'");
+                        parts.push(cspHeader.slice(idx + 10));
+                        cspHeader = parts.join("");
+                    }
+                    else {
+                        cspHeader += "; script-src 'self' 'nonce-" + nonce + "'";
+                    }
+                }
+                ctx.cspNonce = nonce;
+                if (cspReportOnly)
+                    ctx.headers.set("Content-Security-Policy-Report-Only", cspHeader);
+                else
+                    ctx.headers.set("Content-Security-Policy", cspHeader);
+            }
+            else if (cspStatic) {
+                if (cspReportOnly)
+                    ctx.headers.set("Content-Security-Policy-Report-Only", cspStatic);
+                else
+                    ctx.headers.set("Content-Security-Policy", cspStatic);
+            }
+            return await next();
+        }
+        catch (err) {
+            console.error("secureHeaders middleware error", err);
+            return await next();
+        }
+    };
+};

package/node/env.js

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
-import { runtime } from "../utils/runtime.js";
+import { TezXError } from "../core/error.js";
 import { colorText } from "../utils/colors.js";
+import { runtime } from "../utils/runtime.js";
 function parseEnvFile(filePath, result) {
     try {
-        if (runtime !== "bun" && runtime !== "node") {
-            throw new Error(`Please use ${colorText(`import {loadEnv} from "tezx/${runtime}"`, "bgRed")} environment`);
+        if (runtime !== "node") {
+            throw new TezXError(`Please use ${colorText(`import {loadEnv} from "tezx/${runtime}"`, "bgRed")} environment`);
         }
         let fileExists = existsSync(filePath);
         if (!fileExists) {

package/node/serveStatic.d.ts

@@ -15,6 +15,14 @@ import { ServeStatic, StaticFileArray, StaticServeOption } from "../types/index.
  * @param args - Either [route, folder, option] or [folder, option]
  * @returns A list of static files and their associated route paths.
  */
+/**
+ * Universal ETag generator for Deno, Bun, and Node.js environments.
+ * Uses file size + modification time (mtimeMs) to create a unique hash-based ETag.
+ *
+ * @example
+ * const etag = await getETag("/path/to/file.txt");
+ * ctx.setHeader("ETag", etag);
+ */
 export declare function serveStatic(route: string, folder: string, option?: StaticServeOption): ServeStatic;
 export declare function serveStatic(folder: string, option?: StaticServeOption): ServeStatic;
 /**

package/node/serveStatic.js

@@ -1,6 +1,7 @@
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
 import { extensionExtract, sanitizePathSplitBasePath, } from "../utils/low-level.js";
+import { TezXError } from "../core/error.js";
 export function serveStatic(...args) {
     let route = "";
     let dir;
@@ -21,7 +22,7 @@ export function serveStatic(...args) {
             [dir] = args;
             break;
         default:
-            throw new Error(`\x1b[1;31m404 Not Found\x1b[0m \x1b[1;32mInvalid arguments\x1b[0m`);
+            throw new TezXError(`\x1b[1;31m404 Not Found\x1b[0m \x1b[1;32mInvalid arguments\x1b[0m`);
     }
     return {
         files: getFiles(dir, route, options),

package/node/ws.d.ts

@@ -22,7 +22,7 @@ export type nodeWebSocketOptions = {
  *
  * @param {WebSocketCallback} callback - Function that returns WebSocket event handlers.
  * @param {WebSocketOptions} [options={}] - Options for WebSocket upgrade behavior.
- * @param {(error: Error, ctx: T) => any} [options.onUpgradeError] - Custom error handler for upgrade failures.
+ * @param {(error: TezXError, ctx: T) => any} [options.onUpgradeError] - Custom error handler for upgrade failures.
  * @param {number} [options.maxPayload=1048576] - Maximum allowed payload size (in bytes).
  * @param {boolean} [options.perMessageDeflate=false] - Whether to enable per-message deflate.
  *

package/node/ws.js

@@ -1,3 +1,4 @@
+import { TezXError } from "../core/error.js";
 export function upgradeWebSocket(callback, options = {}) {
     const { onUpgradeError = (error, ctx) => {
         ctx.setStatus = 401;
@@ -13,13 +14,13 @@ export function upgradeWebSocket(callback, options = {}) {
                 return next();
             }
             ctx.setStatus = 401;
-            return onUpgradeError(new Error("401 Bad Request: Invalid WebSocket headers"), ctx);
+            return onUpgradeError(new TezXError("401 Bad Request: Invalid WebSocket headers", 401), ctx);
         }
         ctx.wsProtocol = ctx.url?.startsWith("https") ? "wss" : "ws";
         const server = ctx.args?.[2];
         if (!server?.on) {
             ctx.setStatus = 500;
-            return onUpgradeError(new Error("Node server instance missing for WebSocket"), ctx);
+            return onUpgradeError(new TezXError("Node server instance missing for WebSocket", 426), ctx);
         }
         const { WebSocketServer } = await import("ws");
         const wss = new WebSocketServer({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tezx",
-  "version": "3.0.14-beta",
+  "version": "3.0.14-beta2",
   "description": "TezX is a high-performance, lightweight JavaScript framework designed for speed, scalability, and flexibility. It enables efficient routing, middleware management, and static file serving with minimal configuration. Fully compatible with Node.js, Deno, and Bun.",
   "type": "module",
   "main": "cjs/index.js",
@@ -42,6 +42,16 @@
       "require": "./cjs/helper/index.js",
       "types": "./helper/index.d.ts"
     },
+    "./jwt/node": {
+      "import": "./jwt/node.js",
+      "require": "./cjs/jwt/node.js",
+      "types": "./jwt/node.d.ts"
+    },
+    "./jwt/web": {
+      "import": "./jwt/web.js",
+      "require": "./cjs/jwt/web.js",
+      "types": "./jwt/web.d.ts"
+    },
     "./registry": {
       "import": "./registry/index.js",
       "require": "./cjs/registry/index.js",
@@ -64,6 +74,7 @@
     "core/",
     "deno/",
     "helper/",
+    "jwt/",
     "middleware/",
     "node/",
     "registry/",

package/registry/RadixRouter.js

@@ -1,3 +1,4 @@
+import { TezXError } from "../core/error.js";
 import { sanitizePathSplit } from "../helper/index.js";
 export class RadixRouter {
     root = { children: {} };
@@ -19,7 +20,7 @@ export class RadixRouter {
                 }
                 else if (node.children[":"]?.paramName !== paramName ||
                     node.children[":"]?.isOptional !== isOptional) {
-                    throw new Error(`Conflicting param definition for ${paramName}`);
+                    throw new TezXError(`Conflicting param definition for ${paramName}`);
                 }
                 node = node.children[":"];
             }
@@ -141,35 +142,3 @@ export class RadixRouter {
         return result;
     }
 }
-const routes = [
-    "/",
-    "/users",
-    "/users/:id",
-    "/users/:id/profile",
-    "/posts/:postId?",
-    "/files/*",
-    "/admin/settings",
-    "/search/:term?",
-    "/categories/:categoryId/products/:productId",
-    "/about",
-];
-const testPaths = [
-    "/",
-    "/users",
-    "/users/123",
-    "/users/123/profile",
-    "/posts",
-    "/posts/456",
-    "/files/path/to/file.txt",
-    "/admin/settings",
-    "/search",
-    "/search/nodejs",
-    "/categories/12/products/999",
-    "/notfound",
-];
-const router = new RadixRouter();
-let x = function xx() {
-    return {
-        body: "3453455",
-    };
-};

package/types/index.d.ts

@@ -61,7 +61,7 @@ export type WebSocketOptions = {
     /**
      * Called when an error occurs during the upgrade process.
      */
-    onUpgradeError?: (err: Error, ctx: Context) => HttpBaseResponse;
+    onUpgradeError?: (err: TezXError, ctx: Context) => HttpBaseResponse;
 };
 /**
  * Represents a string key used for HTTP headers.

package/utils/buffer.d.ts

@@ -0,0 +1 @@
+export declare function base64Decode(base64: string): string;

package/utils/buffer.js

@@ -0,0 +1,14 @@
+export function base64Decode(base64) {
+    const pad = base64.length % 4;
+    if (pad)
+        base64 += "=".repeat(4 - pad);
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(base64, "base64").toString("utf-8");
+    }
+    else if (typeof atob === "function") {
+        return new TextDecoder().decode(Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)));
+    }
+    else {
+        throw new Error("Base64 decode not supported in this environment");
+    }
+}

package/utils/file.d.ts

@@ -29,6 +29,10 @@ export declare function readStream(path: string): Promise<ReadableStream>;
  * Supports Node.js, Bun, and Deno runtimes.
  *
  * @param {string} path - Path to the file.
- * @returns {Promise<number>} - Resolves to the file size in bytes.
+ * @returns {Promise<{size: number, mtime: Date}>} - Resolves to the file size in bytes.
  */
-export declare function fileSize(path: string): Promise<number>;
+export declare function fileSize(path: string): Promise<{
+    mtime: Date;
+    size: number;
+}>;
+export declare function etagDigest(algo: string | undefined, data: any): Promise<string>;