zyket 1.2.18 → 1.2.20

package/plugin/skills/build/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: build
+description: Build, configure, and run applications with the Zyket framework — start a project from a template, enable services, wire authentication, secure the app, and add features. Use whenever the user wants to use Zyket, create or set up a Zyket project/app, or understand how Zyket works. For scaffolding a single component, use the `generate` skill instead.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Build with Zyket
+
+Use this skill to take a user from zero to a running Zyket application, or to extend an existing one. Zyket is a service-oriented Node.js framework (Express 5 + Socket.IO + better-auth + Sequelize/BullMQ/MinIO) with filesystem auto-discovery and a DI container.
+
+## Golden rules
+
+1. **Read the reference.** After install, the full, authoritative API lives in `node_modules/zyket/AGENTS.md`. Read it before relying on any API; confirm base classes against `node_modules/zyket/` source. Do not invent APIs.
+2. **Filename = identity.** Routes, handlers, guards, events, schedulers, workers, and models are auto-discovered from `src/<folder>/`; the filename determines the URL/event/name. Use kebab-case and `module.exports = class extends Base`. Never add constructor params to these.
+3. **Services activate from `.env`.** A feature that needs sockets/queues/db must have the matching `DISABLE_*=false` / `DATABASE_URL` set.
+4. **Secure by default.** Protect non-public routes/sockets with `RequireAuthMiddleware` / `AuthGuard`. Never weaken cookie/auth settings to "make it work" — use `AUTH_CROSS_DOMAIN` instead.
+
+## Workflow
+
+### A. Starting a new project
+
+1. **Pick a template** by intent:
+
+   | User wants… | Template |
+   |-------------|----------|
+   | A clean REST API | `api-rest` |
+   | Multi-tenant SaaS (orgs, roles, dashboard) | `saas-multitenant` |
+   | Real-time / chat / live updates | `realtime-chat` |
+   | A general starter / unsure | `default` |
+
+2. **Scaffold:**
+   ```bash
+   npm install zyket
+   npx zyket init <template>
+   ```
+   This copies the template, merges its `.env.example` onto sensible defaults, writes `package.json` with the right dependencies, and installs them.
+
+3. **If the template uses auth** (`src/services/auth` exists), create the tables once:
+   ```bash
+   npx @better-auth/cli migrate
+   ```
+
+4. **Run:** `node index.js`. The API is on `PORT` (3000); a frontend, if any, on `VITE_PORT` (5173).
+
+### B. Enabling a capability in an existing project
+
+Flip the env flag, then add the component. Confirm details in `AGENTS.md §3–4`.
+
+| Capability | `.env` | Then add |
+|-----------|--------|----------|
+| HTTP routes | `DISABLE_EXPRESS=false` | `src/routes/**.js` |
+| Real-time | `DISABLE_SOCKET=false` | `src/handlers/*.js`, `src/guards/*.js` |
+| Database | `DATABASE_URL=...`, `DATABASE_DIALECT=...` | `src/models/*.js` |
+| Background jobs | `DISABLE_BULLMQ=false`, `QUEUES=emails` | `src/workers/*.js` |
+| Cron | `DISABLE_SCHEDULER=false` | `src/schedulers/*.js` |
+| Cache | `CACHE_URL=redis://…` (or in-memory) | use `container.get('cache')` |
+| Object storage | `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY` | use `container.get('s3')` |
+| Frontend | `DISABLE_VITE=false`, `VITE_ROOT=./frontend` | `frontend/` React app |
+
+### C. Adding authentication
+
+1. Register the auth service in `index.js`: `["auth", require("./src/services/auth"), ["@service_container"]]`.
+2. Subclass `AuthService` (see `AGENTS.md §6`) to set `organizationEnabled`, `requireEmailVerification`, email senders, etc.
+3. Require `DATABASE_DIALECT` = `sqlite` or `postgresql`; run `npx @better-auth/cli migrate`.
+4. Protect routes with `new RequireAuthMiddleware()` (or `['admin']` / `RequireAdminMiddleware`) and sockets with the `AuthGuard` (`module.exports = require('zyket').AuthGuard` in `src/guards/auth.js`; enforce connect-time auth inside `src/handlers/connection.js` via `container.get('auth').getSession(socket.handshake.headers)`).
+
+### D. Building a feature (recipe)
+
+1. Model → `src/models/Thing.js` (Sequelize factory). Create tables with `container.get('database').sync()` after boot, or migrations.
+2. Routes → `src/routes/things/index.js` (GET/POST) and `src/routes/things/[id].js` (GET/PUT/DELETE), gated by `RequireAuthMiddleware`.
+3. Read data via `container.get('database').models.Thing`.
+4. Optional realtime/jobs per the table in B.
+5. Run and verify.
+
+Delegate individual component scaffolding to the **`generate`** skill (e.g. `/zyket:generate route things/[id]`).
+
+## Common pitfalls
+
+- **PATCH routes don't dispatch** — only `get/post/put/delete` methods are wired.
+- **Connection guards don't block** — do connect-time auth inside `connection.js` (throw to disconnect).
+- **`bullmq`/`scheduler`/`events` default ON when the `DISABLE_*` var is absent**, but the generated `.env` ships them as `true`. Set them to `false` explicitly to enable.
+- **Auth fails to boot** if `AUTH_SECRET` is missing or a known placeholder — let the framework generate it.
+- **Frontend can't resolve `vite`/`react`/`better-auth`** — the project (not just zyket) must declare those deps; `npx zyket init` does this automatically for templates with a frontend.
+- **Boot crashes with `Cannot read properties of undefined (reading 'BarBarToken')`** — a TypeScript 7 got hoisted into the tree, which `node-dependency-injection`'s bundled `typescript-estree@5` can't read. Zyket pins `typescript` to `^5` and `npx zyket init` writes a matching `overrides` block; on a project predating that, add `"overrides": { "typescript": "^5.9.3" }` to `package.json` and reinstall.
+
+## Security pass before shipping
+
+Run through `SECURITY.md`. Minimum: every private route/socket guarded; `BULLBOARD_ADMIN_PASSWORD` set (or the dashboard won't mount); `SWAGGER_PASSWORD` or `DISABLE_SWAGGER=true`; `TRUSTED_ORIGINS` locked; add rate limiting + `helmet` (not bundled).

package/src/extensions/bullboard/index.js

@@ -7,14 +7,17 @@ const basicAuth = require('express-basic-auth')
 module.exports = class BullBoardExtension  extends Extension {
   path;
 
-  constructor({ path = '/bullboard', basePath = '' } = {}) {
+  constructor({ path = '/bullboard', basePath = '', middlewares = [] } = {}) {
     super("BullBoardExtension");
     this.path = path || '/bullboard';
     this.basePath = basePath;
+    // Optional Express middlewares (e.g. custom auth) applied before the board.
+    this.middlewares = middlewares || [];
   }
 
   load(container) {
-    if (!container.get('bullmq')) return container.get('logger').warn('BullBoardExtension: bullmq service not found, skipping BullBoard setup');
+    const logger = container.get('logger')
+    if (!container.get('bullmq')) return logger.warn('BullBoardExtension: bullmq service not found, skipping BullBoard setup');
     const bull = container.get('bullmq')
     const serverAdapter = new ExpressAdapter()
     serverAdapter.setBasePath(this.basePath + this.path)
@@ -25,7 +28,7 @@ module.exports = class BullBoardExtension  extends Extension {
     })
 
     const app = container.get('express').app()
-    const middlewares = []
+    const middlewares = [...this.middlewares]
 
     if (process.env.BULLBOARD_ADMIN_PASSWORD) {
       middlewares.push(basicAuth({
@@ -34,6 +37,14 @@ module.exports = class BullBoardExtension  extends Extension {
       }))
     }
 
+    // Fail closed: never expose the queue dashboard (jobs, payloads, retry/delete)
+    // without authentication. Require a password or custom auth middlewares.
+    if (middlewares.length === 0) {
+      return logger.warn(
+        `BullBoardExtension: no authentication configured. Set BULLBOARD_ADMIN_PASSWORD or pass "middlewares" to expose the dashboard. Skipping mount of ${this.path}.`
+      )
+    }
+
     app.use(this.path, ...middlewares, serverAdapter.getRouter())
   }
 }

package/src/extensions/interactive-storage/index.js

@@ -15,13 +15,15 @@ module.exports = class InteractiveStorageExtension extends Extension {
   path;
   maxFileSize;
   middlewares;
+  maxDeleteBatch;
 
-  constructor({ path = '/storage', bucketName = 'dropbox', maxFileSize = 100 * 1024 * 1024, middlewares = [] } = {}) {
+  constructor({ path = '/storage', bucketName = 'dropbox', maxFileSize = 100 * 1024 * 1024, middlewares = [], maxDeleteBatch = 100 } = {}) {
     super("InteractiveStorageExtension");
     this.path = path || '/storage';
     InteractiveStorageExtension.bucketName = bucketName;
     this.maxFileSize = maxFileSize;
     this.middlewares = middlewares || [];
+    this.maxDeleteBatch = maxDeleteBatch;
   }
 
   load(container) {
@@ -47,15 +49,24 @@ module.exports = class InteractiveStorageExtension extends Extension {
       new BrowseRoute(`${this.path}/browse`, s3, InteractiveStorageExtension.bucketName, normalizePath, listFilesAndFolders),
       new DownloadRoute(`${this.path}/download/:fileName`, s3, InteractiveStorageExtension.bucketName, getFileStat),
       new InfoRoute(`${this.path}/info/:fileName`, s3, InteractiveStorageExtension.bucketName, getFileStat),
-      new DeleteRoute(`${this.path}/delete`, s3, InteractiveStorageExtension.bucketName),
+      new DeleteRoute(`${this.path}/delete`, s3, InteractiveStorageExtension.bucketName, this.maxDeleteBatch),
       new CreateFolderRoute(`${this.path}/create-folder`, s3, InteractiveStorageExtension.bucketName, normalizePath),
-      new DeleteFolderRoute(`${this.path}/delete-folder`, s3, InteractiveStorageExtension.bucketName, normalizePath, listFiles)
+      new DeleteFolderRoute(`${this.path}/delete-folder`, s3, InteractiveStorageExtension.bucketName, normalizePath, listFiles, this.maxDeleteBatch)
     ];
 
-    // Add multer middleware to upload route
-    routes[0].middlewares = {
-      post: [new MulterMiddleware(this.maxFileSize)]
-    };
+    // Apply the user-provided middlewares (e.g. authentication) to every
+    // storage route and method. They run before the route handler.
+    const userMiddlewares = this.middlewares || [];
+    for (const route of routes) {
+      route.middlewares = {
+        get: [...userMiddlewares],
+        post: [...userMiddlewares],
+        delete: [...userMiddlewares]
+      };
+    }
+
+    // Add multer middleware to the upload route, after any auth middlewares.
+    routes[0].middlewares.post = [...userMiddlewares, new MulterMiddleware(this.maxFileSize)];
 
     // Register routes using the express service pattern
     express.registerRoutes(routes);
@@ -148,8 +159,13 @@ module.exports = class InteractiveStorageExtension extends Extension {
   }
 
   #normalizePath(path) {
-    // Remove leading/trailing slashes and normalize
-    return path.replace(/^\/+|\/+$/g, '').replace(/\/+/g, '/');
+    // Normalize slashes and strip any path-traversal segments so a crafted
+    // "folder"/"folderPath" value cannot escape the intended prefix.
+    return String(path)
+      .replace(/\\/g, '/')
+      .split('/')
+      .filter((segment) => segment && segment !== '.' && segment !== '..')
+      .join('/');
   }
 
   async #getFileStat(s3, fileName) {

package/src/extensions/interactive-storage/routes/delete-folder.js

@@ -5,13 +5,15 @@ module.exports = class DeleteFolderRoute extends Route {
   bucketName;
   normalizePath;
   listFiles;
+  maxDeleteBatch;
 
-  constructor(path, s3, bucketName, normalizePath, listFiles) {
+  constructor(path, s3, bucketName, normalizePath, listFiles, maxDeleteBatch = 100) {
     super(path);
     this.s3 = s3;
     this.bucketName = bucketName;
     this.normalizePath = normalizePath;
     this.listFiles = listFiles;
+    this.maxDeleteBatch = maxDeleteBatch;
   }
 
   async delete({ container, request }) {
@@ -36,6 +38,16 @@ module.exports = class DeleteFolderRoute extends Route {
       };
     }
 
+    // Cap the batch size to avoid mass-deletion / resource-exhaustion when a
+    // prefix contains a very large number of objects.
+    if (files.length > this.maxDeleteBatch) {
+      return {
+        success: false,
+        message: `Folder contains too many files (${files.length}). Maximum allowed per request is ${this.maxDeleteBatch}`,
+        status: 400
+      };
+    }
+
     // Delete all files
     const deletePromises = files.map(file => 
       this.s3.removeFile(this.bucketName, file.name).catch(err => ({ error: err.message, fileName: file.name }))

package/src/extensions/interactive-storage/routes/delete.js

@@ -3,24 +3,35 @@ const { Route } = require('../../../services/express');
 module.exports = class DeleteRoute extends Route {
   s3;
   bucketName;
+  maxDeleteBatch;
 
-  constructor(path, s3, bucketName) {
+  constructor(path, s3, bucketName, maxDeleteBatch = 100) {
     super(path);
     this.s3 = s3;
     this.bucketName = bucketName;
+    this.maxDeleteBatch = maxDeleteBatch;
   }
 
   async delete({ container, request }) {
     const logger = container.get('logger');
     const { fileName, fileNames } = request.body;
-    
+
     // Support both single file and multiple files
     const filesToDelete = fileNames || (fileName ? [fileName] : []);
-    
+
     if (!Array.isArray(filesToDelete) || filesToDelete.length === 0) {
       return { success: false, message: 'fileName or fileNames array is required', status: 400 };
     }
 
+    // Cap the batch size to avoid mass-deletion / resource-exhaustion in a single request.
+    if (filesToDelete.length > this.maxDeleteBatch) {
+      return {
+        success: false,
+        message: `Too many files in a single request. Maximum allowed is ${this.maxDeleteBatch}`,
+        status: 400
+      };
+    }
+
     const deletePromises = filesToDelete.map(file => 
       this.s3.removeFile(this.bucketName, file).catch(err => ({ error: err.message, fileName: file }))
     );

package/src/extensions/interactive-storage/routes/download.js

@@ -1,4 +1,13 @@
 const { Route } = require('../../../services/express');
+const path = require('path');
+
+// Reject object keys that try to escape the bucket prefix or are malformed,
+// before they reach the S3 client.
+function isUnsafeKey(key) {
+  if (typeof key !== 'string' || key.length === 0) return true;
+  if (key.includes('\\') || key.startsWith('/')) return true;
+  return key.split('/').some((segment) => segment === '..' || segment === '.');
+}
 
 module.exports = class DownloadRoute extends Route {
   s3;
@@ -15,14 +24,24 @@ module.exports = class DownloadRoute extends Route {
   async get({ container, request, response }) {
     const logger = container.get('logger');
     const { fileName } = request.params;
-    
+
+    if (isUnsafeKey(fileName)) {
+      return { success: false, message: 'Invalid file name', status: 400 };
+    }
+
     try {
       // Get file info first
       const stat = await this.getFileStat(this.s3, fileName);
       
-      // Set response headers
+      // Set response headers. Sanitize the filename to prevent header
+      // injection (CRLF / quote breakout) from the user-controlled key.
+      const baseName = path.posix.basename(fileName);
+      const asciiName = baseName.replace(/[^\w.\- ]/g, '_') || 'download';
       response.setHeader('Content-Type', stat.metaData?.['content-type'] || 'application/octet-stream');
-      response.setHeader('Content-Disposition', `attachment; filename="${fileName}"`);
+      response.setHeader(
+        'Content-Disposition',
+        `attachment; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(baseName)}`
+      );
       response.setHeader('Content-Length', stat.size);
 
       // Stream the file

package/src/extensions/interactive-storage/routes/info.js

@@ -1,5 +1,13 @@
 const { Route } = require('../../../services/express');
 
+// Reject object keys that try to escape the bucket prefix or are malformed,
+// before they reach the S3 client.
+function isUnsafeKey(key) {
+  if (typeof key !== 'string' || key.length === 0) return true;
+  if (key.includes('\\') || key.startsWith('/')) return true;
+  return key.split('/').some((segment) => segment === '..' || segment === '.');
+}
+
 module.exports = class InfoRoute extends Route {
   s3;
   bucketName;
@@ -17,6 +25,11 @@ module.exports = class InfoRoute extends Route {
     
     try {
       const { fileName } = request.params;
+
+      if (isUnsafeKey(fileName)) {
+        return { success: false, message: 'Invalid file name', status: 400 };
+      }
+
       const stat = await this.getFileStat(this.s3, fileName);
       
       return {

package/src/services/auth/index.js

@@ -4,6 +4,7 @@ const { betterAuth } = require("better-auth");
 const { admin, bearer, organization } = require("better-auth/plugins");
 const { Pool } = require("pg");
 const path = require("path");
+const crypto = require("crypto");
 
 module.exports = class AuthService extends Service {
   #container;
@@ -24,13 +25,26 @@ module.exports = class AuthService extends Service {
     express.regiterRawAllRoutes("/api/auth/*splat", toNodeHandler(this.auth));
   }
 
+  // Resolve the current better-auth session from raw Node request headers
+  // (e.g. `request.headers` or `socket.handshake.headers`). Lets application
+  // code check sessions without importing better-auth directly.
+  async getSession(headers) {
+    const { fromNodeHeaders } = require('better-auth/node');
+    return this.client.api.getSession({ headers: fromNodeHeaders(headers) });
+  }
+
   #addAuthEnvVariables() {
     const EnvManager = require('../../utils/EnvManager');
     const envPath = path.join(process.cwd(), '.env');
     
-    const secretAdded = EnvManager.addEnvVariable(envPath, 'AUTH_SECRET', 'change-this-secret-in-production');
+    // Generate a strong, unique secret per project instead of a static value.
+    const generatedSecret = crypto.randomBytes(32).toString('hex');
+    const secretAdded = EnvManager.addEnvVariable(envPath, 'AUTH_SECRET', generatedSecret);
     if (secretAdded) {
-      this.#container.get('logger').info('Added AUTH_SECRET to .env file');
+      // dotenv already loaded before this file was written, so make the freshly
+      // generated value available for this first run too.
+      process.env.AUTH_SECRET = generatedSecret;
+      this.#container.get('logger').info('Generated a random AUTH_SECRET and added it to .env file');
     }
 
     const originsAdded = EnvManager.addEnvVariable(envPath, 'TRUSTED_ORIGINS', 'http://localhost:5173,http://localhost:3000');
@@ -44,6 +58,15 @@ module.exports = class AuthService extends Service {
     }
   }
 
+  #requireAuthSecret() {
+    const secret = process.env.AUTH_SECRET;
+    // Fail closed: never fall back to a hard-coded/shared secret.
+    if (!secret || secret === 'change-this-secret-in-production' || secret === 'your-secret-key-change-in-production') {
+      throw new Error('AUTH_SECRET is missing or insecure. Set a strong, unique AUTH_SECRET in your .env file.');
+    }
+    return secret;
+  }
+
   #getDatabaseConnection() {
     const dialect = process.env.DATABASE_DIALECT;
 
@@ -68,6 +91,10 @@ module.exports = class AuthService extends Service {
     return true;
   }
 
+  get requireEmailVerification() {
+    return false;
+  }
+
   get socialProviders() {
     return {}
   }
@@ -106,6 +133,17 @@ module.exports = class AuthService extends Service {
 
   get auth() {
     const cache = this.#container.get('cache');
+
+    // Environment-aware cookie security:
+    // - Cross-domain front/back (different sites): set AUTH_CROSS_DOMAIN=true ->
+    //   sameSite "none" + secure + cross-subdomain (requires HTTPS).
+    // - Otherwise (local dev, or same-site/same-domain prod): sameSite "lax" and
+    //   secure only in production, so cookies work over http://localhost in dev.
+    const crossDomain = process.env.AUTH_CROSS_DOMAIN === 'true';
+    const isProduction = process.env.NODE_ENV === 'production';
+    const cookieSameSite = crossDomain ? 'none' : 'lax';
+    const cookieSecure = crossDomain || isProduction;
+
     return betterAuth({
       hooks: this.hooks,
       plugins: [
@@ -134,32 +172,12 @@ module.exports = class AuthService extends Service {
       socialProviders: this.socialProviders,
       database: this.#getDatabaseConnection(),
       advanced: {
-        crossSubDomainCookies: {
-          enabled: true,
-        },
-        cookie: {
-          sameSite: "none",
-          secure: true,
-          path: "/",
-          state: {
-            attributes: {
-              sameSite: "none",
-              secure: true,
-            }
-          }
-        },
+        ...(crossDomain ? { crossSubDomainCookies: { enabled: true } } : {}),
         defaultCookieAttributes: {
-          secure: true,
-          sameSite: "none",
+          sameSite: cookieSameSite,
+          secure: cookieSecure,
+          httpOnly: true,
         },
-        cookies: {
-          state: {
-            attributes: {
-              sameSite: "none",
-              secure: true,
-            }
-          }
-        }
       },
       secondaryStorage: {
         get: async (key) => {
@@ -175,7 +193,7 @@ module.exports = class AuthService extends Service {
       },
       emailAndPassword: {
         enabled: true,
-        requireEmailVerification: false,
+        requireEmailVerification: this.requireEmailVerification,
         sendResetPassword: async ({ user, url, token }, request) => this.sendResetPasswordEmail({ user, url, token }, request),
       },
       emailVerification: {
@@ -195,7 +213,7 @@ module.exports = class AuthService extends Service {
         updateAge: 60 * 60 * 24
       },
       baseURL: process.env.BETTER_AUTH_URL || 'http://localhost:3000',
-      secret: process.env.AUTH_SECRET || 'your-secret-key-change-in-production',
+      secret: this.#requireAuthSecret(),
       trustedOrigins: process.env.TRUSTED_ORIGINS?.split(',') || ['http://localhost:5173', 'http://localhost:6632']
     })
   }

package/src/services/express/Express.js

@@ -29,19 +29,36 @@ module.exports = class Express extends Service {
     this.#httpServer = httpServer;
     this.#app = express();
 
-    this.#app.use(express.json({ limit: `100mb` }))
+    // Configurable JSON body limit (defaults to 10mb) to reduce DoS surface.
+    this.#app.use(express.json({ limit: process.env.HTTP_JSON_LIMIT || '10mb' }))
 
     const corsOptions = await this.#loadCorsOrCreateDefault();
 
     if(corsOptions) this.#app.use(cors(corsOptions));
 
-    // Swagger setup
-    const swaggerOptions = {
-      ...(await this.#loadSwaggerOrCreateDefault()),
-    };
+    // Swagger setup (optional). Can be fully disabled, or protected with
+    // HTTP Basic auth by setting SWAGGER_PASSWORD.
+    if (process.env.DISABLE_SWAGGER !== 'true') {
+      const swaggerOptions = {
+        ...(await this.#loadSwaggerOrCreateDefault()),
+      };
+
+      const swaggerDocs = swaggerJsDoc(swaggerOptions);
+      const swaggerPath = process?.env?.SWAGGER_PATH || "/docs";
+      const swaggerMiddlewares = [];
 
-    const swaggerDocs = swaggerJsDoc(swaggerOptions);
-    this.#app.use(process?.env?.SWAGGER_PATH || "/docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs));
+      if (process.env.SWAGGER_PASSWORD) {
+        const basicAuth = require("express-basic-auth");
+        swaggerMiddlewares.push(basicAuth({
+          users: { [process.env.SWAGGER_USER || 'admin']: process.env.SWAGGER_PASSWORD },
+          challenge: true,
+        }));
+      } else {
+        this.#container.get('logger').warn(`Swagger docs are exposed without authentication at ${swaggerPath}. Set SWAGGER_PASSWORD to protect them or DISABLE_SWAGGER=true to disable.`);
+      }
+
+      this.#app.use(swaggerPath, ...swaggerMiddlewares, swaggerUi.serve, swaggerUi.setup(swaggerDocs));
+    }
 
     const routes = await this.#loadRoutesFromFolder(path.join(process.cwd(), "src", "routes"));
 
@@ -64,8 +81,8 @@ module.exports = class Express extends Service {
             try { 
               await mw.handle({ container: this.#container, request: req, response: res, next })
             } catch (error) {
-              this.#container.get('logger').error(`Error in middleware for route [${methodName}] ${route.path}: ${error.message}`);
-              return res.status(500).json({ success: false, message: error.message || 'Internal Server Error' });
+              this.#container.get('logger').error(`Error in middleware for route [${methodName}] ${route.path}: ${error.stack || error.message}`);
+              return res.status(500).json({ success: false, message: 'Internal Server Error' });
             }
           }), 
           async (req, res) => {
@@ -87,8 +104,8 @@ module.exports = class Express extends Service {
                 success: routeResponse?.success !== false,
               });
             } catch (error) {
-              this.#container.get('logger').error(`Error in route [${methodName}] ${route.path}: ${error.message}`);
-              return res.status(500).json({ success: false, message: error.message || 'Internal Server Error' });
+              this.#container.get('logger').error(`Error in route [${methodName}] ${route.path}: ${error.stack || error.message}`);
+              return res.status(500).json({ success: false, message: 'Internal Server Error' });
             }
           });
         }
@@ -120,8 +137,8 @@ module.exports = class Express extends Service {
             try { 
               await mw.handle({ container: this.#container, request: req, response: res, next })
             } catch (error) {
-              this.#container.get('logger').error(`Error in middleware for route [${methodName}] ${route.path}: ${error.message}`);
-              return res.status(500).json({ success: false, message: error.message || 'Internal Server Error' });
+              this.#container.get('logger').error(`Error in middleware for route [${methodName}] ${route.path}: ${error.stack || error.message}`);
+              return res.status(500).json({ success: false, message: 'Internal Server Error' });
             }
           }),
           async (req, res) => {
@@ -143,8 +160,8 @@ module.exports = class Express extends Service {
                 success: routeResponse?.success !== false,
               });
             } catch (error) {
-              this.#container.get('logger').error(`Error in route [${methodName}] ${route.path}: ${error.message}`);
-              return res.status(500).json({ success: false, message: error.message || 'Internal Server Error' });
+              this.#container.get('logger').error(`Error in route [${methodName}] ${route.path}: ${error.stack || error.message}`);
+              return res.status(500).json({ success: false, message: 'Internal Server Error' });
             }
           });
       }

package/src/services/express/RequireAdminMiddleware.js

@@ -0,0 +1,14 @@
+const RequireAuthMiddleware = require("./RequireAuthMiddleware");
+
+/**
+ * Convenience middleware that requires an authenticated user with the
+ * `admin` role (better-auth admin plugin).
+ *
+ * Usage in a Route:
+ *   middlewares = { delete: [ new RequireAdminMiddleware() ] }
+ */
+module.exports = class RequireAdminMiddleware extends RequireAuthMiddleware {
+  constructor(adminRole = 'admin') {
+    super([adminRole]);
+  }
+};

package/src/services/express/RequireAuthMiddleware.js

@@ -0,0 +1,46 @@
+const Middleware = require("./Middleware");
+const { fromNodeHeaders } = require("better-auth/node");
+
+/**
+ * Blocks the request unless there is a valid better-auth session.
+ * Optionally restricts access to a set of roles (admin plugin).
+ *
+ * On success it attaches `request.user` and `request.session`.
+ *
+ * Usage in a Route:
+ *   middlewares = { get: [ new RequireAuthMiddleware() ] }
+ *   middlewares = { post: [ new RequireAuthMiddleware(['admin']) ] }
+ */
+module.exports = class RequireAuthMiddleware extends Middleware {
+  constructor(roles = []) {
+    super();
+    this.roles = Array.isArray(roles) ? roles : [roles].filter(Boolean);
+  }
+
+  async handle({ container, request, response, next }) {
+    const auth = container.get('auth');
+    if (!auth || !auth.client) {
+      return response.status(500).json({ success: false, message: 'Auth service not available' });
+    }
+
+    const session = await auth.client.api.getSession({
+      headers: fromNodeHeaders(request.headers)
+    });
+
+    if (!session || !session.user) {
+      return response.status(401).json({ success: false, message: 'Unauthorized' });
+    }
+
+    if (this.roles.length > 0) {
+      const userRoles = String(session.user.role || '').split(',').map((r) => r.trim());
+      const allowed = this.roles.some((role) => userRoles.includes(role));
+      if (!allowed) {
+        return response.status(403).json({ success: false, message: 'Forbidden' });
+      }
+    }
+
+    request.user = session.user;
+    request.session = session.session;
+    next();
+  }
+};

package/src/services/express/index.js

@@ -1,5 +1,7 @@
-module.exports = {
-  Express: require("./Express"),
-  Route: require("./Route"),
-  Middleware: require("./Middleware"),
-}
+module.exports = {
+  Express: require("./Express"),
+  Route: require("./Route"),
+  Middleware: require("./Middleware"),
+  RequireAuthMiddleware: require("./RequireAuthMiddleware"),
+  RequireAdminMiddleware: require("./RequireAdminMiddleware"),
+}