millas 0.2.12-beta-2 → 0.2.13

package/src/facades/Hash.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { createFacade }              = require('./Facade');
+const { HashManager, BcryptDriver } = require('../hashing/Hash');
+
+/**
+ * Hash facade — Laravel-style hashing.
+ *
+ * Resolved from the DI container as 'hash'.
+ * Falls back to the exported singleton if used before the container boots
+ * (e.g. in migrations or standalone scripts).
+ *
+ * @class
+ *
+ * ── Core ─────────────────────────────────────────────────────────────────────
+ * @property {function(string, object=): Promise<string>}   make
+ *   Hash a plain-text value.
+ *   Options: { rounds: 14 } — overrides the configured rounds for this call.
+ *
+ * @property {function(string, string): Promise<boolean>}   check
+ *   Verify a plain-text value against a stored hash.
+ *   Returns false (never throws) if either argument is falsy.
+ *
+ * @property {function(string): boolean}                    needsRehash
+ *   Returns true if the hash was made with different rounds than currently
+ *   configured. Use after login to silently upgrade stored hashes:
+ *     if (Hash.needsRehash(user.password)) {
+ *       user.password = await Hash.make(plaintext);
+ *       await user.save();
+ *     }
+ *
+ * ── Introspection ─────────────────────────────────────────────────────────────
+ * @property {function(string): { alg: string, rounds: number }}  info
+ *   Return metadata about a stored hash.
+ *   Example: Hash.info(hash) → { alg: 'bcrypt', rounds: 12 }
+ *
+ * @property {function(string): boolean}                          isHashed
+ *   Return true if the value looks like a bcrypt hash.
+ *   Guards against accidentally double-hashing:
+ *     if (!Hash.isHashed(value)) value = await Hash.make(value);
+ *
+ * ── Driver access ─────────────────────────────────────────────────────────────
+ * @property {function(string=): BcryptDriver}   driver
+ *   Get a specific driver instance:
+ *     Hash.driver('bcrypt').make('secret', { rounds: 14 });
+ *
+ * ── Configuration ─────────────────────────────────────────────────────────────
+ * @property {function(number): HashManager}   setRounds
+ *   Change the bcrypt rounds at runtime. Busts the driver cache.
+ *   Useful in tests:  Hash.setRounds(4);
+ *
+ * @property {function(): number}              getRounds
+ *   Return the currently configured bcrypt rounds.
+ *
+ * ── Testing ───────────────────────────────────────────────────────────────────
+ * @property {function(object): void}   swap
+ *   Swap the underlying instance for a fake:
+ *     Hash.swap({ make: async () => 'hashed', check: async () => true });
+ *
+ * @property {function(): void}         restore
+ *   Restore the real implementation after a swap.
+ *
+ * @see src/hashing/Hash.js
+ */
+class Hash extends createFacade('hash') {}
+
+module.exports = Hash

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 };