@veloxts/auth 0.3.3 → 0.3.4

package/dist/session.js

@@ -0,0 +1,795 @@
+/**
+ * Cookie-based Session Management for @veloxts/auth
+ *
+ * Provides server-side session storage with pluggable backends,
+ * secure session ID generation, and automatic session lifecycle management.
+ *
+ * Alternative to JWT authentication - users choose one or the other.
+ *
+ * @module auth/session
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { AuthError } from './types.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Session ID entropy in bytes (32 bytes = 256 bits)
+ * Provides sufficient entropy to prevent brute-force attacks
+ */
+const SESSION_ID_BYTES = 32;
+/**
+ * Minimum secret length for session ID signing (32 characters)
+ */
+const MIN_SECRET_LENGTH = 32;
+/**
+ * Default session TTL (24 hours in seconds)
+ */
+const DEFAULT_SESSION_TTL = 86400;
+/**
+ * Default cookie name
+ */
+const DEFAULT_COOKIE_NAME = 'velox.session';
+// ============================================================================
+// In-Memory Session Store
+// ============================================================================
+/**
+ * In-memory session store for development and testing
+ *
+ * WARNING: NOT suitable for production!
+ * - Sessions are lost on server restart
+ * - Does not work across multiple server instances
+ * - No persistence mechanism
+ *
+ * For production, use Redis or database-backed storage.
+ *
+ * @example
+ * ```typescript
+ * const store = createInMemorySessionStore();
+ *
+ * const sessionManager = createSessionManager({
+ *   store,
+ *   secret: process.env.SESSION_SECRET!,
+ * });
+ * ```
+ */
+export function createInMemorySessionStore() {
+    const sessions = new Map();
+    const userSessions = new Map();
+    /**
+     * Clean up expired sessions
+     */
+    function cleanup() {
+        const now = Date.now();
+        for (const [id, session] of sessions) {
+            if (session.expiresAt <= now) {
+                // Remove from user index
+                const userId = session.data.userId;
+                if (userId) {
+                    const userSessionSet = userSessions.get(userId);
+                    if (userSessionSet) {
+                        userSessionSet.delete(id);
+                        if (userSessionSet.size === 0) {
+                            userSessions.delete(userId);
+                        }
+                    }
+                }
+                sessions.delete(id);
+            }
+        }
+    }
+    // Run cleanup periodically (every 5 minutes)
+    const cleanupInterval = setInterval(cleanup, 5 * 60 * 1000);
+    // Don't prevent process exit
+    cleanupInterval.unref();
+    return {
+        get(sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session) {
+                return null;
+            }
+            // Check expiration
+            if (session.expiresAt <= Date.now()) {
+                sessions.delete(sessionId);
+                return null;
+            }
+            return session;
+        },
+        set(sessionId, session) {
+            // Track user sessions for getSessionsByUser
+            const existingSession = sessions.get(sessionId);
+            const oldUserId = existingSession?.data.userId;
+            const newUserId = session.data.userId;
+            // Update user index if userId changed
+            if (oldUserId && oldUserId !== newUserId) {
+                const oldSet = userSessions.get(oldUserId);
+                if (oldSet) {
+                    oldSet.delete(sessionId);
+                    if (oldSet.size === 0) {
+                        userSessions.delete(oldUserId);
+                    }
+                }
+            }
+            if (newUserId) {
+                let userSet = userSessions.get(newUserId);
+                if (!userSet) {
+                    userSet = new Set();
+                    userSessions.set(newUserId, userSet);
+                }
+                userSet.add(sessionId);
+            }
+            sessions.set(sessionId, session);
+        },
+        delete(sessionId) {
+            const session = sessions.get(sessionId);
+            if (session?.data.userId) {
+                const userSet = userSessions.get(session.data.userId);
+                if (userSet) {
+                    userSet.delete(sessionId);
+                    if (userSet.size === 0) {
+                        userSessions.delete(session.data.userId);
+                    }
+                }
+            }
+            sessions.delete(sessionId);
+        },
+        touch(sessionId, expiresAt) {
+            const session = sessions.get(sessionId);
+            if (session) {
+                session.expiresAt = expiresAt;
+                session.data._lastAccessedAt = Date.now();
+            }
+        },
+        clear() {
+            sessions.clear();
+            userSessions.clear();
+        },
+        getSessionsByUser(userId) {
+            const userSet = userSessions.get(userId);
+            return userSet ? [...userSet] : [];
+        },
+        deleteSessionsByUser(userId) {
+            const userSet = userSessions.get(userId);
+            if (userSet) {
+                for (const sessionId of userSet) {
+                    sessions.delete(sessionId);
+                }
+                userSessions.delete(userId);
+            }
+        },
+    };
+}
+// ============================================================================
+// Session ID Generation and Signing
+// ============================================================================
+/**
+ * Generate a cryptographically secure session ID
+ */
+function generateSessionId() {
+    const bytes = randomBytes(SESSION_ID_BYTES);
+    // Use base64url encoding for URL-safe session IDs
+    return bytes.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+/**
+ * Sign a session ID with HMAC-SHA256
+ */
+function signSessionId(sessionId, secret) {
+    const hmac = createHmac('sha256', secret);
+    hmac.update(sessionId);
+    const signature = hmac.digest('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+    return `${sessionId}.${signature}`;
+}
+/**
+ * Verify and extract session ID from signed value
+ * Uses timing-safe comparison to prevent timing attacks
+ */
+function verifySessionId(signedId, secret) {
+    const dotIndex = signedId.lastIndexOf('.');
+    if (dotIndex === -1) {
+        return null;
+    }
+    const sessionId = signedId.slice(0, dotIndex);
+    const signature = signedId.slice(dotIndex + 1);
+    // Recompute expected signature
+    const hmac = createHmac('sha256', secret);
+    hmac.update(sessionId);
+    const expectedSignature = hmac
+        .digest('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+    // Timing-safe comparison
+    const sigBuffer = Buffer.from(signature, 'utf8');
+    const expectedBuffer = Buffer.from(expectedSignature, 'utf8');
+    if (sigBuffer.length !== expectedBuffer.length) {
+        return null;
+    }
+    if (!timingSafeEqual(sigBuffer, expectedBuffer)) {
+        return null;
+    }
+    return sessionId;
+}
+/**
+ * Validate session ID entropy (prevent weak session IDs)
+ */
+function validateSessionIdEntropy(sessionId) {
+    // Session ID should be at least 32 bytes when decoded
+    // Our base64url encoding produces ~43 characters for 32 bytes
+    if (sessionId.length < 40) {
+        return false;
+    }
+    // Check for sufficient character variety (basic entropy check)
+    const uniqueChars = new Set(sessionId).size;
+    return uniqueChars >= 16;
+}
+// ============================================================================
+// Session Manager Implementation
+// ============================================================================
+/**
+ * Creates a session manager
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = createSessionManager({
+ *   secret: process.env.SESSION_SECRET!,
+ *   cookie: {
+ *     name: 'myapp.session',
+ *     secure: true,
+ *     sameSite: 'strict',
+ *   },
+ *   expiration: {
+ *     ttl: 3600, // 1 hour
+ *     sliding: true,
+ *   },
+ * });
+ * ```
+ */
+export function createSessionManager(config) {
+    // Validate secret
+    if (!config.secret || config.secret.length < MIN_SECRET_LENGTH) {
+        throw new Error(`Session secret must be at least ${MIN_SECRET_LENGTH} characters. ` +
+            'Generate with: openssl rand -base64 32');
+    }
+    // Validate secret entropy
+    const uniqueChars = new Set(config.secret).size;
+    if (uniqueChars < 16) {
+        throw new Error(`Session secret has insufficient entropy (only ${uniqueChars} unique characters). ` +
+            'Use cryptographically random data with at least 16 unique characters.');
+    }
+    // Initialize store
+    const store = config.store ?? createInMemorySessionStore();
+    // Cookie configuration
+    const cookieName = config.cookie?.name ?? DEFAULT_COOKIE_NAME;
+    const cookiePath = config.cookie?.path ?? '/';
+    const cookieDomain = config.cookie?.domain;
+    const cookieSecure = config.cookie?.secure ?? process.env.NODE_ENV === 'production';
+    const cookieHttpOnly = config.cookie?.httpOnly ?? true;
+    const cookieSameSite = config.cookie?.sameSite ?? 'lax';
+    // Expiration configuration
+    const ttl = config.expiration?.ttl ?? DEFAULT_SESSION_TTL;
+    const sliding = config.expiration?.sliding ?? true;
+    const absoluteTimeout = config.expiration?.absoluteTimeout;
+    // Security validation: SameSite=none requires Secure
+    if (cookieSameSite === 'none' && !cookieSecure) {
+        throw new Error('Session cookie with SameSite=none requires Secure flag. ' +
+            'Set cookie.secure: true or use a different SameSite policy.');
+    }
+    /**
+     * Set session cookie
+     */
+    function setCookie(reply, signedId) {
+        reply.cookie(cookieName, signedId, {
+            path: cookiePath,
+            domain: cookieDomain,
+            secure: cookieSecure,
+            httpOnly: cookieHttpOnly,
+            sameSite: cookieSameSite,
+            maxAge: ttl,
+        });
+    }
+    /**
+     * Clear session cookie
+     */
+    function clearCookie(reply) {
+        reply.clearCookie(cookieName, {
+            path: cookiePath,
+            domain: cookieDomain,
+        });
+    }
+    /**
+     * Create a Session handle
+     */
+    function createSessionHandle(sessionId, data, expiresAt, isNew, reply) {
+        let modified = isNew;
+        let destroyed = false;
+        let currentId = sessionId;
+        let currentData = { ...data };
+        let currentExpiresAt = expiresAt;
+        // Move flash data to old flash for reading
+        if (currentData._flash) {
+            currentData._flashOld = currentData._flash;
+            delete currentData._flash;
+            modified = true;
+        }
+        const session = {
+            get id() {
+                return currentId;
+            },
+            get isNew() {
+                return isNew;
+            },
+            get isModified() {
+                return modified;
+            },
+            get isDestroyed() {
+                return destroyed;
+            },
+            get data() {
+                return currentData;
+            },
+            get(key) {
+                return currentData[key];
+            },
+            set(key, value) {
+                if (destroyed) {
+                    throw new AuthError('Cannot modify destroyed session', 400, 'SESSION_DESTROYED');
+                }
+                currentData[key] = value;
+                modified = true;
+            },
+            delete(key) {
+                if (destroyed) {
+                    throw new AuthError('Cannot modify destroyed session', 400, 'SESSION_DESTROYED');
+                }
+                delete currentData[key];
+                modified = true;
+            },
+            has(key) {
+                return key in currentData;
+            },
+            flash(key, value) {
+                if (destroyed) {
+                    throw new AuthError('Cannot modify destroyed session', 400, 'SESSION_DESTROYED');
+                }
+                if (!currentData._flash) {
+                    currentData._flash = {};
+                }
+                currentData._flash[key] = value;
+                modified = true;
+            },
+            getFlash(key) {
+                const value = currentData._flashOld?.[key];
+                return value;
+            },
+            getAllFlash() {
+                return currentData._flashOld ?? {};
+            },
+            async regenerate() {
+                if (destroyed) {
+                    throw new AuthError('Cannot regenerate destroyed session', 400, 'SESSION_DESTROYED');
+                }
+                // Delete old session
+                await store.delete(currentId);
+                // Generate new ID
+                const newSessionId = generateSessionId();
+                const newSignedId = signSessionId(newSessionId, config.secret);
+                // Update tracking
+                currentId = newSessionId;
+                currentData._lastAccessedAt = Date.now();
+                modified = true;
+                // Set new cookie
+                setCookie(reply, newSignedId);
+                // Save with new ID
+                await store.set(currentId, {
+                    id: currentId,
+                    data: currentData,
+                    expiresAt: currentExpiresAt,
+                });
+            },
+            async destroy() {
+                await store.delete(currentId);
+                clearCookie(reply);
+                destroyed = true;
+                currentData = {};
+            },
+            async save() {
+                if (destroyed) {
+                    return;
+                }
+                // Clear old flash data after it's been read
+                delete currentData._flashOld;
+                // Update last accessed time
+                currentData._lastAccessedAt = Date.now();
+                // Check absolute timeout
+                if (absoluteTimeout) {
+                    const absoluteExpiresAt = currentData._createdAt + absoluteTimeout * 1000;
+                    if (Date.now() >= absoluteExpiresAt) {
+                        await session.destroy();
+                        throw new AuthError('Session has reached absolute timeout', 401, 'SESSION_EXPIRED');
+                    }
+                    // Cap expiration at absolute timeout
+                    currentExpiresAt = Math.min(currentExpiresAt, absoluteExpiresAt);
+                }
+                // Update sliding expiration
+                if (sliding) {
+                    currentExpiresAt = Date.now() + ttl * 1000;
+                }
+                await store.set(currentId, {
+                    id: currentId,
+                    data: currentData,
+                    expiresAt: currentExpiresAt,
+                });
+                // Refresh cookie with new expiration
+                const signedId = signSessionId(currentId, config.secret);
+                setCookie(reply, signedId);
+                modified = false;
+            },
+            async reload() {
+                if (destroyed) {
+                    throw new AuthError('Cannot reload destroyed session', 400, 'SESSION_DESTROYED');
+                }
+                const stored = await store.get(currentId);
+                if (!stored) {
+                    throw new AuthError('Session not found', 401, 'SESSION_NOT_FOUND');
+                }
+                currentData = { ...stored.data };
+                currentExpiresAt = stored.expiresAt;
+                modified = false;
+            },
+        };
+        return session;
+    }
+    return {
+        store,
+        createSession(reply) {
+            const sessionId = generateSessionId();
+            const signedId = signSessionId(sessionId, config.secret);
+            const now = Date.now();
+            const expiresAt = now + ttl * 1000;
+            const data = {
+                _createdAt: now,
+                _lastAccessedAt: now,
+            };
+            // Set cookie
+            setCookie(reply, signedId);
+            return createSessionHandle(sessionId, data, expiresAt, true, reply);
+        },
+        async loadSession(request) {
+            const signedId = request.cookies[cookieName];
+            if (!signedId) {
+                return null;
+            }
+            // Verify signature and extract session ID
+            const sessionId = verifySessionId(signedId, config.secret);
+            if (!sessionId) {
+                return null;
+            }
+            // Validate session ID entropy
+            if (!validateSessionIdEntropy(sessionId)) {
+                return null;
+            }
+            // Load from store
+            const stored = await store.get(sessionId);
+            if (!stored) {
+                return null;
+            }
+            // Check expiration
+            if (stored.expiresAt <= Date.now()) {
+                await store.delete(sessionId);
+                return null;
+            }
+            // We need reply for the session handle, but loadSession doesn't have it
+            // This is intentional - loadSession is for checking only
+            // Use getOrCreateSession for full session handling
+            return null;
+        },
+        async getOrCreateSession(request, reply) {
+            const signedId = request.cookies[cookieName];
+            if (signedId) {
+                // Verify signature
+                const sessionId = verifySessionId(signedId, config.secret);
+                if (sessionId && validateSessionIdEntropy(sessionId)) {
+                    // Load from store
+                    const stored = await store.get(sessionId);
+                    if (stored && stored.expiresAt > Date.now()) {
+                        // Check absolute timeout before returning
+                        if (absoluteTimeout) {
+                            const absoluteExpiresAt = stored.data._createdAt + absoluteTimeout * 1000;
+                            if (Date.now() >= absoluteExpiresAt) {
+                                await store.delete(sessionId);
+                                clearCookie(reply);
+                                // Create new session
+                                return this.createSession(reply);
+                            }
+                        }
+                        return createSessionHandle(sessionId, stored.data, stored.expiresAt, false, reply);
+                    }
+                }
+            }
+            // Create new session
+            return this.createSession(reply);
+        },
+        async destroySession(sessionId) {
+            await store.delete(sessionId);
+        },
+        async destroyUserSessions(userId) {
+            if (store.deleteSessionsByUser) {
+                await store.deleteSessionsByUser(userId);
+            }
+            else if (store.getSessionsByUser) {
+                const sessions = await store.getSessionsByUser(userId);
+                for (const sessionId of sessions) {
+                    await store.delete(sessionId);
+                }
+            }
+            // If store doesn't support user session tracking, silently skip
+        },
+        clearCookie,
+    };
+}
+// ============================================================================
+// Session Middleware Factory
+// ============================================================================
+/**
+ * Creates session middleware for procedures
+ *
+ * @example
+ * ```typescript
+ * const session = createSessionMiddleware({
+ *   secret: process.env.SESSION_SECRET!,
+ *   cookie: { secure: true },
+ * });
+ *
+ * // Use in procedures
+ * const getCart = procedure()
+ *   .use(session.middleware())
+ *   .query(async ({ ctx }) => {
+ *     return ctx.session.get('cart') ?? [];
+ *   });
+ *
+ * // Require authentication
+ * const getProfile = procedure()
+ *   .use(session.requireAuth())
+ *   .query(async ({ ctx }) => {
+ *     return ctx.user;
+ *   });
+ * ```
+ */
+export function createSessionMiddleware(config) {
+    const manager = createSessionManager(config);
+    /**
+     * Base session middleware
+     */
+    function middleware(options = {}) {
+        return async ({ ctx, next }) => {
+            const request = ctx.request;
+            const reply = ctx.reply;
+            let session;
+            if (options.lazy) {
+                // Lazy mode: only create session if accessed
+                // This requires a proxy to detect access
+                let realSession = null;
+                const lazySession = new Proxy({}, {
+                    get(_target, prop) {
+                        if (!realSession) {
+                            // Create session on first access
+                            // Note: This is synchronous, so we can't use getOrCreateSession
+                            // For lazy mode, we create a new session
+                            realSession = manager.createSession(reply);
+                        }
+                        const value = realSession[prop];
+                        if (typeof value === 'function') {
+                            return value.bind(realSession);
+                        }
+                        return value;
+                    },
+                });
+                session = lazySession;
+            }
+            else {
+                session = await manager.getOrCreateSession(request, reply);
+            }
+            // Attach to request for hooks
+            request.session = session;
+            try {
+                const result = await next({
+                    ctx: {
+                        ...ctx,
+                        session,
+                    },
+                });
+                // Auto-save session if modified
+                if (session.isModified && !session.isDestroyed) {
+                    await session.save();
+                }
+                return result;
+            }
+            catch (error) {
+                // Still try to save session on error
+                if (session.isModified && !session.isDestroyed) {
+                    try {
+                        await session.save();
+                    }
+                    catch {
+                        // Ignore save errors during error handling
+                    }
+                }
+                throw error;
+            }
+        };
+    }
+    /**
+     * Middleware that requires authentication
+     */
+    function requireAuth() {
+        return async ({ ctx, next }) => {
+            const request = ctx.request;
+            const reply = ctx.reply;
+            const session = await manager.getOrCreateSession(request, reply);
+            // Check if session has userId
+            const userId = session.get('userId');
+            if (!userId) {
+                throw new AuthError('Authentication required', 401, 'SESSION_UNAUTHORIZED');
+            }
+            // Load user if userLoader provided
+            let user;
+            if (config.userLoader) {
+                const loadedUser = await config.userLoader(userId);
+                if (!loadedUser) {
+                    // User no longer exists - destroy session
+                    await session.destroy();
+                    throw new AuthError('User not found', 401, 'USER_NOT_FOUND');
+                }
+                user = loadedUser;
+            }
+            else {
+                // Create minimal user from session
+                user = {
+                    id: userId,
+                    email: session.get('userEmail') ?? '',
+                };
+            }
+            request.session = session;
+            try {
+                const result = await next({
+                    ctx: {
+                        ...ctx,
+                        session,
+                        user,
+                        isAuthenticated: true,
+                    },
+                });
+                if (session.isModified && !session.isDestroyed) {
+                    await session.save();
+                }
+                return result;
+            }
+            catch (error) {
+                if (session.isModified && !session.isDestroyed) {
+                    try {
+                        await session.save();
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+                throw error;
+            }
+        };
+    }
+    /**
+     * Middleware for optional authentication
+     */
+    function optionalAuth() {
+        return async ({ ctx, next }) => {
+            const request = ctx.request;
+            const reply = ctx.reply;
+            const session = await manager.getOrCreateSession(request, reply);
+            const userId = session.get('userId');
+            let user;
+            let isAuthenticated = false;
+            if (userId) {
+                if (config.userLoader) {
+                    const loadedUser = await config.userLoader(userId);
+                    if (loadedUser) {
+                        user = loadedUser;
+                        isAuthenticated = true;
+                    }
+                }
+                else {
+                    user = {
+                        id: userId,
+                        email: session.get('userEmail') ?? '',
+                    };
+                    isAuthenticated = true;
+                }
+            }
+            request.session = session;
+            try {
+                const result = await next({
+                    ctx: {
+                        ...ctx,
+                        session,
+                        user,
+                        isAuthenticated,
+                    },
+                });
+                if (session.isModified && !session.isDestroyed) {
+                    await session.save();
+                }
+                return result;
+            }
+            catch (error) {
+                if (session.isModified && !session.isDestroyed) {
+                    try {
+                        await session.save();
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+                throw error;
+            }
+        };
+    }
+    return {
+        /** Session manager instance */
+        manager,
+        /** Base session middleware */
+        middleware,
+        /** Authentication required middleware */
+        requireAuth,
+        /** Optional authentication middleware */
+        optionalAuth,
+    };
+}
+// ============================================================================
+// Session Helper Functions
+// ============================================================================
+/**
+ * Login helper - sets user in session and regenerates ID
+ *
+ * @example
+ * ```typescript
+ * const login = procedure()
+ *   .use(session.middleware())
+ *   .input(LoginSchema)
+ *   .mutation(async ({ input, ctx }) => {
+ *     const user = await verifyCredentials(input.email, input.password);
+ *     await loginSession(ctx.session, user);
+ *     return { success: true };
+ *   });
+ * ```
+ */
+export async function loginSession(session, user) {
+    // Regenerate session ID to prevent session fixation
+    await session.regenerate();
+    // Store user info in session
+    session.set('userId', user.id);
+    session.set('userEmail', user.email);
+    // Save immediately
+    await session.save();
+}
+/**
+ * Logout helper - destroys session
+ *
+ * @example
+ * ```typescript
+ * const logout = procedure()
+ *   .use(session.requireAuth())
+ *   .mutation(async ({ ctx }) => {
+ *     await logoutSession(ctx.session);
+ *     return { success: true };
+ *   });
+ * ```
+ */
+export async function logoutSession(session) {
+    await session.destroy();
+}
+/**
+ * Check if session is authenticated
+ */
+export function isSessionAuthenticated(session) {
+    return !!session.get('userId');
+}
+//# sourceMappingURL=session.js.map