millas 0.2.13 → 0.2.14

package/src/http/RequestContext.js

@@ -38,11 +38,11 @@
  *     return jsonify(await User.update(params.id, body));
  *   })
  *
- *   // Inline validation on body
+ *   // Inline validation on body — use typed validators from millas/core/validation
  *   Route.post('/posts', async ({ body }) => {
  *     const data = await body.validate({
- *       title:   'required|string|max:255',
- *       content: 'required|string',
+ *       title:   string().required().max(255),
+ *       content: string().required(),
  *     });
  *     return jsonify(await Post.create(data));
  *   })
@@ -129,12 +129,16 @@ class RequestContext {
 
   /**
    * Build the body object with an attached .validate() method.
-   * This keeps validation ergonomic and co-located with the body itself:
+   *
+   *   const { string, email } = require('millas/core/validation');
    *
    *   const data = await body.validate({
-   *     name:  'required|string|max:100',
-   *     email: 'required|email',
+   *     name:  string().required().max(100),
+   *     email: email().required(),
    *   });
+   *
+   * When a route has .shape({ in: {...} }), validation already ran before
+   * the handler — body is pre-validated and body.validate() is not needed.
    */
   _buildBody(rawBody, millaReq) {
     // Start with the raw body data
@@ -173,4 +177,4 @@ class RequestContext {
   }
 }
 
-module.exports = RequestContext;
+module.exports = RequestContext;

package/src/http/SecurityBootstrap.js

@@ -19,8 +19,29 @@ class SecurityBootstrap {
       app.use(globalRateLimit.middleware());
     }
 
+    // ── CSRF ──────────────────────────────────────────────────────────────────
+    // The admin panel (/admin) manages its own CSRF via AdminAuth.
+    // Auto-exclude it so the framework CSRF doesn't double-protect it.
     if (config.csrf !== false) {
-      app.use(CsrfMiddleware.from(config.csrf || {}).middleware());
+      const csrfConfig  = config.csrf || {};
+      const adminPrefix = config.adminPrefix || '/admin';
+      const docsPrefix  = config.docsPrefix  || '/docs';
+      const excluded    = [...(csrfConfig.exclude || [])];
+
+      // Auto-exclude the admin panel — it manages its own CSRF via AdminAuth
+      if (!excluded.some(p => p === adminPrefix || p.startsWith(adminPrefix + '/'))) {
+        excluded.push(adminPrefix + '/');
+      }
+
+      // Auto-exclude the docs internal API — /_api/try is a dev-time proxy,
+      // not a state-changing endpoint on user data. It is already protected by
+      // the docs.enabled flag (off in production by default).
+      const docsApiPrefix = docsPrefix + '/_api/';
+      if (!excluded.some(p => p === docsApiPrefix || docsApiPrefix.startsWith(p))) {
+        excluded.push(docsApiPrefix);
+      }
+
+      app.use(CsrfMiddleware.from({ ...csrfConfig, exclude: excluded }).middleware());
     }
 
     SecurityBootstrap._registerErrorHandler(app);
@@ -30,7 +51,7 @@ class SecurityBootstrap {
       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');
+      console.log('  ✓ CSRF:              ', config.csrf === false ? 'DISABLED' : `enabled (excluding: ${adminPrefix}/, ${docsPrefix}/_api/)`);
     }
   }
 
@@ -51,6 +72,7 @@ class SecurityBootstrap {
       next(err);
     });
   }
