millas 0.2.12-beta-2 → 0.2.13-beta

package/src/logger/LogRedactor.js

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * LogRedactor
+ *
+ * Scrubs sensitive field values from log context objects before they
+ * are serialised and written to any log channel.
+ *
+ * ── Why this matters ─────────────────────────────────────────────────────────
+ *
+ *   Log.d('Auth', 'Login', { email, password });       // password logged ✗
+ *   Log.d('AI',   'Config', this._config);             // API keys logged ✗
+ *   Log.d('HTTP', 'Request', req.body);                // form fields logged ✗
+ *
+ *   With redaction enabled (default):
+ *   Log.d('Auth', 'Login', { email, password });
+ *   → { email: 'alice@example.com', password: '[REDACTED]' }
+ *
+ * ── Default sensitive field names ────────────────────────────────────────────
+ *
+ *   password, passwd, secret, token, apikey, api_key, authorization,
+ *   cookie, access_token, refresh_token, private_key, private, credential,
+ *   ssn, credit_card, card_number, cvv, pin
+ *
+ *   Matching is case-insensitive and substring-based:
+ *     'userPassword' matches 'password'
+ *     'X-API-Key'    matches 'apikey'
+ *     'AUTHORIZATION' matches 'authorization'
+ *
+ * ── Configuration ─────────────────────────────────────────────────────────────
+ *
+ *   // Add custom sensitive field names (globally):
+ *   LogRedactor.addSensitiveKeys(['mpesa_pin', 'stk_passkey', 'webhook_secret']);
+ *
+ *   // Replace the entire list:
+ *   LogRedactor.setSensitiveKeys([...LogRedactor.DEFAULT_KEYS, 'my_secret']);
+ *
+ *   // Change the redaction placeholder:
+ *   LogRedactor.setPlaceholder('***');
+ *
+ *   // Disable redaction entirely (not recommended for production):
+ *   LogRedactor.disable();
+ *
+ * ── Integration ───────────────────────────────────────────────────────────────
+ *
+ *   Redaction is applied automatically inside every formatter's format() call.
+ *   No action needed — it is on by default.
+ */
+
+// ── Default sensitive key fragments ───────────────────────────────────────────
+
+const DEFAULT_KEYS = [
+  'password', 'passwd', 'pass',
+  'secret',
+  'token',
+  'apikey', 'api_key',
+  'authorization', 'auth',
+  'cookie',
+  'access_token', 'accesstoken',
+  'refresh_token', 'refreshtoken',
+  'private_key', 'privatekey', 'private',
+  'credential', 'credentials',
+  'ssn',
+  'credit_card', 'creditcard', 'card_number', 'cardnumber',
+  'cvv', 'cvc',
+  'pin',
+  'passphrase',
+  'webhook_secret', 'signing_secret',
+];
+
+// ── Module-level state ────────────────────────────────────────────────────────
+
+let _sensitiveKeys  = [...DEFAULT_KEYS];
+let _placeholder    = '[REDACTED]';
+let _enabled        = true;
+let _cachedLower    = null;  // lazily built lowercased copy
+
+function _getLower() {
+  if (!_cachedLower) _cachedLower = _sensitiveKeys.map(k => k.toLowerCase());
+  return _cachedLower;
+}
+
+function _invalidateCache() {
+  _cachedLower = null;
+}
+
+// ── Core redaction ────────────────────────────────────────────────────────────
+
+/**
+ * Check if a key name contains any sensitive fragment.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isSensitiveKey(key) {
+  const lower  = String(key).toLowerCase().replace(/[-_\s]/g, '');
+  const frags  = _getLower().map(k => k.replace(/[-_\s]/g, ''));
+  return frags.some(frag => lower.includes(frag));
+}
+
+/**
+ * Redact sensitive values from an object (shallow or deep).
+ * Returns a new object — never mutates the original.
+ *
+ * Handles:
+ *   - Plain objects (nested recursively up to depth 10)
+ *   - Arrays (each element redacted)
+ *   - Primitives (returned as-is unless the key is sensitive)
+ *   - Circular references (detected and replaced with '[Circular]')
+ *
+ * @param {*}      value    — the context value to redact
+ * @param {number} [depth]  — internal recursion counter
+ * @param {Set}    [seen]   — internal circular reference tracker
+ * @returns {*}
+ */
+function redact(value, depth = 0, seen = new Set()) {
+  if (!_enabled) return value;
+
+  // Depth guard — don't recurse into deeply nested structures
+  if (depth > 10) return value;
+
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+
+  // Circular reference guard
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    const result = value.map(item => redact(item, depth + 1, seen));
+    seen.delete(value);
+    return result;
+  }
+
+  const result = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (isSensitiveKey(k)) {
+      result[k] = _placeholder;
+    } else if (v !== null && typeof v === 'object') {
+      result[k] = redact(v, depth + 1, seen);
+    } else {
+      result[k] = v;
+    }
+  }
+  seen.delete(value);
+  return result;
+}
+
+// ── LogRedactor class ─────────────────────────────────────────────────────────
+
+class LogRedactor {
+  /**
+   * The default list of sensitive key fragments.
+   * Useful when callers want to extend it:
+   *   LogRedactor.setSensitiveKeys([...LogRedactor.DEFAULT_KEYS, 'my_key']);
+   */
+  static get DEFAULT_KEYS() { return [...DEFAULT_KEYS]; }
+
+  /**
+   * Redact sensitive fields from a log context value.
+   * Non-objects are returned unchanged.
+   *
+   * @param {*} context
+   * @returns {*}
+   */
+  static redact(context) {
+    if (!_enabled) return context;
+    if (context === null || context === undefined) return context;
+    if (typeof context !== 'object') return context;
+    return redact(context);
+  }
+
+  /**
+   * Add extra sensitive key fragments to the global list.
+   *
+   *   LogRedactor.addSensitiveKeys(['mpesa_pin', 'stk_passkey']);
+   *
+   * @param {string[]} keys
+   */
+  static addSensitiveKeys(keys) {
+    _sensitiveKeys = [...new Set([..._sensitiveKeys, ...keys.map(k => k.toLowerCase())])];
+    _invalidateCache();
+  }
+
+  /**
+   * Replace the entire sensitive key list.
+   *
+   *   LogRedactor.setSensitiveKeys([...LogRedactor.DEFAULT_KEYS, 'my_secret']);
+   *
+   * @param {string[]} keys
+   */
+  static setSensitiveKeys(keys) {
+    _sensitiveKeys = keys.map(k => k.toLowerCase());
+    _invalidateCache();
+  }
+
+  /**
+   * Get a copy of the current sensitive key list.
+   *
+   * @returns {string[]}
+   */
+  static getSensitiveKeys() {
+    return [..._sensitiveKeys];
+  }
+
+  /**
+   * Change the redaction placeholder string.
+   *   LogRedactor.setPlaceholder('***');
+   *
+   * @param {string} placeholder
+   */
+  static setPlaceholder(placeholder) {
+    _placeholder = String(placeholder);
+  }
+
+  /**
+   * Enable redaction (default).
+   */
+  static enable() {
+    _enabled = true;
+  }
+
+  /**
+   * Disable redaction. Use only in test environments where you need
+   * to inspect exact log context values.
+   */
+  static disable() {
+    _enabled = false;
+  }
+
+  /**
+   * Whether redaction is currently enabled.
+   */
+  static get enabled() { return _enabled; }
+
+  /**
+   * Check if a specific key would be redacted.
+   *
+   *   LogRedactor.isSensitive('userPassword')  // true
+   *   LogRedactor.isSensitive('userId')        // false
+   */
+  static isSensitive(key) {
+    return isSensitiveKey(key);
+  }
+}
+
+module.exports = { LogRedactor, redact, isSensitiveKey };

