millas 0.2.12-beta-1 → 0.2.13-beta

package/src/facades/Process.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const { createFacade }                = require('./Facade');
+const ProcessService                  = require('../process/Process');
+const { ProcessManager, PendingProcess,
+        ProcessResult, ProcessPool,
+        ProcessFailedException }      = require('../process/Process');
+
+/**
+ * Process facade — Laravel-style process runner.
+ *
+ * Resolved from the DI container as 'process'.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * QUICK START
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const { Process } = require('millas/facades/Process');
+ *
+ *   // Run a command and get a ProcessResult
+ *   const result = await Process.run('node --version');
+ *   console.log(result.output());    // 'v20.1.0\n'
+ *   console.log(result.successful);  // true
+ *   console.log(result.exitCode());  // 0
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * BUILDER — chain options before running
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const result = await Process
+ *     .path('/var/www/app')      // working directory
+ *     .timeout(120)              // kill after 120 seconds
+ *     .env({ NODE_ENV: 'ci' })   // merge into parent env
+ *     .quietly()                 // suppress passthrough to console
+ *     .throwOnFailure()          // throw if exit code != 0
+ *     .run('npm ci');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SHELL MODE — pipes, &&, ||, globs
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const result = await Process.shell().run('cat package.json | grep version');
+ *   const result = await Process.shell().run('npm run build && npm test');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * STDIN INPUT
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const result = await Process.input('hello world').run('cat');
+ *   console.log(result.output()); // 'hello world'
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * STREAMING OUTPUT — line-by-line callbacks
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   await Process.pipe('npm install', {
+ *     stdout: line => io.emit('deploy:log', line),
+ *     stderr: line => io.emit('deploy:err', line),
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SYNCHRONOUS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const result = Process.quietly().runSync('git rev-parse HEAD');
+ *   const sha    = result.output().trim();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ERROR HANDLING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Manual check
+ *   const result = await Process.quietly().run('npm test');
+ *   if (result.failed) {
+ *     console.error(result.errorOutput());
+ *   }
+ *
+ *   // Throw on failure
+ *   const result = await Process.quietly().run('npm test');
+ *   result.throw();   // throws ProcessFailedException if failed
+ *
+ *   // Auto-throw
+ *   try {
+ *     await Process.throwOnFailure().run('npm test');
+ *   } catch (err) {
+ *     console.log(err.result.errorOutput()); // ProcessFailedException
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * CONCURRENT POOL
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const [lint, test, build] = await Process.pool(pool => [
+ *     pool.quietly().run('npm run lint'),
+ *     pool.quietly().run('npm test'),
+ *     pool.quietly().run('npm run build'),
+ *   ]);
+ *
+ *   if (lint.failed)  console.error('Lint failed:', lint.errorOutput());
+ *   if (test.failed)  console.error('Tests failed:', test.errorOutput());
+ *   if (build.failed) console.error('Build failed:', build.errorOutput());
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PROCESSRESULT API
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   result.output()        // stdout as string
+ *   result.errorOutput()   // stderr as string
+ *   result.exitCode()      // number
+ *   result.successful      // true if exitCode === 0
+ *   result.failed          // true if exitCode !== 0
+ *   result.throw()         // throws ProcessFailedException if failed
+ *   result.throwIfFailed() // alias
+ *   String(result)         // same as result.output()
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ENVIRONMENT
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Merge extra vars into parent env (default)
+ *   Process.env({ DEBUG: '1', PORT: '4000' }).run('node server.js')
+ *
+ *   // Use ONLY these vars — don't inherit parent env
+ *   Process.env({ PATH: '/usr/bin' }, false).run('node server.js')
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TESTING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   Process.swap({
+ *     run: async () => new ProcessResult({ exitCode: 0, stdout: 'mocked', stderr: '' }),
+ *   });
+ *
+ *   // ... run test ...
+ *
+ *   Process.restore();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * @see src/process/Process.js
+ */
+class Process extends createFacade('process') {}
+
+module.exports = { Process, ProcessManager, PendingProcess, ProcessResult, ProcessPool, ProcessFailedException };

package/src/hashing/Hash.js

