millas 0.2.12-beta-2 → 0.2.13-beta

package/src/http/MillasRequest.js

@@ -225,13 +225,26 @@ class MillasRequest {
   // ─── Validation ─────────────────────────────────────────────────────────────
 
   /**
-   * Validate request input against rules. Throws 422 HttpError on failure.
-   * Returns the validated data on success.
+   * Validate request input against rules.
+   * Throws a 422 ValidationError on failure.
+   * Returns the validated + type-coerced data subset on success.
    *
    *   const data = await req.validate({
-   *     name:  'required|string|min:2|max:100',
-   *     email: 'required|email',
-   *     age:   'optional|number|min:0',
+   *     name:     'required|string|min:2|max:100',
+   *     email:    'required|email',
+   *     password: 'required|string|min:8',
+   *     age:      'optional|number|min:13',
+   *   });
+   *
+   * For route-level validation (runs before the handler, result in req.validated):
+   *
+   *   Route.post('/register', {
+   *     validate: {
+   *       email:    'required|email',
+   *       password: 'required|string|min:8',
+   *     },
+   *   }, async (req) => {
+   *     const { email, password } = req.validated;
    *   });
    */
   async validate(rules) {
@@ -239,15 +252,58 @@ class MillasRequest {
     return Validator.validate(this.all(), rules);
   }
 
+  /**
+   * The validated + coerced input — populated by route-level validation middleware.
+   * Null if no route-level validation was declared for this route.
+   *
+   *   Route.post('/login', { validate: { email: 'required|email' } }, async (req) => {
+   *     req.validated.email  // guaranteed valid email string
+   *   });
+   */
+  get validated() {
+    return this._req.validated ?? null;
+  }
+
+  // ─── CSRF ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the CSRF token for the current request.
+   * Use this in templates to populate the hidden _csrf field.
+   *
+   *   <input type="hidden" name="_csrf" value="<%= req.csrfToken() %>">
+   *
+   * Returns an empty string if CSRF middleware is not active (e.g. API routes).
+   */
+  csrfToken() {
+    if (typeof this._req.csrfToken === 'function') {
+      return this._req.csrfToken();
+    }
+    return '';
+  }
+
   // ─── Escape hatch ────────────────────────────────────────────────────────────
 
   /**
    * The raw underlying Express request.
-   * Only use this when you genuinely need something MillasRequest doesn't expose.
+   *
+   * WARNING: Accessing req.raw bypasses all Millas security abstractions
+   * (validation, CSRF, sanitization). Use only when MillasRequest genuinely
+   * does not expose what you need, and never pass req.raw values directly
+   * to database queries or HTML output without manual sanitization.
    */
   get raw() {
+    if (process.env.NODE_ENV === 'development') {
+      // Help developers discover missing MillasRequest features
+      // rather than defaulting to raw access silently
+      const stack = new Error().stack?.split('\n')[2]?.trim() || '';
+      console.warn(
+        `[Millas] req.raw accessed at ${stack}. ` +
+        'If MillasRequest is missing a feature you need, consider opening an issue ' +
+        'rather than bypassing the abstraction layer.'
+      );
+    }
     return this._req;
   }
 }
 
-module.exports = MillasRequest;
+module.exports = MillasRequest;

package/src/http/MillasResponse.js

@@ -1,5 +1,14 @@
 'use strict';
 
+// Secure cookie defaults — can be overridden per-call or via config/security.js
+// These are applied in cookie() below; callers can override any individual option.
+let _cookieDefaults = {
+  httpOnly: true,
+  secure:   process.env.NODE_ENV === 'production',
+  sameSite: 'Lax',
+  path:     '/',
+};
+
 /**
  * MillasResponse
  *
@@ -97,24 +106,53 @@ class MillasResponse {
   /**
    * Set a cookie on the response.
    *
-   *   return jsonify(data).cookie('token', value, { httpOnly: true, maxAge: 3600 })
+   * Secure defaults (httpOnly, secure, sameSite: Lax, path: /) are applied
+   * automatically. Pass explicit options to override any individual default.
+   *
+   *   // Secure by default — no extra options needed:
+   *   return jsonify(data).cookie('session', token)
+   *
+   *   // Override individual options:
+   *   return jsonify(data).cookie('token', jwt, { maxAge: 3600 })
+   *
+   *   // Opt out of a default (e.g. a non-sensitive preference cookie):
+   *   return jsonify(data).cookie('theme', 'dark', { httpOnly: false })
+   *
+   *   // Cross-site cookie (e.g. OAuth callback) — must also set secure: true:
+   *   return jsonify(data).cookie('oauth_state', state, { sameSite: 'None', secure: true })
    */
   cookie(name, value, options = {}) {
+    // Merge: secure defaults < caller options
+    // This means callers can always override, but never accidentally get insecure defaults
+    const merged = { ..._cookieDefaults, ...options };
     return new MillasResponse({
       type:    this._type,
       body:    this._body,
       status:  this._status,
       headers: this._headers,
-      cookies: { ...this._cookies, [name]: { value, options } },
+      cookies: { ...this._cookies, [name]: { value, options: merged } },
     });
   }
 
   /**
    * Clear a cookie.
+   *
    *   return jsonify(data).clearCookie('session')
+   *
+   * Preserves the same path/domain options used when the cookie was set
+   * so the browser correctly removes it.
    */
   clearCookie(name, options = {}) {
-    return this.cookie(name, '', { ...options, maxAge: 0, expires: new Date(0) });
+    // Must match the path/domain of the original cookie for the browser to delete it.
+    // Merge defaults so path always matches.
+    const clearOpts = { ..._cookieDefaults, ...options, maxAge: 0, expires: new Date(0) };
+    return new MillasResponse({
+      type:    this._type,
+      body:    this._body,
+      status:  this._status,
+      headers: this._headers,
+      cookies: { ...this._cookies, [name]: { value: '', options: clearOpts } },
+    });
   }
 
   // ─── Static factories ─────────────────────────────────────────────────────
@@ -191,6 +229,34 @@ class MillasResponse {
   static isResponse(value) {
     return value instanceof MillasResponse;
   }
+
+  /**
+   * Override the global cookie defaults.
+   *
+   * Called by the framework bootstrap when it loads config/security.js.
+   * Can also be called by developers for custom defaults:
+   *
+   *   MillasResponse.configureCookieDefaults({
+   *     httpOnly: true,
+   *     secure:   true,
+   *     sameSite: 'Strict',   // stricter than default Lax
+   *   });
+   *
+   * @param {object} defaults
+   */
+  static configureCookieDefaults(defaults = {}) {
+    _cookieDefaults = { ..._cookieDefaults, ...defaults };
+  }
+
+  /**
+   * Get the current cookie defaults (read-only copy).
+   * Useful for debugging or testing.
+   *
+   * @returns {object}
+   */
+  static getCookieDefaults() {
+    return { ..._cookieDefaults };
+  }
 }
 
-module.exports = MillasResponse;
+module.exports = MillasResponse;

package/src/http/ResponseDispatcher.js

@@ -1,46 +1,40 @@
 'use strict';
 
-const MillasResponse = require('./MillasResponse');
+const MillasResponse                 = require('./MillasResponse');
+const { containsUnsafeHtmlPatterns } = require('./HtmlEscape');
 
 /**
  * ResponseDispatcher
  *
- * Kernel-side utility — handles auto-wrapping plain return values into
- * MillasResponse objects.
- *
- * Actual dispatch to the HTTP engine (setting headers, writing the body)
- * lives in HttpAdapter.dispatch() — that is the only place HTTP-engine
- * APIs are called.
- *
- * This file has zero imports of Express or any HTTP engine.
+ * Auto-wraps plain route handler return values into MillasResponse objects.
+ * In development, warns when returned HTML strings contain patterns that
+ * suggest unescaped user input. Use safeHtml`` or escapeHtml() to fix.
  */
 class ResponseDispatcher {
 
-  /**
-   * Auto-wrap a plain JS return value into a MillasResponse.
-   *
-   * Called when a route handler returns something that is NOT already
-   * a MillasResponse — e.g. a plain object, string, number, or array.
-   *
-   * @param {*} value
-   * @returns {MillasResponse}
-   */
   static autoWrap(value) {
     if (MillasResponse.isResponse(value)) return value;
-
     if (value instanceof Error) throw value;
 
     if (typeof value === 'string') {
-      return value.trimStart().startsWith('<')
-        ? MillasResponse.html(value)
-        : MillasResponse.text(value);
+      const isHtml = value.trimStart().startsWith('<');
+
+      if (isHtml && process.env.NODE_ENV !== 'production') {
+        if (containsUnsafeHtmlPatterns(value)) {
+          console.warn(
+            '[Millas] ⚠ Potentially unsafe HTML returned from route handler.\n' +
+            '  The response contains unescaped patterns (<script>, onerror=, javascript:).\n' +
+            '  Use safeHtml`` or escapeHtml() to escape user input:\n' +
+            '    const { safeHtml } = require(\'millas/src/http/HtmlEscape\');\n' +
+            '    return safeHtml`<p>${userInput}</p>`;\n'
+          );
+        }
+      }
+
+      return isHtml ? MillasResponse.html(value) : MillasResponse.text(value);
     }
 
-    if (
-      typeof value === 'object'  ||
-      typeof value === 'number'  ||
-      typeof value === 'boolean'
-    ) {
+    if (typeof value === 'object' || typeof value === 'number' || typeof value === 'boolean') {
       return MillasResponse.json(value);
     }
 

package/src/http/SafeFilePath.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+/**
+ * SafeFilePath
+ *
+ * Prevents path traversal attacks when constructing file paths from
+ * user-provided input.
+ *
+ * A path traversal attack lets an attacker escape a storage directory by
+ * injecting sequences like '../' into a filename:
+ *
+ *   /storage/uploads/ + ../../etc/passwd  →  /etc/passwd
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const { resolveStoragePath } = require('millas/src/http/SafeFilePath');
+ *
+ *   // Confine a user-provided filename to a directory
+ *   const safePath = resolveStoragePath(req.param('filename'), '/storage/uploads');
+ *   return file(safePath);
+ *
+ *   // With optional existence check
+ *   const safePath = resolveStoragePath(filename, '/storage/uploads', { mustExist: true });
+ *
+ *   // AI file upload — confine to storage root
+ *   const safePath = resolveStoragePath(userPath, process.env.STORAGE_ROOT || '/storage');
+ *   const f = await AI.files.fromPath(safePath).put();
+ *
+ * ── What it protects against ──────────────────────────────────────────────────
+ *
+ *   resolveStoragePath('../../etc/passwd', '/storage/uploads')
+ *   // throws PathTraversalError — '../' escapes the storage root
+ *
+ *   resolveStoragePath('report%2F..%2F..%2Fetc%2Fpasswd', '/storage/uploads')
+ *   // throws PathTraversalError — URL-encoded traversal is also caught
+ *
+ *   resolveStoragePath('/absolute/path/outside', '/storage/uploads')
+ *   // throws PathTraversalError — absolute paths that escape the root are rejected
+ *
+ *   resolveStoragePath('subdir/report.pdf', '/storage/uploads')
+ *   // returns '/storage/uploads/subdir/report.pdf'  ✓ safe
+ *
+ * ── Configuration (config/security.js) ───────────────────────────────────────
+ *
+ *   files: {
+ *     storageRoot: process.env.STORAGE_ROOT || path.join(process.cwd(), 'storage'),
+ *   }
+ */
+
+// ── PathTraversalError ────────────────────────────────────────────────────────
+
+class PathTraversalError extends Error {
+  constructor(userInput, allowedRoot) {
+    super(
+      `Path traversal attempt blocked. ` +
+      `Input "${userInput}" resolves outside the allowed directory "${allowedRoot}".`
+    );
+    this.name    = 'PathTraversalError';
+    this.status  = 403;
+    this.code    = 'EPATH_TRAVERSAL';
+    this.input   = userInput;
+    this.root    = allowedRoot;
+  }
+}
+
+// ── Core resolution ───────────────────────────────────────────────────────────
+
+/**
+ * Resolve a user-provided filename/path within an allowed root directory.
+ * Throws PathTraversalError if the resolved path escapes the root.
+ *
+ * @param {string} userInput   — filename or relative path from user input
+ * @param {string} allowedRoot — the directory all files must stay within
+ * @param {object} [opts]
+ * @param {boolean} [opts.mustExist=false] — throw if file doesn't exist
+ * @param {boolean} [opts.allowSubdirs=true] — allow path separators in input
+ * @returns {string}  — absolute, safe file path
+ * @throws {PathTraversalError}
+ */
+function resolveStoragePath(userInput, allowedRoot, opts = {}) {
+  if (!userInput || typeof userInput !== 'string') {
+    throw new PathTraversalError(String(userInput), allowedRoot);
+  }
+
+  if (!allowedRoot || typeof allowedRoot !== 'string') {
+    throw new Error('[Millas SafeFilePath] allowedRoot must be a non-empty string.');
+  }
+
+  // ── Decode URL encoding first ───────────────────────────────────────────────
+  // Attackers may use %2F, %2E%2E etc. to bypass naive string checks
+  let decoded;
+  try {
+    decoded = decodeURIComponent(userInput);
+  } catch {
+    decoded = userInput;
+  }
+
+  // ── Reject null bytes ───────────────────────────────────────────────────────
+  // Null bytes can truncate paths in some runtimes
+  if (decoded.includes('\0') || userInput.includes('\0')) {
+    throw new PathTraversalError(userInput, allowedRoot);
+  }
+
+  // ── Optionally block subdirectory separators ────────────────────────────────
+  if (opts.allowSubdirs === false) {
+    if (decoded.includes('/') || decoded.includes('\\') || decoded.includes(path.sep)) {
+      throw new PathTraversalError(userInput, allowedRoot);
+    }
+  }
+
+  // ── Resolve both paths to absolute, normalised forms ───────────────────────
+  const resolvedRoot  = path.resolve(allowedRoot);
+  const resolvedInput = path.resolve(resolvedRoot, decoded);
+
+  // ── The core check: resolved path must start with the root ─────────────────
+  // Add path.sep to prevent '/storage/uploads-secret' matching '/storage/uploads'
+  const rootWithSep = resolvedRoot.endsWith(path.sep)
+    ? resolvedRoot
+    : resolvedRoot + path.sep;
+
+  if (resolvedInput !== resolvedRoot && !resolvedInput.startsWith(rootWithSep)) {
+    throw new PathTraversalError(userInput, allowedRoot);
+  }
+
+  // ── Optional existence check ────────────────────────────────────────────────
+  if (opts.mustExist && !fs.existsSync(resolvedInput)) {
+    const err = new Error(`File not found: ${path.basename(resolvedInput)}`);
+    err.status = 404;
+    err.code   = 'EFILE_NOT_FOUND';
+    throw err;
+  }
+
+  return resolvedInput;
+}
+
+/**
+ * Check if a path is safely within a root directory (non-throwing version).
+ *
+ * @param {string} userInput
+ * @param {string} allowedRoot
+ * @returns {boolean}
+ */
+function isSafeFilePath(userInput, allowedRoot) {
+  try {
+    resolveStoragePath(userInput, allowedRoot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── SafeFilePath class ────────────────────────────────────────────────────────
+
+class SafeFilePath {
+  /**
+   * Configure the default storage root.
+   * Called by SecurityBootstrap from config/security.js files.storageRoot.
+   *
+   * @param {string} root
+   */
+  static setStorageRoot(root) {
+    SafeFilePath._storageRoot = root;
+  }
+
+  /**
+   * Get the configured storage root (or the default).
+   */
+  static getStorageRoot() {
+    return SafeFilePath._storageRoot ||
+      process.env.STORAGE_ROOT ||
+      path.join(process.cwd(), 'storage');
+  }
+
+  /**
+   * Resolve a path within the configured default storage root.
+   * Convenience wrapper for the common case.
+   *
+   *   SafeFilePath.resolve('uploads/photo.jpg')
+   *   // → '/var/www/myapp/storage/uploads/photo.jpg'
+   *
+   * @param {string} userInput
+   * @param {object} [opts]
+   * @returns {string}
+   */
+  static resolve(userInput, opts = {}) {
+    return resolveStoragePath(userInput, SafeFilePath.getStorageRoot(), opts);
+  }
+}
+
+SafeFilePath._storageRoot = null;
+
+module.exports = { SafeFilePath, resolveStoragePath, isSafeFilePath, PathTraversalError };

package/src/http/SafeRedirect.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * SafeRedirect — INTERNAL MODULE
+ *
+ * Not part of the developer API. Developers use redirect() from helpers.js.
+ * This module is configured by SecurityBootstrap from config/app.js.
+ */
+
+let _allowedOrigins = [];
+let _appOrigin      = null;
+
+function _parseOrigin(url) {
+  try { return new URL(url).origin; } catch { return null; }
+}
+
+function _getLower() {
+  return _allowedOrigins.map(o => _parseOrigin(o)).filter(Boolean);
+}
+
+function isSafeRedirect(url) {
+  if (!url || typeof url !== 'string') return false;
+
+  const trimmed = url.trim();
+  const lower   = trimmed.toLowerCase().replace(/\s/g, '');
+
+  // Block dangerous schemes
+  if (lower.startsWith('javascript:') || lower.startsWith('data:') || lower.startsWith('vbscript:')) {
+    return false;
+  }
+
+  // Relative paths (not protocol-relative) are always safe
+  if (trimmed.startsWith('/') && !trimmed.startsWith('//')) return true;
+
+  // Absolute URL — parse and check origin
+  let parsed;
+  try { parsed = new URL(trimmed); } catch { return false; }
+  if (!['http:', 'https:'].includes(parsed.protocol)) return false;
+
+  const allowed = new Set([
+    ..._getLower(),
+    ...(_appOrigin ? [_appOrigin] : []),
+  ]);
+
+  return allowed.has(parsed.origin);
+}
+
+class SafeRedirect {
+  static configure(origins = []) {
+    _allowedOrigins = origins;
+  }
+
+  static setAppUrl(url) {
+    _appOrigin = _parseOrigin(url);
+  }
+
+  static isSafe(url) {
+    return isSafeRedirect(url);
+  }
+}
+
+module.exports = { SafeRedirect, isSafeRedirect };

package/src/http/SecurityBootstrap.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const SecurityHeaders  = require('./middleware/SecurityHeaders');
+const CsrfMiddleware   = require('./middleware/CsrfMiddleware');
+const { RateLimiter }  = require('./middleware/RateLimiter');
+const MillasResponse   = require('./MillasResponse');
+
+class SecurityBootstrap {
+  static apply(app, config = {}) {
+    const headerConfig = config.headers !== undefined ? config.headers : {};
+    app.use(SecurityHeaders.from(headerConfig).middleware());
+
+    if (config.cookies) {
+      MillasResponse.configureCookieDefaults(config.cookies);
+    }
+
+    const globalRateLimit = RateLimiter.from(config.rateLimit?.global);
+    if (globalRateLimit) {
+      app.use(globalRateLimit.middleware());
+    }
+
+    if (config.csrf !== false) {
+      app.use(CsrfMiddleware.from(config.csrf || {}).middleware());
+    }
+
+    SecurityBootstrap._registerErrorHandler(app);
+
+    if (process.env.MILLAS_DEBUG_SECURITY === 'true') {
+      console.log('[Millas Security] Controls applied:');
+      console.log('  ✓ Security headers:  ', headerConfig === false ? 'DISABLED' : 'enabled');
+      console.log('  ✓ Cookie defaults:   ', JSON.stringify(MillasResponse.getCookieDefaults()));
+      console.log('  ✓ Global rate limit: ', globalRateLimit ? `${config.rateLimit?.global?.max || 100} req/window` : 'disabled');
+      console.log('  ✓ CSRF:              ', config.csrf === false ? 'DISABLED' : 'enabled');
+    }
+  }
+
+  static _registerErrorHandler(app) {
+    // eslint-disable-next-line no-unused-vars
+    app.use((err, req, res, next) => {
+      if (err.code === 'EBADCSRFTOKEN') {
+        const isApi = (req.headers?.accept || '').includes('application/json') ||
+                      (req.headers?.['content-type'] || '').includes('application/json');
+        res.status(403);
+        return isApi
+          ? res.json({ error: 'Invalid or missing CSRF token' })
+          : res.send('Forbidden: Invalid CSRF token. Please go back and try again.');
+      }
+      if (err.code === 'EVALIDATION' || err.name === 'ValidationError') {
+        return res.status(422).json({ message: 'Validation failed', errors: err.errors || {} });
+      }
+      next(err);
+    });
+  }
+  static loadConfig(configPath) {
+    const path = require('path');
+    const fs   = require('fs');
+    // Accept either a full path to app.js or a directory (falls back to config/app.js)
+    const target = configPath
+      ? (configPath.endsWith('.js') ? configPath : configPath + '.js').replace(/\.js\.js$/, '.js')
+      : path.join(process.cwd(), 'config', 'app.js');
+    if (fs.existsSync(target)) {
+      try { return require(target); } catch (err) {
+        console.warn(`[Millas] Failed to load ${target}: ${err.message}. Using built-in defaults.`);
+      }
+    }
+    return {};
+  }
+}
+
+module.exports = SecurityBootstrap;