bro-framework 2.3.0 → 2.4.0

package/README.md

@@ -20,7 +20,7 @@
 
 ---
 
-> "NestJS wants four decorators, three modules, and an existential crisis just to handle a GET request. Express makes you write the same 40 lines of CORS, JSON parsing, and auth middleware for every project. bro.js gives you file routing, auto-validation, JWT auth, WebSockets, and live docs out of the box. Be honest: you just want to return an object."
+> Skip the boilerplate. bro.js gives you file-based routing, automatic Zod validation, JWT auth, and WebSockets right out of the box. Just write your business logic, return an object, and let the framework handle the rest.
 
 ---
 
@@ -99,8 +99,9 @@ Create a `.js` file in the `routes/` directory, and it automatically becomes an
 ### Bouncer-Grade Validation
 Powered by Zod. Attach a schema to `body`, `query`, or `params` directly in your route definition. If the client sends malformed data, `bro.js` automatically rejects the request with a structured `400 Bad Request` JSON payload *before* your handler ever executes. You never have to manually validate inputs again. You can also define a `response` schema to strongly type your OpenAPI documentation (strictly opt-in; arbitrary 200s work out of the box).
 
-### Zero-Config JWTs
+### Zero-Config Auth (JWTs, RBAC, API Keys)
 Add `auth: true` to your route config. `bro.js` will intercept the request, extract the `Authorization: Bearer <token>` header, verify the signature using your `jwtSecret`, and inject the decoded payload directly into `ctx.user`.
+You can also use Role-Based Access Control by passing an array of roles (e.g. `auth: ['admin']`) or enforce strict service-to-service communication by using `auth: 'api-key'`. API Keys fully support zero-downtime rotation by accepting an array of valid keys in `bro.config.js`.
 
 ### Context Injection
 Stop importing singleton database connections and socket instances into every file. Define your `db` and `sockets` setup once in `bro.config.js`. `bro.js` orchestrates the initialization and injects both instances directly into the `ctx` object for every request handler.
@@ -185,6 +186,8 @@ The locale is negotiated dynamically using RFC 9110 `Accept-Language` headers, s
 | **API Reference** | Scalar | Auto-generated, interactive Swagger/OpenAPI documentation. |
 | **Task Scheduler** | node-cron | Reliable internal background task orchestration. |
 | **File Parsing** | multer | Zero-boilerplate `multipart/form-data` file extraction. |
+| **Caching & Scaling** | Redis | Optional zero-config route caching, distributed rate-limiting, and WebSocket scaling. |
+| **Security** | Helmet | Auto-configured industry-standard HTTP security headers. |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bro-framework",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "The No-BS Backend Framework for Node.js",
   "repository": {
     "type": "git",
@@ -27,14 +27,17 @@
   ],
   "dependencies": {
     "@scalar/express-api-reference": "^0.10.18",
+    "@socket.io/redis-adapter": "^8.3.0",
     "chokidar": "^5.0.0",
     "cors": "^2.8.6",
     "dotenv": "^16.4.5",
     "express": "^4.21.1",
     "express-rate-limit": "^8.7.0",
+    "helmet": "^8.3.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.3.0",
     "node-cron": "^4.6.0",
+    "redis": "^6.2.1",
     "socket.io": "^4.8.3",
     "tsx": "^4.23.13",
     "zod": "^3.23.8",
@@ -43,6 +46,7 @@
   "keywords": [
     "bro",
     "brojs",
+    "bro.js",
     "bro-framework",
     "framework",
     "backend",
@@ -84,5 +88,8 @@
     "ai-friendly",
     "developer-experience",
     "dx"
-  ]
+  ],
+  "devDependencies": {
+    "ioredis-mock": "^8.13.1"
+  }
 }

package/src/index.d.ts

@@ -2,6 +2,18 @@ import { z, ZodTypeAny } from 'zod';
 
 type InferZod<T> = T extends ZodTypeAny ? z.infer<T> : any;
 
