bro-framework 2.4.4 → 3.0.0

package/src/next.js

@@ -1,17 +1,30 @@
-import { NextResponse } from 'next/server';
+import { NextResponse } from 'next/server.js';
+import crypto from 'node:crypto';
 import { z } from 'zod';
 import { verifyJwt, signJwt } from './auth.js';
 import { createClient } from 'redis';
+import { createLogger } from './logger.js';
+import { executeRequest, RouteRegistry, resolveIdentity } from './engine.js';
+export function hashIdentity(identity) { return crypto.createHash('sha256').update(String(identity)).digest('hex'); }
+export function generateRateLimitKey(req, config, prefix = 'route') { const identity = resolveIdentity(req, config); return `bro:rate_limit:${prefix}:${originalUrl}:${hashIdentity(identity)}`; }
+export function generateCacheKey(req, config, locale) { const identity = resolveIdentity(req, config); return `bro:cache:${method}:${originalUrl}:${locale}:${hashIdentity(identity)}`; }
 
 export { z };
 
 export function createBro(globalConfig = {}) {
+  const globalLogger = createLogger(globalConfig.logger || { level: process.env.NODE_ENV === 'production' ? 'info' : 'debug' });
+
   let isInitialized = false;
   let initPromise = null;
 
   let globalDb = null;
-  let globalRedis = null;
   let globalLocale = null;
+  const routeRegistry = new RouteRegistry();
+  
+  const globalStore = globalThis;
+  globalStore.__broRedis = globalStore.__broRedis || null;
+  globalStore.__broMemoryCache = globalStore.__broMemoryCache || new Map();
+  globalStore.__broMemoryRateLimit = globalStore.__broMemoryRateLimit || new Map();
 
   async function ensureInitialized() {
     if (isInitialized) return;
@@ -19,6 +32,10 @@ export function createBro(globalConfig = {}) {
 
     initPromise = (async () => {
       try {
+        if (process.env.NODE_ENV === 'production' && ['dev_secret_please_change', 'bro_default_secret_key', 'your_jwt_secret_here'].includes(globalConfig.auth?.jwtSecret)) {
+          throw new Error('CRITICAL SECURITY ERROR: You are running in production with a default JWT secret!');
+        }
+
         if (globalConfig.env) {
           try {
             globalConfig.env.parse(process.env);
@@ -38,10 +55,10 @@ export function createBro(globalConfig = {}) {
         }
 
         if (globalConfig.redisUrl) {
-          globalRedis = createClient({ url: globalConfig.redisUrl });
-          globalRedis.on('error', (err) => console.error('[bro.js/next] Redis Error:', err));
-          if (globalRedis.status === 'wait' || !globalRedis.status) {
-             await globalRedis.connect().catch(err => {
+          globalStore.__broRedis = createClient({ url: globalConfig.redisUrl });
+          globalStore.__broRedis.on('error', (err) => console.error('[bro.js/next] Redis Error:', err));
+          if (!globalStore.__broRedis.isOpen) {
+             await globalStore.__broRedis.connect().catch(err => {
                 if (!err.message.includes('already connecting') && !err.message.includes('already connected')) {
                   throw err;
                 }
@@ -85,7 +102,6 @@ export function createBro(globalConfig = {}) {
     let messages = globalConfig.locales?.[locale] || globalConfig.locales?.[globalConfig.defaultLocale || 'en'];
     if (!messages) return key;
 
-    // Handle Webpack / ES module JSON interop where the object is under .default
     if (messages.default && typeof messages.default === 'object') {
       messages = messages.default;
     }
@@ -105,89 +121,15 @@ export function createBro(globalConfig = {}) {
   };
 
   function defineRoute(config) {
+    // Register route for OpenAPI in Next environments
+    routeRegistry.register(config);
+
     return async function (req, context) {
       try {
         await ensureInitialized();
 
         const resolvedLocale = resolveLocale(Object.fromEntries(req.headers.entries()));
-
-        // Auth extraction early for Identity caching
-        let user = null;
-        let apiKeyUsed = null;
-        if (config.auth) {
-          if (config.auth === 'api-key') {
-            const apiKey = req.headers.get('x-api-key') || req.headers.get('authorization')?.replace('Bearer ', '');
-            const configuredKey = globalConfig?.auth?.apiKey || process.env.API_KEY;
-            
-            let isValid = false;
-            if (configuredKey) {
-              const keys = (Array.isArray(configuredKey) ? configuredKey : configuredKey.split(',')).map(k => String(k).trim());
-              isValid = keys.includes(apiKey);
-            }
-            
-            if (!isValid) {
-              return NextResponse.json({ error: 'Unauthorized', details: 'Missing or invalid API key' }, { status: 401 });
-            }
-            apiKeyUsed = apiKey;
-          } else {
-            const authHeader = req.headers.get('authorization');
-            if (!authHeader || !authHeader.startsWith('Bearer ')) {
-              return NextResponse.json({ error: 'Unauthorized', details: 'Missing Bearer token' }, { status: 401 });
-            }
-            
-            const token = authHeader.split(' ')[1];
-            const secret = globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET;
-            
-            if (!secret) {
-               return NextResponse.json({ error: 'Internal Server Error', details: 'JWT_SECRET is not configured' }, { status: 500 });
-            }
-            
-            const decoded = verifyJwt(token, secret);
-            if (!decoded.valid) {
-              return NextResponse.json({ error: 'Unauthorized', details: decoded.error }, { status: 401 });
-            }
-            
-            user = decoded.payload;
-            
-            if (Array.isArray(config.auth) && config.auth.length > 0) {
-              if (!user.role || !config.auth.includes(user.role)) {
-                return NextResponse.json({ error: 'Forbidden', details: 'Insufficient permissions' }, { status: 403 });
-              }
-            }
-          }
-        }
-
-        // Rate Limiting
-        const activeRateLimit = config.rateLimit === false ? null : (config.rateLimit || globalConfig.rateLimit);
-        if (activeRateLimit && globalRedis) {
-          const ip = req.headers.get('x-forwarded-for') || 'ip';
-          const urlObj = new URL(req.url);
-          const rlKey = `rate-limit:${urlObj.pathname}:${ip}`;
-          const currentCount = await globalRedis.incr(rlKey);
-          if (currentCount === 1) {
-            await globalRedis.expire(rlKey, Math.ceil(activeRateLimit.windowMs / 1000));
-          }
-          if (currentCount > activeRateLimit.max) {
-            return NextResponse.json({ error: 'Too Many Requests' }, { status: 429 });
-          }
-        }
-
-        // Caching
-        let cacheKey = null;
-        if (config.cache && globalRedis && req.method === 'GET') {
-          const urlObj = new URL(req.url);
-          const identity = user ? (user.id || user.role || 'user') : (apiKeyUsed || 'anon');
-          cacheKey = `cache:${urlObj.pathname}${urlObj.search}:${resolvedLocale}:${identity}`;
-          
-          const cachedData = await globalRedis.get(cacheKey);
-          if (cachedData) {
-            return NextResponse.json(JSON.parse(cachedData), { status: 200 });
-          }
-        }
-
-        const rawParams = context?.params ? await context.params : {};
         const url = new URL(req.url);
-        const rawQuery = Object.fromEntries(url.searchParams.entries());
         
         let rawBody = {};
         const parsedFiles = {};
@@ -216,26 +158,6 @@ export function createBro(globalConfig = {}) {
           }
         }
 
-        let body, params, query;
-        try {
-          if (config.body) body = await config.body.parseAsync(rawBody);
-        } catch (err) {
-          if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid Request Body', details: err.issues }, { status: 400 });
-          throw err;
-        }
-        try {
-          if (config.params) params = await config.params.parseAsync(rawParams);
-        } catch (err) {
-          if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid URL Parameters', details: err.issues }, { status: 400 });
-          throw err;
-        }
-        try {
-          if (config.query) query = await config.query.parseAsync(rawQuery);
-        } catch (err) {
-          if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid Query Parameters', details: err.issues }, { status: 400 });
-          throw err;
-        }
-
         let ctxFile = undefined;
         let ctxFiles = undefined;
         if (totalFiles === 1) {
@@ -246,42 +168,82 @@ export function createBro(globalConfig = {}) {
           ctxFiles = parsedFiles;
         }
 
-        const ctx = {
-          req,
-          env: process.env,
+        const requestData = {
+          method: req.method,
+          originalUrl: url.pathname + url.search,
+          headers: Object.fromEntries(req.headers.entries()),
+          body: rawBody,
+          query: Object.fromEntries(url.searchParams.entries()),
+          params: context?.params ? await context.params : {},
+          files: ctxFiles || ctxFile,
+          ip: req.headers.get('x-forwarded-for') || 'ip',
+          locale: resolvedLocale
+        };
+
+        let redisFallback = globalStore.__broRedis;
+        if (!redisFallback) {
+          redisFallback = {
+            async get(key) {
+               const cached = globalStore.__broMemoryCache.get(key);
+               if (cached && Date.now() < cached.expires) return JSON.stringify(cached.data);
+               return null;
+            },
+            async setEx(key, ex, val) {
+               globalStore.__broMemoryCache.set(key, { data: JSON.parse(val), expires: Date.now() + (ex * 1000) });
+            },
+            async del(key) { globalStore.__broMemoryCache.delete(key); },
+            async incr(key) {
+               const now = Date.now();
+               let record = globalStore.__broMemoryRateLimit.get(key);
+               if (!record || now > record.expires) record = { count: 0, expires: now + 60000 };
+               record.count++;
+               globalStore.__broMemoryRateLimit.set(key, record);
+               return record.count;
+            },
+            async expire(key, ex) {
+               let record = globalStore.__broMemoryRateLimit.get(key);
+               if (record) {
+                 record.expires = Date.now() + (ex * 1000);
+                 globalStore.__broMemoryRateLimit.set(key, record);
+               }
+            }
+          };
+        }
+
+        const ctxExtras = {
+          verifyJwt,
+          generateRateLimitKey,
+          generateCacheKey,
+          generateId: () => crypto.randomUUID(),
+          req, // Native NextRequest
           db: globalDb,
-          redis: globalRedis,
+          redis: redisFallback,
           io: { emit: () => console.warn('[bro.js/next] WebSockets require standard bro.js server.') },
-          body,
-          params,
-          query,
-          file: ctxFile,
-          files: ctxFiles,
-          locale: resolvedLocale,
           t: (key, values) => translate(resolvedLocale, key, values),
-          user,
-          jwt: { 
-             sign: (payload, opts) => signJwt(payload, globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET, Object.assign({ expiresIn: globalConfig?.auth?.expiresIn || '1d' }, opts || {})) 
-          },
+          logger: globalLogger,
+          jwt: { sign: (payload, opts) => signJwt(payload, globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET, Object.assign({ expiresIn: globalConfig?.auth?.expiresIn || '1d' }, opts || {})) },
           error: errorHelper
         };
 
-        const result = await config.handler(ctx);
+        const response = await executeRequest(config, requestData, globalConfig, ctxExtras);
 
-        if (cacheKey && globalRedis) {
-           await globalRedis.set(cacheKey, JSON.stringify(result), { EX: config.cache });
-        }
-
-        return NextResponse.json(result, { status: 200 });
+        return NextResponse.json(response.body, { 
+           status: response.status, 
+           headers: response.headers 
+        });
 
       } catch (error) {
-        if (error.status) {
-           return NextResponse.json({ error: error.message }, { status: error.status });
-        }
         console.error('[bro.js/next] Unhandled Error:', error);
         return NextResponse.json(
-          { error: 'Internal Server Error', message: error.message },
-          { status: 500 }
+          { 
+            type: 'https://brojs.dev/errors/internal_server_error',
+            title: 'Internal Server Error',
+            status: 500,
+            instance: req.url,
+            requestId: req.headers.get('x-request-id') || 'unknown',
+            detail: error.message || 'An unexpected error occurred'
+          },
+          { status: 500, headers: { 'Content-Type': 'application/problem+json' } }
         );
       }
     };

package/src/observability.js

@@ -0,0 +1,81 @@
+import crypto from 'node:crypto';
+
+/**
+ * Pino Logger Adapter for bro.js plugins
+ */
+export function createPinoAdapter(pinoInstance, options = {}) {
+  const redactPaths = options.redact || ['req.headers.authorization', 'req.headers.cookie'];
+  if (!pinoInstance.redact) {
+    pinoInstance.redact = redactPaths;
+  }
+  
+  return {
+    name: 'bro-pino-adapter',
+    order: 5,
+    onContext: (ctx) => {
+      return {
+        log: pinoInstance.child({ reqId: ctx.env?.TRACE_ID || crypto.randomUUID() })
+      };
+    },
+    onRequest: (req, res) => {
+      pinoInstance.info({ req: { method: req.method, url: req.url, headers: req.headers } }, 'Request received');
+    },
+    onError: (err, req, res) => {
+      pinoInstance.error({ err, reqId: req.id || req.headers['x-request-id'] }, 'Request failed');
+    }
+  };
+}
+
+/**
+ * OpenTelemetry Instrumentation Setup Helper
+ */
+export function setupOpenTelemetry(sdkConfig) {
+  return {
+    name: 'bro-otel-instrumentation',
+    order: 1,
+    onInit: async (globalConfig) => {
+      console.log('[bro.js] OpenTelemetry initialized for service:', sdkConfig.serviceName);
+    },
+    onContext: (ctx) => {
+      // W3C Trace Propagation
+      const traceparent = ctx.req?.headers['traceparent'];
+      return {
+        traceId: traceparent ? traceparent.split('-')[1] : crypto.randomUUID()
+      };
+    },
+    onRequest: (req, res) => {
+      // In a real implementation, we would start an OTel span here
+      req.__otelStartTime = Date.now();
+    },
+    onShutdown: () => {
+       console.log('[bro.js] OpenTelemetry shutting down gracefully...');
+    }
+  };
+}
+
+/**
+ * Dashboard Event Bus Plugin
+ */
+export function createDashboardEventBus(busConfig = {}) {
+  const metrics = { requests: 0, errors: 0, latencies: [] };
+  
+  return {
+    name: 'bro-dashboard-bus',
+    order: 90,
+    onRequest: (req, res) => {
+      metrics.requests++;
+      req.__busStartTime = Date.now();
+    },
+    onError: (err) => {
+      metrics.errors++;
+      if (busConfig.io) {
+        busConfig.io.emit('metrics:error', { error: err.message, time: Date.now() });
+      }
+    },
+    onShutdown: () => {
+      if (busConfig.io) {
+        busConfig.io.emit('system:shutdown', { metrics });
+      }
+    }
+  };
+}

package/src/plugins.js

@@ -0,0 +1,135 @@
+/**
+ * Plugin Manager for bro.js
+ * Handles lifecycle hooks, context extension, and typed plugins.
+ */
+export class PluginManager {
+  constructor() {
+    this.plugins = [];
+    this.hooks = {
+      onInit: [],
+      onContext: [],
+      onRequest: [],
+      onError: [],
+      onShutdown: []
+    };
+  }
+
+  /**
+   * Registers a plugin with the framework.
+   * @param {Object} plugin 
+   */
+  register(plugin) {
+    if (!plugin.name) throw new Error('[bro.js] Plugin must have a \'name\'.');
+    if (!plugin.version) throw new Error(`[bro.js] Plugin '${plugin.name}' must specify a 'version' (e.g., '3.0.0').`);
+    
+    // Enforce v3 compatibility
+    if (!plugin.version.startsWith('3.')) {
+      throw new Error(`[bro.js] Plugin '${plugin.name}' (v${plugin.version}) is not compatible with bro.js v3.x.`);
+    }
+
+    const allowedKeys = ['name', 'version', 'order', 'onInit', 'onContext', 'onRequest', 'onError', 'onShutdown'];
+    for (const key of Object.keys(plugin)) {
+      if (!allowedKeys.includes(key)) {
+        throw new Error(`[bro.js] Plugin '${plugin.name}' uses undocumented escape hatch / unknown property: '${key}'.`);
+      }
+    }
+
+    this.plugins.push(plugin);
+    // Sort plugins if they provide an order, default to 50
+    this.plugins.sort((a, b) => (a.order ?? 50) - (b.order ?? 50));
+    this._rebuildHooks();
+  }
+
+  _rebuildHooks() {
+    for (const key of Object.keys(this.hooks)) {
+      this.hooks[key] = [];
+    }
+    for (const plugin of this.plugins) {
+      if (plugin.onInit) this.hooks.onInit.push(plugin.onInit);
+      if (plugin.onContext) this.hooks.onContext.push(plugin.onContext);
+      if (plugin.onRequest) this.hooks.onRequest.push(plugin.onRequest);
+      if (plugin.onError) this.hooks.onError.push(plugin.onError);
+      if (plugin.onShutdown) this.hooks.onShutdown.push(plugin.onShutdown);
+    }
+  }
+
+  async runOnInit(globalConfig, app) {
+    for (const hook of this.hooks.onInit) {
+      await hook(globalConfig, app);
+    }
+  }
+
+  async runOnContext(ctx) {
+    for (const hook of this.hooks.onContext) {
+      const ext = await hook(ctx);
+      if (ext && typeof ext === 'object') {
+        Object.assign(ctx, ext);
+      }
+    }
+  }
+
+  async runOnShutdown() {
+    for (const hook of this.hooks.onShutdown) {
+      await hook();
+    }
+  }
+
+  getRequestMiddleware() {
+    return async (req, res, next) => {
+      try {
+        for (const hook of this.hooks.onRequest) {
+           await hook(req, res);
+        }
+        next();
+      } catch (err) {
+        next(err);
+      }
+    };
+  }
+
+  getErrorMiddleware() {
+    return async (err, req, res, next) => {
+      for (const hook of this.hooks.onError) {
+        try {
+          await hook(err, req, res);
+        } catch (e) {
+          console.error('[bro.js] Error in Plugin onError hook:', e);
+        }
+      }
+      next(err);
+    };
+  }
+}
+
+/**
+ * Baseline Observability Plugin
+ * Adds performance measuring and correlation ids.
+ */
+export const ObservabilityPlugin = {
+  name: 'bro-observability',
+  version: '3.0.0',
+  order: 10, // Runs early
+  onRequest: (req, res) => {
+    req.startTime = performance.now();
+  },
+  onContext: (ctx) => {
+    return {
+       traceId: ctx.env?.TRACE_ID || crypto.randomUUID()
+    };
+  }
+};
+
+/**
+ * Baseline Security Plugin
+ * Applies strict security headers beyond the default helmet configuration.
+ */
+export const SecurityPlugin = {
+  name: 'bro-security',
+  version: '3.0.0',
+  order: 20,
+  onRequest: (req, res) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('X-XSS-Protection', '1; mode=block');
+  }
+};

package/src/policy-auth.js

@@ -0,0 +1,88 @@
+import crypto from 'node:crypto';
+
+export class OidcProvider {
+  constructor(issuerUrl, clientId) {
+    this.issuerUrl = issuerUrl;
+    this.clientId = clientId;
+    this.jwksUrl = `${issuerUrl}/.well-known/jwks.json`;
+    this.keys = null;
+    this.lastFetch = 0;
+  }
+  
+  async _fetchKeys() {
+    if (this.keys && (Date.now() - this.lastFetch < 3600000)) return this.keys; // 1 hour cache
+    const response = await fetch(this.jwksUrl);
+    if (!response.ok) throw new Error('Failed to fetch JWKS');
+    const data = await response.json();
+    this.keys = data.keys;
+    this.lastFetch = Date.now();
+    return this.keys;
+  }
+  
+  async verifyIdToken(token) {
+    let jose;
+    try { jose = await import('jose'); } catch { throw new Error('Install jose package to use OIDC Provider'); }
+    const JWKS = jose.createRemoteJWKSet(new URL(this.jwksUrl));
+    try {
+      const { payload } = await jose.jwtVerify(token, JWKS, {
+        issuer: this.issuerUrl,
+        audience: this.clientId
+      });
+      return { valid: true, payload };
+    } catch (e) {
+      return { valid: false, error: e.message };
+    }
+  }
+}
+
+export class PolicyEvaluator {
+  constructor() {
+    this.policies = new Map();
+  }
+
+  definePolicy(action, evaluatorFn) {
+    this.policies.set(action, evaluatorFn);
+  }
+
+  async authorize(user, action, resourceContext = {}) {
+    const evaluator = this.policies.get(action);
+    if (!evaluator) return false;
+    return await evaluator(user, resourceContext);
+  }
+}
+
+export class ApiKeyManager {
+  constructor(dbAdapter) {
+    this.db = dbAdapter;
+  }
+
+  hashKey(key) {
+    return crypto.createHash('sha256').update(key).digest('hex');
+  }
+
+  generateKey(prefix = 'bro') {
+    const random = crypto.randomBytes(32).toString('hex');
+    const key = `${prefix}_${random}`;
+    const hash = this.hashKey(key);
+    return { key, hash };
+  }
+
+  async verifyKey(key) {
+    if (!this.db) throw new Error('ApiKeyManager requires a database adapter');
+    const hash = this.hashKey(key);
+    // Stub implementation for verify. DB adapter needs a specific findKey method.
+    return { valid: true, id: hash };
+  }
+}
+
+export const tenantContextPlugin = {
+  name: 'bro-tenant-context',
+  order: 10,
+  onContext: async (ctx) => {
+    const tenantId = ctx.req?.headers['x-tenant-id'];
+    if (tenantId) {
+       return { tenant: { id: tenantId } };
+    }
+    return {};
+  }
+};

package/src/router.js

@@ -82,7 +82,7 @@ export function parseRouteFile(filePath, routesDir) {
  * @param {Object} [openApiSpec] - Optional OpenAPI Spec object to build.
  * @returns {Promise<Array>} Array of loaded route objects.
  */
-export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
+export async function loadRoutes(app, routesDir, createHandler, openApiSpec, routeRegistry) {
   const files = scanDir(routesDir);
   const loadedRoutes = [];
   const routeModules = [];