s3db.js 13.4.0 → 13.6.0

package/src/plugins/identity/session-manager.js

@@ -0,0 +1,453 @@
+/**
+ * Session Manager - Handles user sessions for Identity Provider
+ *
+ * Manages session lifecycle using S3DB resource as storage:
+ * - Create/validate/destroy sessions
+ * - Cookie-based session handling
+ * - Automatic session cleanup (expired sessions)
+ * - IP address and user agent tracking
+ */
+
+import { generateSessionId, calculateExpiration, isExpired } from './concerns/token-generator.js';
+import tryFn from '../../concerns/try-fn.js';
+
+/**
+ * Default session configuration
+ */
+const DEFAULT_CONFIG = {
+  sessionExpiry: '24h',           // Default: 24 hours
+  cookieName: 's3db_session',     // Cookie name
+  cookiePath: '/',                // Cookie path
+  cookieHttpOnly: true,           // HTTP-only cookie (no JS access)
+  cookieSecure: false,            // Secure cookie (HTTPS only) - set to true in production
+  cookieSameSite: 'Lax',          // SameSite attribute ('Strict', 'Lax', 'None')
+  cleanupInterval: 3600000,       // Cleanup interval: 1 hour (in ms)
+  enableCleanup: true             // Enable automatic cleanup
+};
+
+/**
+ * SessionManager class
+ * @class
+ */
+export class SessionManager {
+  /**
+   * Create Session Manager
+   * @param {Object} options - Configuration options
+   * @param {Object} options.sessionResource - S3DB sessions resource
+   * @param {Object} [options.config] - Session configuration
+   */
+  constructor(options = {}) {
+    this.sessionResource = options.sessionResource;
+    this.config = { ...DEFAULT_CONFIG, ...options.config };
+
+    this.cleanupTimer = null;
+
+    if (!this.sessionResource) {
+      throw new Error('SessionManager requires a sessionResource');
+    }
+
+    // Start automatic cleanup
+    if (this.config.enableCleanup) {
+      this._startCleanup();
+    }
+  }
+
+  /**
+   * Create a new session
+   * @param {Object} data - Session data
+   * @param {string} data.userId - User ID
+   * @param {Object} [data.metadata] - Additional session metadata
+   * @param {string} [data.ipAddress] - Client IP address
+   * @param {string} [data.userAgent] - Client user agent
+   * @param {string} [duration] - Session duration (overrides default)
+   * @returns {Promise<{sessionId: string, expiresAt: number, session: Object}>}
+   */
+  async createSession(data) {
+    const { userId, metadata = {}, ipAddress, userAgent, duration } = data;
+
+    if (!userId) {
+      throw new Error('userId is required to create a session');
+    }
+
+    // Generate session ID
+    const sessionId = generateSessionId();
+
+    // Calculate expiration
+    const expiresAt = calculateExpiration(duration || this.config.sessionExpiry);
+
+    // Create session record
+    const sessionData = {
+      userId,
+      expiresAt: new Date(expiresAt).toISOString(),
+      ipAddress: ipAddress || null,
+      userAgent: userAgent || null,
+      metadata,
+      createdAt: new Date().toISOString()
+    };
+
+    // Insert into S3DB
+    const [ok, err, session] = await tryFn(() =>
+      this.sessionResource.insert(sessionData)
+    );
+
+    if (!ok) {
+      throw new Error(`Failed to create session: ${err.message}`);
+    }
+
+    return {
+      sessionId: session.id, // S3DB auto-generated ID
+      expiresAt,
+      session
+    };
+  }
+
+  /**
+   * Validate a session
+   * @param {string} sessionId - Session ID to validate
+   * @returns {Promise<{valid: boolean, session: Object|null, reason: string|null}>}
+   */
+  async validateSession(sessionId) {
+    if (!sessionId) {
+      return { valid: false, session: null, reason: 'No session ID provided' };
+    }
+
+    // Fetch session from S3DB
+    const [ok, err, session] = await tryFn(() =>
+      this.sessionResource.get(sessionId)
+    );
+
+    if (!ok || !session) {
+      return { valid: false, session: null, reason: 'Session not found' };
+    }
+
+    // Check if session is expired
+    if (isExpired(session.expiresAt)) {
+      // Delete expired session
+      await this.destroySession(sessionId);
+      return { valid: false, session: null, reason: 'Session expired' };
+    }
+
+    return { valid: true, session, reason: null };
+  }
+
+  /**
+   * Get session data without validation
+   * @param {string} sessionId - Session ID
+   * @returns {Promise<Object|null>} Session object or null
+   */
+  async getSession(sessionId) {
+    if (!sessionId) {
+      return null;
+    }
+
+    const [ok, , session] = await tryFn(() =>
+      this.sessionResource.get(sessionId)
+    );
+
+    return ok ? session : null;
+  }
+
+  /**
+   * Update session metadata
+   * @param {string} sessionId - Session ID
+   * @param {Object} metadata - New metadata to merge
+   * @returns {Promise<Object>} Updated session
+   */
+  async updateSession(sessionId, metadata) {
+    if (!sessionId) {
+      throw new Error('sessionId is required');
+    }
+
+    const session = await this.getSession(sessionId);
+
+    if (!session) {
+      throw new Error('Session not found');
+    }
+
+    const updatedMetadata = { ...session.metadata, ...metadata };
+
+    const [ok, err, updated] = await tryFn(() =>
+      this.sessionResource.update(sessionId, {
+        metadata: updatedMetadata
+      })
+    );
+
+    if (!ok) {
+      throw new Error(`Failed to update session: ${err.message}`);
+    }
+
+    return updated;
+  }
+
+  /**
+   * Destroy a session (logout)
+   * @param {string} sessionId - Session ID to destroy
+   * @returns {Promise<boolean>} True if session was destroyed
+   */
+  async destroySession(sessionId) {
+    if (!sessionId) {
+      return false;
+    }
+
+    const [ok] = await tryFn(() =>
+      this.sessionResource.delete(sessionId)
+    );
+
+    return ok;
+  }
+
+  /**
+   * Destroy all sessions for a user (logout all devices)
+   * @param {string} userId - User ID
+   * @returns {Promise<number>} Number of sessions destroyed
+   */
+  async destroyUserSessions(userId) {
+    if (!userId) {
+      return 0;
+    }
+
+    // Query all sessions for user
+    const [ok, , sessions] = await tryFn(() =>
+      this.sessionResource.query({ userId })
+    );
+
+    if (!ok || !sessions || sessions.length === 0) {
+      return 0;
+    }
+
+    // Delete all sessions
+    let count = 0;
+    for (const session of sessions) {
+      const destroyed = await this.destroySession(session.id);
+      if (destroyed) count++;
+    }
+
+    return count;
+  }
+
+  /**
+   * Get all active sessions for a user
+   * @param {string} userId - User ID
+   * @returns {Promise<Array>} Array of active sessions
+   */
+  async getUserSessions(userId) {
+    if (!userId) {
+      return [];
+    }
+
+    const [ok, , sessions] = await tryFn(() =>
+      this.sessionResource.query({ userId })
+    );
+
+    if (!ok || !sessions) {
+      return [];
+    }
+
+    // Filter out expired sessions
+    const activeSessions = [];
+    for (const session of sessions) {
+      if (!isExpired(session.expiresAt)) {
+        activeSessions.push(session);
+      } else {
+        // Clean up expired session
+        await this.destroySession(session.id);
+      }
+    }
+
+    return activeSessions;
+  }
+
+  /**
+   * Set session cookie in HTTP response
+   * @param {Object} res - HTTP response object (Express/Hono style)
+   * @param {string} sessionId - Session ID
+   * @param {number} expiresAt - Expiration timestamp (Unix ms)
+   */
+  setSessionCookie(res, sessionId, expiresAt) {
+    const expires = new Date(expiresAt);
+
+    const cookieOptions = [
+      `${this.config.cookieName}=${sessionId}`,
+      `Path=${this.config.cookiePath}`,
+      `Expires=${expires.toUTCString()}`,
+      `Max-Age=${Math.floor((expiresAt - Date.now()) / 1000)}`
+    ];
+
+    if (this.config.cookieHttpOnly) {
+      cookieOptions.push('HttpOnly');
+    }
+
+    if (this.config.cookieSecure) {
+      cookieOptions.push('Secure');
+    }
+
+    if (this.config.cookieSameSite) {
+      cookieOptions.push(`SameSite=${this.config.cookieSameSite}`);
+    }
+
+    const cookieValue = cookieOptions.join('; ');
+
+    // Set cookie header
+    if (typeof res.setHeader === 'function') {
+      // Express-style
+      res.setHeader('Set-Cookie', cookieValue);
+    } else if (typeof res.header === 'function') {
+      // Hono-style
+      res.header('Set-Cookie', cookieValue);
+    } else {
+      throw new Error('Unsupported response object');
+    }
+  }
+
+  /**
+   * Clear session cookie in HTTP response
+   * @param {Object} res - HTTP response object
+   */
+  clearSessionCookie(res) {
+    const cookieOptions = [
+      `${this.config.cookieName}=`,
+      `Path=${this.config.cookiePath}`,
+      'Expires=Thu, 01 Jan 1970 00:00:00 GMT',
+      'Max-Age=0'
+    ];
+
+    if (this.config.cookieHttpOnly) {
+      cookieOptions.push('HttpOnly');
+    }
+
+    if (this.config.cookieSecure) {
+      cookieOptions.push('Secure');
+    }
+
+    if (this.config.cookieSameSite) {
+      cookieOptions.push(`SameSite=${this.config.cookieSameSite}`);
+    }
+
+    const cookieValue = cookieOptions.join('; ');
+
+    if (typeof res.setHeader === 'function') {
+      res.setHeader('Set-Cookie', cookieValue);
+    } else if (typeof res.header === 'function') {
+      res.header('Set-Cookie', cookieValue);
+    }
+  }
+
+  /**
+   * Get session ID from HTTP request cookies
+   * @param {Object} req - HTTP request object
+   * @returns {string|null} Session ID or null
+   */
+  getSessionIdFromRequest(req) {
+    // Parse cookies from request
+    const cookieHeader = req.headers?.cookie || req.header?.('cookie');
+
+    if (!cookieHeader) {
+      return null;
+    }
+
+    const cookies = cookieHeader.split(';').reduce((acc, cookie) => {
+      const [key, value] = cookie.trim().split('=');
+      acc[key] = value;
+      return acc;
+    }, {});
+
+    return cookies[this.config.cookieName] || null;
+  }
+
+  /**
+   * Cleanup expired sessions
+   * @returns {Promise<number>} Number of sessions cleaned up
+   */
+  async cleanupExpiredSessions() {
+    // List all sessions
+    const [ok, , sessions] = await tryFn(() =>
+      this.sessionResource.list({ limit: 1000 })
+    );
+
+    if (!ok || !sessions) {
+      return 0;
+    }
+
+    let count = 0;
+    for (const session of sessions) {
+      if (isExpired(session.expiresAt)) {
+        const destroyed = await this.destroySession(session.id);
+        if (destroyed) count++;
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * Start automatic cleanup of expired sessions
+   * @private
+   */
+  _startCleanup() {
+    if (this.cleanupTimer) {
+      return; // Already running
+    }
+
+    this.cleanupTimer = setInterval(async () => {
+      try {
+        const count = await this.cleanupExpiredSessions();
+        if (count > 0) {
+          console.log(`[SessionManager] Cleaned up ${count} expired sessions`);
+        }
+      } catch (error) {
+        console.error('[SessionManager] Cleanup error:', error.message);
+      }
+    }, this.config.cleanupInterval);
+  }
+
+  /**
+   * Stop automatic cleanup
+   */
+  stopCleanup() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  /**
+   * Get session statistics
+   * @returns {Promise<Object>} Session statistics
+   */
+  async getStatistics() {
+    const [ok, , sessions] = await tryFn(() =>
+      this.sessionResource.list({ limit: 10000 })
+    );
+
+    if (!ok || !sessions) {
+      return {
+        total: 0,
+        active: 0,
+        expired: 0,
+        users: 0
+      };
+    }
+
+    let active = 0;
+    let expired = 0;
+    const uniqueUsers = new Set();
+
+    for (const session of sessions) {
+      if (isExpired(session.expiresAt)) {
+        expired++;
+      } else {
+        active++;
+        uniqueUsers.add(session.userId);
+      }
+    }
+
+    return {
+      total: sessions.length,
+      active,
+      expired,
+      users: uniqueUsers.size
+    };
+  }
+}
+
+export default SessionManager;

package/src/plugins/identity/ui/layouts/base.js

@@ -0,0 +1,251 @@
+/**
+ * Base HTML Layout for Identity Provider UI
+ * Uses Hono's html helper for server-side rendering
+ */
+
+import { html } from 'hono/html';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read CSS file once at module load
+const cssPath = join(__dirname, '../styles/main.css');
+let cachedCSS = null;
+
+function getCSS() {
+  if (!cachedCSS) {
+    cachedCSS = readFileSync(cssPath, 'utf-8');
+  }
+  return cachedCSS;
+}
+
+/**
+ * Convert hex colors to rgba for translucent gradients
+ * @param {string} hex - Hex color (#fff or #ffffff)
+ * @param {number} alpha - Alpha channel value between 0 and 1
+ * @returns {string} rgba(...) string
+ */
+function hexToRgba(hex, alpha = 1) {
+  if (!hex || typeof hex !== 'string') {
+    return `rgba(0, 0, 0, ${alpha})`;
+  }
+
+  const normalized = hex.replace('#', '');
+  if (![3, 6].includes(normalized.length)) {
+    return `rgba(0, 0, 0, ${alpha})`;
+  }
+
+  const full = normalized.length === 3
+    ? normalized.split('').map(char => `${char}${char}`).join('')
+    : normalized;
+
+  const r = parseInt(full.slice(0, 2), 16);
+  const g = parseInt(full.slice(2, 4), 16);
+  const b = parseInt(full.slice(4, 6), 16);
+
+  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) {
+    return `rgba(0, 0, 0, ${alpha})`;
+  }
+
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+/**
+ * Base layout component
+ * @param {Object} props - Layout properties
+ * @param {string} props.title - Page title
+ * @param {string} props.content - Page content (HTML string)
+ * @param {Object} [props.user] - Authenticated user (if logged in)
+ * @param {Object} [props.config] - UI configuration (title, logo, etc.)
+ * @param {string} [props.error] - Error message to display
+ * @param {string} [props.success] - Success message to display
+ * @returns {string} HTML string
+ */
+export function BaseLayout(props) {
+  const {
+    title = 'Identity Provider',
+    content = '',
+    user = null,
+    config = {},
+    error = null,
+    success = null
+  } = props;
+
+  // Theme configuration with defaults
+  const theme = {
+    title: config.title || 'S3DB Identity',
+    logo: config.logo || null,
+    logoUrl: config.logoUrl || null,
+    favicon: config.favicon || null,
+    registrationEnabled: config.registrationEnabled !== false,  // Show register link
+
+    // Colors
+    primaryColor: config.primaryColor || '#007bff',
+    secondaryColor: config.secondaryColor || '#6c757d',
+    successColor: config.successColor || '#28a745',
+    dangerColor: config.dangerColor || '#dc3545',
+    warningColor: config.warningColor || '#ffc107',
+    infoColor: config.infoColor || '#17a2b8',
+
+    // Text colors
+    textColor: config.textColor || '#212529',
+    textMuted: config.textMuted || '#6c757d',
+
+    // Background colors
+    backgroundColor: config.backgroundColor || '#ffffff',
+    backgroundLight: config.backgroundLight || '#f8f9fa',
+    borderColor: config.borderColor || '#dee2e6',
+
+    // Typography
+    fontFamily: config.fontFamily || '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+    fontSize: config.fontSize || '16px',
+
+    // Layout
+    borderRadius: config.borderRadius || '0.375rem',
+    boxShadow: config.boxShadow || '0 0.125rem 0.25rem rgba(0, 0, 0, 0.075)',
+
+    // Company info
+    companyName: config.companyName || 'S3DB',
+    legalName: config.legalName || config.companyName || 'S3DB Corp',
+    tagline: config.tagline || 'Secure Identity & Access Management',
+    welcomeMessage: config.welcomeMessage || 'Welcome back!',
+    footerText: config.footerText || null,
+    supportEmail: config.supportEmail || null,
+    privacyUrl: config.privacyUrl || '/privacy',
+    termsUrl: config.termsUrl || '/terms',
+
+    // Social links
+    socialLinks: config.socialLinks || null,
+
+    // Custom CSS
+    customCSS: config.customCSS || null
+  };
+
+  const primaryGlow = hexToRgba(theme.primaryColor, 0.28);
+  const secondaryGlow = hexToRgba(theme.secondaryColor, 0.22);
+  const surfaceGlow = hexToRgba(theme.backgroundLight, 0.65);
+
+  // Build dynamic CSS variables
+  const themeCSS = `
+    :root {
+      --color-primary: ${theme.primaryColor};
+      --color-secondary: ${theme.secondaryColor};
+      --color-success: ${theme.successColor};
+      --color-danger: ${theme.dangerColor};
+      --color-warning: ${theme.warningColor};
+      --color-info: ${theme.infoColor};
+
+      --color-text: ${theme.textColor};
+      --color-text-muted: ${theme.textMuted};
+
+      --color-bg: ${theme.backgroundColor};
+      --color-light: ${theme.backgroundLight};
+      --color-border: ${theme.borderColor};
+      --color-card-bg: ${theme.backgroundLight};
+      --color-primary-glow: ${primaryGlow};
+      --color-secondary-glow: ${secondaryGlow};
+      --color-surface-glow: ${surfaceGlow};
+
+      --font-family: ${theme.fontFamily};
+      --font-size-base: ${theme.fontSize};
+
+      --border-radius: ${theme.borderRadius};
+      --box-shadow: ${theme.boxShadow};
+    }
+  `;
+
+  const backgroundGradient = `
+    radial-gradient(circle at 12% 18%, ${primaryGlow} 0%, transparent 52%),
+    radial-gradient(circle at 88% 16%, ${secondaryGlow} 0%, transparent 55%),
+    linear-gradient(160deg, ${theme.backgroundColor} 0%, ${theme.backgroundLight} 55%, ${theme.backgroundColor} 100%)
+  `;
+
+  const flashContainer = (error || success) ? html`
+    <div class="mx-auto mb-8 w-full max-w-3xl space-y-3">
+      ${error ? html`
+        <div class="rounded-2xl border border-red-500/40 bg-red-500/15 px-4 py-3 text-sm leading-6 text-red-100 shadow-lg shadow-red-900/30 backdrop-blur">
+          ${error}
+        </div>
+      ` : ''}
+      ${success ? html`
+        <div class="rounded-2xl border border-emerald-400/40 bg-emerald-500/15 px-4 py-3 text-sm leading-6 text-emerald-100 shadow-lg shadow-emerald-900/25 backdrop-blur">
+          ${success}
+        </div>
+      ` : ''}
+    </div>
+  ` : '';
+
+  return html`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no">
+  <meta http-equiv="x-ua-compatible" content="ie=edge">
+  <meta name="description" content="${theme.tagline}">
+  <title>${title} - ${theme.title}</title>
+
+  ${theme.favicon ? html`
+    <link rel="shortcut icon" href="${theme.favicon}">
+    <link rel="icon" href="${theme.favicon}">
+  ` : ''}
+
+  <script>
+    window.tailwind = window.tailwind || {};
+    window.tailwind.config = {
+      darkMode: 'class',
+      theme: {
+        extend: {
+          colors: {
+            primary: 'var(--color-primary)',
+            secondary: 'var(--color-secondary)',
+            surface: 'var(--color-card-bg)'
+          },
+          fontFamily: {
+            display: ['var(--font-family)'],
+            body: ['var(--font-family)']
+          },
+          boxShadow: {
+            surface: 'var(--box-shadow)'
+          }
+        }
+      }
+    };
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
+
+  <!-- Custom Styles -->
+  <style>${themeCSS}</style>
+  <style>${getCSS()}</style>
+  ${theme.customCSS ? html`<style>${theme.customCSS}</style>` : ''}
+</head>
+<body class="min-h-screen bg-slate-950 antialiased text-white">
+  <div
+    class="relative flex min-h-screen flex-col overflow-hidden"
+    style="
+      background-image: ${backgroundGradient};
+      background-attachment: fixed;
+      background-size: cover;
+      color: ${theme.textColor};
+      font-family: ${theme.fontFamily};
+      font-size: ${theme.fontSize};
+    "
+  >
+    <div class="pointer-events-none absolute inset-0 overflow-hidden">
+      <div class="absolute -left-20 top-[10%] h-64 w-64 rounded-full blur-[120px]" style="background: ${primaryGlow}; opacity: 0.85;"></div>
+      <div class="absolute right-[-15%] top-[5%] h-72 w-72 rounded-full blur-[120px]" style="background: ${secondaryGlow}; opacity: 0.65;"></div>
+      <div class="absolute left-1/2 top-[65%] h-96 w-[36rem] -translate-x-1/2 rounded-[200px] blur-[160px]" style="background: ${surfaceGlow}; opacity: 0.35;"></div>
+    </div>
+
+    <main class="relative z-10 flex flex-1 items-stretch justify-center">
+      ${flashContainer}
+      ${content}
+    </main>
+  </div>
+</body>
+</html>`;
+}
+
+export default BaseLayout;