+export interface UploadedFile {
+  fieldname: string;
+  originalname: string;
+  encoding: string;
+  mimetype: string;
+  size: number;
+  destination?: string;
+  filename?: string;
+  path?: string;
+  buffer?: Buffer;
+}
+
 export interface BroContext<Body = any, Params = any, Query = any> {
   env?: any;
   jwt?: { sign: (payload: any, options?: any) => string };
@@ -11,19 +23,22 @@ export interface BroContext<Body = any, Params = any, Query = any> {
   user?: any;
   db?: any;
   io?: any;
-  files?: any[];
+  file?: UploadedFile;
+  files?: UploadedFile[] | Record<string, UploadedFile[]>;
   locale: string;
   t: (key: string, values?: Record<string, unknown>) => string;
   error?: any;
+  redis?: any;
 }
 
 export interface RouteConfig<Body = any, Params = any, Query = any> {
-  auth?: boolean;
+  auth?: boolean | string[] | 'api-key';
   upload?: boolean | { limits?: any, fields?: { name: string, maxCount?: number }[], single?: string, array?: string, fileFilter?: any, storage?: any };
   body?: Body;
   params?: Params;
   query?: Query;
   response?: ZodTypeAny;
+  cache?: number;
   rateLimit?: {
     windowMs: number;
     max: number;
@@ -48,6 +63,7 @@ export interface BroConfig {
   server?: {
     port?: number;
     cors?: boolean | object;
+    helmet?: boolean | object;
   };
   locale?: {
     directory?: string;
@@ -56,6 +72,7 @@ export interface BroConfig {
   auth?: {
     jwtSecret?: string;
     expiresIn?: string | number;
+    apiKey?: string | string[];
   };
   docs?: boolean | { auth?: { user: string; pass: string } };
   rateLimit?: {
@@ -73,6 +90,7 @@ export interface BroConfig {
   db?: () => Promise<any> | any;
   sockets?: (io: any, db: any) => Promise<void> | void;
   onShutdown?: (db: any) => Promise<void> | void;
+  redisUrl?: string;
 }
 
 export function defineConfig(config: BroConfig): BroConfig;

package/src/router.js

@@ -158,7 +158,9 @@ export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
       }
       
       // Auto-inject security definition if auth is true
-      if (config.auth) {
+      if (config.auth === 'api-key') {
+        operation.security = [{ apiKeyAuth: [] }];
+      } else if (config.auth) {
         operation.security = [{ bearerAuth: [] }];
       }
       

package/src/server.js

@@ -2,9 +2,13 @@ import express from 'express';
 import cors from 'cors';
 import http from 'node:http';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { Server } from 'socket.io';
 import rateLimit from 'express-rate-limit';
 import multer from 'multer';
+import helmet from 'helmet';
+import { createClient } from 'redis';
+import { createAdapter } from '@socket.io/redis-adapter';
 import { apiReference } from '@scalar/express-api-reference';
 import { verifyJwt, signJwt } from './auth.js';
 import { loadLocale } from './locale.js';
@@ -28,6 +32,21 @@ export async function createServer(globalConfig, routesDir, db) {
   const localeDirectory = globalConfig.locale?.directory || path.join(process.cwd(), 'locale');
   let locale = await loadLocale(localeDirectory, globalConfig.locale);
   
+  const helmetConfig = globalConfig.server?.helmet !== undefined ? globalConfig.server.helmet : true;
+  if (helmetConfig !== false) {
+    const userConfig = typeof helmetConfig === 'object' ? helmetConfig : {};
+    app.use(helmet({
+      ...userConfig,
+      contentSecurityPolicy: userConfig.contentSecurityPolicy ?? {
+        directives: {
+          ...helmet.contentSecurityPolicy.getDefaultDirectives(),
+          "script-src": ["'self'", "'unsafe-inline'"],
+          "style-src": ["'self'", "'unsafe-inline'"],
+        },
+      }
+    }));
+  }
+
   const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : true;
   
   if (corsConfig !== false) {
@@ -36,12 +55,84 @@ export async function createServer(globalConfig, routesDir, db) {
   
   app.use(express.json());
   
+  const safeConnect = async (client) => {
+    if (typeof client.connect !== 'function') return;
+    if (client.status && client.status !== 'wait') return;
+    try {
+      await client.connect();
+    } catch (err) {
+      if (!err.message.includes('already connecting') && !err.message.includes('already connected')) {
+        throw err;
+      }
+    }
+  };
+
+  let redisClient = null;
+  let pubClient = null;
+  let subClient = null;
+  
+  try {
+    if (globalConfig.redisUrl) {
+      redisClient = createClient({ url: globalConfig.redisUrl });
+      redisClient.on('error', (err) => console.error('[bro.js] Redis Error:', err));
+      await safeConnect(redisClient);
+    } else if (process.env.NODE_ENV === 'test') {
+      try {
+        const IORedisMock = (await import('ioredis-mock')).default;
+        redisClient = new IORedisMock();
+        redisClient.connect = async () => {};
+        redisClient.setEx = redisClient.setex.bind(redisClient);
+      } catch (err) {
+        throw new Error("ioredis-mock is required for test mode. Please install it as a devDependency to use NODE_ENV=test.");
+      }
+    }
+  } catch (err) {
+    if (redisClient) await redisClient.quit().catch(() => {});
+    throw err;
+  }
+
   if (globalConfig.rateLimit) {
-    app.use(rateLimit(globalConfig.rateLimit));
+    if (redisClient) {
+      const fallbackLimiter = rateLimit(globalConfig.rateLimit);
+      app.use(async (req, res, next) => {
+        try {
+          const key = `rate_limit:global:${req.ip}`;
+          const current = await redisClient.incr(key);
+          if (current === 1) {
+            await redisClient.expire(key, Math.floor(globalConfig.rateLimit.windowMs / 1000));
+          }
+          if (current > globalConfig.rateLimit.max) {
+            return res.status(429).json({ error: 'Too Many Requests' });
+          }
+          next();
+        } catch (err) {
+          console.error('[bro.js] Redis Global Rate Limit Error:', err);
+          fallbackLimiter(req, res, next);
+        }
+      });
+    } else {
+      app.use(rateLimit(globalConfig.rateLimit));
+    }
   }
   
   const io = new Server(server, { cors: typeof corsConfig === 'object' ? corsConfig : undefined });
   
+  try {
+    if (redisClient) {
+      pubClient = redisClient.duplicate();
+      subClient = redisClient.duplicate();
+      await Promise.all([safeConnect(pubClient), safeConnect(subClient)]);
+      io.adapter(createAdapter(pubClient, subClient));
+    }
+  } catch (err) {
+    await Promise.allSettled([
+      redisClient?.quit(),
+      pubClient?.quit(),
+      subClient?.quit()
+    ].filter(Boolean));
+    throw err;
+  }
+  
   if (globalConfig.sockets) {
     await globalConfig.sockets(io, db);
   }
@@ -55,7 +146,27 @@ export async function createServer(globalConfig, routesDir, db) {
     const querySchema = routeConfig.query;
     
     if (routeConfig.rateLimit) {
-      middlewares.push(rateLimit(routeConfig.rateLimit));
+      if (redisClient) {
+        const fallbackLimiter = rateLimit(routeConfig.rateLimit);
+        middlewares.push(async (req, res, next) => {
+          try {
+            const key = `rate_limit:${req.ip}:${req.originalUrl}`;
+            const current = await redisClient.incr(key);
+            if (current === 1) {
+              await redisClient.expire(key, Math.floor(routeConfig.rateLimit.windowMs / 1000));
+            }
+            if (current > routeConfig.rateLimit.max) {
+              return res.status(429).json({ error: 'Too Many Requests' });
+            }
+            next();
+          } catch (err) {
+            console.error('[bro.js] Redis Route Rate Limit Error:', err);
+            fallbackLimiter(req, res, next);
+          }
+        });
+      } else {
+        middlewares.push(rateLimit(routeConfig.rateLimit));
+      }
     }
     
     if (routeConfig.upload) {
@@ -91,6 +202,7 @@ export async function createServer(globalConfig, routesDir, db) {
           env: globalConfig.envData || process.env,
           db,
           io,
+          redis: redisClient,
           body: req.body,
           params: req.params,
           query: req.query,
@@ -106,20 +218,39 @@ export async function createServer(globalConfig, routesDir, db) {
           }
         };
 
-        if (routeConfig.auth) {
+        if (routeConfig.auth === 'api-key') {
+          const apiKey = req.headers['x-api-key'];
+          const validKey = globalConfig.auth?.apiKey || process.env.API_KEY;
+          
+          let isValid = false;
+          if (Array.isArray(validKey)) {
+            isValid = validKey.includes(apiKey);
+          } else {
+            isValid = apiKey && apiKey === validKey;
+          }
+          
+          if (!isValid) {
+            return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid API key' });
+          }
+        } else if (routeConfig.auth) {
           const authHeader = req.headers.authorization;
           if (!authHeader || !authHeader.startsWith('Bearer ')) {
             return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid Bearer token' });
           }
           
-          const token = authHeader.split(' ')[1];
+          const token = authHeader?.split(' ')[1] ?? '';
           const authResult = verifyJwt(token, globalConfig.jwtSecret);
           
           if (!authResult.valid) {
             return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
           }
+          ctx.user = authResult.payload ?? null;
           
-          ctx.user = authResult.payload;
+          if (Array.isArray(routeConfig.auth)) {
+             if (!ctx.user || !ctx.user.role || !routeConfig.auth.includes(ctx.user.role)) {
+                return res.status(403).json({ error: 'Forbidden', details: 'Insufficient role permissions' });
+             }
+          }
         }
 
         if (paramsSchema) {
@@ -150,9 +281,29 @@ export async function createServer(globalConfig, routesDir, db) {
            throw new Error('Route "handler" is missing or is not a function');
         }
 
+        let cacheKey = null;
+        if (routeConfig.cache && redisClient) {
+          const authIdentity = crypto.createHash('sha256').update(req.headers.authorization || req.headers['x-api-key'] || 'anonymous').digest('hex');
+          cacheKey = `bro:cache:${req.method}:${req.originalUrl}:${requestLocale}:${authIdentity}`;
+          try {
+            const cached = await redisClient.get(cacheKey);
+            if (cached) {
+              const parsed = JSON.parse(cached);
+              if (!res.headersSent) res.status(200).json(parsed);
+              return;
+            }
+          } catch (err) {
+            console.error('[bro.js] Cache parsing failed, deleting key:', cacheKey);
+            await redisClient.del(cacheKey).catch(() => {});
+          }
+        }
+
         const responseData = await routeConfig.handler(ctx);
         
         if (!res.headersSent) {
+           if (cacheKey && routeConfig.cache) {
+             await redisClient.setEx(cacheKey, routeConfig.cache, JSON.stringify(responseData));
+           }
            res.status(200).json(responseData);
         }
 
@@ -186,6 +337,11 @@ export async function createServer(globalConfig, routesDir, db) {
           type: 'http',
           scheme: 'bearer',
           bearerFormat: 'JWT'
+        },
+        apiKeyAuth: {
+          type: 'apiKey',
+          in: 'header',
+          name: 'x-api-key'
         }
       },
       responses: {
@@ -259,6 +415,11 @@ export async function createServer(globalConfig, routesDir, db) {
     isShuttingDown = true;
     if (taskManager) taskManager.stopAll();
     if (io) io.close();
+    await Promise.allSettled([
+      redisClient?.quit(),
+      pubClient?.quit(),
+      subClient?.quit()
+    ].filter(Boolean));
     
     if (typeof globalConfig.onShutdown === 'function') {
       try {