millas 0.1.0

package/src/admin/resources/AdminResource.js

@@ -0,0 +1,317 @@
+'use strict';
+
+/**
+ * AdminResource
+ *
+ * Defines how a Model is represented in the admin panel.
+ * Subclass this and override properties/methods to customise.
+ *
+ * Usage:
+ *   class UserResource extends AdminResource {
+ *     static model      = User;
+ *     static label      = 'Users';
+ *     static icon       = '👤';
+ *     static perPage    = 25;
+ *     static searchable = ['name', 'email'];
+ *     static sortable   = ['id', 'name', 'email', 'created_at'];
+ *
+ *     static fields() {
+ *       return [
+ *         AdminField.id('id'),
+ *         AdminField.text('name').label('Full Name').sortable(),
+ *         AdminField.email('email').sortable(),
+ *         AdminField.badge('role').colors({ admin: 'red', user: 'blue' }),
+ *         AdminField.boolean('active'),
+ *         AdminField.datetime('created_at').label('Registered'),
+ *       ];
+ *     }
+ *
+ *     static filters() {
+ *       return [
+ *         AdminFilter.select('role', ['admin', 'user']),
+ *         AdminFilter.boolean('active'),
+ *         AdminFilter.dateRange('created_at'),
+ *       ];
+ *     }
+ *   }
+ *
+ *   Admin.register(UserResource);
+ */
+class AdminResource {
+  /** @type {typeof import('../orm/model/Model')} The Millas Model class */
+  static model = null;
+
+  /** Display name (plural) shown in sidebar and page title */
+  static label = null;
+
+  /** Singular label */
+  static labelSingular = null;
+
+  /** Emoji or icon string for the sidebar */
+  static icon = '📋';
+
+  /** Records per page */
+  static perPage = 20;
+
+  /** Columns to search across (SQL LIKE) */
+  static searchable = [];
+
+  /** Columns users can click to sort */
+  static sortable = ['id', 'created_at'];
+
+  /** Whether to show a Create button */
+  static canCreate = true;
+
+  /** Whether to show Edit buttons */
+  static canEdit = true;
+
+  /** Whether to show Delete buttons */
+  static canDelete = true;
+
+  /** URL-safe slug used in routes */
+  static get slug() {
+    return (this.label || this.model?.name || 'resource')
+      .toLowerCase().replace(/\s+/g, '-');
+  }
+
+  /**
+   * Define the fields shown in list + detail views.
+   * Must return an array of AdminField instances.
+   */
+  static fields() {
+    // Default: infer from model.fields if available
+    if (!this.model?.fields) return [];
+    return Object.entries(this.model.fields).map(([name, def]) =>
+      AdminField.fromModelField(name, def)
+    );
+  }
+
+  /**
+   * Define filter controls shown in the sidebar.
+   * Must return an array of AdminFilter instances.
+   */
+  static filters() {
+    return [];
+  }
+
+  /**
+   * Override to customise how records are fetched.
+   * Receives { page, perPage, search, sort, order, filters }
+   */
+  static async fetchList({ page = 1, perPage, search, sort = 'id', order = 'desc', filters = {} } = {}) {
+    const limit  = perPage || this.perPage;
+    const offset = (page - 1) * limit;
+    const db     = this.model._db();
+
+    let query = db.orderBy(sort, order);
+
+    // Search
+    if (search && this.searchable.length) {
+      query = query.where(function () {
+        for (const col of this.constructor.searchable || []) {
+          this.orWhere(col, 'like', `%${search}%`);
+        }
+      });
+    }
+
+    // Filters
+    for (const [key, value] of Object.entries(filters)) {
+      if (value !== '' && value !== null && value !== undefined) {
+        query = query.where(key, value);
+      }
+    }
+
+    const [rows, countResult] = await Promise.all([
+      query.clone().limit(limit).offset(offset),
+      query.clone().count('* as count').first(),
+    ]);
+
+    const total = Number(countResult?.count || 0);
+
+    return {
+      data:     rows.map(r => this.model._hydrate(r)),
+      total,
+      page:     Number(page),
+      perPage:  limit,
+      lastPage: Math.ceil(total / limit),
+    };
+  }
+
+  /**
+   * Fetch a single record by id.
+   */
+  static async fetchOne(id) {
+    return this.model.findOrFail(id);
+  }
+
+  /**
+   * Create a new record from form data.
+   */
+  static async create(data) {
+    return this.model.create(this._sanitise(data));
+  }
+
+  /**
+   * Update a record from form data.
+   */
+  static async update(id, data) {
+    const record = await this.model.findOrFail(id);
+    return record.update(this._sanitise(data));
+  }
+
+  /**
+   * Delete a record.
+   */
+  static async destroy(id) {
+    return this.model.destroy(id);
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  static _sanitise(data) {
+    // Remove private/system fields
+    const clean = { ...data };
+    delete clean.id;
+    delete clean._method;
+    delete clean._token;
+    return clean;
+  }
+
+  static _getLabel() {
+    return this.label || (this.model?.name ? this.model.name + 's' : 'Records');
+  }
+
+  static _getLabelSingular() {
+    return this.labelSingular || this.model?.name || 'Record';
+  }
+}
+
+// ── AdminField ────────────────────────────────────────────────────────────────
+
+class AdminField {
+  constructor(name, type) {
+    this._name      = name;
+    this._type      = type;
+    this._label     = name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    this._sortable  = false;
+    this._hidden    = false;
+    this._listOnly  = false;
+    this._detailOnly = false;
+    this._colors    = {};
+    this._format    = null;
+  }
+
+  // ─── Field types ────────────────────────────────────────────────────────
+
+  static id(name = 'id')           { return new AdminField(name, 'id'); }
+  static text(name)                { return new AdminField(name, 'text'); }
+  static email(name)               { return new AdminField(name, 'email'); }
+  static number(name)              { return new AdminField(name, 'number'); }
+  static boolean(name)             { return new AdminField(name, 'boolean'); }
+  static badge(name)               { return new AdminField(name, 'badge'); }
+  static datetime(name)            { return new AdminField(name, 'datetime'); }
+  static date(name)                { return new AdminField(name, 'date'); }
+  static image(name)               { return new AdminField(name, 'image'); }
+  static textarea(name)            { return new AdminField(name, 'textarea'); }
+  static select(name, options)     { const f = new AdminField(name, 'select'); f._options = options; return f; }
+  static password(name)            { return new AdminField(name, 'password'); }
+  static json(name)                { return new AdminField(name, 'json'); }
+
+  // ─── Fluent modifiers ───────────────────────────────────────────────────
+
+  label(l)         { this._label = l; return this; }
+  sortable()       { this._sortable = true; return this; }
+  hidden()         { this._hidden = true; return this; }
+  listOnly()       { this._listOnly = true; return this; }
+  detailOnly()     { this._detailOnly = true; return this; }
+  colors(map)      { this._colors = map; return this; }
+  format(fn)       { this._format = fn; return this; }
+  placeholder(p)   { this._placeholder = p; return this; }
+  help(h)          { this._help = h; return this; }
+  readonly()       { this._readonly = true; return this; }
+
+  // ─── Serialise for rendering ─────────────────────────────────────────────
+
+  toJSON() {
+    return {
+      name:        this._name,
+      type:        this._type,
+      label:       this._label,
+      sortable:    this._sortable,
+      hidden:      this._hidden,
+      listOnly:    this._listOnly,
+      detailOnly:  this._detailOnly,
+      colors:      this._colors,
+      options:     this._options,
+      placeholder: this._placeholder,
+      help:        this._help,
+      readonly:    this._readonly,
+    };
+  }
+
+  /**
+   * Format a raw value for display.
+   */
+  display(value) {
+    if (this._format) return this._format(value);
+    if (value === null || value === undefined) return '—';
+    if (this._type === 'boolean') return value ? '✓' : '✗';
+    if (this._type === 'datetime' && value) {
+      return new Date(value).toLocaleString();
+    }
+    if (this._type === 'date' && value) {
+      return new Date(value).toLocaleDateString();
+    }
+    if (this._type === 'password') return '••••••••';
+    if (this._type === 'json') return JSON.stringify(value);
+    return String(value);
+  }
+
+  static fromModelField(name, fieldDef) {
+    const typeMap = {
+      id:        () => AdminField.id(name),
+      string:    () => AdminField.text(name),
+      text:      () => AdminField.textarea(name),
+      integer:   () => AdminField.number(name),
+      bigInteger:() => AdminField.number(name),
+      float:     () => AdminField.number(name),
+      decimal:   () => AdminField.number(name),
+      boolean:   () => AdminField.boolean(name),
+      timestamp: () => AdminField.datetime(name),
+      date:      () => AdminField.date(name),
+      enum:      () => AdminField.select(name, fieldDef.enumValues || []),
+      json:      () => AdminField.json(name),
+    };
+    const fn = typeMap[fieldDef.type] || (() => AdminField.text(name));
+    return fn();
+  }
+}
+
+// ── AdminFilter ───────────────────────────────────────────────────────────────
+
+class AdminFilter {
+  constructor(name, type) {
+    this._name  = name;
+    this._type  = type;
+    this._label = name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+  }
+
+  static text(name)              { return new AdminFilter(name, 'text'); }
+  static select(name, options)   { const f = new AdminFilter(name, 'select'); f._options = options; return f; }
+  static boolean(name)           { return new AdminFilter(name, 'boolean'); }
+  static dateRange(name)         { return new AdminFilter(name, 'dateRange'); }
+  static number(name)            { return new AdminFilter(name, 'number'); }
+
+  label(l) { this._label = l; return this; }
+
+  toJSON() {
+    return {
+      name:    this._name,
+      type:    this._type,
+      label:   this._label,
+      options: this._options,
+    };
+  }
+}
+
+module.exports = { AdminResource, AdminField, AdminFilter };

package/src/auth/Auth.js

@@ -0,0 +1,254 @@
+'use strict';
+
+const Hasher    = require('./Hasher');
+const JwtDriver = require('./JwtDriver');
+const HttpError = require('../errors/HttpError');
+
+/**
+ * Auth
+ *
+ * The primary authentication facade.
+ *
+ * Usage:
+ *   const { Auth } = require('millas/src');
+ *
+ *   // Register a new user
+ *   const user = await Auth.register({
+ *     name:     'Alice',
+ *     email:    'alice@example.com',
+ *     password: 'secret123',
+ *   });
+ *
+ *   // Login
+ *   const { user, token } = await Auth.login('alice@example.com', 'secret123');
+ *
+ *   // Verify a token
+ *   const payload = Auth.verify(token);
+ *
+ *   // Get logged-in user from a request
+ *   const user = await Auth.user(req);
+ *
+ *   // Check password
+ *   const ok = await Auth.checkPassword('plain', user.password);
+ */
+class Auth {
+  constructor() {
+    this._jwt    = null;
+    this._config = null;
+    this._UserModel = null;
+  }
+
+  // ─── Configuration ───────────────────────────────────────────────────────
+
+  /**
+   * Configure Auth with config/auth.js settings.
+   * Called automatically by AuthServiceProvider.
+   */
+  configure(config, UserModel = null) {
+    this._config    = config;
+    this._UserModel = UserModel;
+
+    const jwtConfig = config?.guards?.jwt || {};
+    this._jwt = new JwtDriver(jwtConfig);
+  }
+
+  /**
+   * Set the User model used for lookups.
+   */
+  setUserModel(UserModel) {
+    this._UserModel = UserModel;
+  }
+
+  // ─── Core auth operations ─────────────────────────────────────────────────
+
+  /**
+   * Register a new user.
+   *
+   * Automatically hashes the password before saving.
+   * Returns the created user instance.
+   *
+   * @param {object} data — { name, email, password, ...rest }
+   */
+  async register(data) {
+    this._requireUserModel();
+
+    if (!data.password) throw new HttpError(422, 'Password is required');
+    if (!data.email)    throw new HttpError(422, 'Email is required');
+
+    // Check for duplicate email
+    const existing = await this._UserModel.findBy('email', data.email);
+    if (existing) throw new HttpError(422, 'Email already in use');
+
+    const hashed = await Hasher.make(data.password);
+    return this._UserModel.create({ ...data, password: hashed });
+  }
+
+  /**
+   * Attempt to log in with email + password.
+   *
+   * Returns { user, token, refreshToken } on success.
+   * Throws 401 on failure.
+   *
+   * @param {string} email
+   * @param {string} password
+   */
+  async login(email, password) {
+    this._requireUserModel();
+
+    const user = await this._UserModel.findBy('email', email);
+    if (!user) throw new HttpError(401, 'Invalid credentials');
+
+    const ok = await Hasher.check(password, user.password);
+    if (!ok)  throw new HttpError(401, 'Invalid credentials');
+
+    const payload = this._buildTokenPayload(user);
+    const token   = this._jwt.sign(payload);
+    const refreshToken = this._jwt.signRefreshToken(payload);
+
+    return { user, token, refreshToken };
+  }
+
+  /**
+   * Verify and decode a token string.
+   * Throws 401 if expired or invalid.
+   *
+   * @param {string} token
+   * @returns {object} decoded payload
+   */
+  verify(token) {
+    try {
+      return this._jwt.verify(token);
+    } catch (err) {
+      if (err.name === 'TokenExpiredError') {
+        throw new HttpError(401, 'Token has expired');
+      }
+      throw new HttpError(401, 'Invalid token');
+    }
+  }
+
+  /**
+   * Resolve the authenticated user from a request.
+   * Reads the Bearer token from Authorization header.
+   *
+   * Returns null if no token present or invalid.
+   *
+   * @param {object} req — Express request
+   * @returns {object|null} user model instance
+   */
+  async user(req) {
+    this._requireUserModel();
+
+    const token = this._extractToken(req);
+    if (!token) return null;
+
+    let payload;
+    try {
+      payload = this._jwt.verify(token);
+    } catch {
+      return null;
+    }
+
+    return this._UserModel.find(payload.id || payload.sub);
+  }
+
+  /**
+   * Resolve the authenticated user and throw 401 if not found.
+   */
+  async userOrFail(req) {
+    const u = await this.user(req);
+    if (!u) throw new HttpError(401, 'Unauthenticated');
+    return u;
+  }
+
+  /**
+   * Hash a plain-text password.
+   */
+  async hashPassword(plain) {
+    return Hasher.make(plain);
+  }
+
+  /**
+   * Check a plain-text password against a hash.
+   */
+  async checkPassword(plain, hash) {
+    return Hasher.check(plain, hash);
+  }
+
+  /**
+   * Issue a new token for a user directly.
+   * Useful for token refresh flows.
+   */
+  issueToken(user, options = {}) {
+    const payload = this._buildTokenPayload(user);
+    return this._jwt.sign(payload, options);
+  }
+
+  /**
+   * Decode a token without verifying (inspect expired tokens).
+   */
+  decode(token) {
+    return this._jwt.decode(token);
+  }
+
+  /**
+   * Generate a secure password reset token for a user.
+   */
+  generateResetToken(user) {
+    return this._jwt.signResetToken({
+      sub:   user.id,
+      email: user.email,
+      type:  'password_reset',
+    });
+  }
+
+  /**
+   * Verify a password reset token.
+   * Returns the payload or throws 400.
+   */
+  verifyResetToken(token) {
+    try {
+      const payload = this._jwt.verify(token);
+      if (payload.type !== 'password_reset') {
+        throw new HttpError(400, 'Invalid reset token type');
+      }
+      return payload;
+    } catch (err) {
+      if (err instanceof HttpError) throw err;
+      throw new HttpError(400, 'Invalid or expired reset token');
+    }
+  }
+
+  // ─── Helpers ─────────────────────────────────────────────────────────────
+
+  _extractToken(req) {
+    const header = req.headers?.['authorization'] || '';
+    if (header.startsWith('Bearer ')) {
+      return header.slice(7);
+    }
+    // Also check query param for websocket / download links
+    return req.query?.token || null;
+  }
+
+  _buildTokenPayload(user) {
+    return {
+      id:    user.id,
+      sub:   user.id,
+      email: user.email,
+      role:  user.role || null,
+      iat:   Math.floor(Date.now() / 1000),
+    };
+  }
+
+  _requireUserModel() {
+    if (!this._UserModel) {
+      throw new Error(
+        'Auth has no User model. ' +
+        'Call Auth.setUserModel(User) or boot AuthServiceProvider.'
+      );
+    }
+  }
+}
+
+// Singleton facade
+module.exports = new Auth();
+module.exports.Auth = Auth;