@@ -0,0 +1,262 @@
+'use strict';
+
+const bcrypt = require('bcryptjs');
+
+// ── BcryptDriver ──────────────────────────────────────────────────────────────
+
+class BcryptDriver {
+  /**
+   * @param {object} config
+   * @param {number} config.rounds  — cost factor (default 12)
+   */
+  constructor(config = {}) {
+    this.rounds = config.rounds ?? 12;
+  }
+
+  /**
+   * Hash a plain-text value.
+   *
+   *   await Hash.make('secret');
+   *   await Hash.make('secret', { rounds: 14 });
+   *
+   * @param {string} value
+   * @param {object} options
+   * @returns {Promise<string>}
+   */
+  async make(value, options = {}) {
+    const rounds = options.rounds ?? this.rounds;
+    return bcrypt.hash(String(value), rounds);
+  }
+
+  /**
+   * Verify a plain-text value against a stored hash.
+   *
+   *   const ok = await Hash.check('secret', storedHash);
+   *
+   * @param {string} value
+   * @param {string} hashedValue
+   * @returns {Promise<boolean>}
+   */
+  async check(value, hashedValue) {
+    if (!value || !hashedValue) return false;
+    return bcrypt.compare(String(value), String(hashedValue));
+  }
+
+  /**
+   * Determine if a hash needs to be rehashed.
+   * Returns true if the hash was made with fewer rounds than currently configured.
+   *
+   *   if (Hash.needsRehash(user.password)) {
+   *     user.password = await Hash.make(plaintext);
+   *     await user.save();
+   *   }
+   *
+   * @param {string} hashedValue
+   * @returns {boolean}
+   */
+  needsRehash(hashedValue) {
+    try {
+      return bcrypt.getRounds(hashedValue) !== this.rounds;
+    } catch {
+      return true;
+    }
+  }
+
+  /**
+   * Return info about a hash: algorithm, rounds.
+   *
+   *   Hash.info(hash)
+   *   // → { alg: 'bcrypt', rounds: 12 }
+   *
+   * @param {string} hashedValue
+   * @returns {{ alg: string, rounds: number }}
+   */
+  info(hashedValue) {
+    try {
+      return { alg: 'bcrypt', rounds: bcrypt.getRounds(hashedValue) };
+    } catch {
+      return { alg: 'unknown', rounds: null };
+    }
+  }
+
+  /**
+   * Check whether a value is already hashed (not plain-text).
+   * Detects bcrypt hash format: $2a$, $2b$, $2y$ prefixes.
+   *
+   * @param {string} value
+   * @returns {boolean}
+   */
+  isHashed(value) {
+    return /^\$2[aby]\$\d{2}\$/.test(String(value));
+  }
+}
+
+// ── HashManager ───────────────────────────────────────────────────────────────
+
+/**
+ * HashManager
+ *
+ * Laravel-style hashing service. Manages multiple drivers (currently bcrypt)
+ * and delegates all calls to the active driver.
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const { Hash } = require('millas/facades/Hash');
+ *
+ *   // Hash a password
+ *   const hashed = await Hash.make('my-password');
+ *
+ *   // Verify
+ *   const ok = await Hash.check('my-password', hashed);   // true
+ *
+ *   // Rehash check (e.g. rounds changed in config)
+ *   if (Hash.needsRehash(user.password)) {
+ *     user.password = await Hash.make(plainPassword);
+ *     await user.save();
+ *   }
+ *
+ *   // Info
+ *   Hash.info(hashed);  // { alg: 'bcrypt', rounds: 12 }
+ *
+ *   // Guard against double-hashing
+ *   if (!Hash.isHashed(value)) {
+ *     value = await Hash.make(value);
+ *   }
+ *
+ *   // Use a different driver temporarily
+ *   Hash.driver('bcrypt').make('secret', { rounds: 14 });
+ *
+ *   // Adjust rounds globally (e.g. in tests)
+ *   Hash.setRounds(4);
+ *
+ * ── Service provider registration ─────────────────────────────────────────────
+ *
+ *   container.singleton('hash', () => new HashManager({ default: 'bcrypt', bcrypt: { rounds: 12 } }));
+ *   container.alias('Hash', 'hash');
+ */
+class HashManager {
+  /**
+   * @param {object} config
+   * @param {string} config.default      — driver name (default: 'bcrypt')
+   * @param {object} config.bcrypt       — bcrypt driver config
+   * @param {number} config.bcrypt.rounds
+   */
+  constructor(config = {}) {
+    this._config  = config;
+    this._default = config.default || 'bcrypt';
+    this._drivers = new Map();
+  }
+
+  // ── Driver resolution ──────────────────────────────────────────────────────
+
+  /**
+   * Get a named driver instance (cached).
+   *
+   * @param {string} [name]
+   * @returns {BcryptDriver}
+   */
+  driver(name) {
+    const driverName = name || this._default;
+    if (!this._drivers.has(driverName)) {
+      this._drivers.set(driverName, this._createDriver(driverName));
+    }
+    return this._drivers.get(driverName);
+  }
+
+  _createDriver(name) {
+    if (name === 'bcrypt') {
+      return new BcryptDriver(this._config.bcrypt || {});
+    }
+    throw new Error(`[Hash] Unknown driver: "${name}". Only 'bcrypt' is supported.`);
+  }
+
+  // ── Configuration helpers ──────────────────────────────────────────────────
+
+  /**
+   * Change the bcrypt rounds at runtime.
+   * Useful for lowering cost in test environments:
+   *
+   *   Hash.setRounds(4);  // fast in tests
+   *
+   * @param {number} rounds
+   * @returns {this}
+   */
+  setRounds(rounds) {
+    this._config.bcrypt      = this._config.bcrypt || {};
+    this._config.bcrypt.rounds = rounds;
+    // Bust the cached driver so next call picks up the new config
+    this._drivers.delete('bcrypt');
+    return this;
+  }
+
+  /**
+   * Return the currently configured bcrypt rounds.
+   *
+   * @returns {number}
+   */
+  getRounds() {
+    return (this._config.bcrypt || {}).rounds ?? 12;
+  }
+
+  // ── Delegated methods (forward to the default driver) ─────────────────────
+
+  /**
+   * Hash a value using the default driver.
+   *
+   * @param {string}  value
+   * @param {object}  [options]
+   * @param {number}  [options.rounds]   — override rounds for this call only
+   * @returns {Promise<string>}
+   */
+  make(value, options = {}) {
+    return this.driver().make(value, options);
+  }
+
+  /**
+   * Check a plain value against a stored hash.
+   *
+   * @param {string} value
+   * @param {string} hashedValue
+   * @returns {Promise<boolean>}
+   */
+  check(value, hashedValue) {
+    return this.driver().check(value, hashedValue);
+  }
+
+  /**
+   * Determine whether a hash needs to be rehashed (e.g. rounds have changed).
+   *
+   * @param {string} hashedValue
+   * @returns {boolean}
+   */
+  needsRehash(hashedValue) {
+    return this.driver().needsRehash(hashedValue);
+  }
+
+  /**
+   * Return metadata about a hash.
+   *
+   * @param {string} hashedValue
+   * @returns {{ alg: string, rounds: number }}
+   */
+  info(hashedValue) {
+    return this.driver().info(hashedValue);
+  }
+
+  /**
+   * Detect whether a value is already hashed (guards against double-hashing).
+   *
+   * @param {string} value
+   * @returns {boolean}
+   */
+  isHashed(value) {
+    return this.driver().isHashed(value);
+  }
+}
+
+// ── Singleton with default config ─────────────────────────────────────────────
+const defaultHash = new HashManager({ default: 'bcrypt', bcrypt: { rounds: 12 } });
+
+module.exports             = defaultHash;
+module.exports.HashManager = HashManager;
+module.exports.BcryptDriver = BcryptDriver;