package/src/logger/Logger.js

@@ -181,7 +181,7 @@ class Logger {
           ctx.slow = true;
         }
 
-        self._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
+        self._log(level, `HTTP [${method}]`, `${url} ${status} ${ms}ms`);
       });
 
       next();

package/src/logger/formatters/JsonFormatter.js

@@ -1,12 +1,14 @@
 'use strict';
 
-const { LEVEL_NAMES } = require('../levels');
+const { LEVEL_NAMES }     = require('../levels');
+const { LogRedactor }     = require('../LogRedactor');
 
 /**
  * JsonFormatter
  *
  * Emits one JSON object per log entry — ideal for production environments
  * where logs are shipped to Datadog, Elasticsearch, CloudWatch, etc.
+ * Sensitive context fields are automatically redacted before serialisation.
  *
  * Output (one line per entry):
  *   {"ts":"2026-03-15T12:00:00.000Z","level":"INFO","tag":"Auth","msg":"Login","ctx":{...}}
@@ -15,11 +17,13 @@ class JsonFormatter {
   /**
    * @param {object} options
    * @param {boolean} [options.pretty=false]   — pretty-print JSON (for debugging)
-   * @param {object}  [options.extra]          — static fields merged into every entry (e.g. service name)
+   * @param {object}  [options.extra]          — static fields merged into every entry
+   * @param {boolean} [options.redact=true]    — redact sensitive context fields
    */
   constructor(options = {}) {
     this.pretty = options.pretty || false;
     this.extra  = options.extra  || {};
+    this.redact = options.redact !== false;   // default: true
   }
 
   format(entry) {
@@ -33,7 +37,10 @@ class JsonFormatter {
 
     if (tag)     record.tag = tag;
     record.msg = message;
-    if (context !== undefined && context !== null) record.ctx = context;
+
+    if (context !== undefined && context !== null) {
+      record.ctx = this.redact ? LogRedactor.redact(context) : context;
+    }
 
     if (error instanceof Error) {
       record.error = {
@@ -49,4 +56,4 @@ class JsonFormatter {
   }
 }
 
-module.exports = JsonFormatter;
+module.exports = JsonFormatter;

package/src/logger/formatters/PrettyFormatter.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD } = require('../levels');
+const { LogRedactor } = require('../LogRedactor');
 
 const SEP = '  ';
 const TAG_WIDTH = 18;
@@ -72,7 +73,8 @@ class PrettyFormatter {
     for (const l of String(message).split('\n')) logicalLines.push({ text: l, dim: false });
 
     if (context != null) {
-      const ctx = typeof context === 'object' ? JSON.stringify(context) : String(context);
+      const safe = this.redact !== false ? LogRedactor.redact(context) : context;
+      const ctx  = typeof safe === 'object' ? JSON.stringify(safe) : String(safe);
       logicalLines.push({ text: ctx, dim: true });
     }
 

package/src/logger/formatters/SimpleFormatter.js

@@ -1,18 +1,28 @@
 'use strict';
 
 const { LEVEL_NAMES } = require('../levels');
+const { LogRedactor } = require('../LogRedactor');
 
 /**
  * SimpleFormatter
  *
  * Plain, no-colour text. Suitable for file output or any sink
- * where ANSI codes would be noise.
+ * where ANSI codes would be noise. Sensitive context fields are
+ * automatically redacted before serialisation.
  *
  * Output:
  *   [2026-03-15 12:00:00] [INFO]  Auth: User logged in
  *   [2026-03-15 12:00:01] [ERROR] DB: Query failed {"table":"users"}
  */
 class SimpleFormatter {
+  /**
+   * @param {object} [options]
+   * @param {boolean} [options.redact=true]  — redact sensitive context fields
+   */
+  constructor(options = {}) {
+    this.redact = options.redact !== false;
+  }
+
   format(entry) {
     const { level, tag, message, context, error, timestamp } = entry;
 
@@ -23,7 +33,8 @@ class SimpleFormatter {
     let line = `[${ts}] [${lvlName}] ${tagPart}${message}`;
 
     if (context !== undefined && context !== null) {
-      line += ' ' + (typeof context === 'object' ? JSON.stringify(context) : String(context));
+      const safe = this.redact ? LogRedactor.redact(context) : context;
+      line += ' ' + (typeof safe === 'object' ? JSON.stringify(safe) : String(safe));
     }
 
     if (error instanceof Error) {
@@ -34,4 +45,4 @@ class SimpleFormatter {
   }
 }
 
-module.exports = SimpleFormatter;
+module.exports = SimpleFormatter;

package/src/middleware/ThrottleMiddleware.js

@@ -7,18 +7,41 @@ const { jsonify }    = require('../http/helpers');
 /**
  * ThrottleMiddleware
  *
- * Simple in-memory rate limiter.
- * Uses the Millas middleware signature: handle(req, next).
+ * Per-IP (or per-user) rate limiter registered as the 'throttle' middleware alias.
+ * Used via the route middleware system — developers never import this directly.
+ *
+ * Usage in routes:
+ *   Route.middleware('throttle:5,10').group(() => {    // 5 req per 10 min
+ *     Route.post('/login', AuthController, 'login');
+ *   });
+ *
+ *   Route.post('/login', AuthController, 'login')     // same, single route
+ *     — add 'throttle:5,10' to route middleware array
+ *
+ * Format: 'throttle:<max>,<minutes>'
+ *   throttle:60,1   — 60 requests per minute
+ *   throttle:5,10   — 5 requests per 10 minutes
+ *   throttle:100,15 — 100 requests per 15 minutes
  */
 class ThrottleMiddleware extends Middleware {
   constructor(options = {}) {
     super();
     this.max    = options.max    || 60;
-    this.window = options.window || 60;
+    this.window = options.window || 60;   // seconds
     this.keyBy  = options.keyBy  || ((req) => req.ip || 'anonymous');
     this._store = new Map();
   }
 
+  /**
+   * Factory used by MiddlewareRegistry when parsing 'throttle:max,minutes'.
+   * @param {string[]} params  — ['5', '10'] from 'throttle:5,10'
+   */
+  static fromParams(params) {
+    const max     = parseInt(params[0], 10) || 60;
+    const minutes = parseInt(params[1], 10) || 1;
+    return new ThrottleMiddleware({ max, window: minutes * 60 });
+  }
+
   async handle(req, next) {
     const key    = this.keyBy(req);
     const now    = Date.now();
@@ -54,4 +77,4 @@ class ThrottleMiddleware extends Middleware {
   }
 }
 
-module.exports = ThrottleMiddleware;
+module.exports = ThrottleMiddleware;