cynx-lib 1.3.84 → 1.3.86

package/utils/utils/session_manager.js

@@ -0,0 +1,549 @@
+/**
+ * cynx/utils — Universal Enterprise Session Manager (session_manager.js)
+ *
+ * Universal PostgreSQL and in-memory session management engine with dual-token architecture:
+ *  - v2: Compound token format (`st_${sessionId}$${secretCode}`) for O(1) indexed lookups
+ *        and safe non-secret Real-Time / WebSocket event targeting.
+ *  - v1: Legacy flat token format (`st_${hex}`) for seamless backward compatibility.
+ *
+ * STRICT NO EMOJIS!
+ */
+
+import { genUid, getRandomBytes } from './uid.js';
+import { parseDurationMs } from './duration.js';
+import { deriveDeviceName, genSessionToken } from './session.js';
+
+/**
+ * Format a compound v2 token: prefix + sessionId + '$' + secretCode
+ * Example: "st_2SuO33NNKhXd$d9e1807390014a5b6c7d8e9f01234567"
+ *
+ * @param {string} sessionId Unique session row identifier (ID)
+ * @param {string} secret Cryptographically secure random secret
+ * @param {string} [prefix='st_'] Token prefix
+ * @returns {string}
+ */
+export function formatToken(sessionId, secret, prefix = 'st_') {
+  return `${prefix}${sessionId}$${secret}`;
+}
+
+/**
+ * Parse an incoming token string.
+ * Automatically recognizes v2 compound tokens and legacy v1 flat tokens.
+ *
+ * @param {string} token Raw token string or Bearer header
+ * @param {string} [prefix='st_'] Expected token prefix
+ * @returns {{ version: number, sessionId: string|null, secret: string|null, prefix: string, raw: string, isValid: boolean }}
+ */
+export function parseToken(token, prefix = 'st_') {
+  if (!token || typeof token !== 'string') {
+    return { version: 0, sessionId: null, secret: null, prefix, raw: '', isValid: false };
+  }
+  const clean = token.replace(/^Bearer\s+/i, '').trim();
+  if (!clean) {
+    return { version: 0, sessionId: null, secret: null, prefix, raw: '', isValid: false };
+  }
+
+  if (clean.includes('$')) {
+    const parts = clean.split('$');
+    const head = parts[0];
+    const secret = parts.slice(1).join('$');
+    const sessionId = head.startsWith(prefix) ? head.slice(prefix.length) : head;
+    return {
+      version: 2,
+      sessionId,
+      secret,
+      prefix,
+      raw: clean,
+      isValid: Boolean(sessionId && secret),
+    };
+  }
+
+  // Legacy v1 token (flat string without '$')
+  return {
+    version: 1,
+    sessionId: null,
+    secret: clean,
+    prefix,
+    raw: clean,
+    isValid: true,
+  };
+}
+
+/**
+ * Extract public sessionId from token if available.
+ * Returns null for legacy v1 tokens.
+ *
+ * @param {string} token
+ * @param {string} [prefix='st_']
+ * @returns {string|null}
+ */
+export function getSessionId(token, prefix = 'st_') {
+  const parsed = parseToken(token, prefix);
+  return parsed.sessionId;
+}
+
+/**
+ * Universally extract session token from HTTP Request object (Express, Fastify, Next.js, Node).
+ * Inspects Authorization Bearer header, x-auth-token, x-session-token, and query parameter.
+ *
+ * @param {object} req HTTP request object
+ * @returns {string} Clean session token string or empty string
+ */
+export function extractToken(req) {
+  if (!req) return '';
+  const headers = req.headers || {};
+  const auth = headers.authorization || headers.Authorization || '';
+  if (typeof auth === 'string' && auth.startsWith('Bearer ')) {
+    return auth.split(' ')[1].trim();
+  }
+  const custom = headers['x-auth-token'] || headers['x-session-token'] || headers['x-token'] || '';
+  if (typeof custom === 'string' && custom.trim()) {
+    return custom.trim();
+  }
+  if (req.query && req.query.token) {
+    return String(req.query.token).trim();
+  }
+  return '';
+}
+
+/**
+ * Universal Session Manager Engine.
+ */
+export class SessionManager {
+  constructor(options = {}) {
+    this.options = {
+      query: options.query || null,
+      sessionsTable: options.sessionsTable || 'user_sessions',
+      usersTable: options.usersTable || 'users',
+      rolesTable: options.rolesTable || 'roles',
+      settingsTable: options.settingsTable || 'system_settings',
+      superRole: (options.superRole || 'superadmin').toLowerCase(),
+      tokenPrefix: options.tokenPrefix || 'st_',
+      tokenVersion: options.tokenVersion || 2,
+      secretBytes: options.secretBytes || 32,
+      idLength: options.idLength || 12,
+      defaultAbsoluteTimeoutMs: options.defaultAbsoluteTimeoutMs || 30 * 24 * 60 * 60 * 1000,
+      inactivityCacheTtlMs: options.inactivityCacheTtlMs || 30000,
+      jwtSecret: options.jwtSecret || (typeof process !== 'undefined' ? process.env.JWT_SECRET : ''),
+      ...options,
+    };
+
+    this._inactTimeoutMs = null;
+    this._inactFetchedAt = 0;
+  }
+
+  async _query(sql, params = []) {
+    if (typeof this.options.query !== 'function') {
+      throw new Error('[cynx/session] Database query function not configured in SessionManager.');
+    }
+    return this.options.query(sql, params);
+  }
+
+  parseToken(token) {
+    return parseToken(token, this.options.tokenPrefix);
+  }
+
+  getSessionId(token) {
+    return getSessionId(token, this.options.tokenPrefix);
+  }
+
+  extractToken(req) {
+    return extractToken(req);
+  }
+
+  formatToken(sessionId, secret) {
+    return formatToken(sessionId, secret, this.options.tokenPrefix);
+  }
+
+  async getInactivityTimeoutMs() {
+    const now = Date.now();
+    if (this._inactTimeoutMs !== null && now - this._inactFetchedAt < this.options.inactivityCacheTtlMs) {
+      return this._inactTimeoutMs;
+    }
+    try {
+      const sql = `SELECT value FROM ${this.options.settingsTable} WHERE key = 'session_inactivity_timeout'`;
+      const sRes = await this._query(sql).catch(() => ({ rows: [] }));
+      if (sRes.rows && sRes.rows.length > 0) {
+        let val = sRes.rows[0].value;
+        if (typeof val === 'string') {
+          try { val = JSON.parse(val); } catch {}
+        }
+        this._inactTimeoutMs = parseDurationMs(val, 0);
+      } else {
+        this._inactTimeoutMs = 0;
+      }
+    } catch {
+      this._inactTimeoutMs = 0;
+    }
+    this._inactFetchedAt = now;
+    return this._inactTimeoutMs;
+  }
+
+  clearSettingsCache() {
+    this._inactTimeoutMs = null;
+    this._inactFetchedAt = 0;
+  }
+
+  /**
+   * Create and persist a new session for a user.
+   *
+   * @param {string|number} userId
+   * @param {object} [req] HTTP request object for device and IP detection
+   * @param {object} [options]
+   * @returns {Promise<string>} Generated session token
+   */
+  async createSession(userId, req = null, options = {}) {
+    const id = genUid(this.options.idLength);
+    const userAgent = (req?.headers ? req.headers['user-agent'] || '' : '').slice(0, 500);
+    const ipAddress = (req?.headers ? req.headers['x-forwarded-for'] || req.socket?.remoteAddress || '' : '').slice(0, 45);
+    const deviceName = deriveDeviceName(req, userAgent);
+
+    let token;
+    if (this.options.tokenVersion === 2) {
+      const bytes = getRandomBytes(this.options.secretBytes);
+      let hex = '';
+      for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+      }
+      token = formatToken(id, hex, this.options.tokenPrefix);
+    } else {
+      token = genSessionToken(this.options.secretBytes);
+    }
+
+    let absoluteMs = this.options.defaultAbsoluteTimeoutMs;
+    try {
+      const sRes = await this._query(`SELECT value FROM ${this.options.settingsTable} WHERE key = 'session_absolute_timeout'`);
+      if (sRes.rows && sRes.rows.length > 0) {
+        let val = sRes.rows[0].value;
+        if (typeof val === 'string') {
+          try { val = JSON.parse(val); } catch {}
+        }
+        const parsed = parseDurationMs(val, absoluteMs);
+        if (parsed > 0) absoluteMs = parsed;
+      }
+    } catch {}
+
+    const expiresAt = new Date(Date.now() + absoluteMs);
+
+    const insertSql = `
+      INSERT INTO ${this.options.sessionsTable} (id, user_id, token, user_agent, device_name, ip_address, is_active, expires_at)
+      VALUES ($1, $2, $3, $4, $5, $6, true, $7)
+    `;
+    await this._query(insertSql, [id, userId, token, userAgent, deviceName, ipAddress, expiresAt]);
+
+    return token;
+  }
+
+  /**
+   * Validate a session token against PostgreSQL database and users table.
+   * Seamlessly resolves v2 compound tokens (O(1) lookup by primary key id) and v1 tokens.
+   *
+   * @param {string} token
+   * @param {object} [options] Options: { updateActivity: boolean }
+   * @returns {Promise<object|null>}
+   */
+  async validateSession(token, options = {}) {
+    if (!token || typeof token !== 'string') return null;
+    const cleanToken = token.replace(/^Bearer\s+/i, '').trim();
+    if (!cleanToken) return null;
+
+    try {
+      const parsed = parseToken(cleanToken, this.options.tokenPrefix);
+      let sessionRes;
+
+      if (parsed.version === 2 && parsed.sessionId) {
+        // v2: Ultra-fast O(1) Primary Key lookup by id
+        const sql = `
+          SELECT s.id as session_id, s.user_id, s.token, s.is_active as session_active,
+                 s.expires_at, s.last_activity, s.device_name, s.ip_address,
+                 u.id as user_id, u.username, u.full_name, u.role, u.is_active as user_active,
+                 COALESCE(u.is_disabled, false) as user_disabled,
+                 u.employee_id, u.leader_id,
+                 u.permissions as user_permissions,
+                 r.permissions as role_permissions
+          FROM ${this.options.sessionsTable} s
+          JOIN ${this.options.usersTable} u ON u.id = s.user_id
+          LEFT JOIN ${this.options.rolesTable} r ON r.id = u.role OR r.name = u.role OR LOWER(r.name) = LOWER(u.role)
+          WHERE s.id = $1
+        `;
+        sessionRes = await this._query(sql, [parsed.sessionId]).catch(() => ({ rows: [] }));
+      } else {
+        // v1 (legacy): Direct token string matching
+        const sql = `
+          SELECT s.id as session_id, s.user_id, s.token, s.is_active as session_active,
+                 s.expires_at, s.last_activity, s.device_name, s.ip_address,
+                 u.id as user_id, u.username, u.full_name, u.role, u.is_active as user_active,
+                 COALESCE(u.is_disabled, false) as user_disabled,
+                 u.employee_id, u.leader_id,
+                 u.permissions as user_permissions,
+                 r.permissions as role_permissions
+          FROM ${this.options.sessionsTable} s
+          JOIN ${this.options.usersTable} u ON u.id = s.user_id
+          LEFT JOIN ${this.options.rolesTable} r ON r.id = u.role OR r.name = u.role OR LOWER(r.name) = LOWER(u.role)
+          WHERE s.token = $1
+        `;
+        sessionRes = await this._query(sql, [cleanToken]).catch(() => ({ rows: [] }));
+      }
+
+      if (sessionRes.rows && sessionRes.rows.length > 0) {
+        const row = sessionRes.rows[0];
+
+        // Security check: verify that row.token matches cleanToken
+        if (row.token !== cleanToken) {
+          return null;
+        }
+
+        const now = new Date();
+
+        // Check active status & expiration
+        if (!row.session_active || !row.user_active || row.user_disabled || new Date(row.expires_at) < now) {
+          return null;
+        }
+
+        // Check inactivity timeout
+        const inactTimeoutMs = await this.getInactivityTimeoutMs();
+        if (inactTimeoutMs > 0 && row.last_activity) {
+          const lastAct = new Date(row.last_activity).getTime();
+          if (now.getTime() - lastAct > inactTimeoutMs) {
+            this._query(`UPDATE ${this.options.sessionsTable} SET is_active = false WHERE id = $1`, [row.session_id]).catch(() => {});
+            return null;
+          }
+        }
+
+        // Asynchronously update last_activity
+        if (options.updateActivity !== false) {
+          this._query(`UPDATE ${this.options.sessionsTable} SET last_activity = NOW() WHERE id = $1`, [row.session_id]).catch(() => {});
+        }
+
+        return {
+          valid: true,
+          userId: row.user_id,
+          sessionId: row.session_id,
+          token: cleanToken,
+          role: row.role,
+          employeeId: row.employee_id || null,
+          leaderId: row.leader_id || null,
+          userPermissions: row.user_permissions || {},
+          rolePermissions: row.role_permissions || {},
+          user: {
+            id: row.user_id,
+            username: row.username,
+            fullName: row.full_name,
+            role: row.role,
+            employeeId: row.employee_id,
+            leaderId: row.leader_id,
+          },
+        };
+      }
+
+      // Legacy JWT fallback if enabled
+      if (this.options.jwtSecret) {
+        try {
+          const jwtModule = typeof require === 'function' ? require('jsonwebtoken') : null;
+          if (jwtModule) {
+            const decoded = jwtModule.verify(cleanToken, this.options.jwtSecret);
+            if (decoded && (decoded.userId || decoded.id)) {
+              const uId = decoded.userId || decoded.id;
+              const uRes = await this._query(
+                `SELECT u.id, u.username, u.full_name, u.role, u.is_active, COALESCE(u.is_disabled, false) as is_disabled,
+                        u.employee_id, u.leader_id, u.permissions as user_permissions, r.permissions as role_permissions
+                 FROM ${this.options.usersTable} u
+                 LEFT JOIN ${this.options.rolesTable} r ON r.id = u.role OR r.name = u.role OR LOWER(r.name) = LOWER(u.role)
+                 WHERE u.id = $1`,
+                [uId]
+              ).catch(() => ({ rows: [] }));
+
+              if (uRes.rows && uRes.rows.length > 0 && uRes.rows[0].is_active && !uRes.rows[0].is_disabled) {
+                const uRow = uRes.rows[0];
+                return {
+                  valid: true,
+                  userId: uRow.id,
+                  sessionId: null,
+                  token: cleanToken,
+                  role: uRow.role || decoded.role,
+                  employeeId: uRow.employee_id || null,
+                  leaderId: uRow.leader_id || null,
+                  userPermissions: uRow.user_permissions || {},
+                  rolePermissions: uRow.role_permissions || {},
+                  user: {
+                    id: uRow.id,
+                    username: uRow.username,
+                    fullName: uRow.full_name,
+                    role: uRow.role || decoded.role,
+                    employeeId: uRow.employee_id,
+                    leaderId: uRow.leader_id,
+                  },
+                };
+              }
+            }
+          }
+        } catch {}
+      }
+
+      return null;
+    } catch (err) {
+      console.warn('[SessionManager validateSession error]:', err.message);
+      return null;
+    }
+  }
+
+  /**
+   * Lock a session screen.
+   *
+   * @param {string} sessionIdOrToken Session ID or Token
+   * @returns {Promise<{ ok: boolean, sessionId: string, userId: string, token: string } | null>}
+   */
+  async lockSession(sessionIdOrToken) {
+    if (!sessionIdOrToken) return null;
+    const parsed = parseToken(sessionIdOrToken, this.options.tokenPrefix);
+    const idToUse = parsed.sessionId || sessionIdOrToken;
+
+    const sql = `
+      UPDATE ${this.options.sessionsTable}
+      SET is_locked = true, locked_at = NOW()
+      WHERE (id = $1 OR token = $1) AND is_active = true
+      RETURNING id, user_id, token
+    `;
+    const r = await this._query(sql, [idToUse]);
+    if (r.rows && r.rows.length > 0) {
+      const row = r.rows[0];
+      return { ok: true, sessionId: row.id, userId: row.user_id, token: row.token };
+    }
+    return null;
+  }
+
+  /**
+   * Unlock a session screen.
+   *
+   * @param {string} sessionIdOrToken Session ID or Token
+   * @returns {Promise<{ ok: boolean, sessionId: string, userId: string, token: string } | null>}
+   */
+  async unlockSession(sessionIdOrToken) {
+    if (!sessionIdOrToken) return null;
+    const parsed = parseToken(sessionIdOrToken, this.options.tokenPrefix);
+    const idToUse = parsed.sessionId || sessionIdOrToken;
+
+    const sql = `
+      UPDATE ${this.options.sessionsTable}
+      SET is_locked = false, locked_at = NULL
+      WHERE (id = $1 OR token = $1) AND is_active = true
+      RETURNING id, user_id, token
+    `;
+    const r = await this._query(sql, [idToUse]);
+    if (r.rows && r.rows.length > 0) {
+      const row = r.rows[0];
+      return { ok: true, sessionId: row.id, userId: row.user_id, token: row.token };
+    }
+    return null;
+  }
+
+  /**
+   * Terminate/revoke a single session.
+   *
+   * @param {string} sessionIdOrToken Session ID or Token
+   * @returns {Promise<{ ok: boolean, sessionId: string, userId: string, token: string } | null>}
+   */
+  async terminateSession(sessionIdOrToken) {
+    if (!sessionIdOrToken) return null;
+    const parsed = parseToken(sessionIdOrToken, this.options.tokenPrefix);
+    const idToUse = parsed.sessionId || sessionIdOrToken;
+
+    const sql = `
+      UPDATE ${this.options.sessionsTable}
+      SET is_active = false
+      WHERE id = $1 OR token = $1
+      RETURNING id, user_id, token
+    `;
+    const r = await this._query(sql, [idToUse]);
+    if (r.rows && r.rows.length > 0) {
+      const row = r.rows[0];
+      return { ok: true, sessionId: row.id, userId: row.user_id, token: row.token };
+    }
+    return null;
+  }
+
+  /**
+   * Terminate all other sessions except the current one.
+   *
+   * @param {string} currentSessionIdOrToken Current session ID or token to preserve
+   * @param {string|number} [currentUserId]
+   * @param {boolean} [protectSuperAdmin=true]
+   * @returns {Promise<Array<{ sessionId: string, userId: string, token: string }>>}
+   */
+  async terminateOtherSessions(currentSessionIdOrToken, currentUserId = null, protectSuperAdmin = true) {
+    const parsed = parseToken(currentSessionIdOrToken, this.options.tokenPrefix);
+    const preserveId = parsed.sessionId || currentSessionIdOrToken;
+
+    let whereClause = `id != $1 AND token != $1`;
+    let params = [preserveId];
+
+    if (currentUserId) {
+      whereClause += ` AND user_id = $2`;
+      params.push(currentUserId);
+    } else if (protectSuperAdmin) {
+      whereClause += ` AND user_id NOT IN (SELECT id FROM ${this.options.usersTable} WHERE LOWER(COALESCE(role, '')) = '${this.options.superRole}' OR LOWER(username) = '${this.options.superRole}')`;
+    }
+
+    const sql = `
+      UPDATE ${this.options.sessionsTable}
+      SET is_active = false
+      WHERE ${whereClause} AND is_active = true
+      RETURNING id, user_id, token
+    `;
+    const r = await this._query(sql, params);
+    return (r.rows || []).map(row => ({
+      sessionId: row.id,
+      userId: row.user_id,
+      token: row.token,
+    }));
+  }
+
+  /**
+   * Terminate all active sessions for a specific user.
+   *
+   * @param {string|number} userId
+   * @returns {Promise<Array<{ sessionId: string, userId: string, token: string }>>}
+   */
+  async terminateUserSessions(userId) {
+    if (!userId) return [];
+    const sql = `
+      UPDATE ${this.options.sessionsTable}
+      SET is_active = false
+      WHERE user_id = $1 AND is_active = true
+      RETURNING id, user_id, token
+    `;
+    const r = await this._query(sql, [userId]);
+    return (r.rows || []).map(row => ({
+      sessionId: row.id,
+      userId: row.user_id,
+      token: row.token,
+    }));
+  }
+
+  /**
+   * Aliases for backward compatibility.
+   */
+  async revokeSession(tokenOrId) {
+    return this.terminateSession(tokenOrId);
+  }
+
+  async revokeAllUserSessions(userId) {
+    return this.terminateUserSessions(userId);
+  }
+}
+
+/**
+ * Universal Factory.
+ */
+export function createSessionManager(options) {
+  return new SessionManager(options);
+}
+
+export default {
+  SessionManager,
+  createSessionManager,
+  formatToken,
+  parseToken,
+  getSessionId,
+  extractToken,
+};