+
   static loadConfig(configPath) {
     const path = require('path');
     const fs   = require('fs');

package/src/http/Shape.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * Shape — route input/output contract
+ *
+ * A shape defines what a route accepts and what it returns.
+ * It serves two purposes simultaneously — zero duplication:
+ *
+ *   1. Runtime validation middleware
+ *      When a route has .shape() or .fromShape(), the framework validates
+ *      incoming data BEFORE the handler runs. Bad requests are rejected
+ *      with 422 automatically — the handler only runs with clean data.
+ *
+ *   2. API docs generation
+ *      The docs panel reads the shape to render the body schema, query
+ *      params, expected responses, and "Try it" form — no separate
+ *      ApiResource declaration needed.
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const { shape }  = require('millas/core/http');
+ *   const { string, number, email, boolean, array } = require('millas/core/validation');
+ *
+ *   // Inline on a route:
+ *   Route.post('/properties', PropertyController, 'store')
+ *     .shape({
+ *       label: 'Create property',
+ *       group: 'Properties & Units',
+ *       in: {
+ *         name: string().required().max(200).example('Sunset Apartments'),
+ *         city: string().required().example('Nairobi'),
+ *         type: string().required().oneOf(['apartment','house','commercial']),
+ *       },
+ *       out: {
+ *         201: { id: 1, name: 'Sunset Apartments' },
+ *         422: { message: 'Validation failed', errors: {} },
+ *       },
+ *     });
+ *
+ *   // From a shared shape file:
+ *   Route.post('/properties', PropertyController, 'store')
+ *     .fromShape(CreatePropertyShape);
+ *
+ * ── Shape file convention ─────────────────────────────────────────────────────
+ *
+ *   Scaffold with:  millas make:shape PropertyShape
+ *   Outputs to:     app/shapes/PropertyShape.js
+ *
+ *   const { shape }  = require('millas/core/http');
+ *   const { string, number, array } = require('millas/core/validation');
+ *
+ *   const CreatePropertyShape = shape({
+ *     label: 'Create property',
+ *     group: 'Properties & Units',
+ *     in: {
+ *       name: string().required().max(200).example('Sunset Apartments'),
+ *       city: string().required().example('Nairobi'),
+ *     },
+ *     out: { 201: { id: 1 } },
+ *   });
+ *
+ *   const UpdatePropertyShape = shape({
+ *     label: 'Update property',
+ *     group: 'Properties & Units',
+ *     in: {
+ *       name: string().optional().max(200),
+ *       city: string().optional(),
+ *     },
+ *     out: { 200: { id: 1 } },
+ *   });
+ *
+ *   module.exports = { CreatePropertyShape, UpdatePropertyShape };
+ *
+ * ── Handler access ────────────────────────────────────────────────────────────
+ *
+ *   The handler receives clean, coerced data via the normal context keys:
+ *
+ *     async store({ body, user }) {
+ *       // body is already validated and coerced — guaranteed clean
+ *       return this.created(await Property.create(body));
+ *     }
+ *
+ *   If validation fails the handler never runs — 422 is returned immediately.
+ */
+
+'use strict';
+
+const { BaseValidator } = require('../validation/BaseValidator');
+
+const SHAPE_BRAND = Symbol('MillasShape');
+
+/**
+ * shape(def) — create a sealed, validated shape definition.
+ *
+ * Validates the definition at module load time so mistakes surface
+ * immediately, not at request time.
+ *
+ * @param {object} def
+ * @returns {ShapeDefinition}
+ */
+function shape(def) {
+  if (!def || typeof def !== 'object') {
+    throw new Error('[shape] shape() requires a definition object.');
+  }
+
+  // Dev-time validation of the "in" schema
+  if (def.in) {
+    if (typeof def.in !== 'object' || Array.isArray(def.in)) {
+      throw new Error('[shape] "in" must be a plain object of field validators.');
+    }
+    for (const [field, v] of Object.entries(def.in)) {
+      if (!(v instanceof BaseValidator)) {
+        throw new Error(
+          `[shape] Field "${field}" in "in" must be a validator instance.\n` +
+          `  Use: string(), number(), email(), boolean(), array(), date(), file()\n` +
+          `  from millas/core/validation.\n` +
+          `  Got: ${typeof v}`
+        );
+      }
+    }
+  }
+
+  // Dev-time validation of the "query" schema
+  if (def.query) {
+    for (const [field, v] of Object.entries(def.query)) {
+      if (!(v instanceof BaseValidator)) {
+        throw new Error(
+          `[shape] Field "${field}" in "query" must be a validator instance. Got: ${typeof v}`
+        );
+      }
+    }
+  }
+
+  // Dev-time validation of "out"
+  if (def.out) {
+    for (const [status] of Object.entries(def.out)) {
+      if (isNaN(Number(status))) {
+        throw new Error(
+          `[shape] Keys in "out" must be HTTP status codes (numbers). Got: "${status}"`
+        );
+      }
+    }
+  }
+
+  const built = {
+    [SHAPE_BRAND]: true,
+    label:       def.label       || null,
+    group:       def.group       || null,
+    icon:        def.icon        || null,
+    description: def.description || null,
+    encoding:    def.encoding    || 'json',     // 'json' | 'form' | 'multipart'
+    in:          Object.freeze(def.in    || {}),
+    query:       Object.freeze(def.query || {}),
+    out:         Object.freeze(def.out   || {}),
+  };
+
+  return Object.freeze(built);
+}
+
+/**
+ * Returns true if the value is a shape definition built by shape().
+ * @param {*} val
+ */
+function isShape(val) {
+  return val && typeof val === 'object' && val[SHAPE_BRAND] === true;
+}
+
+module.exports = { shape, isShape, SHAPE_BRAND };

package/src/http/adapters/ExpressAdapter.js

@@ -167,11 +167,15 @@ class ExpressAdapter extends HttpAdapter {
         // Status
         expressRes.status(response.statusCode);
 
-        // CORS headers stored by CorsMiddleware on next() calls
-        const corsHeaders = expressRes.req?._corsHeaders;
-        if (corsHeaders) {
-            for (const [name, value] of Object.entries(corsHeaders)) {
-                expressRes.setHeader(name, value);
+        // Headers stashed by middleware during the request pipeline
+        // (e.g. CorsMiddleware → _corsHeaders, ThrottleMiddleware → _rateLimitHeaders)
+        const corsHeaders      = expressRes.req?._corsHeaders;
+        const rateLimitHeaders = expressRes.req?._rateLimitHeaders;
+        for (const map of [corsHeaders, rateLimitHeaders]) {
+            if (map) {
+                for (const [name, value] of Object.entries(map)) {
+                    expressRes.setHeader(name, value);
+                }
             }
         }
 

package/src/middleware/CorsMiddleware.js

@@ -11,6 +11,7 @@ const MillasResponse = require('../http/MillasResponse');
 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'];
@@ -23,7 +24,9 @@ class CorsMiddleware extends Middleware {
 
     // Build headers map
     const h = {};
+
     if (this.origins.includes('*')) {
+
       h['Access-Control-Allow-Origin'] = '*';
     } else if (origin && this.origins.includes(origin)) {
       h['Access-Control-Allow-Origin'] = origin;

package/src/middleware/ThrottleMiddleware.js

@@ -42,7 +42,7 @@ class ThrottleMiddleware extends Middleware {
     return new ThrottleMiddleware({ max, window: minutes * 60 });
   }
 
-  async handle(req, next) {
+  async handle({ req }, next) {
     const key    = this.keyBy(req);
     const now    = Date.now();
     let   record = this._store.get(key);
@@ -57,12 +57,15 @@ class ThrottleMiddleware extends Middleware {
     const remaining = Math.max(0, this.max - record.count);
     const resetIn   = Math.ceil((record.resetAt - now) / 1000);
 
-    // Rate limit headers — added to whatever response comes back
-    // We set them on the raw Express res since we don't have the final response yet.
-    // These headers will be present on all responses from throttled routes.
-    req.raw.res.setHeader('X-RateLimit-Limit',     String(this.max));
-    req.raw.res.setHeader('X-RateLimit-Remaining', String(remaining));
-    req.raw.res.setHeader('X-RateLimit-Reset',     String(Math.ceil(record.resetAt / 1000)));
+    // Rate limit headers — set on the raw Express res since we don't have
+    // the final MillasResponse yet. Present on all responses from throttled routes.
+    // Stash rate-limit headers on the raw request so ExpressAdapter.dispatch()
+    // can apply them to the final MillasResponse — same pattern as CorsMiddleware.
+    req.raw._rateLimitHeaders = {
+      'X-RateLimit-Limit':     String(this.max),
+      'X-RateLimit-Remaining': String(remaining),
+      'X-RateLimit-Reset':     String(Math.ceil(record.resetAt / 1000)),
+    };
 
     if (record.count > this.max) {
       return jsonify({

package/src/orm/model/Model.js

@@ -198,6 +198,18 @@ class Model {
   /** Define relations: static relations = { author: new BelongsTo(...) } */
   static relations = {};
 
+  /**
+   * Fields always excluded from toJSON() — the universal safety net.
+   * Applied everywhere a model is serialized: API responses, logs, admin.
+   * Individual models extend this list for their own sensitive fields.
+   *
+   *   // In your User model:
+   *   static hidden = ['password', 'remember_token', 'two_factor_secret'];
+   *
+   * Default covers the two fields that should never leak anywhere.
+   */
+  static hidden = ['password', 'remember_token'];
+
   // ─── Lifecycle hooks (override in subclass) ───────────────────────────────
 
   static async beforeCreate(data)    { return data; }
@@ -724,9 +736,10 @@ class Model {
   get isTrashed()   { return !!this.deleted_at; }
 
   toJSON() {
+    const hidden = new Set(this.constructor.hidden || []);
     const obj = {};
     for (const key of Object.keys(this)) {
-      if (!key.startsWith('_') && typeof this[key] !== 'function') {
+      if (!key.startsWith('_') && typeof this[key] !== 'function' && !hidden.has(key)) {
         obj[key] = this[key];
       }
     }

package/src/providers/EncryptionServiceProvider.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const ServiceProvider        = require('./ServiceProvider');
+const { EncrypterManager }   = require('../encryption/Encrypter');
+
+/**
+ * EncryptionServiceProvider
+ *
+ * Registers the Encrypter as a singleton in the DI container.
+ * Reads APP_KEY and (optionally) MILLAS_CIPHER from config or environment.
+ *
+ * ── Registration ──────────────────────────────────────────────────────────────
+ *
+ * Add to bootstrap/app.js:
+ *
+ *   const { EncryptionServiceProvider } = require('millas/providers/EncryptionServiceProvider');
+ *
+ *   app.providers([
+ *     EncryptionServiceProvider,
+ *     // ... other providers
+ *   ]);
+ *
+ * ── Configuration ─────────────────────────────────────────────────────────────
+ *
+ * The provider resolves keys in this order:
+ *
+ *   1. config/app.js  →  { key: '...', cipher: 'AES-256-CBC' }
+ *   2. Environment variables  →  APP_KEY, MILLAS_CIPHER
+ *   3. Defaults  →  cipher: 'AES-256-CBC'
+ *
+ * Example config/app.js:
+ *
+ *   module.exports = {
+ *     key:    process.env.APP_KEY,
+ *     cipher: 'AES-256-CBC',   // optional — default
+ *   };
+ *
+ * ── Key generation ─────────────────────────────────────────────────────────────
+ *
+ * Generate a key for your .env file:
+ *
+ *   const { Encrypter } = require('millas/encryption/Encrypter');
+ *   console.log(Encrypter.generateKey('AES-256-CBC'));
+ *   // → 'base64:...'  ← paste this as APP_KEY=
+ */
+class EncryptionServiceProvider extends ServiceProvider {
+  register(container) {
+    container.singleton('encrypter', () => {
+      const basePath = (() => { try { return container.make('basePath'); } catch { return process.cwd(); } })();
+
+      let appConfig = {};
+      try { appConfig = require(basePath + '/config/app'); } catch { /* no config/app.js */ }
+
+      return new EncrypterManager({
+        key:    appConfig.key    || process.env.APP_KEY    || '',
+        cipher: appConfig.cipher || process.env.MILLAS_CIPHER || 'AES-256-CBC',
+      });
+    });
+
+    // Aliases — 'encrypter', 'Encrypter', and 'crypt' all resolve to the same binding
+    container.alias('Encrypter', 'encrypter');
+    container.alias('crypt',     'encrypter');
+  }
+}
+
+module.exports = EncryptionServiceProvider;

package/src/router/MiddlewareRegistry.js

@@ -3,13 +3,12 @@
 /**
  * MiddlewareRegistry
  *
- * Maps string aliases → middleware handler classes or functions.
+ * Maps string aliases → Millas middleware classes or instances.
+ * Resolution produces adapter-native handler functions via the adapter,
+ * so this class has zero knowledge of Express (or any HTTP engine).
  *
- * Usage:
- *   MiddlewareRegistry.register('auth', AuthMiddleware);
- *   MiddlewareRegistry.register('throttle', ThrottleMiddleware);
- *
- * Registered automatically by AppServiceProvider (Phase 3+).
+ * The adapter is injected at resolution time (not construction time)
+ * so the registry can be built before the adapter exists.
  */
 class MiddlewareRegistry {
   constructor() {
@@ -18,24 +17,31 @@ class MiddlewareRegistry {
 
   /**
    * Register a middleware alias.
-   * @param {string} alias
-   * @param {Function|object} handler  — class with handle() or raw Express fn
+   *
+   *   registry.register('auth',     AuthMiddleware)
+   *   registry.register('throttle', new ThrottleMiddleware({ max: 60 }))
    */
   register(alias, handler) {
     this._map[alias] = handler;
+    return this;
   }
 
   /**
-   * Resolve a single alias to an Express-compatible function.
-   * Supports parameterised aliases: 'throttle:60,1' → 60 req per 1 minute.
+   * Resolve a middleware alias or class/instance into an adapter-native handler.
+   * Supports parameterized aliases: 'throttle:60,1' → 60 req per 1 minute.
    *
-   * @param {string|Function} aliasOrFn
-   * @returns {Function}
+   * @param {string|Function|object} aliasOrFn
+   * @param {import('../http/adapters/HttpAdapter')} adapter
+   * @param {object|null} container
+   * @returns {Function}  adapter-native handler
    */
-  resolve(aliasOrFn) {
-    if (typeof aliasOrFn === 'function') return aliasOrFn;
+  resolve(aliasOrFn, adapter, container = null) {
+    // If it's already a function, pass through
+    if (typeof aliasOrFn === 'function') {
+      return aliasOrFn;
+    }
 
-    // Parse parameterised alias: 'throttle:60,1' → alias='throttle', params=['60','1']
+    // Parse parameterized alias: 'throttle:60,1' → alias='throttle', params=['60','1']
     let alias  = aliasOrFn;
     let params = [];
     if (typeof aliasOrFn === 'string' && aliasOrFn.includes(':')) {
@@ -49,50 +55,26 @@ class MiddlewareRegistry {
       throw new Error(`Middleware "${aliasOrFn}" is not registered.`);
     }
 
-    // If params provided, instantiate the class with them via fromParams() or constructor
-    if (params.length > 0) {
-      if (typeof Handler === 'function' && Handler.prototype &&
-          typeof Handler.prototype.handle === 'function') {
-        const instance = typeof Handler.fromParams === 'function'
-          ? Handler.fromParams(params)
-          : new Handler(...params);
-        return (req, res, next) => {
-          const result = instance.handle(req, res, next);
-          if (result && typeof result.catch === 'function') result.catch(next);
-        };
-      }
-    }
-
-    // Pre-instantiated object with handle() method (e.g. new ThrottleMiddleware())
-    if (typeof Handler === 'object' && Handler !== null && typeof Handler.handle === 'function') {
-      return (req, res, next) => {
-        const result = Handler.handle(req, res, next);
-        if (result && typeof result.catch === 'function') result.catch(next);
-      };
-    }
-
-    // Class with handle() on prototype
-    if (typeof Handler === 'function' && Handler.prototype && typeof Handler.prototype.handle === 'function') {
-      const instance = new Handler();
-      return (req, res, next) => {
-        const result = instance.handle(req, res, next);
-        if (result && typeof result.catch === 'function') result.catch(next);
-      };
-    }
-
-    // Raw Express function
-    if (typeof Handler === 'function') return Handler;
+    return this._wrap(Handler, adapter, container, params);
+  }
 
-    throw new Error(`Middleware "${aliasOrFn}" must be a function or class with handle().`);
+  /**
+   * Resolve all aliases in a list.
+   */
+  resolveAll(list = [], adapter, container = null) {
+    return list.map(m => this.resolve(m, adapter, container));
   }
 
   /**
-   * Resolve an array of aliases/functions.
-   * @param {Array} list
-   * @returns {Function[]}
+   * Return a no-op passthrough handler for the given adapter.
+   * Used when a middleware alias is missing but should not crash the app.
    */
-  resolveAll(list = []) {
-    return list.map(m => this.resolve(m));
+  resolvePassthrough(adapter) {
+    // Adapter-agnostic: return a function matching the native signature
+    // by asking the adapter to wrap a no-op middleware instance.
+    return adapter.wrapMiddleware({
+      handle: (_ctx, next) => next(),
+    }, null);
   }
 
   has(alias) {
@@ -102,6 +84,49 @@ class MiddlewareRegistry {
   all() {
     return { ...this._map };
   }
+
+  // ── Internal ────────────────────────────────────────────────────────────────
+
+  _wrap(Handler, adapter, container, params = []) {
+    // If params provided, instantiate with fromParams() or constructor
+    if (params.length > 0) {
+      if (
+        typeof Handler === 'function' &&
+        Handler.prototype &&
+        typeof Handler.prototype.handle === 'function'
+      ) {
+        const instance = typeof Handler.fromParams === 'function'
+          ? Handler.fromParams(params)
+          : new Handler(...params);
+        return adapter.wrapMiddleware(instance, container);
+      }
+    }
+
+    // Pre-instantiated Millas middleware object with handle()
+    if (
+      typeof Handler === 'object' &&
+      Handler !== null &&
+      typeof Handler.handle === 'function'
+    ) {
+      return adapter.wrapMiddleware(Handler, container);
+    }
+
+    // Millas middleware class (handle on prototype)
+    if (
+      typeof Handler === 'function' &&
+      Handler.prototype &&
+      typeof Handler.prototype.handle === 'function'
+    ) {
+      return adapter.wrapMiddleware(new Handler(), container);
+    }
+
+    // Raw adapter-native function — pass through as-is (escape hatch)
+    if (typeof Handler === 'function') {
+      return Handler;
+    }
+
+    throw new Error('Middleware must be a function or a class with handle().');
+  }
 }
 
 module.exports = MiddlewareRegistry;

package/src/router/Route.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const RouteGroup = require('./RouteGroup');
+const RouteGroup  = require('./RouteGroup');
 const RouteRegistry = require('./RouteRegistry');
+const RouteEntry  = require('./RouteEntry');
 
 /**
  * Route
@@ -170,15 +171,19 @@ class Route {
 
     const entry = {
       verb,
-      path: fullPath,
+      path:       fullPath,
       handler,
       method,      // string method name OR raw function
       middleware,
       name,
+      shape:       null,   // populated by RouteEntry.shape() / .fromShape()
     };
 
     this._registry.register(entry);
-    return this;
+    // Return a RouteEntry so .shape() / .fromShape() can be chained.
+    // The RouteEntry holds a reference back to this Route so group-level
+    // calls (which don't use the returned value) still work normally.
+    return new RouteEntry(entry, this);
   }
 
   _mergeGroupStack() {
@@ -252,4 +257,4 @@ class RouteGroupBuilder {
   }
 }
 
-module.exports = Route;
+module.exports = Route;