@synchjs/ewb 1.0.1 → 1.0.2

package/README.md

@@ -1,17 +1,17 @@
 # @synchjs/ewb
 
-A robust, decorator-based web server framework built on top of **Express** and optimized for **Bun**. It provides a structured way to build scalable APIs with built-in support for **OpenAPI (Swagger)**, **Validation**, **Authentication**, and **Frontend Asset Serving** (with Tailwind CSS support).
+A robust, decorator-based web server framework built on top of **Express** and optimized for **Bun**. It provides a structured way to build scalable APIs with built-in support for **OpenAPI (Swagger)**, **Validation**, **Custom User Management**, and **Frontend Asset Serving** with **HMR (Hot Module Replacement)**.
 
 ## Features
 
 - 🏗 **Decorator-based Routing**: Define controllers and routes using concise decorators (`@Controller`, `@Get`, `@Post`).
-- 🔒 **Built-in Authentication**: Easy-to-use Bearer Token authentication (`@BearerAuth`).
+- 👥 **Flexible User Management**: Pluggable `UserHandler` for custom Auth/Identity logic (JWT, Session, Database, etc.).
 - 📜 **Auto-generated Swagger Docs**: Your API documentation is generated automatically from your code.
-- ✅ **Request Validation**: Schema-based validation using AJV.
-- 🎨 **Frontend Serving**: Serve HTML/CSS/JS assets from memory, with built-in **Tailwind CSS** processing via Bun plugins.
-- 🧩 **Dependency Injection**: Support for IoC containers.
-- 🚀 **Bun Optimized**: Leverages Bun's build capabilities for static assets.
-- 🖥 **TUI-style Logs**: Clean and informative startup messages.
+- ✅ **Request Validation**: Strict schema-based validation using AJV.
+- 🔥 **Hot Module Replacement (HMR)**: Real-time frontend updates without full page reloads using Socket.io and hot script swapping.
+- 🎨 **Frontend Serving**: Serve HTML/CSS/JS assets from memory, with built-in **Tailwind CSS** processing.
+- 🐚 **Security Hardened**: Built-in protection with **Helmet**, **CORS**, **Rate Limiting**, and path traversal protection.
+- 🖥 **Premium TUI Logs**: Clean, informative, and beautiful startup messages.
 
 ## Installation
 
@@ -26,16 +26,14 @@ bun add @synchjs/ewb
 Create a file `controllers/HomeController.ts`:
 
 ```typescript
-import { Controller, Get } from "ewb";
-import type { Request, Response } from "express";
+import { Controller, Get } from "@synchjs/ewb";
 
 @Controller("/")
 export class HomeController {
   @Get("/", {
     summary: "Welcome endpoint",
-    description: "Returns a welcome message.",
   })
-  public index(req: Request, res: Response) {
+  public index() {
     return { message: "Hello from @synchjs/ewb!" };
   }
 }
@@ -46,246 +44,128 @@ export class HomeController {
 Create `index.ts`:
 
 ```typescript
-import { Server } from "ewb";
+import { Server } from "@synchjs/ewb";
 
 const server = new Server({
   id: "main",
   port: 3000,
-  controllersDir: "controllers", // Directory where your controllers are located
-  enableSwagger: true, // Enable Swagger UI at /api-docs
+  controllersDir: "controllers",
 });
 
-server.init();
+await server.init();
 ```
 
-Run with Bun:
-
-```bash
-bun run index.ts
-```
+## Authentication & User Management
 
-### 3. Customize Swagger Path
+The framework uses a `UserHandler` system to give you full control over identity.
 
-You can change where Swagger UI is served:
+### 1. Define your User Handler
 
 ```typescript
-const server = new Server({
-  id: "main",
-  port: 3000,
-  enableSwagger: true,
-  swaggerPath: "/docs", // Now available at http://localhost:3000/docs
-});
-```
-
-## Detailed Usage
-
-### Controllers & Routing
-
-Use `@Controller` to define a base path and HTTP method decorators for routes.
-
-```typescript
-import { Controller, Get, Post, Put, Delete } from "ewb";
+import { UserHandler } from "@synchjs/ewb";
 import type { Request, Response } from "express";
 