package/src/http/HtmlEscape.js

@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * HtmlEscape
+ *
+ * Escapes user-provided strings for safe inclusion in HTML output,
+ * preventing Cross-Site Scripting (XSS) attacks.
+ *
+ * ── The problem ───────────────────────────────────────────────────────────────
+ *
+ *   const name = req.input('name');  // attacker sends: <script>alert(1)</script>
+ *   return `<p>Hello ${name}</p>`;   // → XSS vulnerability
+ *
+ * ── The solution ──────────────────────────────────────────────────────────────
+ *
+ *   const { e } = require('millas/src/http/HtmlEscape');
+ *   return `<p>Hello ${e(name)}</p>`;  // → <p>Hello &lt;script&gt;...&lt;/script&gt;</p>
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const { escapeHtml, e, safeHtml } = require('millas/src/http/HtmlEscape');
+ *
+ *   // Escape a single value
+ *   escapeHtml('<script>alert(1)</script>')
+ *   // → '&lt;script&gt;alert(1)&lt;/script&gt;'
+ *
+ *   // Short alias for use in template literals
+ *   `<p>${e(user.name)}</p>`
+ *
+ *   // Build a safe HTML response — all interpolated values are escaped
+ *   return safeHtml`<h1>Hello ${user.name}</h1><p>${user.bio}</p>`;
+ *
+ *   // Mark a value as already-safe (trusted HTML — use with caution)
+ *   const trusted = new SafeString('<b>bold</b>');
+ *   safeHtml`<div>${trusted}</div>`  // not double-escaped
+ *
+ * ── In templates ─────────────────────────────────────────────────────────────
+ *
+ *   When using a template engine, enable auto-escaping at the engine level.
+ *   These utilities are for cases where you build HTML strings in route handlers
+ *   or helpers without a template engine.
+ *
+ * ── What is escaped ──────────────────────────────────────────────────────────
+ *
+ *   &   →  &amp;     (must be first to avoid double-escaping)
+ *   <   →  &lt;
+ *   >   →  &gt;
+ *   "   →  &quot;    (safe in attribute values)
+ *   '   →  &#x27;    (safe in attribute values)
+ *   /   →  &#x2F;    (helps close tags inside attribute values)
+ *   `   →  &#x60;    (template literal injection)
+ *   =   →  &#x3D;    (attribute injection without quotes)
+ */
+
+// ── SafeString ────────────────────────────────────────────────────────────────
+
+/**
+ * A wrapper that marks a string as already-escaped / trusted HTML.
+ * safeHtml`` will not escape SafeString instances.
+ *
+ *   const html = new SafeString('<strong>bold</strong>');
+ */
+class SafeString {
+  constructor(value) {
+    this.value = String(value);
+  }
+  toString() {
+    return this.value;
+  }
+}
+
+// ── Core escape function ──────────────────────────────────────────────────────
+
+const ESCAPE_MAP = {
+  '&':  '&amp;',
+  '<':  '&lt;',
+  '>':  '&gt;',
+  '"':  '&quot;',
+  "'":  '&#x27;',
+  '/':  '&#x2F;',
+  '`':  '&#x60;',
+  '=':  '&#x3D;',
+};
+
+const ESCAPE_RE = /[&<>"'`=/]/g;
+
+/**
+ * Escape a value for safe inclusion in HTML.
+ * Returns an empty string for null/undefined.
+ * Non-string values are converted to string first.
+ * SafeString instances are returned as-is (already trusted).
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+function escapeHtml(value) {
+  if (value instanceof SafeString) return value.value;
+  if (value === null || value === undefined) return '';
+  return String(value).replace(ESCAPE_RE, c => ESCAPE_MAP[c]);
+}
+
+/**
+ * Short alias — designed for template literals:
+ *   `<p>${e(user.name)}</p>`
+ */
+const e = escapeHtml;
+
+// ── Tagged template literal ───────────────────────────────────────────────────
+
+/**
+ * Tagged template literal that auto-escapes all interpolated values.
+ * Returns a MillasResponse (html type) so it can be returned directly
+ * from a route handler.
+ *
+ *   return safeHtml`<h1>Hello ${user.name}</h1>`;
+ *   return safeHtml`<ul>${items.map(i => safeHtml`<li>${i.name}</li>`).join('')}</ul>`;
+ *
+ * To include trusted HTML without escaping, wrap it in SafeString:
+ *   const icon = new SafeString('<svg>...</svg>');
+ *   return safeHtml`<div>${icon} ${user.name}</div>`;
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {...*} values
+ * @returns {string}  — escaped HTML string
+ */
+function safeHtml(strings, ...values) {
+  let result = '';
+  for (let i = 0; i < strings.length; i++) {
+    result += strings[i];
+    if (i < values.length) {
+      result += escapeHtml(values[i]);
+    }
+  }
+  return result;
+}
+
+// ── ResponseDispatcher integration ───────────────────────────────────────────
+
+/**
+ * Detect whether a string contains unescaped HTML characters that could
+ * indicate unsanitized user input was interpolated directly.
+ *
+ * Used by ResponseDispatcher.autoWrap() to emit a development warning
+ * when a route returns an HTML string containing potentially dangerous chars.
+ *
+ * This is NOT a security control — it is a development-time hint to help
+ * developers discover forgotten escaping. The real protection is using
+ * safeHtml`` or a template engine with auto-escaping enabled.
+ *
+ * @param {string} html
+ * @returns {boolean}
+ */
+function containsUnsafeHtmlPatterns(html) {
+  // Look for raw script tags, event handlers, javascript: URIs
+  // that are commonly injected — not exhaustive, just a hint
+  return /<script[\s>]/i.test(html)           ||
+         /\son\w+\s*=/i.test(html)            ||
+         /javascript\s*:/i.test(html)         ||
+         /data\s*:\s*text\/html/i.test(html);
+}
+
+module.exports = { escapeHtml, e, safeHtml, SafeString, containsUnsafeHtmlPatterns };

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;