tezx 1.0.43 → 1.0.45

package/cjs/core/server.js

@@ -7,13 +7,15 @@ const context_1 = require("./context");
 const router_1 = require("./router");
 const params_1 = require("../utils/params");
 class TezX extends router_1.Router {
-    constructor({ basePath = "/", env = {}, debugMode = false, allowDuplicateMw = false, overwriteMethod = true, } = {}) {
+    #onPathResolve;
+    constructor({ basePath = "/", env = {}, debugMode = false, onPathResolve, allowDuplicateMw = false, overwriteMethod = true, } = {}) {
         config_1.GlobalConfig.allowDuplicateMw = allowDuplicateMw;
         config_1.GlobalConfig.overwriteMethod = overwriteMethod;
         if (debugMode) {
             config_1.GlobalConfig.debugMode = debugMode;
         }
         super({ basePath, env });
+        this.#onPathResolve = onPathResolve;
         this.serve = this.serve.bind(this);
     }
     #hashRouter(method, pathname) {
@@ -121,11 +123,19 @@ class TezX extends router_1.Router {
         let ctx = new context_1.Context(req, connInfo);
         const urlRef = ctx.req.urlRef;
         const { pathname } = urlRef;
-        let middlewares = this.#findMiddleware(pathname);
+        let resolvePath = pathname;
+        if (this.#onPathResolve) {
+            resolvePath = this.#onPathResolve(pathname);
+            config_1.GlobalConfig.debugging.warn(`${colors_1.COLORS.white} PATH RESOLVE ${colors_1.COLORS.reset} ${colors_1.COLORS.red}${pathname}${colors_1.COLORS.reset} ➞ ${colors_1.COLORS.cyan}${resolvePath}${colors_1.COLORS.reset}`);
+        }
+        if (typeof resolvePath !== 'string') {
+            throw new Error(`Path resolution failed: expected a string, got ${typeof resolvePath}`);
+        }
+        let middlewares = this.#findMiddleware(resolvePath);
         ctx.env = this.env;
         try {
             let callback = async (ctx) => {
-                const find = this.findRoute(ctx.req.method, pathname);
+                const find = this.findRoute(ctx.req.method, resolvePath);
                 if (find?.callback) {
                     ctx.params = find.params;
                     const callback = find.callback;

package/cjs/index.js

@@ -7,4 +7,4 @@ var server_1 = require("./core/server");
 Object.defineProperty(exports, "TezX", { enumerable: true, get: function () { return server_1.TezX; } });
 var params_1 = require("./utils/params");
 Object.defineProperty(exports, "useParams", { enumerable: true, get: function () { return params_1.useParams; } });
-exports.version = "1.0.43";
+exports.version = "1.0.45";

package/cjs/middleware/basicAuth.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.basicAuth = void 0;
+const config_1 = require("../core/config");
+const colors_1 = require("../utils/colors");
+const detectBot_1 = require("./detectBot");
+const basicAuth = (options) => {
+    const { validateCredentials, getRealm = () => "Restricted Area", onUnauthorized = (ctx, error) => {
+        const realm = getRealm(ctx);
+        ctx.setStatus = 401;
+        ctx.header("WWW-Authenticate", `Basic realm="${realm}"`);
+        ctx.body = { error: error?.message };
+    }, rateLimit, supportedMethods = ["basic", "api-key", "bearer-token"], checkAccess, } = options;
+    let storage = rateLimit?.storage;
+    if (rateLimit && !rateLimit.storage) {
+        storage = (0, detectBot_1.createRateLimitDefaultStorage)();
+    }
+    return async (ctx, next) => {
+        let authMethod;
+        let credentials = {};
+        const authHeader = ctx.req.headers.get("authorization");
+        if (authHeader) {
+            if (authHeader.startsWith("Basic ")) {
+                authMethod = "basic";
+                const base64Credentials = authHeader.split(" ")[1];
+                const decoded = Buffer.from(base64Credentials, "base64").toString("utf-8");
+                const [username, password] = decoded.split(":");
+                credentials = { username, password };
+            }
+            else if (authHeader.startsWith("Bearer ")) {
+                authMethod = "bearer-token";
+                credentials = { token: authHeader.split(" ")[1] };
+            }
+        }
+        else if (ctx.headers.get("x-api-key")) {
+            authMethod = "api-key";
+            credentials = { apiKey: ctx.headers.get("x-api-key") };
+        }
+        if (!authMethod || !supportedMethods.includes(authMethod)) {
+            config_1.GlobalConfig.debugging.error(`${colors_1.COLORS.bgRed}[AUTH]${colors_1.COLORS.reset} Unsupported or missing authentication method.`);
+            return onUnauthorized(ctx, new Error("Unsupported authentication method"));
+        }
+        if (rateLimit) {
+            let key = `${ctx.req.remoteAddress.address}:${ctx.req.remoteAddress.port}`;
+            const { check, entry } = (0, detectBot_1.isRateLimit)(ctx, key, storage, rateLimit.maxRequests, rateLimit.windowMs);
+            if (check) {
+                const retryAfter = Math.ceil((entry.resetTime - Date.now()) / 1000);
+                ctx.headers.set("Retry-After", retryAfter.toString());
+                return onUnauthorized(ctx, new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`));
+            }
+        }
+        try {
+            const isValid = await validateCredentials(authMethod, credentials, ctx);
+            if (!isValid) {
+                throw new Error("Invalid credentials.");
+            }
+            if (checkAccess) {
+                const hasAccess = await checkAccess(ctx, credentials);
+                if (!hasAccess) {
+                    return onUnauthorized(ctx, new Error("Access denied."));
+                }
+            }
+            return await next();
+        }
+        catch (error) {
+            config_1.GlobalConfig.debugging.error(`${colors_1.COLORS.bgRed}[AUTH]${colors_1.COLORS.reset} Failure for method: ${ctx.method}`);
+            return onUnauthorized(ctx, error);
+        }
+    };
+};
+exports.basicAuth = basicAuth;

package/cjs/middleware/index.js

@@ -29,3 +29,4 @@ __exportStar(require("./request-id"), exports);
 __exportStar(require("./sanitizeHeader"), exports);
 __exportStar(require("./secureHeaders"), exports);
 __exportStar(require("./xssProtection"), exports);
+__exportStar(require("./basicAuth"), exports);

package/core/server.d.ts

@@ -32,6 +32,25 @@ export type TezXConfig = {
      * @default true
      */
     overwriteMethod?: boolean;
+    /**
+     * 🔄 Hook to transform or normalize the incoming request pathname before routing.
+     *
+     * This function allows you to customize how incoming paths are handled.
+     * You can use it to:
+     * - Remove trailing slashes
+     * - Normalize casing
+     * - Rewrite certain paths dynamically
+     * - Add localization or versioning prefixes
+     *
+     * @example
+     * ```ts
+     * onPathResolve: (pathname) => pathname.replace(/\/+$/, "").toLowerCase()
+     * ```
+     *
+     * @param pathname - The raw incoming request path (e.g., `/Api/Users/`)
+     * @returns The transformed or resolved path used for routing (e.g., `/api/users`)
+     */
+    onPathResolve?: (pathname: string) => string;
     /**
      * Enables or disables debugging for the middleware.
      * When set to `true`, detailed debug logs will be output,
@@ -43,7 +62,7 @@ export type TezXConfig = {
 } & RouterConfig;
 export declare class TezX<T extends Record<string, any> = {}> extends Router<T> {
     #private;
-    constructor({ basePath, env, debugMode, allowDuplicateMw, overwriteMethod, }?: TezXConfig);
+    constructor({ basePath, env, debugMode, onPathResolve, allowDuplicateMw, overwriteMethod, }?: TezXConfig);
     protected findRoute(method: HTTPMethod, pathname: string): {
         callback: any;
         middlewares: Middleware<T>[];

package/core/server.js

@@ -4,13 +4,15 @@ import { Context, httpStatusMap } from "./context";
 import { Router } from "./router";
 import { useParams } from "../utils/params";
 export class TezX extends Router {
-    constructor({ basePath = "/", env = {}, debugMode = false, allowDuplicateMw = false, overwriteMethod = true, } = {}) {
+    #onPathResolve;
+    constructor({ basePath = "/", env = {}, debugMode = false, onPathResolve, allowDuplicateMw = false, overwriteMethod = true, } = {}) {
         GlobalConfig.allowDuplicateMw = allowDuplicateMw;
         GlobalConfig.overwriteMethod = overwriteMethod;
         if (debugMode) {
             GlobalConfig.debugMode = debugMode;
         }
         super({ basePath, env });
+        this.#onPathResolve = onPathResolve;
         this.serve = this.serve.bind(this);
     }
     #hashRouter(method, pathname) {
@@ -118,11 +120,19 @@ export class TezX extends Router {
         let ctx = new Context(req, connInfo);
         const urlRef = ctx.req.urlRef;
         const { pathname } = urlRef;
-        let middlewares = this.#findMiddleware(pathname);
+        let resolvePath = pathname;
+        if (this.#onPathResolve) {
+            resolvePath = this.#onPathResolve(pathname);
+            GlobalConfig.debugging.warn(`${COLORS.white} PATH RESOLVE ${COLORS.reset} ${COLORS.red}${pathname}${COLORS.reset} ➞ ${COLORS.cyan}${resolvePath}${COLORS.reset}`);
+        }
+        if (typeof resolvePath !== 'string') {
+            throw new Error(`Path resolution failed: expected a string, got ${typeof resolvePath}`);
+        }
+        let middlewares = this.#findMiddleware(resolvePath);
         ctx.env = this.env;
         try {
             let callback = async (ctx) => {
-                const find = this.findRoute(ctx.req.method, pathname);
+                const find = this.findRoute(ctx.req.method, resolvePath);
                 if (find?.callback) {
                     ctx.params = find.params;
                     const callback = find.callback;

package/index.js

@@ -1,4 +1,4 @@
 export { Router } from "./core/router";
 export { TezX } from "./core/server";
 export { useParams } from "./utils/params";
-export let version = "1.0.43";
+export let version = "1.0.45";

package/middleware/basicAuth.d.ts

@@ -0,0 +1,84 @@
+import { Middleware } from "..";
+import { Context } from "../core/context";
+import { CallbackReturn } from "../core/router";
+/**
+ * Supported authentication method types.
+ */
+export type AuthMethod = "basic" | "api-key" | "bearer-token";
+export type AuthCredential = {
+    username?: any;
+    password?: any;
+    token?: any;
+    apiKey?: any;
+};
+/**
+ * Configuration options for dynamic basic authentication.
+ */
+type DynamicBasicAuthOptions = {
+    /**
+     * 🔐 Function to validate the provided credentials.
+     * @param method - The method of authentication.
+     * @param credentials - The extracted credentials.
+     * @param ctx - The current request context.
+     * @returns A boolean or Promise resolving to whether the credentials are valid.
+     */
+    validateCredentials: (method: AuthMethod, credentials: AuthCredential, ctx: Context) => boolean | Promise<boolean>;
+    /**
+     * 🔒 Function to dynamically determine the realm for authentication prompt.
+     * @param ctx - The current request context.
+     * @returns The authentication realm string.
+     */
+    getRealm?: (ctx: Context) => string;
+    /**
+     * ❌ Custom handler for unauthorized access.
+     * @param ctx - The current request context.
+     * @param error - Optional error information.
+     * @returns A CallbackReturn to end the response.
+     */
+    onUnauthorized?: (ctx: Context, error?: Error) => CallbackReturn;
+    /**
+     * 🚦 Rate-limiting configuration.
+     */
+    rateLimit?: {
+        /**
+         * 🧠 Custom cache or storage for rate-limit tracking.
+         */
+        storage?: {
+            get: (key: string) => {
+                count: number;
+                resetTime: number;
+            } | undefined;
+            set: (key: string, value: {
+                count: number;
+                resetTime: number;
+            }) => void;
+            delete: (key: string) => void;
+            clearExpired: () => void;
+        };
+        /** 🔁 Max requests allowed within the window */
+        maxRequests: number;
+        /** ⏲️ Duration of window in milliseconds */
+        windowMs: number;
+    };
+    /**
+     * 🛠 Supported authentication types.
+     * @default ["basic"]
+     */
+    supportedMethods?: AuthMethod[];
+    /**
+     * 🧑‍⚖️ Optional RBAC (Role-Based Access Control) check.
+     * @param ctx - The current request context.
+     * @param credentials - The validated credentials.
+     * @returns Whether access is allowed.
+     */
+    checkAccess?: (ctx: Context, credentials: AuthCredential) => boolean | Promise<boolean>;
+};
+/**
+ * 🔐 Middleware for flexible authentication using Basic, API Key, or Bearer Token.
+ * Supports rate limiting, IP filtering, and role-based access control.
+ *
+ * @param options - Custom authentication handler options.
+ * @returns A middleware function.
+ */
+export declare const basicAuth: (options: DynamicBasicAuthOptions) => Middleware;
+export {};

package/middleware/basicAuth.js

@@ -0,0 +1,67 @@
+import { GlobalConfig } from "../core/config";
+import { COLORS } from "../utils/colors";
+import { createRateLimitDefaultStorage, isRateLimit } from "./detectBot";
+export const basicAuth = (options) => {
+    const { validateCredentials, getRealm = () => "Restricted Area", onUnauthorized = (ctx, error) => {
+        const realm = getRealm(ctx);
+        ctx.setStatus = 401;
+        ctx.header("WWW-Authenticate", `Basic realm="${realm}"`);
+        ctx.body = { error: error?.message };
+    }, rateLimit, supportedMethods = ["basic", "api-key", "bearer-token"], checkAccess, } = options;
+    let storage = rateLimit?.storage;
+    if (rateLimit && !rateLimit.storage) {
+        storage = createRateLimitDefaultStorage();
+    }
+    return async (ctx, next) => {
+        let authMethod;
+        let credentials = {};
+        const authHeader = ctx.req.headers.get("authorization");
+        if (authHeader) {
+            if (authHeader.startsWith("Basic ")) {
+                authMethod = "basic";
+                const base64Credentials = authHeader.split(" ")[1];
+                const decoded = Buffer.from(base64Credentials, "base64").toString("utf-8");
+                const [username, password] = decoded.split(":");
+                credentials = { username, password };
+            }
+            else if (authHeader.startsWith("Bearer ")) {
+                authMethod = "bearer-token";
+                credentials = { token: authHeader.split(" ")[1] };
+            }
+        }
+        else if (ctx.headers.get("x-api-key")) {
+            authMethod = "api-key";
+            credentials = { apiKey: ctx.headers.get("x-api-key") };
+        }
+        if (!authMethod || !supportedMethods.includes(authMethod)) {
+            GlobalConfig.debugging.error(`${COLORS.bgRed}[AUTH]${COLORS.reset} Unsupported or missing authentication method.`);
+            return onUnauthorized(ctx, new Error("Unsupported authentication method"));
+        }
+        if (rateLimit) {
+            let key = `${ctx.req.remoteAddress.address}:${ctx.req.remoteAddress.port}`;
+            const { check, entry } = isRateLimit(ctx, key, storage, rateLimit.maxRequests, rateLimit.windowMs);
+            if (check) {
+                const retryAfter = Math.ceil((entry.resetTime - Date.now()) / 1000);
+                ctx.headers.set("Retry-After", retryAfter.toString());
+                return onUnauthorized(ctx, new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`));
+            }
+        }
+        try {
+            const isValid = await validateCredentials(authMethod, credentials, ctx);
+            if (!isValid) {
+                throw new Error("Invalid credentials.");
+            }
+            if (checkAccess) {
+                const hasAccess = await checkAccess(ctx, credentials);
+                if (!hasAccess) {
+                    return onUnauthorized(ctx, new Error("Access denied."));
+                }
+            }
+            return await next();
+        }
+        catch (error) {
+            GlobalConfig.debugging.error(`${COLORS.bgRed}[AUTH]${COLORS.reset} Failure for method: ${ctx.method}`);
+            return onUnauthorized(ctx, error);
+        }
+    };
+};

package/middleware/index.d.ts

@@ -12,3 +12,4 @@ export * from "./request-id";
 export * from "./sanitizeHeader";
 export * from "./secureHeaders";
 export * from "./xssProtection";
+export * from "./basicAuth";

package/middleware/index.js

@@ -10,3 +10,4 @@ export * from "./request-id";
 export * from "./sanitizeHeader";
 export * from "./secureHeaders";
 export * from "./xssProtection";
+export * from "./basicAuth";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tezx",
-  "version": "1.0.43",
+  "version": "1.0.45",
   "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.",
   "main": "cjs/index.js",
   "module": "index.js",