millas 0.1.0

package/src/auth/AuthController.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const Controller = require('../controller/Controller');
+const Auth       = require('./Auth');
+
+/**
+ * AuthController
+ *
+ * Drop-in authentication controller.
+ * Register its routes in routes/api.js:
+ *
+ *   const AuthController = require('millas/src/auth/AuthController');
+ *
+ *   Route.post('/auth/register', AuthController, 'register');
+ *   Route.post('/auth/login',    AuthController, 'login');
+ *   Route.post('/auth/logout',   AuthController, 'logout');
+ *   Route.get('/auth/me',        AuthController, 'me');
+ *   Route.post('/auth/refresh',  AuthController, 'refresh');
+ *   Route.post('/auth/forgot-password',  AuthController, 'forgotPassword');
+ *   Route.post('/auth/reset-password',   AuthController, 'resetPassword');
+ *
+ * Or use the convenience helper:
+ *   Route.auth()  — registers all routes above under /auth
+ */
+class AuthController extends Controller {
+
+  /**
+   * POST /auth/register
+   * Body: { name, email, password, password_confirmation? }
+   */
+  async register(req, res) {
+    const data = await this.validate(req, {
+      name:     'required|string|min:2|max:100',
+      email:    'required|email',
+      password: 'required|string|min:8',
+    });
+
+    const user  = await Auth.register(data);
+    const token = Auth.issueToken(user);
+
+    return this.created(res, {
+      message: 'Registration successful',
+      user:    this._safeUser(user),
+      token,
+    });
+  }
+
+  /**
+   * POST /auth/login
+   * Body: { email, password }
+   */
+  async login(req, res) {
+    const { email, password } = await this.validate(req, {
+      email:    'required|email',
+      password: 'required|string',
+    });
+
+    const { user, token, refreshToken } = await Auth.login(email, password);
+
+    return this.ok(res, {
+      message: 'Login successful',
+      user:    this._safeUser(user),
+      token,
+      refresh_token: refreshToken,
+    });
+  }
+
+  /**
+   * POST /auth/logout
+   * Header: Authorization: Bearer <token>
+   *
+   * JWT is stateless — logout just instructs the client to discard the token.
+   * Phase 11 (cache) will add token blocklisting.
+   */
+  async logout(req, res) {
+    return this.ok(res, { message: 'Logged out successfully' });
+  }
+
+  /**
+   * GET /auth/me
+   * Header: Authorization: Bearer <token>
+   */
+  async me(req, res) {
+    try {
+      const user = await Auth.userOrFail(req);
+      return this.ok(res, { user: this._safeUser(user) });
+    } catch (err) {
+      if (err.status === 401) return this.unauthorized(res, err.message);
+      return this.unauthorized(res, 'Unauthenticated');
+    }
+  }
+
+  /**
+   * POST /auth/refresh
+   * Body: { refresh_token }
+   */
+  async refresh(req, res) {
+    const { refresh_token } = await this.validate(req, {
+      refresh_token: 'required|string',
+    });
+
+    // Verify the refresh token
+    let payload;
+    try {
+      payload = Auth.verify(refresh_token);
+    } catch {
+      return this.unauthorized(res, 'Invalid or expired refresh token');
+    }
+
+    const user = await Auth.user({ headers: { authorization: `Bearer ${refresh_token}` } });
+    if (!user) return this.unauthorized(res, 'User not found');
+
+    const newToken        = Auth.issueToken(user);
+    const newRefreshToken = Auth.issueToken(user, { expiresIn: '30d' });
+
+    return this.ok(res, {
+      token:         newToken,
+      refresh_token: newRefreshToken,
+    });
+  }
+
+  /**
+   * POST /auth/forgot-password
+   * Body: { email }
+   */
+  async forgotPassword(req, res) {
+    const { email } = await this.validate(req, {
+      email: 'required|email',
+    });
+
+    // Always return 200 to prevent email enumeration
+    try {
+      const user = await Auth.user({ headers: {} });
+      if (user) {
+        const resetToken = Auth.generateResetToken(user);
+        // Phase 8: Mail.send({ to: email, template: 'password-reset', data: { resetToken } })
+        // For now, return token in dev mode only
+        if (process.env.APP_ENV !== 'production') {
+          return this.ok(res, {
+            message:     'Reset link sent (dev mode — token exposed)',
+            reset_token: resetToken,
+          });
+        }
+      }
+    } catch { /* silent */ }
+
+    return this.ok(res, {
+      message: 'If that email exists, a reset link has been sent.',
+    });
+  }
+
+  /**
+   * POST /auth/reset-password
+   * Body: { token, password }
+   */
+  async resetPassword(req, res) {
+    const { token, password } = await this.validate(req, {
+      token:    'required|string',
+      password: 'required|string|min:8',
+    });
+
+    const payload = Auth.verifyResetToken(token);
+    const user    = await Auth.user({
+      headers: { authorization: `Bearer ${token}` },
+    });
+
+    if (!user || user.email !== payload.email) {
+      return this.badRequest(res, 'Invalid reset token');
+    }
+
+    const hashed = await Auth.hashPassword(password);
+    await user.update({ password: hashed });
+
+    return this.ok(res, { message: 'Password reset successfully' });
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  _safeUser(user) {
+    if (!user) return null;
+    const obj = user.toJSON ? user.toJSON() : { ...user };
+    delete obj.password;
+    delete obj.remember_token;
+    return obj;
+  }
+}
+
+module.exports = AuthController;

package/src/auth/AuthMiddleware.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const Middleware = require('../middleware/Middleware');
+const HttpError  = require('../errors/HttpError');
+const Auth       = require('./Auth');
+
+/**
+ * AuthMiddleware
+ *
+ * Guards routes from unauthenticated access using JWT.
+ *
+ * Reads the Bearer token from the Authorization header,
+ * verifies it, loads the user from the database,
+ * and attaches them to req.user.
+ *
+ * Throws 401 if:
+ *   - No Authorization header
+ *   - Token is malformed / expired
+ *   - User no longer exists in DB
+ *
+ * Register in bootstrap/app.js:
+ *   app.middleware('auth', AuthMiddleware)
+ *
+ * Apply to routes:
+ *   Route.prefix('/api').middleware(['auth']).group(() => { ... })
+ */
+class AuthMiddleware extends Middleware {
+  async handle(req, res, next) {
+    const header = req.headers['authorization'];
+
+    if (!header) {
+      throw new HttpError(401, 'Authorization header missing');
+    }
+
+    if (!header.startsWith('Bearer ')) {
+      throw new HttpError(401, 'Invalid authorization format. Use: Bearer <token>');
+    }
+
+    const token = header.slice(7);
+    if (!token) {
+      throw new HttpError(401, 'Token is empty');
+    }
+
+    // Verify token — throws 401 if expired or invalid
+    const payload = Auth.verify(token);
+
+    // Load user from DB
+    let user;
+    try {
+      user = await Auth.user(req);
+    } catch {
+      throw new HttpError(401, 'Authentication service not configured');
+    }
+    if (!user) {
+      throw new HttpError(401, 'User not found or has been deleted');
+    }
+
+    // Attach to request
+    req.user     = user;
+    req.token    = token;
+    req.tokenPayload = payload;
+
+    next();
+  }
+}
+
+module.exports = AuthMiddleware;

package/src/auth/Hasher.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const bcrypt = require('bcryptjs');
+
+/**
+ * Hasher
+ *
+ * Wraps bcrypt for password hashing and verification.
+ *
+ * Usage:
+ *   const hash = await Hasher.make('my-password');
+ *   const ok   = await Hasher.check('my-password', hash);
+ */
+class Hasher {
+  constructor(rounds = 12) {
+    this.rounds = rounds;
+  }
+
+  /**
+   * Hash a plain-text password.
+   * @param {string} plain
+   * @returns {Promise<string>}
+   */
+  async make(plain) {
+    return bcrypt.hash(String(plain), this.rounds);
+  }
+
+  /**
+   * Verify a plain-text password against a hash.
+   * @param {string} plain
+   * @param {string} hash
+   * @returns {Promise<boolean>}
+   */
+  async check(plain, hash) {
+    if (!plain || !hash) return false;
+    return bcrypt.compare(String(plain), String(hash));
+  }
+
+  /**
+   * Determine if a value needs to be re-hashed
+   * (e.g. rounds have changed).
+   */
+  needsRehash(hash) {
+    const rounds = bcrypt.getRounds(hash);
+    return rounds !== this.rounds;
+  }
+}
+
+// Singleton with default rounds
+module.exports = new Hasher(12);
+module.exports.Hasher = Hasher;

package/src/auth/JwtDriver.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const jwt = require('jsonwebtoken');
+
+/**
+ * JwtDriver
+ *
+ * Issues and verifies JSON Web Tokens.
+ *
+ * Config (config/auth.js):
+ *   guards: {
+ *     jwt: {
+ *       driver:    'jwt',
+ *       secret:    process.env.APP_KEY,
+ *       expiresIn: '7d',
+ *     }
+ *   }
+ */
+class JwtDriver {
+  constructor(config = {}) {
+    this.secret    = config.secret    || process.env.APP_KEY || 'millas-secret-change-me';
+    this.expiresIn = config.expiresIn || '7d';
+    this.algorithm = config.algorithm || 'HS256';
+  }
+
+  /**
+   * Sign a payload and return a token string.
+   * @param {object} payload  — data to encode (e.g. { id, email, role })
+   * @param {object} options  — override expiresIn etc.
+   */
+  sign(payload, options = {}) {
+    return jwt.sign(payload, this.secret, {
+      algorithm: this.algorithm,
+      expiresIn: options.expiresIn || this.expiresIn,
+      ...options,
+    });
+  }
+
+  /**
+   * Verify a token and return the decoded payload.
+   * Throws if expired or invalid.
+   * @param {string} token
+   * @returns {object} decoded payload
+   */
+  verify(token) {
+    return jwt.verify(token, this.secret, { algorithms: [this.algorithm] });
+  }
+
+  /**
+   * Decode a token WITHOUT verifying the signature.
+   * Useful for inspecting expired tokens.
+   * @param {string} token
+   * @returns {object|null}
+   */
+  decode(token) {
+    return jwt.decode(token);
+  }
+
+  /**
+   * Sign a short-lived token for password resets.
+   */
+  signResetToken(payload) {
+    return this.sign(payload, { expiresIn: '1h' });
+  }
+
+  /**
+   * Sign a refresh token with a longer lifetime.
+   */
+  signRefreshToken(payload) {
+    return this.sign(payload, { expiresIn: '30d' });
+  }
+}
+
+module.exports = JwtDriver;

package/src/auth/RoleMiddleware.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const Middleware = require('../middleware/Middleware');
+const HttpError  = require('../errors/HttpError');
+
+/**
+ * RoleMiddleware
+ *
+ * Restricts route access to users with specific roles.
+ * Must be used AFTER AuthMiddleware (requires req.user).
+ *
+ * Usage:
+ *   middlewareRegistry.register('admin', new RoleMiddleware(['admin']));
+ *   middlewareRegistry.register('staff', new RoleMiddleware(['admin', 'staff']));
+ *
+ *   Route.prefix('/admin').middleware(['auth', 'admin']).group(() => { ... });
+ */
+class RoleMiddleware extends Middleware {
+  /**
+   * @param {string[]} roles — list of allowed role values
+   */
+  constructor(roles = []) {
+    super();
+    this.roles = Array.isArray(roles) ? roles : [roles];
+  }
+
+  async handle(req, res, next) {
+    if (!req.user) {
+      throw new HttpError(401, 'Unauthenticated — run AuthMiddleware before RoleMiddleware');
+    }
+
+    const userRole = req.user.role || null;
+
+    if (!userRole || !this.roles.includes(userRole)) {
+      throw new HttpError(403,
+        `Access denied. Required role: ${this.roles.join(' or ')}`
+      );
+    }
+
+    next();
+  }
+}
+
+module.exports = RoleMiddleware;

package/src/cache/Cache.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const MemoryDriver = require('./drivers/MemoryDriver');
+
+/**
+ * Cache
+ *
+ * The primary caching facade.
+ *
+ * Usage:
+ *   const { Cache } = require('millas/src');
+ *
+ *   await Cache.set('user:1', user, 300);         // cache for 5 minutes
+ *   const user = await Cache.get('user:1');        // retrieve
+ *   await Cache.delete('user:1');
+ *
+ *   // remember() — get or compute
+ *   const posts = await Cache.remember('posts:all', 60, async () => {
+ *     return Post.all();
+ *   });
+ *
+ *   // Tags — group related keys
+ *   await Cache.tags('users').set('user:1', user, 300);
+ *   await Cache.tags('users').flush();  // clear all user keys
+ */
+class Cache {
+  constructor() {
+    this._driver = null;
+    this._config = null;
+    this._prefix = '';
+  }
+
+  // ─── Configuration ─────────────────────────────────────────────────────────
+
+  configure(config) {
+    this._config = config;
+    this._prefix = config.prefix || '';
+    this._driver = null; // reset so driver is rebuilt
+  }
+
+  // ─── Core API ──────────────────────────────────────────────────────────────
+
+  /**
+   * Store a value in the cache.
+   * @param {string} key
+   * @param {*}      value   — must be JSON-serialisable
+   * @param {number} ttl     — seconds (0 = forever)
+   */
+  async set(key, value, ttl = 0) {
+    return this._getDriver().set(this._k(key), value, ttl);
+  }
+
+  /**
+   * Retrieve a value. Returns null if missing or expired.
+   */
+  async get(key, defaultValue = null) {
+    const val = await this._getDriver().get(this._k(key));
+    return val !== null ? val : defaultValue;
+  }
+
+  /**
+   * Check if a key exists and is not expired.
+   */
+  async has(key) {
+    return this._getDriver().has(this._k(key));
+  }
+
+  /**
+   * Delete a key.
+   */
+  async delete(key) {
+    return this._getDriver().delete(this._k(key));
+  }
+
+  /**
+   * Delete all keys matching a prefix pattern.
+   */
+  async deletePattern(prefix) {
+    return this._getDriver().deletePattern(this._k(prefix));
+  }
+
+  /**
+   * Flush the entire cache.
+   */
+  async flush() {
+    return this._getDriver().flush();
+  }
+
+  /**
+   * Get or compute and cache.
+   *
+   * const data = await Cache.remember('key', 300, () => fetchExpensiveData());
+   */
+  async remember(key, ttl, fn) {
+    return this._getDriver().remember(this._k(key), ttl, fn);
+  }
+
+  /**
+   * Get once and delete — useful for flash messages / one-time tokens.
+   */
+  async pull(key) {
+    const value = await this.get(key);
+    if (value !== null) await this.delete(key);
+    return value;
+  }
+
+  /**
+   * Increment a numeric value.
+   */
+  async increment(key, amount = 1) {
+    return this._getDriver().increment(this._k(key), amount);
+  }
+
+  /**
+   * Decrement a numeric value.
+   */
+  async decrement(key, amount = 1) {
+    return this._getDriver().decrement(this._k(key), amount);
+  }
+
+  /**
+   * Add only if key does not exist. Returns true if stored, false if skipped.
+   */
+  async add(key, value, ttl = 0) {
+    return this._getDriver().add(this._k(key), value, ttl);
+  }
+
+  /**
+   * Retrieve multiple keys at once.
+   * Returns { key: value|null, ... }
+   */
+  async getMany(keys) {
+    return this._getDriver().getMany(keys.map(k => this._k(k)));
+  }
+
+  /**
+   * Set multiple key/value pairs at once.
+   */
+  async setMany(entries, ttl = 0) {
+    const prefixed = Object.fromEntries(
+      Object.entries(entries).map(([k, v]) => [this._k(k), v])
+    );
+    return this._getDriver().setMany(prefixed, ttl);
+  }
+
+  /**
+   * Cache with tag grouping — lets you flush groups of related keys.
+   *
+   * await Cache.tags('users').set('user:1', user, 300);
+   * await Cache.tags('users', 'posts').flush(); // flush all tagged keys
+   */
+  tags(...tagNames) {
+    return new TaggedCache(this, tagNames.flat());
+  }
+
+  /**
+   * Return the underlying driver instance.
+   */
+  driver() {
+    return this._getDriver();
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  _k(key) {
+    return this._prefix ? `${this._prefix}:${key}` : String(key);
+  }
+
+  _getDriver() {
+    if (this._driver) return this._driver;
+
+    const name = this._config?.default || process.env.CACHE_DRIVER || 'memory';
+    const conf = this._config?.drivers?.[name] || {};
+
+    switch (name) {
+      case 'file': {
+        const FileDriver = require('./drivers/FileDriver');
+        this._driver = new FileDriver(conf);
+        break;
+      }
+      case 'null': {
+        const NullDriver = require('./drivers/NullDriver');
+        this._driver = new NullDriver();
+        break;
+      }
+      case 'memory':
+      default:
+        this._driver = new MemoryDriver();
+    }
+
+    return this._driver;
+  }
+}
+
+// ── TaggedCache ───────────────────────────────────────────────────────────────
+
+/**
+ * TaggedCache
+ *
+ * Wraps a Cache instance and prefixes every key with a tag namespace.
+ * Flush all keys for a tag group with .flush().
+ */
+class TaggedCache {
+  constructor(cache, tags) {
+    this._cache  = cache;
+    this._tags   = tags;
+    this._prefix = tags.join(':');
+  }
+
+  _k(key) { return `tag:${this._prefix}:${key}`; }
+
+  async set(key, value, ttl = 0) { return this._cache.set(this._k(key), value, ttl); }
+  async get(key, def = null)     { return this._cache.get(this._k(key), def); }
+  async has(key)                 { return this._cache.has(this._k(key)); }
+  async delete(key)              { return this._cache.delete(this._k(key)); }
+  async remember(key, ttl, fn)   { return this._cache.remember(this._k(key), ttl, fn); }
+  async pull(key)                { return this._cache.pull(this._k(key)); }
+
+  /**
+   * Flush all keys belonging to these tags.
+   */
+  async flush() {
+    return this._cache.deletePattern(`tag:${this._prefix}:`);
+  }
+}
+
+// Singleton
+const cache = new Cache();
+module.exports = cache;
+module.exports.Cache       = Cache;
+module.exports.TaggedCache = TaggedCache;