webspresso 0.0.98 → 0.0.100

package/core/auth/session-manager.js

@@ -0,0 +1,255 @@
+/**
+ * Webspresso Session Revocation & Device Manager
+ * Orchestrates session tracking, activity throttling, store cleanup, and event dispatching
+ * @module core/auth/session-manager
+ */
+
+'use strict';
+
+const { getClientIp, parseUserAgent } = require('./user-agent');
+const { createMemorySessionTracker, createKnexSessionTracker } = require('./sessions');
+
+class SessionManager {
+  /**
+   * @param {Object} options
+   * @param {Object} [options.tracker] - Session tracker adapter (knex or memory)
+   * @param {Object} [options.sessionStore] - Optional express-session store instance
+   * @param {number} [options.touchThrottleMs=60000] - Throttle last_active_at updates (default 1 min)
+   * @param {import('events').EventEmitter} [options.emitter] - AuthManager instance for event dispatching
+   */
+  constructor(options = {}) {
+    this.tracker = options.tracker || createMemorySessionTracker();
+    this.sessionStore = options.sessionStore || null;
+    this.touchThrottleMs = options.touchThrottleMs ?? 60000;
+    this.emitter = options.emitter || null;
+    /** @type {Map<string, number>} */
+    this._lastTouchMap = new Map();
+  }
+
+  /**
+   * Record or update session for a user request
+   * @param {string} sessionId
+   * @param {string|number} userId
+   * @param {Object} req - Express request
+   * @returns {Promise<Object>}
+   */
+  async track(sessionId, userId, req) {
+    if (!sessionId || !userId) return null;
+
+    const userAgent = req?.headers?.['user-agent'] || '';
+    const ip = getClientIp(req);
+    const parsed = parseUserAgent(userAgent);
+
+    const record = await this.tracker.track(sessionId, userId, {
+      ip,
+      userAgent,
+      browser: parsed.browser,
+      os: parsed.os,
+      device: parsed.device,
+    });
+
+    this._lastTouchMap.set(sessionId, Date.now());
+
+    if (this.emitter) {
+      this.emitter.emit('session:created', {
+        sessionId,
+        userId,
+        ip,
+        browser: parsed.browser,
+        os: parsed.os,
+        device: parsed.device,
+      });
+    }
+
+    return record;
+  }
+
+  /**
+   * Touch session to update last_active_at with throttling
+   * @param {string} sessionId
+   * @returns {Promise<boolean>}
+   */
+  async touch(sessionId) {
+    if (!sessionId) return false;
+
+    const now = Date.now();
+    const lastTouch = this._lastTouchMap.get(sessionId) || 0;
+
+    if (now - lastTouch < this.touchThrottleMs) {
+      return false; // Throttled
+    }
+
+    this._lastTouchMap.set(sessionId, now);
+    return await this.tracker.touch(sessionId);
+  }
+
+  /**
+   * Check if session is valid and active
+   * @param {string} sessionId
+   * @param {string|number} [userId]
+   * @returns {Promise<boolean>}
+   */
+  async isSessionValid(sessionId, userId = null) {
+    if (!sessionId) return false;
+    return await this.tracker.isSessionValid(sessionId, userId);
+  }
+
+  /**
+   * List all active sessions for a user
+   * @param {string|number} userId
+   * @param {string} [currentSessionId]
+   * @returns {Promise<Array<Object>>}
+   */
+  async listSessions(userId, currentSessionId = null) {
+    if (!userId) return [];
+    return await this.tracker.list(userId, currentSessionId);
+  }
+
+  /**
+   * Revoke a specific session
+   * @param {string} sessionId
+   * @param {Object} [options]
+   * @param {string|number} [options.userId]
+   * @param {string} [options.revokedBy]
+   * @returns {Promise<boolean>}
+   */
+  async revokeSession(sessionId, options = {}) {
+    if (!sessionId) return false;
+
+    this._lastTouchMap.delete(sessionId);
+    const success = await this.tracker.revoke(sessionId);
+
+    // If express-session store is available, destroy physical session
+    if (this.sessionStore && typeof this.sessionStore.destroy === 'function') {
+      try {
+        await new Promise((resolve) => this.sessionStore.destroy(sessionId, () => resolve()));
+      } catch (err) {
+        // Continue even if session store destroy errors
+      }
+    }
+
+    if (this.emitter) {
+      this.emitter.emit('session:revoked', {
+        sessionId,
+        userId: options.userId,
+        revokedBy: options.revokedBy,
+      });
+    }
+
+    return success;
+  }
+
+  /**
+   * Revoke all other sessions for a user except the current one
+   * @param {string|number} userId
+   * @param {string} currentSessionId
+   * @returns {Promise<number>} Count of revoked sessions
+   */
+  async revokeOtherSessions(userId, currentSessionId) {
+    if (!userId) return 0;
+
+    const count = await this.tracker.revokeOthers(userId, currentSessionId);
+
+    if (this.emitter) {
+      this.emitter.emit('sessions:revoked_others', {
+        userId,
+        currentSessionId,
+        count,
+      });
+    }
+
+    return count;
+  }
+
+  /**
+   * Revoke all sessions for a user (e.g. password reset or admin security action)
+   * @param {string|number} userId
+   * @returns {Promise<number>} Count of revoked sessions
+   */
+  async revokeAllSessions(userId) {
+    if (!userId) return 0;
+
+    const count = await this.tracker.revokeAll(userId);
+
+    if (this.emitter) {
+      this.emitter.emit('sessions:revoked_all', {
+        userId,
+        count,
+      });
+    }
+
+    return count;
+  }
+}
+
+/**
+ * Route handler to list active sessions for current user (GET /api/auth/sessions)
+ * @param {import('./manager').AuthManager} authManager
+ * @returns {Function} Express route handler
+ */
+function createListSessionsHandler(authManager) {
+  return async function listSessionsHandler(req, res) {
+    if (!req.user || !req.user.id) {
+      return res.status(401).json({ error: 'Authentication required' });
+    }
+
+    try {
+      const currentSessionId = req.sessionID || null;
+      const sessions = await authManager.listSessions(req.user.id, currentSessionId);
+      return res.json({ ok: true, sessions });
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to list sessions' });
+    }
+  };
+}
+
+/**
+ * Route handler to revoke a session (POST /api/auth/sessions/revoke)
+ * @param {import('./manager').AuthManager} authManager
+ * @returns {Function} Express route handler
+ */
+function createRevokeSessionHandler(authManager) {
+  return async function revokeSessionHandler(req, res) {
+    if (!req.user || !req.user.id) {
+      return res.status(401).json({ error: 'Authentication required' });
+    }
+
+    const { sessionId, allOthers } = req.body || {};
+
+    try {
+      if (allOthers) {
+        const count = await authManager.revokeOtherSessions(req.user.id, req.sessionID);
+        return res.json({ ok: true, revokedCount: count, message: 'All other sessions revoked' });
+      }
+
+      if (!sessionId) {
+        return res.status(400).json({ error: 'sessionId is required' });
+      }
+
+      // Check ownership: ensure session belongs to current user unless user is admin
+      const sessions = await authManager.listSessions(req.user.id);
+      const ownsSession = sessions.some((s) => s.session_id === sessionId);
+
+      if (!ownsSession && req.user.role !== 'admin') {
+        return res.status(403).json({ error: 'Cannot revoke session belonging to another user' });
+      }
+
+      await authManager.revokeSession(sessionId, { userId: req.user.id });
+
+      // If user revoked their own current session, log them out
+      if (sessionId === req.sessionID && req.auth && typeof req.auth.logout === 'function') {
+        await req.auth.logout();
+      }
+
+      return res.json({ ok: true, message: 'Session revoked successfully' });
+    } catch (err) {
+      return res.status(500).json({ error: err.message || 'Failed to revoke session' });
+    }
+  };
+}
+
+module.exports = {
+  SessionManager,
+  createListSessionsHandler,
+  createRevokeSessionHandler,
+};

