millas 0.2.12-beta-1 → 0.2.13

package/src/http/middleware/RateLimiter.js

@@ -0,0 +1,314 @@
+'use strict';
+
+/**
+ * RateLimiter
+ *
+ * Per-IP and per-user rate limiting with an in-memory store by default
+ * and a pluggable store interface for Redis in production.
+ *
+ * ── Quick usage ───────────────────────────────────────────────────────────────
+ *
+ *   const { RateLimiter } = require('millas/src/http/middleware/RateLimiter');
+ *
+ *   // Global: 100 requests per 15 minutes per IP (applied in SecurityBootstrap)
+ *   app.use(RateLimiter.perIp({ max: 100, windowMs: 15 * 60 * 1000 }).middleware());
+ *
+ *   // Route-level: 5 login attempts per 10 minutes per IP
+ *   Route.post('/login', [
+ *     RateLimiter.perIp({ max: 5, windowMs: 10 * 60 * 1000, message: 'Too many login attempts' }).middleware(),
+ *   ], loginHandler);
+ *
+ *   // Authenticated routes: per-user limiting
+ *   Route.post('/ai/chat', [
+ *     RateLimiter.perUser({ max: 20, windowMs: 60 * 1000 }).middleware(),
+ *   ], chatHandler);
+ *
+ *   // Combined: per-IP first, then per-user
+ *   Route.post('/api/messages', [
+ *     RateLimiter.perIp({ max: 60, windowMs: 60 * 1000 }).middleware(),
+ *     RateLimiter.perUser({ max: 30, windowMs: 60 * 1000 }).middleware(),
+ *   ], handler);
+ *
+ * ── Redis store (production) ──────────────────────────────────────────────────
+ *
+ *   const { RedisRateLimitStore } = require('millas/src/http/middleware/RateLimiter');
+ *   const redis = require('ioredis');
+ *
+ *   const store = new RedisRateLimitStore(new redis(process.env.REDIS_URL));
+ *
+ *   RateLimiter.perIp({ max: 100, windowMs: 60000, store }).middleware();
+ *
+ * ── Configuration (config/security.js) ───────────────────────────────────────
+ *
+ *   rateLimit: {
+ *     global: {
+ *       enabled:  true,
+ *       max:      100,
+ *       windowMs: 15 * 60 * 1000,   // 15 minutes
+ *     },
+ *   }
+ *
+ * ── Response headers ──────────────────────────────────────────────────────────
+ *
+ *   Every rate-limited response includes:
+ *     X-RateLimit-Limit:     100        — max requests in window
+ *     X-RateLimit-Remaining: 42         — requests left in current window
+ *     X-RateLimit-Reset:     1711234567 — UNIX timestamp when window resets
+ *
+ *   On 429:
+ *     Retry-After: 300                  — seconds until the window resets
+ */
+
+// ── In-memory store ────────────────────────────────────────────────────────────
+
+/**
+ * MemoryRateLimitStore
+ *
+ * Simple in-memory store using a Map.
+ * Fine for single-process deployments and development.
+ * For multi-process or multi-server deployments, use RedisRateLimitStore.
+ *
+ * Entries expire automatically — a cleanup sweep runs every 5 minutes
+ * to prevent unbounded memory growth.
+ */
+class MemoryRateLimitStore {
+  constructor() {
+    this._store   = new Map();
+    this._cleanup = setInterval(() => this._sweep(), 5 * 60 * 1000);
+    // Don't hold the process open just for cleanup
+    if (this._cleanup.unref) this._cleanup.unref();
+  }
+
+  /**
+   * Increment hit count for a key within a window.
+   *
+   * @param {string} key
+   * @param {number} windowMs
+   * @returns {{ count: number, resetAt: number }}
+   */
+  async increment(key, windowMs) {
+    const now     = Date.now();
+    const entry   = this._store.get(key);
+    const resetAt = entry && entry.resetAt > now ? entry.resetAt : now + windowMs;
+    const count   = entry && entry.resetAt > now ? entry.count + 1 : 1;
+
+    this._store.set(key, { count, resetAt });
+    return { count, resetAt };
+  }
+
+  /**
+   * Reset the counter for a key (e.g. after successful login).
+   *
+   * @param {string} key
+   */
+  async reset(key) {
+    this._store.delete(key);
+  }
+
+  /**
+   * Stop the background cleanup interval.
+   * Call this in tests or on graceful shutdown to allow the process to exit.
+   */
+  destroy() {
+    clearInterval(this._cleanup);
+  }
+
+  /** Remove expired entries */
+  _sweep() {
+    const now = Date.now();
+    for (const [key, entry] of this._store) {
+      if (entry.resetAt <= now) this._store.delete(key);
+    }
+  }
+}
+
+// ── Redis store ────────────────────────────────────────────────────────────────
+
+/**
+ * RedisRateLimitStore
+ *
+ * Production store backed by Redis. Requires an ioredis (or node-redis) client.
+ * Uses atomic INCR + PEXPIRE so it works correctly across multiple processes.
+ *
+ * @example
+ *   const redis = new Redis(process.env.REDIS_URL);
+ *   const store = new RedisRateLimitStore(redis);
+ *   RateLimiter.perIp({ max: 100, windowMs: 60000, store });
+ */
+class RedisRateLimitStore {
+  /**
+   * @param {object} redisClient  — ioredis or node-redis client instance
+   * @param {string} [prefix]     — key prefix (default: 'rl:')
+   */
+  constructor(redisClient, prefix = 'rl:') {
+    this._redis  = redisClient;
+    this._prefix = prefix;
+  }
+
+  async increment(key, windowMs) {
+    const redisKey = `${this._prefix}${key}`;
+
+    // Atomic pipeline: INCR then set expiry only on first hit
+    const [[, count], [, ttlMs]] = await this._redis
+      .pipeline()
+      .incr(redisKey)
+      .pttl(redisKey)
+      .exec();
+
+    // If this is the first hit (or key had no TTL), set the window expiry
+    if (count === 1 || ttlMs < 0) {
+      await this._redis.pexpire(redisKey, windowMs);
+    }
+
+    const resetAt = Date.now() + (ttlMs > 0 ? ttlMs : windowMs);
+    return { count, resetAt };
+  }
+
+  async reset(key) {
+    await this._redis.del(`${this._prefix}${key}`);
+  }
+}
+
+// ── RateLimiter class ──────────────────────────────────────────────────────────
+
+const DEFAULT_OPTIONS = {
+  max:        100,
+  windowMs:   15 * 60 * 1000,   // 15 minutes
+  message:    'Too many requests, please try again later.',
+  statusCode: 429,
+  keyBy:      'ip',              // 'ip' | 'user' | function(req) => string
+  store:      null,              // defaults to MemoryRateLimitStore
+  skip:       null,              // optional function(req) => bool — return true to skip
+  onLimitReached: null,          // optional function(req, res, options) — called on 429
+};
+
+class RateLimiter {
+  /**
+   * @param {object} options
+   */
+  constructor(options = {}) {
+    this._opts  = { ...DEFAULT_OPTIONS, ...options };
+    this._store = options.store || new MemoryRateLimitStore();
+  }
+
+  // ── Express middleware ────────────────────────────────────────────────────
+
+  middleware() {
+    const opts  = this._opts;
+    const store = this._store;
+
+    return async (req, res, next) => {
+      try {
+        // ── Skip check ─────────────────────────────────────────────────────
+        if (opts.skip && opts.skip(req)) return next();
+
+        // ── Resolve key ────────────────────────────────────────────────────
+        const key = this._resolveKey(req, opts.keyBy);
+        if (!key) return next(); // can't rate-limit without a key (e.g. no user yet)
+
+        // ── Increment counter ──────────────────────────────────────────────
+        const { count, resetAt } = await store.increment(key, opts.windowMs);
+        const remaining           = Math.max(0, opts.max - count);
+        const resetSec            = Math.ceil(resetAt / 1000);
+
+        // ── Set rate-limit headers (always, even on 429) ───────────────────
+        res.setHeader('X-RateLimit-Limit',     opts.max);
+        res.setHeader('X-RateLimit-Remaining', remaining);
+        res.setHeader('X-RateLimit-Reset',     resetSec);
+
+        // ── Attach store reset helper to req for auth flows ────────────────
+        // e.g. after successful login: await req.resetRateLimit()
+        req.resetRateLimit = () => store.reset(key);
+
+        // ── Enforce limit ──────────────────────────────────────────────────
+        if (count > opts.max) {
+          const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+          res.setHeader('Retry-After', retryAfter);
+
+          if (opts.onLimitReached) {
+            opts.onLimitReached(req, res, opts);
+          }
+
+          // Return JSON for API requests, plain text for others
+          const isApi = (req.headers?.accept || '').includes('application/json') ||
+                        (req.headers?.['content-type'] || '').includes('application/json');
+
+          res.status(opts.statusCode);
+          if (isApi) {
+            res.setHeader('Content-Type', 'application/json');
+            return res.end(JSON.stringify({ error: opts.message, retryAfter }));
+          }
+          return res.end(opts.message);
+        }
+
+        next();
+      } catch (err) {
+        // Store errors must never block requests — fail open
+        console.error('[Millas RateLimit] Store error:', err.message);
+        next();
+      }
+    };
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────────────
+
+  _resolveKey(req, keyBy) {
+    if (typeof keyBy === 'function') return keyBy(req);
+
+    if (keyBy === 'user') {
+      // req.user is set by AuthMiddleware — if not authenticated, fall back to IP
+      const userId = req.user?.id || req.user?._id;
+      return userId ? `user:${userId}` : this._resolveKey(req, 'ip');
+    }
+
+    if (keyBy === 'ip') {
+      const ip = req.ip ||
+                 req.headers?.['x-forwarded-for']?.split(',')[0]?.trim() ||
+                 req.connection?.remoteAddress;
+      return ip ? `ip:${ip}` : null;
+    }
+
+    return null;
+  }
+
+  // ── Static factories (fluent API) ─────────────────────────────────────────
+
+  /**
+   * Limit by IP address.
+   *
+   *   RateLimiter.perIp({ max: 5, windowMs: 10 * 60 * 1000 }).middleware()
+   */
+  static perIp(options = {}) {
+    return new RateLimiter({ ...options, keyBy: 'ip' });
+  }
+
+  /**
+   * Limit by authenticated user (falls back to IP if not authenticated).
+   *
+   *   RateLimiter.perUser({ max: 20, windowMs: 60 * 1000 }).middleware()
+   */
+  static perUser(options = {}) {
+    return new RateLimiter({ ...options, keyBy: 'user' });
+  }
+
+  /**
+   * Limit by a custom key resolver.
+   *
+   *   RateLimiter.by(req => req.headers['x-api-key'], { max: 1000 }).middleware()
+   */
+  static by(keyFn, options = {}) {
+    return new RateLimiter({ ...options, keyBy: keyFn });
+  }
+
+  /**
+   * Create from config section.
+   *
+   *   RateLimiter.from(config.security?.rateLimit?.global)
+   */
+  static from(options) {
+    if (options === false || options?.enabled === false) return null;
+    return RateLimiter.perIp(options || {});
+  }
+}
+
+module.exports = { RateLimiter, MemoryRateLimitStore, RedisRateLimitStore };

package/src/http/middleware/SecurityHeaders.js

@@ -0,0 +1,281 @@
+'use strict';
+
+/**
+ * SecurityHeaders middleware
+ *
+ * Sets secure HTTP response headers on every outgoing response.
+ * Enabled by default in the Millas HTTP kernel — opt-out, not opt-in.
+ *
+ * Covers:
+ *   • Content-Security-Policy     — XSS mitigation
+ *   • Strict-Transport-Security   — HTTPS enforcement
+ *   • X-Frame-Options             — clickjacking prevention
+ *   • X-Content-Type-Options      — MIME sniffing prevention
+ *   • Referrer-Policy             — referrer leakage prevention
+ *   • Permissions-Policy          — browser feature scoping
+ *   • X-Powered-By removal        — fingerprinting reduction
+ *
+ * ── Usage (automatic — loaded by HttpKernel) ────────────────────────────────
+ *
+ *   // Loaded automatically. No developer action required.
+ *
+ * ── Customising CSP (config/security.js) ────────────────────────────────────
+ *
+ *   module.exports = {
+ *     headers: {
+ *       contentSecurityPolicy: {
+ *         directives: {
+ *           defaultSrc: ["'self'"],
+ *           scriptSrc:  ["'self'", 'cdn.example.com'],
+ *           imgSrc:     ["'self'", 'data:', 'https:'],
+ *         },
+ *       },
+ *       // Disable a specific header:
+ *       xFrameOptions: false,
+ *     },
+ *   };
+ *
+ * ── Disabling entirely (not recommended) ───────────────────────────────────
+ *
+ *   // config/security.js
+ *   module.exports = { headers: false };
+ *
+ * ── Nonces (for inline scripts) ────────────────────────────────────────────
+ *
+ *   // The middleware attaches a per-request nonce to req.cspNonce
+ *   // Use it in templates: <script nonce="<%= req.cspNonce %>">
+ *   //
+ *   // Enable via config:
+ *   contentSecurityPolicy: {
+ *     useNonce: true,
+ *     directives: {
+ *       scriptSrc: ["'self'"],  // nonce is appended automatically
+ *     },
+ *   },
+ */
+
+const crypto = require('crypto');
+
+// ── Defaults ──────────────────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  contentSecurityPolicy: {
+    useNonce: false,
+    directives: {
+      defaultSrc:    ["'self'"],
+      scriptSrc:     ["'self'"],
+      styleSrc:      ["'self'", "'unsafe-inline'"],
+      imgSrc:        ["'self'", 'data:'],
+      fontSrc:       ["'self'"],
+      connectSrc:    ["'self'"],
+      objectSrc:     ["'none'"],
+      frameSrc:      ["'none'"],
+      baseUri:       ["'self'"],
+      formAction:    ["'self'"],
+      frameAncestors:["'none'"],
+      upgradeInsecureRequests: [],
+    },
+  },
+
+  // HSTS: 1 year, include subdomains, allow preload
+  // Only sent over HTTPS — the middleware checks req.secure
+  strictTransportSecurity: {
+    maxAge:            31536000,
+    includeSubDomains: true,
+    preload:           true,
+  },
+
+  // Deny framing entirely — use 'SAMEORIGIN' if you need iframes on your own domain
+  xFrameOptions: 'DENY',
+
+  // Prevent MIME-type sniffing
+  xContentTypeOptions: true,
+
+  // Only send the origin (no path) as referrer; never send cross-origin referrer
+  referrerPolicy: 'strict-origin-when-cross-origin',
+
+  // Disable access to sensitive browser features by default
+  permissionsPolicy: {
+    camera:         '()',
+    microphone:     '()',
+    geolocation:    '()',
+    payment:        '()',
+    usb:            '()',
+    magnetometer:   '()',
+    gyroscope:      '()',
+    accelerometer:  '()',
+  },
+
+  // Remove X-Powered-By: Express
+  removePoweredBy: true,
+};
+
+// ── CSP builder ───────────────────────────────────────────────────────────────
+
+/**
+ * Build a Content-Security-Policy header value from a directives object.
+ *
+ * @param {object} directives
+ * @param {string|null} nonce
+ * @returns {string}
+ */
+function buildCsp(directives, nonce = null) {
+  return Object.entries(directives)
+    .map(([key, value]) => {
+      // camelCase → kebab-case
+      const directive = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+
+      if (!Array.isArray(value) || value.length === 0) {
+        // Bare directives (e.g. upgrade-insecure-requests)
+        if (Array.isArray(value) && value.length === 0) return directive;
+        return null;
+      }
+
+      let sources = [...value];
+
+      // Inject nonce into scriptSrc and styleSrc if enabled
+      if (nonce && (key === 'scriptSrc' || key === 'styleSrc')) {
+        sources = sources.filter(s => !s.startsWith("'nonce-"));
+        sources.push(`'nonce-${nonce}'`);
+      }
+
+      return `${directive} ${sources.join(' ')}`;
+    })
+    .filter(Boolean)
+    .join('; ');
+}
+
+// ── Permissions-Policy builder ────────────────────────────────────────────────
+
+function buildPermissionsPolicy(features) {
+  return Object.entries(features)
+    .map(([feature, allowlist]) => `${feature}=${allowlist}`)
+    .join(', ');
+}
+
+// ── Merge helpers ─────────────────────────────────────────────────────────────
+
+function mergeDeep(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] !== null &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = mergeDeep(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+// ── SecurityHeaders class ─────────────────────────────────────────────────────
+
+class SecurityHeaders {
+  /**
+   * @param {object|false} config  — merged with DEFAULTS; pass false to disable
+   */
+  constructor(config = {}) {
+    if (config === false) {
+      this._disabled = true;
+      return;
+    }
+
+    this._disabled = false;
+    this._config   = mergeDeep(DEFAULTS, config);
+  }
+
+  // ── Express middleware ────────────────────────────────────────────────────
+
+  /**
+   * Returns an Express-compatible middleware function.
+   *
+   *   app.use(new SecurityHeaders(config).middleware());
+   *
+   * The Millas HttpKernel calls this automatically — developers
+   * do not need to call it directly unless customising bootstrap.
+   */
+  middleware() {
+    if (this._disabled) {
+      return (_req, _res, next) => next();
+    }
+
+    const cfg = this._config;
+
+    return (req, res, next) => {
+      // ── Remove X-Powered-By ──────────────────────────────────────────────
+      if (cfg.removePoweredBy) {
+        res.removeHeader('X-Powered-By');
+      }
+
+      // ── Content-Security-Policy ──────────────────────────────────────────
+      if (cfg.contentSecurityPolicy !== false) {
+        const cspCfg = cfg.contentSecurityPolicy;
+        let nonce = null;
+
+        if (cspCfg.useNonce) {
+          nonce = crypto.randomBytes(16).toString('base64');
+          // Attach to req so templates can use it: req.cspNonce
+          req.cspNonce = nonce;
+        }
+
+        const cspValue = buildCsp(cspCfg.directives, nonce);
+        res.setHeader('Content-Security-Policy', cspValue);
+      }
+
+      // ── Strict-Transport-Security ────────────────────────────────────────
+      // Only set over HTTPS. Express sets req.secure based on protocol.
+      if (cfg.strictTransportSecurity !== false) {
+        const hsts = cfg.strictTransportSecurity;
+        let value  = `max-age=${hsts.maxAge}`;
+        if (hsts.includeSubDomains) value += '; includeSubDomains';
+        if (hsts.preload)           value += '; preload';
+        // Always set it — if behind a proxy, trust the X-Forwarded-Proto header
+        res.setHeader('Strict-Transport-Security', value);
+      }
+
+      // ── X-Frame-Options ──────────────────────────────────────────────────
+      if (cfg.xFrameOptions !== false) {
+        res.setHeader('X-Frame-Options', cfg.xFrameOptions);
+      }
+
+      // ── X-Content-Type-Options ───────────────────────────────────────────
+      if (cfg.xContentTypeOptions !== false) {
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+      }
+
+      // ── Referrer-Policy ──────────────────────────────────────────────────
+      if (cfg.referrerPolicy !== false) {
+        res.setHeader('Referrer-Policy', cfg.referrerPolicy);
+      }
+
+      // ── Permissions-Policy ───────────────────────────────────────────────
+      if (cfg.permissionsPolicy !== false) {
+        res.setHeader('Permissions-Policy', buildPermissionsPolicy(cfg.permissionsPolicy));
+      }
+
+      next();
+    };
+  }
+
+  // ── Static factory (convenience) ─────────────────────────────────────────
+
+  /**
+   * Create a SecurityHeaders instance from a config section.
+   *
+   *   SecurityHeaders.from(config.security?.headers)
+   *
+   * @param {object|false|undefined} config
+   * @returns {SecurityHeaders}
+   */
+  static from(config) {
+    if (config === false) return new SecurityHeaders(false);
+    return new SecurityHeaders(config || {});
+  }
+}
+
+module.exports = SecurityHeaders;

package/src/i18n/I18nServiceProvider.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const path        = require('path');
+const fs          = require('fs');
+const ServiceProvider = require('../providers/ServiceProvider');
+const Translator  = require('./Translator');
+
+/**
+ * I18nServiceProvider
+ *
+ * Boots the translation system and registers the Trans singleton
+ * into the DI container.
+ *
+ * ── Setup in bootstrap/app.js ─────────────────────────────────────────────
+ *
+ *   const { Millas } = require('millas');
+ *   const I18nServiceProvider = require('millas/src/i18n/I18nServiceProvider');
+ *
+ *   module.exports = Millas.config()
+ *     .providers([I18nServiceProvider, AppServiceProvider])
+ *     .create();
+ *
+ * ── config/app.js ─────────────────────────────────────────────────────────
+ *
+ *   module.exports = {
+ *     locale:   'en',       // default locale
+ *     fallback: 'en',       // fallback when translation missing
+ *   };
+ *
+ * ── lang/ directory ───────────────────────────────────────────────────────
+ *
+ *   Place translation files at <basePath>/lang/:
+ *
+ *   lang/
+ *     en.js     ← source language
+ *     sw.js     ← Swahili
+ *     fr.js     ← French
+ *
+ * ── Route-level locale switching ──────────────────────────────────────────
+ *
+ *   Use the built-in middleware to auto-detect locale from requests:
+ *
+ *   const { Trans } = require('millas/src/i18n');
+ *   app.use(Trans.middleware());
+ *
+ *   Or manually in a route:
+ *   Trans.setLocale('sw');
+ */
+class I18nServiceProvider extends ServiceProvider {
+
+  register(container) {
+    // Register the Trans singleton into the DI container
+    const trans = require('./index').Trans;
+    container.instance('trans', trans);
+    container.instance('Trans', trans);
+    container.alias('i18n', 'trans');
+  }
+
+  async boot(container, app) {
+    const basePath = container.make('basePath') || process.cwd();
+    const trans    = container.make('trans');
+
+    // Load config/app.js for locale settings
+    let locale   = 'en';
+    let fallback = 'en';
+    let warnMissing = process.env.NODE_ENV !== 'production';
+
+    try {
+      const appConfig = require(path.join(basePath, 'config/app'));
+      if (appConfig.locale)   locale   = appConfig.locale;
+      if (appConfig.fallback) fallback = appConfig.fallback;
+    } catch { /* config/app.js not found or no locale keys */ }
+
+    // Lang path: <basePath>/lang/
+    const langPath = path.join(basePath, 'lang');
+
+    trans.configure({ locale, fallback, langPath, warnMissing });
+
+    // Log available locales on startup in debug mode
+    if (process.env.DEBUG || process.env.NODE_ENV === 'development') {
+      const available = trans.availableLocales();
+      if (available.length > 0 && !(available.length === 1 && available[0] === 'en')) {
+        process.stdout.write(
+          `[i18n] Locale: ${locale} | Fallback: ${fallback} | Available: ${available.join(', ')}\n`
+        );
+      }
+    }
+  }
+}
+
+module.exports = I18nServiceProvider;