millas 0.1.0

package/src/mail/drivers/MailgunDriver.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * MailgunDriver
+ *
+ * Sends mail via the Mailgun API v3.
+ * No extra npm package needed.
+ *
+ * Config (config/mail.js):
+ *   drivers: {
+ *     mailgun: {
+ *       key:    process.env.MAILGUN_API_KEY,
+ *       domain: process.env.MAILGUN_DOMAIN,
+ *       region: 'us',   // 'us' | 'eu'
+ *     }
+ *   }
+ */
+class MailgunDriver {
+  constructor(config = {}) {
+    this._key    = config.key    || process.env.MAILGUN_API_KEY;
+    this._domain = config.domain || process.env.MAILGUN_DOMAIN;
+    this._region = config.region || 'us';
+
+    if (!this._key)    throw new Error('MailgunDriver: API key is required');
+    if (!this._domain) throw new Error('MailgunDriver: domain is required');
+  }
+
+  async send(message) {
+    const params = new URLSearchParams();
+
+    const toStr = [].concat(message.to).join(', ');
+    params.append('from',    message.from);
+    params.append('to',      toStr);
+    params.append('subject', message.subject);
+
+    if (message.cc)   params.append('cc',  [].concat(message.cc).join(', '));
+    if (message.bcc)  params.append('bcc', [].concat(message.bcc).join(', '));
+    if (message.html) params.append('html', message.html);
+    if (message.text) params.append('text', message.text);
+
+    const host = this._region === 'eu'
+      ? 'api.eu.mailgun.net'
+      : 'api.mailgun.net';
+
+    return this._post(host, `/v3/${this._domain}/messages`, params.toString());
+  }
+
+  _post(host, path, body) {
+    return new Promise((resolve, reject) => {
+      const https = require('https');
+      const auth  = Buffer.from(`api:${this._key}`).toString('base64');
+
+      const options = {
+        hostname: host,
+        port:     443,
+        path,
+        method:   'POST',
+        headers:  {
+          'Authorization': `Basic ${auth}`,
+          'Content-Type':  'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(body),
+        },
+      };
+
+      const req = https.request(options, (res) => {
+        let raw = '';
+        res.on('data', c => raw += c);
+        res.on('end',  () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve(JSON.parse(raw || '{}'));
+          } else {
+            reject(new Error(`Mailgun error ${res.statusCode}: ${raw}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = MailgunDriver;

package/src/mail/drivers/SendGridDriver.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * SendGridDriver
+ *
+ * Sends mail via the SendGrid Web API v3.
+ * Does not require any extra npm package — uses the built-in https module.
+ *
+ * Config (config/mail.js):
+ *   drivers: {
+ *     sendgrid: {
+ *       key: process.env.SENDGRID_API_KEY,
+ *     }
+ *   }
+ */
+class SendGridDriver {
+  constructor(config = {}) {
+    this._apiKey = config.key || process.env.SENDGRID_API_KEY;
+    if (!this._apiKey) {
+      throw new Error('SendGridDriver: API key is required (config/mail.js → drivers.sendgrid.key)');
+    }
+  }
+
+  async send(message) {
+    const payload = {
+      personalizations: [{
+        to:  this._toRecipients(message.to),
+        cc:  message.cc  ? this._toRecipients(message.cc)  : undefined,
+        bcc: message.bcc ? this._toRecipients(message.bcc) : undefined,
+        subject: message.subject,
+      }],
+      from:     this._parseAddress(message.from),
+      reply_to: message.replyTo ? this._parseAddress(message.replyTo) : undefined,
+      content: [
+        ...(message.text ? [{ type: 'text/plain', value: message.text }] : []),
+        ...(message.html ? [{ type: 'text/html',  value: message.html }] : []),
+      ],
+      attachments: message.attachments
+        ? message.attachments.map(a => ({
+            content:  Buffer.isBuffer(a.content)
+              ? a.content.toString('base64')
+              : Buffer.from(a.content || '').toString('base64'),
+            filename: a.filename,
+            type:     a.contentType,
+          }))
+        : undefined,
+    };
+
+    return this._post('/v3/mail/send', payload);
+  }
+
+  async _post(path, body) {
+    return new Promise((resolve, reject) => {
+      const https   = require('https');
+      const data    = JSON.stringify(body);
+      const options = {
+        hostname: 'api.sendgrid.com',
+        port:     443,
+        path,
+        method:   'POST',
+        headers:  {
+          'Authorization': `Bearer ${this._apiKey}`,
+          'Content-Type':  'application/json',
+          'Content-Length': Buffer.byteLength(data),
+        },
+      };
+
+      const req = https.request(options, (res) => {
+        let raw = '';
+        res.on('data', chunk => raw += chunk);
+        res.on('end',  () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({ statusCode: res.statusCode });
+          } else {
+            reject(new Error(`SendGrid API error ${res.statusCode}: ${raw}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.write(data);
+      req.end();
+    });
+  }
+
+  _toRecipients(addresses) {
+    return [].concat(addresses).map(a => this._parseAddress(a));
+  }
+
+  _parseAddress(address) {
+    const match = String(address).match(/^(.+?)\s*<(.+?)>$/);
+    if (match) return { name: match[1].trim(), email: match[2].trim() };
+    return { email: address };
+  }
+}
+
+module.exports = SendGridDriver;

package/src/mail/drivers/SmtpDriver.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * SmtpDriver
+ *
+ * Sends mail via SMTP using nodemailer.
+ *
+ * Config (config/mail.js):
+ *   drivers: {
+ *     smtp: {
+ *       host:       'smtp.mailtrap.io',
+ *       port:       2525,
+ *       username:   'user',
+ *       password:   'pass',
+ *       encryption: 'tls',   // 'tls' | 'ssl' | false
+ *     }
+ *   }
+ */
+class SmtpDriver {
+  constructor(config = {}) {
+    this._config    = config;
+    this._transport = null;
+  }
+
+  async send(message) {
+    const transport = this._getTransport();
+    return transport.sendMail(this._toNodemailer(message));
+  }
+
+  _getTransport() {
+    if (this._transport) return this._transport;
+
+    const nodemailer = require('nodemailer');
+    const cfg        = this._config;
+
+    const secure = cfg.encryption === 'ssl';
+    const tls    = cfg.encryption === 'tls' ? { rejectUnauthorized: false } : undefined;
+
+    this._transport = nodemailer.createTransport({
+      host:   cfg.host     || 'localhost',
+      port:   cfg.port     || 587,
+      secure,
+      auth:   cfg.username ? { user: cfg.username, pass: cfg.password } : undefined,
+      tls,
+    });
+
+    return this._transport;
+  }
+
+  _toNodemailer(msg) {
+    return {
+      from:        msg.from,
+      to:          Array.isArray(msg.to)  ? msg.to.join(', ')  : msg.to,
+      cc:          Array.isArray(msg.cc)  ? msg.cc.join(', ')  : msg.cc,
+      bcc:         Array.isArray(msg.bcc) ? msg.bcc.join(', ') : msg.bcc,
+      replyTo:     msg.replyTo,
+      subject:     msg.subject,
+      html:        msg.html,
+      text:        msg.text,
+      attachments: msg.attachments,
+      headers:     msg.headers,
+      priority:    msg.priority,
+    };
+  }
+}
+
+module.exports = SmtpDriver;

package/src/mail/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const Mail           = require('./Mail');
+const MailMessage    = require('./MailMessage');
+const TemplateEngine = require('./TemplateEngine');
+const SmtpDriver     = require('./drivers/SmtpDriver');
+const SendGridDriver = require('./drivers/SendGridDriver');
+const MailgunDriver  = require('./drivers/MailgunDriver');
+const LogDriver      = require('./drivers/LogDriver');
+
+module.exports = {
+  Mail,
+  MailMessage,
+  TemplateEngine,
+  SmtpDriver,
+  SendGridDriver,
+  MailgunDriver,
+  LogDriver,
+};

package/src/middleware/AuthMiddleware.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const Middleware = require('./Middleware');
+const HttpError  = require('../errors/HttpError');
+
+/**
+ * AuthMiddleware
+ *
+ * Guards routes from unauthenticated access.
+ * Full JWT/session implementation unlocked in Phase 7.
+ *
+ * For now: checks for presence of Authorization header.
+ * Replace the verify() method with real token logic in Phase 7.
+ *
+ * Register:
+ *   middlewareRegistry.register('auth', AuthMiddleware);
+ *
+ * Apply:
+ *   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, 'No authorization token provided');
+    }
+
+    const [scheme, token] = header.split(' ');
+
+    if (scheme !== 'Bearer' || !token) {
+      throw new HttpError(401, 'Invalid authorization format. Use: Bearer <token>');
+    }
+
+    // Phase 7 will replace this with real JWT verification:
+    // const user = await Auth.verifyToken(token);
+    // req.user = user;
+
+    // For now: attach a stub user so downstream handlers don't break
+    req.user = { id: null, token, authenticated: false, _stub: true };
+
+    next();
+  }
+}
+
+module.exports = AuthMiddleware;

package/src/middleware/CorsMiddleware.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const Middleware = require('./Middleware');
+
+/**
+ * CorsMiddleware
+ *
+ * Adds Cross-Origin Resource Sharing headers to every response.
+ *
+ * Register:
+ *   middlewareRegistry.register('cors', CorsMiddleware);
+ *
+ * Configure in bootstrap/app.js:
+ *   new CorsMiddleware({
+ *     origins: ['https://myapp.com'],
+ *     methods: ['GET', 'POST'],
+ *   })
+ *
+ * Or register the class directly for default permissive settings.
+ */
+class CorsMiddleware extends Middleware {
+  constructor(options = {}) {
+    super();
+    this.origins     = options.origins     || ['*'];
+    this.methods     = options.methods     || ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+    this.headers     = options.headers     || ['Content-Type', 'Authorization', 'X-Requested-With'];
+    this.credentials = options.credentials ?? false;
+    this.maxAge      = options.maxAge      || 86400;
+  }
+
+  async handle(req, res, next) {
+    const origin = req.headers.origin;
+
+    // Origin matching
+    if (this.origins.includes('*')) {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+    } else if (origin && this.origins.includes(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
+
+    res.setHeader('Access-Control-Allow-Methods', this.methods.join(', '));
+    res.setHeader('Access-Control-Allow-Headers', this.headers.join(', '));
+    res.setHeader('Access-Control-Max-Age', String(this.maxAge));
+
+    if (this.credentials) {
+      res.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+
+    // Handle preflight
+    if (req.method === 'OPTIONS') {
+      return res.status(204).send();
+    }
+
+    next();
+  }
+}
+
+module.exports = CorsMiddleware;

package/src/middleware/LogMiddleware.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const Middleware = require('./Middleware');
+
+/**
+ * LogMiddleware
+ *
+ * Logs every incoming request and its response time.
+ *
+ * Output format:
+ *   [2026-03-14 12:00:00] GET /api/users 200 12ms
+ *
+ * Register:
+ *   middlewareRegistry.register('log', LogMiddleware);
+ *
+ * Options:
+ *   silent  — suppress output (default: false)
+ *   format  — 'dev' (coloured) | 'combined' (plain)
+ */
+class LogMiddleware extends Middleware {
+  constructor(options = {}) {
+    super();
+    this.silent = options.silent || false;
+    this.format = options.format || 'dev';
+  }
+
+  async handle(req, res, next) {
+    if (this.silent) return next();
+
+    const start = Date.now();
+    const { method, path: routePath, url } = req;
+
+    res.on('finish', () => {
+      const ms     = Date.now() - start;
+      const status = res.statusCode;
+      const ts     = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+      if (this.format === 'dev') {
+        const statusColor = status < 300 ? '\x1b[32m'
+          : status < 400 ? '\x1b[36m'
+          : status < 500 ? '\x1b[33m'
+          : '\x1b[31m';
+        const reset = '\x1b[0m';
+        const methodColor = '\x1b[1m';
+        console.log(
+          `  ${'\x1b[90m'}[${ts}]${reset} ` +
+          `${methodColor}${method.padEnd(7)}${reset} ` +
+          `${routePath || url} ` +
+          `${statusColor}${status}${reset} ` +
+          `${'\x1b[90m'}${ms}ms${reset}`
+        );
+      } else {
+        console.log(`[${ts}] ${method} ${routePath || url} ${status} ${ms}ms`);
+      }
+    });
+
+    next();
+  }
+}
+
+module.exports = LogMiddleware;

package/src/middleware/Middleware.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Middleware
+ *
+ * Base class for all Millas middleware.
+ * Subclasses must implement handle(req, res, next).
+ *
+ * Usage:
+ *   class AuthMiddleware extends Middleware {
+ *     async handle(req, res, next) {
+ *       // ...
+ *       next();
+ *     }
+ *   }
+ */
+class Middleware {
+  /**
+   * Handle the incoming request.
+   *
+   * @param {import('express').Request}  req
+   * @param {import('express').Response} res
+   * @param {Function}                   next
+   */
+  async handle(req, res, next) {
+    throw new Error(`${this.constructor.name} must implement handle(req, res, next)`);
+  }
+
+  /**
+   * Called after the response is sent.
+   * Override for cleanup, logging, etc.
+   */
+  async terminate(req, res) {}
+}
+
+module.exports = Middleware;

package/src/middleware/MiddlewarePipeline.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * MiddlewarePipeline
+ *
+ * Composes an ordered list of middleware handlers into a single
+ * Express-compatible function. Used internally by the Router.
+ *
+ * Each handler can be:
+ *   - A Middleware subclass (instantiated automatically)
+ *   - An already-instantiated Middleware object
+ *   - A raw Express function (req, res, next) => {}
+ *
+ * Usage (internal):
+ *   const pipeline = new MiddlewarePipeline([AuthMiddleware, LogMiddleware]);
+ *   app.use(pipeline.compose());
+ */
+class MiddlewarePipeline {
+  constructor(handlers = []) {
+    this._handlers = handlers;
+  }
+
+  /**
+   * Add a handler to the end of the pipeline.
+   */
+  pipe(handler) {
+    this._handlers.push(handler);
+    return this;
+  }
+
+  /**
+   * Add a handler to the beginning of the pipeline.
+   */
+  prepend(handler) {
+    this._handlers.unshift(handler);
+    return this;
+  }
+
+  /**
+   * Compose all handlers into a single (req, res, next) function.
+   */
+  compose() {
+    const fns = this._handlers.map(h => this._resolve(h));
+
+    return function pipeline(req, res, next) {
+      let index = 0;
+
+      function dispatch(i) {
+        if (i >= fns.length) return next();
+        const fn = fns[i];
+
+        try {
+          const result = fn(req, res, (err) => {
+            if (err) return next(err);
+            dispatch(i + 1);
+          });
+          // Handle async middleware that returns a Promise
+          if (result && typeof result.catch === 'function') {
+            result.catch(next);
+          }
+        } catch (err) {
+          next(err);
+        }
+      }
+
+      dispatch(0);
+    };
+  }
+
+  /**
+   * Resolve a handler to a plain (req, res, next) => {} function.
+   */
+  _resolve(handler) {
+    // Raw Express function
+    if (typeof handler === 'function' && !(handler.prototype instanceof require('./Middleware'))) {
+      return handler;
+    }
+
+    // Middleware class (not yet instantiated)
+    if (typeof handler === 'function' && handler.prototype instanceof require('./Middleware')) {
+      const instance = new handler();
+      return (req, res, next) => instance.handle(req, res, next);
+    }
+
+    // Instantiated Middleware object
+    if (handler && typeof handler.handle === 'function') {
+      return (req, res, next) => handler.handle(req, res, next);
+    }
+
+    throw new Error(`Invalid middleware: ${handler}. Must be a Middleware class, instance, or function.`);
+  }
+}
+
+module.exports = MiddlewarePipeline;

package/src/middleware/ThrottleMiddleware.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const Middleware = require('./Middleware');
+
+/**
+ * ThrottleMiddleware
+ *
+ * Simple in-memory rate limiter.
+ * For production use, replace the store with a Redis-backed one (Phase 11).
+ *
+ * Register:
+ *   middlewareRegistry.register('throttle', new ThrottleMiddleware({ max: 60, window: 60 }));
+ *
+ * Options:
+ *   max     — max requests per window (default: 60)
+ *   window  — window in seconds (default: 60)
+ *   keyBy   — function(req) => string, defaults to IP
+ */
+class ThrottleMiddleware extends Middleware {
+  constructor(options = {}) {
+    super();
+    this.max    = options.max    || 60;
+    this.window = options.window || 60;       // seconds
+    this.keyBy  = options.keyBy  || ((req) => req.ip || 'anonymous');
+    this._store = new Map();                   // { key: { count, resetAt } }
+  }
+
+  async handle(req, res, next) {
+    const key   = this.keyBy(req);
+    const now   = Date.now();
+
+    let record = this._store.get(key);
+
+    if (!record || now > record.resetAt) {
+      record = { count: 0, resetAt: now + this.window * 1000 };
+      this._store.set(key, record);
+    }
+
+    record.count++;
+
+    const remaining = Math.max(0, this.max - record.count);
+    const resetIn   = Math.ceil((record.resetAt - now) / 1000);
+
+    res.setHeader('X-RateLimit-Limit',     String(this.max));
+    res.setHeader('X-RateLimit-Remaining', String(remaining));
+    res.setHeader('X-RateLimit-Reset',     String(Math.ceil(record.resetAt / 1000)));
+
+    if (record.count > this.max) {
+      return res.status(429).json({
+        error:   'Too Many Requests',
+        message: `Rate limit exceeded. Try again in ${resetIn}s.`,
+        status:  429,
+        retryAfter: resetIn,
+      });
+    }
+
+    next();
+  }
+}
+
+module.exports = ThrottleMiddleware;