package/core/auth/sessions.js

@@ -0,0 +1,351 @@
+/**
+ * Webspresso Active Sessions & Device Management Store
+ * Tracks active devices, last active timestamps, and handles remote session revocation
+ * @module core/auth/sessions
+ */
+
+'use strict';
+
+const { parseUserAgent, getClientIp } = require('./user-agent');
+
+/**
+ * Migration helper to create user_sessions table
+ * @param {import('knex').Knex} knex
+ * @returns {Promise<void>}
+ */
+async function createUserSessionsTable(knex) {
+  const exists = await knex.schema.hasTable('user_sessions');
+  if (exists) return;
+
+  await knex.schema.createTable('user_sessions', (table) => {
+    table.bigIncrements('id').primary();
+    table.string('session_id', 128).notNullable().unique();
+    table.bigInteger('user_id').unsigned().notNullable();
+    table.string('ip_address', 64).nullable();
+    table.text('user_agent').nullable();
+    table.string('browser', 64).nullable();
+    table.string('os', 64).nullable();
+    table.string('device', 32).nullable();
+    table.timestamp('last_active_at').notNullable().defaultTo(knex.fn.now());
+    table.timestamp('created_at').defaultTo(knex.fn.now());
+
+    table.index(['user_id', 'last_active_at']);
+    table.index('session_id');
+    table.index('last_active_at');
+  });
+}
+
+/**
+ * Migration helper to drop user_sessions table
+ * @param {import('knex').Knex} knex
+ * @returns {Promise<void>}
+ */
+async function dropUserSessionsTable(knex) {
+  await knex.schema.dropTableIfExists('user_sessions');
+}
+
+/**
+ * Create Knex session tracker adapter
+ * @param {Object} db - Database with knex or knex instance
+ * @param {Object} [options]
+ * @param {string} [options.tableName='user_sessions']
+ * @returns {Object} Session tracker adapter
+ */
+function createKnexSessionTracker(db, options = {}) {
+  const knex = db.knex || db;
+  const tableName = options.tableName || 'user_sessions';
+
+  return {
+    /**
+     * Record or update an active session for a user
+     * @param {string} sessionId - Express session ID
+     * @param {string|number} userId - User ID
+     * @param {Object} [metadata]
+     * @param {string} [metadata.ip]
+     * @param {string} [metadata.userAgent]
+     * @param {string} [metadata.browser]
+     * @param {string} [metadata.os]
+     * @param {string} [metadata.device]
+     * @returns {Promise<Object>}
+     */
+    track: async (sessionId, userId, metadata = {}) => {
+      if (!sessionId || !userId) return null;
+
+      const ua = metadata.userAgent || '';
+      const parsed = parseUserAgent(ua);
+      const ip = metadata.ip || '127.0.0.1';
+      const browser = metadata.browser || parsed.browser;
+      const os = metadata.os || parsed.os;
+      const device = metadata.device || parsed.device;
+
+      const existing = await knex(tableName).where({ session_id: sessionId }).first();
+      const now = new Date();
+
+      if (existing) {
+        await knex(tableName).where({ session_id: sessionId }).update({
+          user_id: userId,
+          ip_address: ip,
+          user_agent: ua ? ua.slice(0, 1000) : null,
+          browser,
+          os,
+          device,
+          last_active_at: now,
+        });
+        return {
+          ...existing,
+          user_id: userId,
+          ip_address: ip,
+          browser,
+          os,
+          device,
+          last_active_at: now,
+        };
+      }
+
+      const [id] = await knex(tableName).insert({
+        session_id: sessionId,
+        user_id: userId,
+        ip_address: ip,
+        user_agent: ua ? ua.slice(0, 1000) : null,
+        browser,
+        os,
+        device,
+        last_active_at: now,
+        created_at: now,
+      });
+
+      return {
+        id,
+        session_id: sessionId,
+        user_id: userId,
+        ip_address: ip,
+        browser,
+        os,
+        device,
+        last_active_at: now,
+        created_at: now,
+      };
+    },
+
+    /**
+     * Touch session to update last_active_at
+     * @param {string} sessionId
+     * @returns {Promise<boolean>}
+     */
+    touch: async (sessionId) => {
+      if (!sessionId) return false;
+      const count = await knex(tableName).where({ session_id: sessionId }).update({
+        last_active_at: new Date(),
+      });
+      return count > 0;
+    },
+
+    /**
+     * Get a session record by session_id
+     * @param {string} sessionId
+     * @returns {Promise<Object|null>}
+     */
+    get: async (sessionId) => {
+      if (!sessionId) return null;
+      return await knex(tableName).where({ session_id: sessionId }).first() || null;
+    },
+
+    /**
+     * List all active sessions for a user, marking the current session
+     * @param {string|number} userId
+     * @param {string} [currentSessionId]
+     * @returns {Promise<Array<Object>>}
+     */
+    list: async (userId, currentSessionId = null) => {
+      if (!userId) return [];
+      const rows = await knex(tableName)
+        .where({ user_id: userId })
+        .orderBy('last_active_at', 'desc');
+
+      return rows.map((row) => ({
+        ...row,
+        is_current: Boolean(currentSessionId && row.session_id === currentSessionId),
+      }));
+    },
+
+    /**
+     * Check if a session exists and belongs to the given user
+     * @param {string} sessionId
+     * @param {string|number} [userId]
+     * @returns {Promise<boolean>}
+     */
+    isSessionValid: async (sessionId, userId = null) => {
+      if (!sessionId) return false;
+      const query = knex(tableName).where({ session_id: sessionId });
+      if (userId) {
+        query.andWhere({ user_id: userId });
+      }
+      const record = await query.first();
+      return Boolean(record);
+    },
+
+    /**
+     * Revoke a single session
+     * @param {string} sessionId
+     * @returns {Promise<boolean>}
+     */
+    revoke: async (sessionId) => {
+      if (!sessionId) return false;
+      const count = await knex(tableName).where({ session_id: sessionId }).delete();
+      return count > 0;
+    },
+
+    /**
+     * Revoke all other sessions for user, keeping the current session active
+     * @param {string|number} userId
+     * @param {string} currentSessionId
+     * @returns {Promise<number>} Number of revoked sessions
+     */
+    revokeOthers: async (userId, currentSessionId) => {
+      if (!userId) return 0;
+      let query = knex(tableName).where({ user_id: userId });
+      if (currentSessionId) {
+        query = query.whereNot({ session_id: currentSessionId });
+      }
+      return await query.delete();
+    },
+
+    /**
+     * Revoke all sessions for a user (force logout from all devices)
+     * @param {string|number} userId
+     * @returns {Promise<number>} Number of revoked sessions
+     */
+    revokeAll: async (userId) => {
+      if (!userId) return 0;
+      return await knex(tableName).where({ user_id: userId }).delete();
+    },
+
+    /**
+     * Purge sessions older than maxAgeMs
+     * @param {number} maxAgeMs
+     * @returns {Promise<number>}
+     */
+    purgeExpired: async (maxAgeMs) => {
+      const cutoff = new Date(Date.now() - maxAgeMs);
+      return await knex(tableName).where('last_active_at', '<', cutoff).delete();
+    },
+  };
+}
+
+/**
+ * In-memory session tracker for testing or development without a database table
+ * @returns {Object} Session tracker adapter
+ */
+function createMemorySessionTracker() {
+  /** @type {Map<string, Object>} */
+  const sessions = new Map();
+
+  return {
+    track: async (sessionId, userId, metadata = {}) => {
+      if (!sessionId || !userId) return null;
+
+      const ua = metadata.userAgent || '';
+      const parsed = parseUserAgent(ua);
+      const ip = metadata.ip || '127.0.0.1';
+      const browser = metadata.browser || parsed.browser;
+      const os = metadata.os || parsed.os;
+      const device = metadata.device || parsed.device;
+      const now = new Date();
+
+      const existing = sessions.get(sessionId);
+      const record = {
+        id: existing?.id || sessions.size + 1,
+        session_id: sessionId,
+        user_id: userId,
+        ip_address: ip,
+        user_agent: ua ? ua.slice(0, 1000) : null,
+        browser,
+        os,
+        device,
+        last_active_at: now,
+        created_at: existing?.created_at || now,
+      };
+
+      sessions.set(sessionId, record);
+      return record;
+    },
+
+    touch: async (sessionId) => {
+      const record = sessions.get(sessionId);
+      if (!record) return false;
+      record.last_active_at = new Date();
+      return true;
+    },
+
+    get: async (sessionId) => {
+      return sessions.get(sessionId) || null;
+    },
+
+    list: async (userId, currentSessionId = null) => {
+      const list = [];
+      for (const row of sessions.values()) {
+        if (String(row.user_id) === String(userId)) {
+          list.push({
+            ...row,
+            is_current: Boolean(currentSessionId && row.session_id === currentSessionId),
+          });
+        }
+      }
+      return list.sort((a, b) => b.last_active_at.getTime() - a.last_active_at.getTime());
+    },
+
+    isSessionValid: async (sessionId, userId = null) => {
+      const record = sessions.get(sessionId);
+      if (!record) return false;
+      if (userId && String(record.user_id) !== String(userId)) return false;
+      return true;
+    },
+
+    revoke: async (sessionId) => {
+      return sessions.delete(sessionId);
+    },
+
+    revokeOthers: async (userId, currentSessionId) => {
+      let count = 0;
+      for (const [sid, row] of sessions.entries()) {
+        if (String(row.user_id) === String(userId) && sid !== currentSessionId) {
+          sessions.delete(sid);
+          count++;
+        }
+      }
+      return count;
+    },
+
+    revokeAll: async (userId) => {
+      let count = 0;
+      for (const [sid, row] of sessions.entries()) {
+        if (String(row.user_id) === String(userId)) {
+          sessions.delete(sid);
+          count++;
+        }
+      }
+      return count;
+    },
+
+    purgeExpired: async (maxAgeMs) => {
+      const cutoff = Date.now() - maxAgeMs;
+      let count = 0;
+      for (const [sid, row] of sessions.entries()) {
+        if (row.last_active_at.getTime() < cutoff) {
+          sessions.delete(sid);
+          count++;
+        }
+      }
+      return count;
+    },
+  };
+}
+
+module.exports = {
+  createUserSessionsTable,
+  dropUserSessionsTable,
+  createKnexSessionTracker,
+  createMemorySessionTracker,
+  getClientIp,
+  parseUserAgent,
+};

package/core/auth/tokens.js

@@ -8,6 +8,7 @@ const { generateToken, hashToken, hash } = require('./hash');
 const TOKEN_TYPES = {
   PASSWORD_RESET: 'password_reset',
   EMAIL_VERIFY: 'email_verify',
+  MAGIC_LINK: 'magic_link',
 };
 
 /**