@plyaz/auth 1.0.0

package/src/session/enhanced-session-manager.ts

@@ -0,0 +1,406 @@
+/**
+ * @fileoverview Enhanced session manager for @plyaz/auth
+ * @module @plyaz/auth/session/enhanced-session-manager
+ * 
+ * @description
+ * Enhanced session manager that implements all documented session management
+ * methods. Provides comprehensive session lifecycle management including
+ * CSRF token generation, concurrent session detection, and session validation.
+ * Uses pluggable session stores for flexible storage backends.
+ * 
+ * @example
+ * ```typescript
+ * import { EnhancedSessionManager, MemoryStore } from '@plyaz/auth';
+ * 
+ * const sessionManager = new EnhancedSessionManager({
+ *   store: new MemoryStore(),
+ *   sessionTTL: 3600,
+ *   maxConcurrentSessions: 5
+ * });
+ * 
+ * const session = await sessionManager.createSession(userContext, sessionData);
+ * ```
+ */
+
+
+import type { Session, SessionData, SessionStore } from '@plyaz/types';
+import { randomBytes } from 'crypto';
+import { CSRFProtection } from '../security';
+import { NUMERIX } from '@plyaz/config';
+
+/**
+ * User context for session creation
+ */
+export interface UserContext {
+  /** User ID */
+  userId: string;
+  /** User email */
+  email?: string;
+  /** User roles */
+  roles?: string[];
+  /** Additional user metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Session creation data
+ */
+export interface SessionCreationData {
+  /** IP address */
+  ipAddress?: string;
+  /** User agent string */
+  userAgent?: string;
+  /** Device information */
+  deviceInfo?: Record<string, unknown>;
+  /** Additional session metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Enhanced session manager configuration
+ */
+export interface EnhancedSessionManagerConfig {
+  /** Session store implementation */
+  store: SessionStore;
+  /** Default session TTL in seconds */
+  sessionTTL: number;
+  /** Maximum concurrent sessions per user */
+  maxConcurrentSessions: number;
+  /** Enable CSRF protection */
+  enableCSRF: boolean;
+  /** CSRF token TTL in seconds */
+  csrfTTL: number;
+  /** Enable session refresh */
+  enableRefresh: boolean;
+  /** Session refresh threshold (seconds before expiry) */
+  refreshThreshold: number;
+}
+
+/**
+ * Enhanced session manager implementation
+ * Provides comprehensive session management with all documented methods
+ */
+export class EnhancedSessionManager {
+  private readonly config: EnhancedSessionManagerConfig;
+  private readonly store: SessionStore;
+  private readonly csrfProtection: CSRFProtection;
+
+  constructor(config: Partial<EnhancedSessionManagerConfig> & { store: SessionStore }) {
+    this.config = {
+      sessionTTL: 3600,
+      maxConcurrentSessions: 5,
+      enableCSRF: true,
+      csrfTTL: 3600,
+      enableRefresh: true,
+      refreshThreshold: 300, // 5 minutes
+      ...config
+    };
+
+    this.store = config.store;
+    this.csrfProtection = new CSRFProtection();
+  }
+
+  /**
+   * Create a new session
+   * Generate session ID, store data, set expiry, generate CSRF token
+   * @param userContext - User context information
+   * @param sessionData - Session creation data
+   * @returns Created session
+   */
+  async createSession(userContext: UserContext, sessionData: SessionCreationData = {}): Promise<Session> {
+    // Generate unique session ID
+    const sessionId = this.generateSessionId();
+    
+    // Enforce session limits
+    await this.enforceSessionLimits(userContext.userId);
+
+    // Create session data
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + this.config.sessionTTL * NUMERIX.THOUSAND);
+    
+    const session: SessionData = {
+      id: sessionId,
+      userId: userContext.userId,
+      expiresAt,
+      createdAt: now,
+      lastActivityAt: now,
+      ipAddress: sessionData.ipAddress,
+      userAgent: sessionData.userAgent,
+      metadata: {
+        ...sessionData.metadata,
+        deviceInfo: sessionData.deviceInfo,
+        userRoles: userContext.roles,
+        userEmail: userContext.email
+      }
+    };
+
+    // Store session
+    await this.store.set(sessionId, session, this.config.sessionTTL);
+
+    // Generate CSRF token if enabled
+    let csrfToken: string | undefined;
+    if (this.config.enableCSRF) {
+      csrfToken = this.csrfProtection.generateToken(sessionId);
+    }
+
+    return {
+      id: sessionId,
+      userId: userContext.userId,
+      provider: 'enhanced-session-manager',
+      providerSessionId: sessionId,
+      expiresAt,
+      createdAt: now,
+      lastActivityAt: now,
+      ipAddress: sessionData.ipAddress,
+      userAgent: sessionData.userAgent,
+      metadata: {
+        ...session.metadata,
+        csrfToken
+      }
+    };
+  }
+
+  /**
+   * Retrieve session by ID
+   * @param sessionId - Session identifier
+   * @returns Session or null if not found
+   */
+  async getSession(sessionId: string): Promise<Session | null> {
+    const sessionData = await this.store.get(sessionId);
+    
+    if (!sessionData) {
+      return null;
+    }
+
+    return this.mapSessionDataToSession(sessionData);
+  }
+
+  /**
+   * Update session data
+   * @param sessionId - Session identifier
+   * @param updates - Partial session updates
+   * @returns Updated session
+   */
+  async updateSession(sessionId: string, updates: Partial<SessionData>): Promise<Session> {
+    const existingSession = await this.store.get(sessionId);
+    
+    if (!existingSession) {
+      throw new Error('Session not found');
+    }
+
+    // Merge updates
+    const updatedSession: SessionData = {
+      ...existingSession,
+      ...updates,
+      lastActivityAt: new Date()
+    };
+
+    // Calculate remaining TTL
+    const remainingTTL = Math.max(0, Math.floor((updatedSession.expiresAt.getTime() - Date.now()) / NUMERIX.THOUSAND));
+    
+    if (remainingTTL <= 0) {
+      throw new Error('Session has expired');
+    }
+
+    // Store updated session
+    await this.store.set(sessionId, updatedSession, remainingTTL);
+
+    return this.mapSessionDataToSession(updatedSession);
+  }
+
+  /**
+   * Delete session
+   * @param sessionId - Session identifier
+   */
+  async deleteSession(sessionId: string): Promise<void> {
+    await this.store.delete(sessionId);
+    
+    // Remove CSRF token if enabled
+    if (this.config.enableCSRF) {
+      this.csrfProtection.removeToken(sessionId);
+    }
+  }
+
+  /**
+   * Refresh session (extend expiry)
+   * @param sessionId - Session identifier
+   * @returns Refreshed session
+   */
+  async refreshSession(sessionId: string): Promise<Session> {
+    const sessionData = await this.store.get(sessionId);
+    
+    if (!sessionData) {
+      throw new Error('Session not found');
+    }
+
+    // Extend expiry
+    const now = new Date();
+    const newExpiresAt = new Date(now.getTime() + this.config.sessionTTL * NUMERIX.THOUSAND);
+    
+    const refreshedSession: SessionData = {
+      ...sessionData,
+      expiresAt: newExpiresAt,
+      lastActivityAt: now
+    };
+
+    // Store refreshed session
+    await this.store.set(sessionId, refreshedSession, this.config.sessionTTL);
+
+    return this.mapSessionDataToSession(refreshedSession);
+  }
+
+  /**
+   * Validate session
+   * @param sessionId - Session identifier
+   * @returns True if session is valid
+   */
+  async validateSession(sessionId: string): Promise<boolean> {
+    const sessionData = await this.store.get(sessionId);
+    
+    if (!sessionData) {
+      return false;
+    }
+
+    // Check expiration
+    if (sessionData.expiresAt < new Date()) {
+      await this.deleteSession(sessionId);
+      return false;
+    }
+
+    // Update activity
+    await this.store.updateActivity(sessionId);
+
+    return true;
+  }
+
+  /**
+   * Invalidate all sessions for a user (logout all devices)
+   * @param userId - User identifier
+   */
+  async invalidateAllUserSessions(userId: string): Promise<void> {
+    await this.store.deleteByUserId(userId);
+  }
+
+  /**
+   * Detect concurrent sessions for a user
+   * @param userId - User identifier
+   * @returns Array of active sessions
+   */
+  async detectConcurrentSessions(userId: string): Promise<Session[]> {
+    const sessionDataArray = await this.store.getByUserId(userId);
+    
+    return sessionDataArray.map(sessionData => this.mapSessionDataToSession(sessionData));
+  }
+
+  /**
+   * Apply maximum session policy for a user
+   * @param userId - User identifier
+   */
+  async enforceSessionLimits(userId: string): Promise<void> {
+    const userSessions = await this.store.getByUserId(userId);
+    
+    if (userSessions.length >= this.config.maxConcurrentSessions) {
+      // Sort by last activity (oldest first)
+      userSessions.sort((a, b) => a.lastActivityAt.getTime() - b.lastActivityAt.getTime());
+      
+      // Remove oldest sessions to make room
+      const sessionsToRemove = userSessions.length - this.config.maxConcurrentSessions + 1;
+      for (let i = 0; i < sessionsToRemove; i++) {
+        await this.deleteSession(userSessions[i].id);
+      }
+    }
+  }
+
+  /**
+   * Generate CSRF token for session
+   * @param sessionId - Session identifier
+   * @returns CSRF token
+   */
+  async generateCsrfToken(sessionId: string): Promise<string> {
+    if (!this.config.enableCSRF) {
+      throw new Error('CSRF protection is disabled');
+    }
+
+    return this.csrfProtection.generateToken(sessionId);
+  }
+
+  /**
+   * Validate CSRF token for session
+   * @param sessionId - Session identifier
+   * @param token - CSRF token to validate
+   * @returns True if token is valid
+   */
+  async validateCsrfToken(sessionId: string, token: string): Promise<boolean> {
+    if (!this.config.enableCSRF) {
+      return true; // CSRF disabled, always valid
+    }
+
+    return this.csrfProtection.validateToken(sessionId, token);
+  }
+
+  /**
+   * Check if session needs refresh
+   * @param sessionId - Session identifier
+   * @returns True if session should be refreshed
+   */
+  async shouldRefreshSession(sessionId: string): Promise<boolean> {
+    if (!this.config.enableRefresh) {
+      return false;
+    }
+
+    const sessionData = await this.store.get(sessionId);
+    
+    if (!sessionData) {
+      return false;
+    }
+
+    const timeUntilExpiry = sessionData.expiresAt.getTime() - Date.now();
+    return timeUntilExpiry <= this.config.refreshThreshold * NUMERIX.THOUSAND;
+  }
+
+  /**
+   * Get session statistics
+   * @returns Session statistics
+   */
+  async getSessionStats(): Promise<{
+    totalSessions: number;
+    activeUsers: number;
+  }> {
+    // This would require additional tracking in a real implementation
+    return {
+      totalSessions: 0, // Would need to scan all sessions
+      activeUsers: 0    // Would need to count unique user IDs
+    };
+  }
+
+  /**
+   * Generate cryptographically secure session ID
+   * @returns Session ID
+   * @private
+   */
+  private generateSessionId(): string {
+    const randomBytesNumber = 32;
+    return randomBytes(randomBytesNumber).toString('hex');
+  }
+
+  /**
+   * Map session data to session interface
+   * @param sessionData - Session data from store
+   * @returns Session interface
+   * @private
+   */
+  private mapSessionDataToSession(sessionData: SessionData): Session {
+    return {
+      id: sessionData.id,
+      userId: sessionData.userId,
+      provider: 'enhanced-session-manager',
+      providerSessionId: sessionData.id,
+      expiresAt: sessionData.expiresAt,
+      createdAt: sessionData.createdAt,
+      lastActivityAt: sessionData.lastActivityAt,
+      ipAddress: sessionData.ipAddress,
+      userAgent: sessionData.userAgent,
+      metadata: sessionData.metadata
+    };
+  }
+}

package/src/session/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Session management barrel export for @plyaz/auth
+ * @module @plyaz/auth/session
+ * 
+ * @description
+ * Centralized export of all session management components including
+ * session stores, interfaces, and the enhanced session manager.
+ * Provides a single import point for all session-related functionality.
+ */
+
+export * from './cookie-store';
+export * from './memory-store';
+export * from './redis-store';
+export * from './enhanced-session-manager';