-@Controller("/users", { tags: ["Users"] })
-export class UserController {
-  @Get("/:id")
-  public getUser(req: Request, res: Response) {
-    const { id } = req.params;
-    return { id, name: "User " + id };
+class MyUserHandler extends UserHandler {
+  // Determine who the user is for every request
+  public async authenticate(req: Request, res: Response) {
+    const token = req.headers.authorization?.replace("Bearer ", "");
+    if (token === "admin-secret") {
+      return { id: 1, name: "Admin", roles: ["admin"] };
+    }
+    return null;
   }
 
-  @Post("/", {
-    summary: "Create User",
-    responses: {
-      201: { description: "User created" },
-    },
-  })
-  public createUser(req: Request, res: Response) {
-    // Logic to create user
-    return { id: 1, ...req.body };
+  // Optional: Automatic routes for /auth/signin, signup, logout
+  public signin(req: Request, res: Response) {
+    /* ... */
   }
-}
-```
-
-### Authentication
-
-Secure your endpoints using `@BearerAuth`. It integrates with JWT verification automatically.
-
-- **Class Level:** Protects all routes in the controller.
-- **Method Level:** Protects specific routes.
-- **@Public():** Excludes a route from class-level auth.
-
-```typescript
-import { Controller, Get, BearerAuth, Public } from "ewb";
-
-@Controller("/secure")
-@BearerAuth("my_secret_key") // Optional: Custom secret, defaults to process.env.JWT_SECRET
-export class SecureController {
-  @Get("/dashboard")
-  public dashboard(req: Request, res: Response) {
-    // Access user data attached by middleware (req.user)
-    const user = (req as any).user;
-    return { message: "Secret data", user };
+  public signup(req: Request, res: Response) {
+    /* ... */
   }
-
-  @Get("/status")
-  @Public() // Accessible without token
-  public status(req: Request, res: Response) {
-    return { status: "OK" };
+  public logout(req: Request, res: Response) {
+    /* ... */
   }
 }
 ```
 
-#### Advanced Security (@Security, @OAuth, @ApiKey)
+### 2. Protect Routes
 
-For other authentication methods like OAuth2 or API Keys, use generic decorators:
+Use `@Authorized` to require a user, or specify roles.
 
 ```typescript
-import { Controller, Get, OAuth, ApiKey } from "ewb";
+import { Controller, Get, Authorized } from "@synchjs/ewb";
 
-@Controller("/api")
-export class ApiController {
+@Controller("/dashboard")
+export class DashboardController {
   @Get("/profile")
-  @OAuth(["read:profile"]) // Marks route as requiring OAuth2 with specific scope
-  public getProfile() {
-    return { name: "John Doe" };
+  @Authorized() // Requires a non-null return from your UserHandler
+  public getProfile({ user }: { user: any }) {
+    return { message: `Hello ${user.name}` };
   }
 
-  @Get("/data")
-  @ApiKey("X-API-KEY") // Custom security scheme name
-  public getData() {
-    return { sensitive: "data" };
+  @Get("/admin")
+  @Authorized(["admin"]) // Checks roles array from UserHandler
+  public adminOnly() {
+    return { message: "Admin area" };
   }
 }
 ```
 
-**Configure Handlers and Schemes:**
+### 3. Register the Handler
 
 ```typescript
-const server = new Server({
-  // ...,
-  securitySchemes: {
-    oauth2: {
-      type: "oauth2",
-      flows: {
-        /* ... standard OpenAPI flow definition ... */
-      },
-    },
-  },
-  securityHandlers: {
-    oauth2: (req, res, next) => {
-      // Your OAuth validation logic here
-      next();
-    },
-  },
-});
+const server = new Server({ ... });
+server.setUserHandler(new MyUserHandler()); // Routes /auth/* are created automatically
+await server.init();
 ```
 
-### Request Validation
-
-Define a JSON schema in the `@Post` (or other method) decorator to automatically validate the request body using AJV.
+## Hot Module Replacement (HMR)
 
-```typescript
-@Post("/register", {
-  summary: "Register new user",
-  requestBody: {
-    content: {
-      "application/json": {
-        schema: {
-          type: "object",
-          properties: {
-            username: { type: "string" },
-            email: { type: "string", format: "email" },
-            age: { type: "integer", minimum: 18 }
-          },
-          required: ["username", "email"]
-        }
-      }
-    }
-  }
-})
-public register(req: Request, res: Response) {
-  // If execution reaches here, req.body is valid
-  return { success: true };
-}
-```
+HMR is active by default when `NODE_ENV` is not set to `production`. It uses Socket.io to sync changes.
 
-### Serving Frontend Assets (with Tailwind CSS)
+- **Fast Refresh**: Specifically optimized for React applications.
+- **Hot Script Swapping**: Updates code in the browser without losing state or full page reloads.
+- **Cache Control**: Automatically disables browser caching during development.
 
-You can serve compiled HTML and automatically process Tailwind CSS using the `@Serve` and `@Tailwindcss` decorators.
+## Serving Frontend Assets
 
-1.  **Project Structure**:
-
-    ```
-    /views
-      src/
-        index.html
-        index.css (imports tailwind, or handled via plugin)
-        frontend.tsx
-    ```
-
-2.  **Controller Setup**:
+Use `@Serve` to bundle and serve frontend entry points.
 
 ```typescript
-import { Controller, Get, Serve, Tailwindcss } from "ewb";
+import { Controller, Get, Serve, Tailwindcss } from "@synchjs/ewb";
 
 @Controller("/")
-@Tailwindcss({
-  enable: true,
-  plugins: [
-    /* Bun plugins or custom PostCSS wrappers */
-  ],
-})
+@Tailwindcss({ enable: true })
 export class FrontendController {
   @Get("/")
-  @Serve("views/src/index.html") // Path to your HTML entry point
-  public app(req: Request, res: Response) {
-    // The decorator handles the response.
+  @Serve("views/src/index.html")
+  public app() {
+    // Handled by memory store
   }
 }
 ```
 
-### Middleware
-
-Apply custom Express middleware to controllers or routes using `@Middleware`.
-
-```typescript
-import { Controller, Get, Middleware } from "ewb";
-
-const logAccess = (req: Request, res: Response, next: NextFunction) => {
-  console.log("Accessed!");
-  next();
-};
+## Security & Best Practices
 
-@Controller("/audit")
-@Middleware(logAccess)
-export class AuditController {
-  @Get("/")
-  public index(req: Request, res: Response) {
-    return { message: "Audited" };
-  }
-}
-```
+- **Strict Validation**: AJV validates all request bodies defined in Swagger options. It automatically removes additional properties and enforces strict types.
+- **Rate Limiting**: Protects your API from brute-force/DoS. (Static assets are automatically exempt).
+- **Security Headers**: Powered by Helmet, with dynamic CSP adjustments for HMR.
+- **Error Handling**: Production mode masks internal errors and stack traces.
 
 ## Server Configuration
 
-The `Server` class accepts the following options:
-
-| Option             | Type               | Description                                                      |
-| ------------------ | ------------------ | ---------------------------------------------------------------- |
-| `id`               | `string`           | Unique identifier for the server instance.                       |
-| `port`             | `number`           | Port to listen on.                                               |
-| `controllersDir`   | `string`           | Directory containing controller files.                           |
-| `enableSwagger`    | `boolean`          | Enable OpenAPI documentation.                                    |
-| `swaggerPath`      | `string`           | Custom path for Swagger UI (default: `/api-docs`).               |
-| `logging`          | `boolean`          | Enable/disable TUI startup messages (default: true).             |
-| `corsOptions`      | `CorsOptions`      | Configuration for CORS.                                          |
-| `helmetOptions`    | `HelmetOptions`    | Configuration for Helmet security headers.                       |
-| `rateLimitOptions` | `RateLimitOptions` | Configuration for rate limiting.                                 |
-| `securitySchemes`  | `object`           | custom OpenAPI security schemes definitions.                     |
-| `securityHandlers` | `object`           | Middleware handlers for security schemes.                        |
-| `container`        | `object`           | IoC container for dependency injection (must have `get` method). |
+| Option             | Type       | Description                                            |
+| ------------------ | ---------- | ------------------------------------------------------ |
+| `id`               | `string`   | ID for logging and console output.                     |
+| `port`             | `number`   | Port to listen on.                                     |
+| `controllersDir`   | `string`   | Location of your controllers (default: `controllers`). |
+| `viewsDir`         | `string`   | Base directory for frontend views.                     |
+| `enableSwagger`    | `boolean`  | Enable Swagger UI (default: `false`).                  |
+| `swaggerPath`      | `string`   | Path for docs (default: `/api-docs`).                  |
+| `helmetOptions`    | `object`   | Custom Helmet configuration.                           |
+| `corsOptions`      | `object`   | Custom CORS configuration.                             |
+| `rateLimitOptions` | `object`   | Custom Rate Limit configuration.                       |
+| `roleHandler`      | `function` | Custom function for advanced role checking logic.      |
 
 ## License
 

package/dist/Components/ServeMemoryStore.d.ts

@@ -8,11 +8,15 @@ export declare class ServeMemoryStore {
     private _watchers;
     private _listeners;
     private constructor();
+    private ensureCacheDir;
+    clearCache(): void;
     static get instance(): ServeMemoryStore;
     setDevMode(enabled: boolean): void;
-    onRebuild(listener: () => void): void;
+    onRebuild(listener: (data?: {
+        html: string;
+    }) => void): void;
     private notify;
-    getAsset(path: string): {
+    getAsset(rawPath: string): {
         type: string;
         content: Uint8Array;
     };

package/dist/Components/ServeMemoryStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServeMemoryStore.d.ts","sourceRoot":"","sources":["../../src/Components/ServeMemoryStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI/D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAmB;IAC3C,OAAO,CAAC,OAAO,CACH;IACZ,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,SAAS,CAA0C;IAC3D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,UAAU,CAAsB;IAExC,OAAO;IAUP,WAAkB,QAAQ,IAAI,gBAAgB,CAK7C;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO;IAI3B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI;IAIrC,OAAO,CAAC,MAAM;IAIP,QAAQ,CAAC,IAAI,EAAE,MAAM;cArCS,MAAM;iBAAW,UAAU;;IAyChE,OAAO,CAAC,WAAW;YAQL,YAAY;IAuB1B,OAAO,CAAC,YAAY;IA4CP,aAAa,CACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAgD,GACxD,OAAO,CAAC,MAAM,CAAC;CAqHnB"}
+{"version":3,"file":"ServeMemoryStore.d.ts","sourceRoot":"","sources":["../../src/Components/ServeMemoryStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAK/D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAmB;IAC3C,OAAO,CAAC,OAAO,CACH;IACZ,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,SAAS,CAA0C;IAC3D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,UAAU,CAA6C;IAE/D,OAAO;IAIP,OAAO,CAAC,cAAc;IAUf,UAAU;IAgBjB,WAAkB,QAAQ,IAAI,gBAAgB,CAK7C;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO;IAI3B,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI;IAI5D,OAAO,CAAC,MAAM;IAIP,QAAQ,CAAC,OAAO,EAAE,MAAM;cAzDM,MAAM;iBAAW,UAAU;;IAgEhE,OAAO,CAAC,WAAW;YAQL,YAAY;IAyB1B,OAAO,CAAC,YAAY;IA4CP,aAAa,CACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAgD,GACxD,OAAO,CAAC,MAAM,CAAC;CA4JnB"}

package/dist/Components/ServeMemoryStore.js

@@ -1,6 +1,7 @@
 import tailwindPlugin from "bun-plugin-tailwind";
 import fs from "fs";
 import path from "path";
+import { load } from "cheerio";
 export class ServeMemoryStore {
     static _instance;
     _assets = new Map();
@@ -10,6 +11,9 @@ export class ServeMemoryStore {
     _watchers = new Map();
     _listeners = [];
     constructor() {
+        this.ensureCacheDir();
+    }
+    ensureCacheDir() {
         if (!fs.existsSync(this._cacheDir)) {
             try {
                 fs.mkdirSync(this._cacheDir, { recursive: true });
@@ -19,6 +23,22 @@ export class ServeMemoryStore {
             }
         }
     }
+    clearCache() {
+        if (fs.existsSync(this._cacheDir)) {
+            try {
+                const files = fs.readdirSync(this._cacheDir);
+                for (const file of files) {
+                    fs.unlinkSync(path.join(this._cacheDir, file));
+                }
+                // Silent clear
+            }
+            catch (e) {
+                console.error("[Cache] Error clearing cache:", e);
+            }
+        }
+        this._htmlCache.clear();
+        this._assets.clear();
+    }
     static get instance() {
         if (!ServeMemoryStore._instance) {
             ServeMemoryStore._instance = new ServeMemoryStore();
@@ -31,11 +51,15 @@ export class ServeMemoryStore {
     onRebuild(listener) {
         this._listeners.push(listener);
     }
-    notify() {
-        this._listeners.forEach((l) => l());
+    notify(data) {
+        this._listeners.forEach((l) => l(data));
     }
-    getAsset(path) {
-        return this._assets.get(path);
+    getAsset(rawPath) {
+        // Basic path traversal protection
+        const normalizedPath = path.posix.normalize(rawPath);
+        if (normalizedPath.includes(".."))
+            return undefined;
+        return this._assets.get(normalizedPath);
     }
     getCacheKey(htmlPath, options) {
         return (htmlPath +
@@ -43,6 +67,8 @@ export class ServeMemoryStore {
             (options.plugins ? ":" + options.plugins.length : ""));
     }
     async loadFromDisk(cacheKey) {
+        if (this._devMode)
+            return null; // Skip disk cache in dev mode
         const hash = Bun.hash(cacheKey).toString(16);
         const cacheFile = path.join(this._cacheDir, `${hash}.json`);
         if (fs.existsSync(cacheFile)) {
@@ -77,7 +103,7 @@ export class ServeMemoryStore {
                 filename.includes(".git") ||
                 filename.includes(".ebw-cache"))
                 return;
-            console.log(`[HMR] Change detected in ${filename}. Rebuilding...`);
+            // Silent detect
             // Clear cache for this entry
             this._htmlCache.delete(cacheKey);
             // Clear disk cache by deleting file
@@ -87,8 +113,8 @@ export class ServeMemoryStore {
                 fs.unlinkSync(cacheFile);
             }
             try {
-                await this.buildAndCache(htmlPath, options);
-                this.notify();
+                const newHtml = await this.buildAndCache(htmlPath, options);
+                this.notify({ html: newHtml });
             }
             catch (e) {
                 console.error("[HMR] Rebuild failed:", e);
@@ -99,11 +125,10 @@ export class ServeMemoryStore {
     async buildAndCache(htmlPath, options = { enable: false, plugins: [] }) {
         const cacheKey = this.getCacheKey(htmlPath, options);
         // 1. Check Memory Cache
-        if (this._htmlCache.has(cacheKey)) {
+        if (!this._devMode && this._htmlCache.has(cacheKey)) {
             return this._htmlCache.get(cacheKey);
         }
-        // 2. Check Disk Cache (unless in dev mode and we want to ensure fresh start,
-        // but usually disk cache is fine as watcher will invalidate it)
+        // 2. Check Disk Cache
         const diskHtml = await this.loadFromDisk(cacheKey);
         if (diskHtml) {
             if (this._devMode) {
@@ -154,37 +179,76 @@ export class ServeMemoryStore {
             // Inject HMR/Reload script in dev mode
             if (this._devMode) {
                 const reloadScript = `
+<script src="/socket.io/socket.io.js"></script>
 <script id="ebw-hmr-script">
   (function() {
-    const sse = new EventSource('/ebw-hmr');
-    sse.onmessage = (e) => {
-      if (e.data === 'reload') {
-        console.log('[HMR] Reloading page...');
+    const socket = io(window.location.origin);
+    
+    socket.on('rebuild', (data) => {
+      if (!data || !data.html) return;
+      console.log('[HMR] Rebuild detected. Hot swapping scripts...');
+      
+      const parser = new DOMParser();
+      const newDoc = parser.parseFromString(data.html, 'text/html');
+      const newScripts = Array.from(newDoc.querySelectorAll('script[src]'))
+        .filter(s => !s.id && s.getAttribute('src').includes('-')); // Find bundled scripts
+        
+      if (newScripts.length === 0) {
+        console.warn('[HMR] No bundled scripts found in rebuild. Falling back to reload.');
         location.reload();
+        return;
       }
-    };
-    sse.onerror = () => {
+      
+      // Remove old bundled scripts
+      const oldScripts = Array.from(document.querySelectorAll('script[src]'))
+        .filter(s => !s.id && s.getAttribute('src').includes('-'));
+      
+      oldScripts.forEach(s => s.remove());
+      
+      // Add new scripts
+      newScripts.forEach(s => {
+        const script = document.createElement('script');
+        Array.from(s.attributes).forEach(attr => script.setAttribute(attr.name, attr.value));
+        document.body.appendChild(script);
+      });
+      
+      console.log('[HMR] Hot swap complete!');
+    });
+
+    socket.on('reload', () => {
+      console.log('[HMR] Hard reload signal received.');
+      location.reload();
+    });
+    
+    socket.on('disconnect', () => {
       console.warn('[HMR] Connection lost. Attempting to reconnect...');
-    };
+    });
   })();
 </script>
 `;
-                if (htmlContent.includes("</body>")) {
-                    htmlContent = htmlContent.replace("</body>", `${reloadScript}</body>`);
+                // In dev mode, we might want to prevent caching by appending a timestamp to asset links in the HTML
+                const timestamp = Date.now();
+                htmlContent = htmlContent.replace(/(\.js|\.css)(\?.*)?/g, `$1?t=${timestamp}`);
+                const $ = load(htmlContent);
+                if ($("body").length > 0) {
+                    $("body").append(reloadScript);
                 }
                 else {
-                    htmlContent += reloadScript;
+                    $.root().append(reloadScript);
                 }
+                htmlContent = $.html();
                 this.setupWatcher(htmlPath, options);
             }
             // 4. Save to Memory and Disk
             this._htmlCache.set(cacheKey, htmlContent);
-            const hash = Bun.hash(cacheKey).toString(16);
-            const cacheFile = path.join(this._cacheDir, `${hash}.json`);
-            fs.writeFileSync(cacheFile, JSON.stringify({
-                html: htmlContent,
-                assets: currentBuildAssets,
-            }));
+            if (!this._devMode) {
+                const hash = Bun.hash(cacheKey).toString(16);
+                const cacheFile = path.join(this._cacheDir, `${hash}.json`);
+                fs.writeFileSync(cacheFile, JSON.stringify({
+                    html: htmlContent,
+                    assets: currentBuildAssets,
+                }));
+            }
             return htmlContent;
         }
         catch (error) {

package/dist/Components/Server.d.ts

@@ -2,10 +2,12 @@ import { type Request, type Response, type NextFunction } from "express";
 import { type HelmetOptions } from "helmet";
 import cors from "cors";
 import { type Options as RateLimitOptions } from "express-rate-limit";
+import { UserHandler } from "./UserHandler";
 export declare class Server {
     private readonly _app;
     private readonly _port;
     private readonly _controllersDir;
+    private readonly _viewsDir?;
     readonly _id: string;
     private readonly _enableSwagger;
     private readonly _swaggerPath;
@@ -14,20 +16,24 @@ export declare class Server {
     private readonly _ajv;
     private readonly _securityHandlers;
     private readonly _container?;
+    private readonly _roleHandler?;
+    private _userHandler?;
     private _serverInstance?;
+    private _io?;
     private _controllerCount;
     private _routeCount;
     private _tailwindEnabled;
     private _devMode;
-    private _sseClients;
     constructor(options: ServerOptions);
     private setupHmr;
     private log;
     init(): Promise<void>;
     private printStartupMessage;
     close(): void;
+    setUserHandler(handler: UserHandler): void;
+    private setupAuthRoutes;
     private loadControllers;
-    private createJwtMiddleware;
+    private createRoleMiddleware;
     private createAuthMiddleware;
     private createValidationMiddleware;
     private setupSwagger;
@@ -39,7 +45,7 @@ export interface ServerOptions {
     logging?: boolean;
     id: string;
     controllersDir?: string;
-    devMode?: boolean;
+    viewsDir?: string;
     corsOptions?: cors.CorsOptions;
     helmetOptions?: HelmetOptions;
     rateLimitOptions?: Partial<RateLimitOptions>;
@@ -48,5 +54,6 @@ export interface ServerOptions {
     container?: {
         get: (target: any) => any;
     };
+    roleHandler?: (req: Request, roles: string[]) => boolean | Promise<boolean>;
 }
 //# sourceMappingURL=Server.d.ts.map

package/dist/Components/Server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../src/Components/Server.ts"],"names":[],"mappings":"AAAA,OAAgB,EAEd,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAKjB,OAAe,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAkB,EAChB,KAAK,OAAO,IAAI,gBAAgB,EACjC,MAAM,oBAAoB,CAAC;AAwB5B,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAM;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAM;IAC3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAGhC;IACF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAgC;IAC5D,OAAO,CAAC,eAAe,CAAC,CAAa;IAErC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAkB;gBAEzB,OAAO,EAAE,aAAa;IAuClC,OAAO,CAAC,QAAQ;IAyBhB,OAAO,CAAC,GAAG;IAME,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqClC,OAAO,CAAC,mBAAmB;IAsCpB,KAAK,IAAI,IAAI;YASN,eAAe;IAkQ7B,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,oBAAoB;IAyD5B,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,YAAY;CAmErB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC;IAC/B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CACvB,MAAM,EACN,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAC1D,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAA;KAAE,CAAC;CAC3C"}
+{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../src/Components/Server.ts"],"names":[],"mappings":"AAAA,OAAgB,EAEd,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAKjB,OAAe,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAkB,EAChB,KAAK,OAAO,IAAI,gBAAgB,EACjC,MAAM,oBAAoB,CAAC;AAM5B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAkB5C,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAM;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAM;IAC3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAGhC;IACF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAGE;IAChC,OAAO,CAAC,YAAY,CAAC,CAAc;IACnC,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,GAAG,CAAC,CAAe;IAE3B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,aAAa;IAgElC,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,GAAG;IAME,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqElC,OAAO,CAAC,mBAAmB;IA0CpB,KAAK,IAAI,IAAI;IASb,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIjD,OAAO,CAAC,eAAe;YA+BT,eAAe;IAuQ7B,OAAO,CAAC,oBAAoB;IAkD5B,OAAO,CAAC,oBAAoB;IAyD5B,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,YAAY;CAmErB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC;IAC/B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CACvB,MAAM,EACN,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAC1D,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAA;KAAE,CAAC;IAC1C,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E"}

package/dist/Components/Server.js

@@ -9,8 +9,9 @@ import rateLimit from "express-rate-limit";
 import Ajv from "ajv";
 import addFormats from "ajv-formats";
 import { MetadataStorage } from "../Decorations";
-import * as jwt from "jsonwebtoken";
-import { AUTH_METADATA_KEY, PUBLIC_METADATA_KEY, } from "../Decorations/Authorized";
+import { createServer } from "http";
+import { Server as SocketServer } from "socket.io";
+import { PUBLIC_METADATA_KEY, ROLES_METADATA_KEY, } from "../Decorations/Authorized";
 import { SECURITY_METADATA_KEY, } from "../Decorations/Security";
 import { TAILWIND_METADATA_KEY, } from "../Decorations/Tailwind";
 import { SERVE_HTML_METADATA_KEY } from "../Decorations/Serve";
@@ -21,6 +22,7 @@ export class Server {
     _app;
     _port;
     _controllersDir;
+    _viewsDir;
     _id;
     _enableSwagger;
     _swaggerPath;
@@ -29,13 +31,15 @@ export class Server {
     _ajv;
     _securityHandlers;
     _container;
+    _roleHandler;
+    _userHandler;
     _serverInstance;
+    _io;
     // Stats
     _controllerCount = 0;
     _routeCount = 0;
     _tailwindEnabled = false;
     _devMode = false;
-    _sseClients = [];
     constructor(options) {
         this._port = options.port;
         this._app = express();
@@ -45,21 +49,44 @@ export class Server {
         this._enableLogging =
             options.logging === undefined ? true : options.logging;
         this._controllersDir = options.controllersDir || "controllers";
+        this._viewsDir = options.viewsDir;
         this._securityHandlers = options.securityHandlers || {};
         this._securitySchemes = options.securitySchemes;
         this._container = options.container;
-        // Initialize AJV
-        this._ajv = new Ajv({ allErrors: true, strict: false });
+        this._roleHandler = options.roleHandler;
+        // Initialize AJV with strict mode for better security
+        this._ajv = new Ajv({
+            allErrors: true,
+            strict: true,
+            removeAdditional: true, // Automatically remove properties not in schema
+        });
         addFormats(this._ajv);
         // Security Middleware
-        this._app.use(helmet(options.helmetOptions));
+        const helmetOptions = options.helmetOptions || {};
+        if (process.env.NODE_ENV !== "production") {
+            // Relax CSP for HMR in development
+            helmetOptions.contentSecurityPolicy = {
+                directives: {
+                    defaultSrc: ["'self'"],
+                    scriptSrc: ["'self'", "'unsafe-inline'", "'unsafe-eval'", "blob:"],
+                    connectSrc: ["'self'", "ws:", "wss:", "http:", "https:"],
+                    styleSrc: ["'self'", "'unsafe-inline'"],
+                    imgSrc: ["'self'", "data:", "blob:"],
+                    frameSrc: ["'self'"],
+                },
+            };
+        }
+        this._app.use(helmet(helmetOptions));
         this._app.use(cors(options.corsOptions));
         this._app.use(rateLimit(options.rateLimitOptions || {
             windowMs: 15 * 60 * 1000,
             max: 100,
+            skip: (req) => ServeMemoryStore.instance.getAsset(req.path) !== undefined, // Don't rate limit static assets
         }));
-        this._app.use(express.json());
-        this._devMode = options.devMode ?? process.env.NODE_ENV === "development";
+        this._app.use(express.json({ limit: "1mb" })); // Protection against large payloads
+        // Clear cache on startup
+        ServeMemoryStore.instance.clearCache();
+        this._devMode = process.env.NODE_ENV !== "production";
         if (this._devMode) {
             this.setupHmr();
         }
@@ -67,22 +94,16 @@ export class Server {
     }
     setupHmr() {
         ServeMemoryStore.instance.setDevMode(true);
-        ServeMemoryStore.instance.onRebuild(() => {
-            this.log(`[${this._id}] Sending reload signal to ${this._sseClients.length} clients`);
-            this._sseClients.forEach((res) => {
-                res.write("data: reload\n\n");
-            });
-        });
-        this._app.get("/ebw-hmr", (req, res) => {
-            res.setHeader("Content-Type", "text/event-stream");
-            res.setHeader("Cache-Control", "no-cache");
-            res.setHeader("Connection", "keep-alive");
-            res.flushHeaders();
-            this._sseClients.push(res);
-            req.on("close", () => {
-                this._sseClients = this._sseClients.filter((c) => c !== res);
-            });
+        ServeMemoryStore.instance.onRebuild((data) => {
+            if (data && data.html) {
+                this._io?.emit("rebuild", { html: data.html });
+            }
+            else {
+                this._io?.emit("reload");
+            }
         });
+        // No redundant global watcher here, we rely on ServeMemoryStore's specific watchers
+        // which rebuild before notifying.
     }
     log(message) {
         if (this._enableLogging) {
@@ -90,6 +111,9 @@ export class Server {
         }
     }
     async init() {
+        if (this._userHandler) {
+            this.setupAuthRoutes();
+        }
         await this.loadControllers();
         if (this._enableSwagger) {
             this.setupSwagger();
@@ -100,6 +124,11 @@ export class Server {
                 return next();
             const asset = ServeMemoryStore.instance.getAsset(req.path);
             if (asset) {
+                if (this._devMode) {
+                    res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate, proxy-revalidate");
+                    res.setHeader("Pragma", "no-cache");
+                    res.setHeader("Expires", "0");
+                }
                 res.type(asset.type).send(Buffer.from(asset.content));
                 return;
             }
@@ -107,13 +136,31 @@ export class Server {
         });
         // Global Error Handler
         this._app.use((err, req, res, next) => {
-            console.error(`[${this._id}] Error:`, err);
+            const isProd = process.env.NODE_ENV === "production";
+            if (!isProd) {
+                console.error(`[${this._id}] Error:`, err);
+            }
             res.status(err.status || 500).json({
                 error: "Internal Server Error",
-                message: "An unexpected error occurred",
+                message: isProd
+                    ? "An unexpected error occurred"
+                    : err.message || "An unexpected error occurred",
+                // Mask stack trace in production
+                stack: isProd ? undefined : err.stack,
             });
         });
-        this._serverInstance = this._app.listen(this._port, () => {
+        this._serverInstance = createServer(this._app);
+        if (this._devMode) {
+            this._io = new SocketServer(this._serverInstance, {
+                cors: {
+                    origin: [/localhost/, /127\.0\.0\.1/], // Restrict HMR to local development origin
+                },
+            });
+            this._io.on("connection", (socket) => {
+                // Disconnected client log
+            });
+        }
+        this._serverInstance.listen(this._port, () => {
             if (this._enableLogging) {
                 this.printStartupMessage();
             }
@@ -131,6 +178,9 @@ export class Server {
             `${pc.bold(pad("Tailwind:"))}${this._tailwindEnabled ? pc.blue("Enabled") : pc.dim("Disabled")}`,
             `${pc.bold(pad("HMR:"))}${this._devMode ? pc.cyan("Active") : pc.dim("Inactive")}`,
         ];
+        if (this._viewsDir) {
+            lines.push(`${pc.bold(pad("Views:"))}${this._viewsDir}`);
+        }
         if (this._enableSwagger) {
             lines.push(`${pc.bold(pad("Swagger:"))}http://localhost:${this._port}${this._swaggerPath}`);
         }
@@ -151,6 +201,40 @@ export class Server {
         }
         global.servers.delete(this._id);
     }
+    setUserHandler(handler) {
+        this._userHandler = handler;
+    }
+    setupAuthRoutes() {
+        if (!this._userHandler)
+            return;
+        this._app.post("/auth/signin", async (req, res, next) => {
+            try {
+                const result = await this._userHandler.signin(req, res);
+                res.json(result);
+            }
+            catch (err) {
+                next(err);
+            }
+        });
+        this._app.post("/auth/signup", async (req, res, next) => {
+            try {
+                const result = await this._userHandler.signup(req, res);
+                res.json(result);
+            }
+            catch (err) {
+                next(err);
+            }
+        });
+        this._app.post("/auth/logout", async (req, res, next) => {
+            try {
+                const result = await this._userHandler.logout(req, res);
+                res.json(result);
+            }
+            catch (err) {
+                next(err);
+            }
+        });
+    }
     async loadControllers() {
         const absoluteControllersPath = path.resolve(process.cwd(), this._controllersDir);
         if (!fs.existsSync(absoluteControllersPath)) {
@@ -178,28 +262,18 @@ export class Server {
             const instance = this._container?.get
                 ? this._container.get(controller.target)
                 : new controller.target();
-            // Check class level auth
-            const classAuthInfo = Reflect.getMetadata(AUTH_METADATA_KEY, controller.target);
             for (const route of controller.routes) {
                 const fullPath = (controller.path + "/" + route.path).replace(/\/+/g, "/");
                 const middlewares = [];
-                // Check method level metadata
-                const methodAuthInfo = Reflect.getMetadata(AUTH_METADATA_KEY, controller.target.prototype, route.handlerName);
+                // Check ROLES metadata
+                const classRoles = Reflect.getMetadata(ROLES_METADATA_KEY, controller.target);
+                const methodRoles = Reflect.getMetadata(ROLES_METADATA_KEY, controller.target.prototype, route.handlerName);
+                const requiredRoles = methodRoles || classRoles;
                 const isPublic = Reflect.getMetadata(PUBLIC_METADATA_KEY, controller.target.prototype, route.handlerName);
-                // Determine if auth is required and which secret to use
-                let authSecret;
-                if (isPublic) {
-                    authSecret = undefined;
-                }
-                else if (methodAuthInfo) {
-                    authSecret = methodAuthInfo.secret || process.env.JWT_SECRET;
-                }
-                else if (classAuthInfo) {
-                    authSecret = classAuthInfo.secret || process.env.JWT_SECRET;
-                }
-                // 1. Auth Middleware (New Decorator Logic)
-                if (authSecret) {
-                    middlewares.push(this.createJwtMiddleware(authSecret));
+                // 1. Auth & Role Middlewares
+                if (!isPublic) {
+                    // If not public, we always run the role check (which might include authentication via UserHandler)
+                    middlewares.push(this.createRoleMiddleware(requiredRoles || []));
                     // Inject Swagger security definition automatically
                     if (!route.swagger) {
                         route.swagger = {
@@ -219,7 +293,8 @@ export class Server {
                         route.swagger.security.push({ bearerAuth: [] });
                     }
                 }
-                // 2. Generic Security Middleware (@Security, @OAuth, etc)
+                // 1.1 Role Middlewares - now handled above for non-public routes
+                // 2. Generic Security Middleware (@Security, @ApiKey, etc)
                 const classGenericSecurity = Reflect.getMetadata(SECURITY_METADATA_KEY, controller.target) || [];
                 const methodGenericSecurity = Reflect.getMetadata(SECURITY_METADATA_KEY, controller.target.prototype, route.handlerName) || [];
                 let genericRequirements = [];
@@ -301,9 +376,17 @@ export class Server {
                     middlewares.push(...route.middlewares);
                 }
                 // 3. Route Handler
-                const handler = (req, res, next) => {
+                const handler = async (req, res, next) => {
                     try {
-                        const result = instance[route.handlerName](req, res, next);
+                        const user = this._userHandler
+                            ? await this._userHandler.authenticate(req, res)
+                            : req.user;
+                        const result = instance[route.handlerName]({
+                            req,
+                            res,
+                            user,
+                            next,
+                        });
                         const handleResult = (val) => {
                             if (val !== undefined && !res.headersSent) {
                                 if (typeof val === "string") {
@@ -330,28 +413,55 @@ export class Server {
                 // Pre-build if @Serve is used
                 const htmlPath = Reflect.getMetadata(SERVE_HTML_METADATA_KEY, controller.target.prototype, route.handlerName);
                 if (htmlPath) {
-                    this.log(`[${this._id}] Pre-building HTML: ${htmlPath}`);
+                    // Silent pre-build
                     await ServeMemoryStore.instance.buildAndCache(htmlPath, tailwindOptions);
                 }
             }
         }
     }
-    createJwtMiddleware(secret) {
-        return (req, res, next) => {
-            const authHeader = req.headers.authorization;
-            if (!authHeader || !authHeader.startsWith("Bearer ")) {
-                return res
-                    .status(401)
-                    .json({ error: "Unauthorized: Missing Bearer token" });
+    createRoleMiddleware(roles) {
+        return async (req, res, next) => {
+            const user = this._userHandler
+                ? await this._userHandler.authenticate(req, res)
+                : req.user;
+            if (!user) {
+                return res.status(401).json({ error: "Unauthorized: No user found" });
+            }
+            // If no specific roles required, but it's not public, just authentication is enough
+            if (roles.length === 0) {
+                return next();
+            }
+            if (!this._roleHandler) {
+                // Default role check behavior
+                const userRoles = Array.isArray(user.roles)
+                    ? user.roles
+                    : user.role
+                        ? [user.role]
+                        : [];
+                const hasRole = roles.some((role) => userRoles.includes(role));
+                if (!hasRole) {
+                    return res.status(403).json({
+                        error: "Forbidden: You do not have the required permissions",
+                    });
+                }
+                return next();
             }
-            const token = authHeader.split(" ")[1];
             try {
-                const decoded = jwt.verify(token, secret);
-                req.user = decoded; // Attach user to request
-                next();
+                const result = await this._roleHandler(req, roles);
+                if (result) {
+                    // Assuming 'result' is a boolean indicating success
+                    next();
+                }
+                else {
+                    // The provided snippet seems to be for serving HTML, which is out of context for a role middleware.
+                    // Applying the original logic for role failure.
+                    res.status(403).json({
+                        error: "Forbidden: You do not have the required permissions",
+                    });
+                }
             }
             catch (err) {
-                return res.status(403).json({ error: "Forbidden: Invalid token" });
+                next(err);
             }
         };
     }

package/dist/Components/UserHandler.d.ts

@@ -0,0 +1,21 @@
+import { Request, Response } from "express";
+export declare abstract class UserHandler {
+    /**
+     * Optional: Logic to authenticate the request and return the user object.
+     * If this is not implemented, 'user' will be undefined in route parameters.
+     */
+    authenticate(req: Request, res: Response): Promise<any | null>;
+    /**
+     * Sign in logic. Usually returns a token or user info.
+     */
+    abstract signin(req: Request, res: Response): Promise<any> | any;
+    /**
+     * Sign up logic.
+     */
+    abstract signup(req: Request, res: Response): Promise<any> | any;
+    /**
+     * Logout logic.
+     */
+    abstract logout(req: Request, res: Response): Promise<any> | any;
+}
+//# sourceMappingURL=UserHandler.d.ts.map

package/dist/Components/UserHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserHandler.d.ts","sourceRoot":"","sources":["../../src/Components/UserHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AAE1D,8BAAsB,WAAW;IAC/B;;;OAGG;IACU,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAI3E;;OAEG;aACa,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG;IAEvE;;OAEG;aACa,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG;IAEvE;;OAEG;aACa,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG;CACxE"}

package/dist/Components/UserHandler.js

@@ -0,0 +1,9 @@
+export class UserHandler {
+    /**
+     * Optional: Logic to authenticate the request and return the user object.
+     * If this is not implemented, 'user' will be undefined in route parameters.
+     */
+    async authenticate(req, res) {
+        return req.user;
+    }
+}

package/dist/Decorations/Authorized.d.ts

@@ -1,8 +1,5 @@
-export declare const AUTH_METADATA_KEY = "auth:info";
 export declare const PUBLIC_METADATA_KEY = "auth:public";
-export interface AuthInfo {
-    secret?: string;
-}
-export declare function BearerAuth(secret?: string): MethodDecorator & ClassDecorator;
+export declare const ROLES_METADATA_KEY = "auth:roles";
+export declare function Authorized(roles?: string[]): MethodDecorator & ClassDecorator;
 export declare function Public(): MethodDecorator;
 //# sourceMappingURL=Authorized.d.ts.map

package/dist/Decorations/Authorized.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Authorized.d.ts","sourceRoot":"","sources":["../../src/Decorations/Authorized.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,cAAc,CAmB5E;AAED,wBAAgB,MAAM,IAAI,eAAe,CAQxC"}
+{"version":3,"file":"Authorized.d.ts","sourceRoot":"","sources":["../../src/Decorations/Authorized.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AACjD,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C,wBAAgB,UAAU,CACxB,KAAK,GAAE,MAAM,EAAO,GACnB,eAAe,GAAG,cAAc,CAclC;AAED,wBAAgB,MAAM,IAAI,eAAe,CAQxC"}

package/dist/Decorations/Authorized.js

@@ -1,15 +1,15 @@
 // Key to store auth metadata
-export const AUTH_METADATA_KEY = "auth:info";
 export const PUBLIC_METADATA_KEY = "auth:public";
-export function BearerAuth(secret) {
+export const ROLES_METADATA_KEY = "auth:roles";
+export function Authorized(roles = []) {
     return function (target, propertyKey, descriptor) {
-        // If used on a method
         if (propertyKey) {
-            Reflect.defineMetadata(AUTH_METADATA_KEY, { secret }, target, propertyKey);
+            Reflect.defineMetadata(ROLES_METADATA_KEY, roles, target, propertyKey);
+            // Explicitly mark as not public to prevent bypass if @Public() is also used
+            Reflect.defineMetadata(PUBLIC_METADATA_KEY, false, target, propertyKey);
         }
         else {
-            // If used on a class
-            Reflect.defineMetadata(AUTH_METADATA_KEY, { secret }, target);
+            Reflect.defineMetadata(ROLES_METADATA_KEY, roles, target);
         }
     };
 }

package/dist/Decorations/Security.d.ts

@@ -4,6 +4,5 @@ export interface SecurityRequirement {
     [name: string]: string[];
 }
 export declare function Security(name: string, scopes?: string[]): MethodDecorator & ClassDecorator;
-export declare function OAuth(scopes?: string[]): MethodDecorator & ClassDecorator;
 export declare function ApiKey(name: string): MethodDecorator & ClassDecorator;
 //# sourceMappingURL=Security.d.ts.map

package/dist/Decorations/Security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Security.d.ts","sourceRoot":"","sources":["../../src/Decorations/Security.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,eAAO,MAAM,qBAAqB,eAAqB,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,EAAO,GACpB,eAAe,GAAG,cAAc,CAyBlC;AAED,wBAAgB,KAAK,CAAC,MAAM,GAAE,MAAM,EAAO,GAAG,eAAe,GAAG,cAAc,CAE7E;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,cAAc,CAErE"}
+{"version":3,"file":"Security.d.ts","sourceRoot":"","sources":["../../src/Decorations/Security.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,eAAO,MAAM,qBAAqB,eAAqB,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,EAAO,GACpB,eAAe,GAAG,cAAc,CAyBlC;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,cAAc,CAErE"}

package/dist/Decorations/Security.js

@@ -16,9 +16,6 @@ export function Security(name, scopes = []) {
         }
     };
 }
-export function OAuth(scopes = []) {
-    return Security("oauth2", scopes);
-}
 export function ApiKey(name) {
     return Security(name, []);
 }

package/dist/Decorations/Serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Serve.d.ts","sourceRoot":"","sources":["../../src/Decorations/Serve.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAmDvD"}
+{"version":3,"file":"Serve.d.ts","sourceRoot":"","sources":["../../src/Decorations/Serve.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAwEvD"}

package/dist/Decorations/Serve.js

@@ -6,10 +6,12 @@ export function Serve(htmlPath) {
         // Store the HTML path in metadata for pre-building
         Reflect.defineMetadata(SERVE_HTML_METADATA_KEY, htmlPath, target, propertyKey);
         const originalMethod = descriptor.value;
-        descriptor.value = async function (req, res, next) {
+        descriptor.value = async function ({ req, res, user, next, }) {
             try {
                 // Execute the original method
-                const result = await originalMethod.apply(this, [req, res, next]);
+                const result = await originalMethod.apply(this, [
+                    { req, res, user, next },
+                ]);
                 // Check if response has been sent or if result is not undefined/void
                 if (res.headersSent || result !== undefined) {
                     return result;
@@ -19,14 +21,25 @@ export function Serve(htmlPath) {
                 // If no response, build and serve the HTML
                 const html = await ServeMemoryStore.instance.buildAndCache(htmlPath, tailwindOptions);
                 if (html) {
+                    const devMode = process.env.NODE_ENV === "development";
+                    if (devMode) {
+                        res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate, proxy-revalidate");
+                        res.setHeader("Pragma", "no-cache");
+                        res.setHeader("Expires", "0");
+                    }
                     res.type("html").send(html);
                 }
-                else {
+                else if (next) {
                     next(); // No HTML found?
                 }
             }
             catch (error) {
-                next(error);
+                if (next) {
+                    next(error);
+                }
+                else {
+                    throw error;
+                }
             }
         };
         return descriptor;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import "./globals";
 export * from "./Components/Server";
 export * from "./Components/ServeMemoryStore";
+export * from "./Components/UserHandler";
 export * from "./Decorations";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,WAAW,CAAC;AACnB,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,WAAW,CAAC;AACnB,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ global.servers = new Map();
 import "./globals";
 export * from "./Components/Server";
 export * from "./Components/ServeMemoryStore";
+export * from "./Components/UserHandler";
 export * from "./Decorations";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synchjs/ewb",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -26,26 +26,29 @@
     "example": "bun run --watch example/index.ts"
   },
   "dependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/express-serve-static-core": "^5.1.1",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/socket.io": "^3.0.2",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "boxen": "^8.0.1",
     "bun-plugin-tailwind": "^0.1.2",
+    "cheerio": "^1.2.0",
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "express-rate-limit": "^8.2.1",
     "helmet": "^8.1.0",
     "jsonwebtoken": "^9.0.3",
+    "openapi-types": "^12.1.3",
     "picocolors": "^1.1.1",
     "reflect-metadata": "^0.2.2",
+    "socket.io": "^4.8.3",
     "swagger-jsdoc": "^6.2.8",
     "swagger-ui-express": "^5.0.1",
-    "tailwindcss": "^4.1.18",
-    "openapi-types": "^12.1.3",
-    "@types/express": "^5.0.6",
-    "@types/cors": "^2.8.19",
-    "@types/jsonwebtoken": "^9.0.10",
-    "@types/swagger-jsdoc": "^6.0.4",
-    "@types/swagger-ui-express": "^4.1.8",
-    "@types/express-serve-static-core": "^5.1.1"
+    "tailwindcss": "^4.1.18"
   }
 }