@veloxts/auth 0.6.87 → 0.6.88

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @veloxts/auth
 
+## 0.6.88
+
+### Patch Changes
+
+- add ecosystem presets for environment-aware configuration
+- Updated dependencies
+  - @veloxts/core@0.6.88
+  - @veloxts/router@0.6.88
+
 ## 0.6.87
 
 ### Patch Changes

package/dist/guards.d.ts

@@ -47,16 +47,30 @@ export interface GuardBuilder<TContext> {
 /**
  * Resets the guard counter to zero.
  *
- * This is intended for testing purposes only to ensure deterministic
- * guard naming across test runs. Should not be used in production code.
+ * **IMPORTANT:** This function MUST be called in test setup (beforeEach/beforeAll)
+ * when tests depend on deterministic auto-generated guard names. Without this,
+ * tests may pass individually but fail when run together due to counter pollution.
+ *
+ * @internal - Exported for testing purposes only. Do not use in production code.
  *
- * @internal
  * @example
  * ```typescript
- * import { _resetGuardCounter } from '@veloxts/auth';
- *
- * beforeEach(() => {
- *   _resetGuardCounter();
+ * import { guard, _resetGuardCounter } from '@veloxts/auth';
+ * import { describe, beforeEach, it, expect } from 'vitest';
+ *
+ * describe('Guard tests', () => {
+ *   // Reset counter before each test for deterministic naming
+ *   beforeEach(() => {
+ *     _resetGuardCounter();
+ *   });
+ *
+ *   it('should generate sequential names', () => {
+ *     const guard1 = guard((ctx) => true);
+ *     const guard2 = guard((ctx) => false);
+ *
+ *     expect(guard1.name).toBe('guard_1'); // Always 1, not affected by previous tests
+ *     expect(guard2.name).toBe('guard_2');
+ *   });
  * });
  * ```
  */

package/dist/guards.js

@@ -25,22 +25,43 @@ export function defineGuard(definition) {
 }
 /**
  * Counter for generating unique guard names when not provided
+ *
+ * **IMPORTANT for testing:** This counter is module-level state that persists
+ * across test runs. If your tests create guards without explicit names and
+ * assert on the generated names (e.g., 'guard_1', 'guard_2'), you MUST call
+ * `_resetGuardCounter()` in your test setup (beforeEach) to ensure deterministic
+ * results.
+ *
  * @internal
  */
 let guardCounter = 0;
 /**
  * Resets the guard counter to zero.
  *
- * This is intended for testing purposes only to ensure deterministic
- * guard naming across test runs. Should not be used in production code.
+ * **IMPORTANT:** This function MUST be called in test setup (beforeEach/beforeAll)
+ * when tests depend on deterministic auto-generated guard names. Without this,
+ * tests may pass individually but fail when run together due to counter pollution.
+ *
+ * @internal - Exported for testing purposes only. Do not use in production code.
  *
- * @internal
  * @example
  * ```typescript
- * import { _resetGuardCounter } from '@veloxts/auth';
+ * import { guard, _resetGuardCounter } from '@veloxts/auth';
+ * import { describe, beforeEach, it, expect } from 'vitest';
+ *
+ * describe('Guard tests', () => {
+ *   // Reset counter before each test for deterministic naming
+ *   beforeEach(() => {
+ *     _resetGuardCounter();
+ *   });
+ *
+ *   it('should generate sequential names', () => {
+ *     const guard1 = guard((ctx) => true);
+ *     const guard2 = guard((ctx) => false);
  *
- * beforeEach(() => {
- *   _resetGuardCounter();
+ *     expect(guard1.name).toBe('guard_1'); // Always 1, not affected by previous tests
+ *     expect(guard2.name).toBe('guard_2');
+ *   });
  * });
  * ```
  */

package/dist/jwt.js

@@ -22,34 +22,29 @@ const MIN_SECRET_ENTROPY_CHARS = 16;
 // Token Expiration Bounds (Security Phase 3.1)
 // ============================================================================
 /**
- * Minimum access token expiry: 1 minute
- * Shorter tokens increase security but may impact UX
- */
-const MIN_ACCESS_TOKEN_SECONDS = 60;
-/**
- * Maximum access token expiry: 1 hour
- * Longer lived tokens are a security risk if stolen
- */
-const MAX_ACCESS_TOKEN_SECONDS = 60 * 60;
-/**
- * Minimum refresh token expiry: 1 hour
- * Too short reduces usability
- */
-const MIN_REFRESH_TOKEN_SECONDS = 60 * 60;
-/**
- * Maximum refresh token expiry: 30 days
- * Longer lived refresh tokens increase risk window
- */
-const MAX_REFRESH_TOKEN_SECONDS = 30 * 24 * 60 * 60;
-/**
- * Recommended maximum access token expiry: 15 minutes
- * Beyond this, consider shorter lived tokens with refresh
- */
-const RECOMMENDED_MAX_ACCESS_SECONDS = 15 * 60;
-/**
- * Recommended maximum refresh token expiry: 7 days
+ * Token expiration bounds for security validation
+ *
+ * Groups all token lifetime constraints into a single configuration object.
+ * Used by validateTokenExpiry() to enforce security policies.
  */
-const RECOMMENDED_MAX_REFRESH_SECONDS = 7 * 24 * 60 * 60;
+const TOKEN_BOUNDS = {
+    access: {
+        /** Minimum: 1 minute - shorter tokens cause excessive refreshes */
+        min: 60,
+        /** Maximum: 1 hour - longer tokens are a security risk */
+        max: 60 * 60,
+        /** Recommended: 15 minutes - balance of security and UX */
+        recommended: 15 * 60,
+    },
+    refresh: {
+        /** Minimum: 1 hour - shorter tokens impact usability */
+        min: 60 * 60,
+        /** Maximum: 30 days - longer tokens increase attack window */
+        max: 30 * 24 * 60 * 60,
+        /** Recommended: 7 days - standard refresh cycle */
+        recommended: 7 * 24 * 60 * 60,
+    },
+};
 /**
  * Reserved JWT claims that cannot be overridden via additionalClaims
  */
@@ -147,29 +142,29 @@ export function validateTokenExpiration(accessExpiry, refreshExpiry) {
     const accessSeconds = parseTimeToSeconds(accessExpiry);
     const refreshSeconds = parseTimeToSeconds(refreshExpiry);
     // Validate access token bounds
-    if (accessSeconds < MIN_ACCESS_TOKEN_SECONDS) {
+    if (accessSeconds < TOKEN_BOUNDS.access.min) {
         throw new AuthError(`Access token expiry (${accessExpiry} = ${accessSeconds}s) is below minimum of ` +
-            `${MIN_ACCESS_TOKEN_SECONDS}s (1 minute). Very short tokens cause excessive refreshes.`, 400, 'INVALID_TOKEN_EXPIRY');
+            `${TOKEN_BOUNDS.access.min}s (1 minute). Very short tokens cause excessive refreshes.`, 400, 'INVALID_TOKEN_EXPIRY');
     }
-    if (accessSeconds > MAX_ACCESS_TOKEN_SECONDS) {
+    if (accessSeconds > TOKEN_BOUNDS.access.max) {
         throw new AuthError(`Access token expiry (${accessExpiry} = ${accessSeconds}s) exceeds maximum of ` +
-            `${MAX_ACCESS_TOKEN_SECONDS}s (1 hour). Long-lived access tokens are a security risk.`, 400, 'INVALID_TOKEN_EXPIRY');
+            `${TOKEN_BOUNDS.access.max}s (1 hour). Long-lived access tokens are a security risk.`, 400, 'INVALID_TOKEN_EXPIRY');
     }
     // Validate refresh token bounds
-    if (refreshSeconds < MIN_REFRESH_TOKEN_SECONDS) {
+    if (refreshSeconds < TOKEN_BOUNDS.refresh.min) {
         throw new AuthError(`Refresh token expiry (${refreshExpiry} = ${refreshSeconds}s) is below minimum of ` +
-            `${MIN_REFRESH_TOKEN_SECONDS}s (1 hour). Very short refresh tokens impact usability.`, 400, 'INVALID_TOKEN_EXPIRY');
+            `${TOKEN_BOUNDS.refresh.min}s (1 hour). Very short refresh tokens impact usability.`, 400, 'INVALID_TOKEN_EXPIRY');
     }
-    if (refreshSeconds > MAX_REFRESH_TOKEN_SECONDS) {
+    if (refreshSeconds > TOKEN_BOUNDS.refresh.max) {
         throw new AuthError(`Refresh token expiry (${refreshExpiry} = ${refreshSeconds}s) exceeds maximum of ` +
-            `${MAX_REFRESH_TOKEN_SECONDS}s (30 days). Long-lived refresh tokens increase attack window.`, 400, 'INVALID_TOKEN_EXPIRY');
+            `${TOKEN_BOUNDS.refresh.max}s (30 days). Long-lived refresh tokens increase attack window.`, 400, 'INVALID_TOKEN_EXPIRY');
     }
     // Warn about exceeding recommended limits (non-fatal)
-    if (accessSeconds > RECOMMENDED_MAX_ACCESS_SECONDS) {
+    if (accessSeconds > TOKEN_BOUNDS.access.recommended) {
         console.warn(`[Security] Access token expiry (${accessExpiry}) exceeds recommended maximum of 15 minutes. ` +
             'Consider using shorter-lived access tokens with refresh.');
     }
-    if (refreshSeconds > RECOMMENDED_MAX_REFRESH_SECONDS) {
+    if (refreshSeconds > TOKEN_BOUNDS.refresh.recommended) {
         console.warn(`[Security] Refresh token expiry (${refreshExpiry}) exceeds recommended maximum of 7 days. ` +
             'Long-lived refresh tokens increase the window for token theft attacks.');
     }

package/dist/session/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Session module barrel export
+ *
+ * Re-exports all session types, stores, and utilities.
+ *
+ * @module session
+ */
+export type { SessionStore } from './store.js';
+export { inMemorySessionStore } from './store.js';
+export type { Session, SessionAuthContext, SessionContext, SessionData, SessionMiddlewareOptions, StoredSession, } from './types.js';
+export { DEFAULT_COOKIE_NAME, DEFAULT_SESSION_TTL, MIN_SECRET_LENGTH, SESSION_ID_BYTES, } from './types.js';

package/dist/session/index.js

@@ -0,0 +1,9 @@
+/**
+ * Session module barrel export
+ *
+ * Re-exports all session types, stores, and utilities.
+ *
+ * @module session
+ */
+export { inMemorySessionStore } from './store.js';
+export { DEFAULT_COOKIE_NAME, DEFAULT_SESSION_TTL, MIN_SECRET_LENGTH, SESSION_ID_BYTES, } from './types.js';

package/dist/session/store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Session storage backends
+ *
+ * Provides pluggable session storage interfaces and implementations.
+ *
+ * @module session/store
+ */
+import type { StoredSession } from './types.js';
+/**
+ * Pluggable session storage backend interface
+ *
+ * Implementations:
+ * - InMemorySessionStore (default, for development)
+ * - RedisSessionStore (production, distributed)
+ * - DatabaseSessionStore (production, audit trail)
+ *
+ * @example
+ * ```typescript
+ * // Custom Redis implementation
+ * class RedisSessionStore implements SessionStore {
+ *   constructor(private redis: Redis) {}
+ *
+ *   async get(sessionId: string): Promise<StoredSession | null> {
+ *     const data = await this.redis.get(`session:${sessionId}`);
+ *     return data ? JSON.parse(data) : null;
+ *   }
+ *
+ *   async set(sessionId: string, session: StoredSession): Promise<void> {
+ *     const ttl = Math.ceil((session.expiresAt - Date.now()) / 1000);
+ *     await this.redis.setex(`session:${sessionId}`, ttl, JSON.stringify(session));
+ *   }
+ *
+ *   async delete(sessionId: string): Promise<void> {
+ *     await this.redis.del(`session:${sessionId}`);
+ *   }
+ *
+ *   async touch(sessionId: string, expiresAt: number): Promise<void> {
+ *     const session = await this.get(sessionId);
+ *     if (session) {
+ *       session.expiresAt = expiresAt;
+ *       session.data._lastAccessedAt = Date.now();
+ *       await this.set(sessionId, session);
+ *     }
+ *   }
+ *
+ *   async clear(): Promise<void> {
+ *     const keys = await this.redis.keys('session:*');
+ *     if (keys.length > 0) {
+ *       await this.redis.del(...keys);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface SessionStore {
+    /**
+     * Retrieve a session by ID
+     * @param sessionId - The session ID to look up
+     * @returns The stored session or null if not found/expired
+     */
+    get(sessionId: string): Promise<StoredSession | null> | StoredSession | null;
+    /**
+     * Store or update a session
+     * @param sessionId - The session ID
+     * @param session - The session data to store
+     */
+    set(sessionId: string, session: StoredSession): Promise<void> | void;
+    /**
+     * Delete a session
+     * @param sessionId - The session ID to delete
+     */
+    delete(sessionId: string): Promise<void> | void;
+    /**
+     * Refresh session TTL without modifying data
+     * Used for sliding expiration
+     * @param sessionId - The session ID to touch
+     * @param expiresAt - New expiration timestamp (Unix ms)
+     */
+    touch(sessionId: string, expiresAt: number): Promise<void> | void;
+    /**
+     * Clear all sessions (useful for testing and maintenance)
+     */
+    clear(): Promise<void> | void;
+    /**
+     * Get all active session IDs for a user (optional)
+     * Useful for "logout from all devices" functionality
+     * @param userId - The user ID to look up
+     * @returns Array of session IDs for the user
+     */
+    getSessionsByUser?(userId: string): Promise<string[]> | string[];
+    /**
+     * Delete all sessions for a user (optional)
+     * Useful for "logout from all devices" functionality
+     * @param userId - The user ID whose sessions to delete
+     */
+    deleteSessionsByUser?(userId: string): Promise<void> | void;
+}
+/**
+ * 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 = inMemorySessionStore();
+ *
+ * const manager = sessionManager({
+ *   store,
+ *   secret: process.env.SESSION_SECRET!,
+ * });
+ * ```
+ */
+export declare function inMemorySessionStore(): SessionStore;

package/dist/session/store.js

@@ -0,0 +1,136 @@
+/**
+ * Session storage backends
+ *
+ * Provides pluggable session storage interfaces and implementations.
+ *
+ * @module session/store
+ */
+// ============================================================================
+// 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 = inMemorySessionStore();
+ *
+ * const manager = sessionManager({
+ *   store,
+ *   secret: process.env.SESSION_SECRET!,
+ * });
+ * ```
+ */
+export function inMemorySessionStore() {
+    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);
+            }
+        },
+    };
+}

package/dist/session/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Session type definitions
+ *
+ * Core types for cookie-based session management.
+ *
+ * @module session/types
+ */
+import type { User } from '../types.js';
+/**
+ * Session ID entropy in bytes (32 bytes = 256 bits)
+ * Provides sufficient entropy to prevent brute-force attacks
+ */
+export declare const SESSION_ID_BYTES = 32;
+/**
+ * Minimum secret length for session ID signing (32 characters)
+ */
+export declare const MIN_SECRET_LENGTH = 32;
+/**
+ * Default session TTL (24 hours in seconds)
+ */
+export declare const DEFAULT_SESSION_TTL = 86400;
+/**
+ * Default cookie name
+ */
+export declare const DEFAULT_COOKIE_NAME = "velox.session";
+/**
+ * Base session data interface
+ *
+ * Applications should extend this via declaration merging:
+ * @example
+ * ```typescript
+ * declare module '@veloxts/auth' {
+ *   interface SessionData {
+ *     cart: CartItem[];
+ *     preferences: UserPreferences;
+ *   }
+ * }
+ * ```
+ */
+export interface SessionData {
+    /** User ID if authenticated */
+    userId?: string;
+    /** User email if authenticated */
+    userEmail?: string;
+    /** Flash data - persists for one request only */
+    _flash?: Record<string, unknown>;
+    /** Previous flash data being read */
+    _flashOld?: Record<string, unknown>;
+    /** Session creation timestamp (Unix ms) */
+    _createdAt: number;
+    /** Last access timestamp (Unix ms) */
+    _lastAccessedAt: number;
+    /** Allow extension via declaration merging */
+    [key: string]: unknown;
+}
+/**
+ * Stored session entry in the session store
+ */
+export interface StoredSession {
+    /** Session ID (signed) */
+    id: string;
+    /** Session data */
+    data: SessionData;
+    /** Expiration timestamp (Unix ms) */
+    expiresAt: number;
+}
+/**
+ * Session handle for accessing and modifying session data
+ */
+export interface Session {
+    /** Session ID */
+    readonly id: string;
+    /** Whether this is a new session */
+    readonly isNew: boolean;
+    /** Whether the session has been modified */
+    readonly isModified: boolean;
+    /** Whether the session has been destroyed */
+    readonly isDestroyed: boolean;
+    /** Session data */
+    readonly data: SessionData;
+    /**
+     * Get a session value
+     */
+    get<K extends keyof SessionData>(key: K): SessionData[K];
+    /**
+     * Set a session value
+     */
+    set<K extends keyof SessionData>(key: K, value: SessionData[K]): void;
+    /**
+     * Delete a session value
+     */
+    delete<K extends keyof SessionData>(key: K): void;
+    /**
+     * Check if a key exists
+     */
+    has<K extends keyof SessionData>(key: K): boolean;
+    /**
+     * Set flash data (persists for one request only)
+     */
+    flash(key: string, value: unknown): void;
+    /**
+     * Get flash data (clears after read)
+     */
+    getFlash<T = unknown>(key: string): T | undefined;
+    /**
+     * Get all flash data
+     */
+    getAllFlash(): Record<string, unknown>;
+    /**
+     * Regenerate session ID (for security after privilege change)
+     * Preserves session data with new ID
+     */
+    regenerate(): Promise<void>;
+    /**
+     * Destroy the session completely
+     */
+    destroy(): Promise<void>;
+    /**
+     * Save session changes
+     * Called automatically by middleware, but can be called manually
+     */
+    save(): Promise<void>;
+    /**
+     * Reload session data from store
+     */
+    reload(): Promise<void>;
+    /**
+     * Log in a user to the session
+     *
+     * Regenerates the session ID to prevent session fixation attacks,
+     * then stores the user's ID and email in the session.
+     *
+     * @example
+     * ```typescript
+     * const login = procedure()
+     *   .input(LoginSchema)
+     *   .mutation(async ({ input, ctx }) => {
+     *     const user = await verifyCredentials(input.email, input.password);
+     *     await ctx.session.login(user);
+     *     return { success: true };
+     *   });
+     * ```
+     */
+    login(user: User): Promise<void>;
+    /**
+     * Log out the current user by destroying the session
+     *
+     * @example
+     * ```typescript
+     * const logout = procedure()
+     *   .use(session.requireAuth())
+     *   .mutation(async ({ ctx }) => {
+     *     await ctx.session.logout();
+     *     return { success: true };
+     *   });
+     * ```
+     */
+    logout(): Promise<void>;
+    /**
+     * Check if the session is authenticated (has a logged-in user)
+     *
+     * @returns true if a user is logged in, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (ctx.session.check()) {
+     *   // User is authenticated
+     *   console.log('User ID:', ctx.session.get('userId'));
+     * }
+     * ```
+     */
+    check(): boolean;
+}
+/**
+ * Session context added to request context
+ */
+export interface SessionContext {
+    /** Current session */
+    session: Session;
+}
+/**
+ * Extended context with session and optional user
+ */
+export interface SessionAuthContext extends SessionContext {
+    /** Authenticated user (if logged in) */
+    user?: User;
+    /** Whether user is authenticated via session */
+    isAuthenticated: boolean;
+}
+/**
+ * Options for session middleware
+ */
+export interface SessionMiddlewareOptions {
+    /**
+     * Create session lazily (only when data is set)
+     * @default false
+     */
+    lazy?: boolean;
+    /**
+     * Require authentication (session with userId)
+     * @default false
+     */
+    requireAuth?: boolean;
+}

package/dist/session/types.js

@@ -0,0 +1,27 @@
+/**
+ * Session type definitions
+ *
+ * Core types for cookie-based session management.
+ *
+ * @module session/types
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Session ID entropy in bytes (32 bytes = 256 bits)
+ * Provides sufficient entropy to prevent brute-force attacks
+ */
+export const SESSION_ID_BYTES = 32;
+/**
+ * Minimum secret length for session ID signing (32 characters)
+ */
+export const MIN_SECRET_LENGTH = 32;
+/**
+ * Default session TTL (24 hours in seconds)
+ */
+export const DEFAULT_SESSION_TTL = 86400;
+/**
+ * Default cookie name
+ */
+export const DEFAULT_COOKIE_NAME = 'velox.session';

package/dist/session.d.ts

@@ -12,157 +12,12 @@ import type { BaseContext } from '@veloxts/core';
 import type { MiddlewareFunction } from '@veloxts/router';
 import type { User } from './types.js';
 import { type FastifyReplyWithCookies, type FastifyRequestWithCookies } from './utils/cookie-support.js';
-/**
- * Base session data interface
- *
- * Applications should extend this via declaration merging:
- * @example
- * ```typescript
- * declare module '@veloxts/auth' {
- *   interface SessionData {
- *     cart: CartItem[];
- *     preferences: UserPreferences;
- *   }
- * }
- * ```
- */
-export interface SessionData {
-    /** User ID if authenticated */
-    userId?: string;
-    /** User email if authenticated */
-    userEmail?: string;
-    /** Flash data - persists for one request only */
-    _flash?: Record<string, unknown>;
-    /** Previous flash data being read */
-    _flashOld?: Record<string, unknown>;
-    /** Session creation timestamp (Unix ms) */
-    _createdAt: number;
-    /** Last access timestamp (Unix ms) */
-    _lastAccessedAt: number;
-    /** Allow extension via declaration merging */
-    [key: string]: unknown;
-}
-/**
- * Stored session entry in the session store
- */
-export interface StoredSession {
-    /** Session ID (signed) */
-    id: string;
-    /** Session data */
-    data: SessionData;
-    /** Expiration timestamp (Unix ms) */
-    expiresAt: number;
-}
-/**
- * Pluggable session storage backend interface
- *
- * Implementations:
- * - InMemorySessionStore (default, for development)
- * - RedisSessionStore (production, distributed)
- * - DatabaseSessionStore (production, audit trail)
- *
- * @example
- * ```typescript
- * // Custom Redis implementation
- * class RedisSessionStore implements SessionStore {
- *   constructor(private redis: Redis) {}
- *
- *   async get(sessionId: string): Promise<StoredSession | null> {
- *     const data = await this.redis.get(`session:${sessionId}`);
- *     return data ? JSON.parse(data) : null;
- *   }
- *
- *   async set(sessionId: string, session: StoredSession): Promise<void> {
- *     const ttl = Math.ceil((session.expiresAt - Date.now()) / 1000);
- *     await this.redis.setex(`session:${sessionId}`, ttl, JSON.stringify(session));
- *   }
- *
- *   async delete(sessionId: string): Promise<void> {
- *     await this.redis.del(`session:${sessionId}`);
- *   }
- *
- *   async touch(sessionId: string, expiresAt: number): Promise<void> {
- *     const session = await this.get(sessionId);
- *     if (session) {
- *       session.expiresAt = expiresAt;
- *       session.data._lastAccessedAt = Date.now();
- *       await this.set(sessionId, session);
- *     }
- *   }
- *
- *   async clear(): Promise<void> {
- *     const keys = await this.redis.keys('session:*');
- *     if (keys.length > 0) {
- *       await this.redis.del(...keys);
- *     }
- *   }
- * }
- * ```
- */
-export interface SessionStore {
-    /**
-     * Retrieve a session by ID
-     * @param sessionId - The session ID to look up
-     * @returns The stored session or null if not found/expired
-     */
-    get(sessionId: string): Promise<StoredSession | null> | StoredSession | null;
-    /**
-     * Store or update a session
-     * @param sessionId - The session ID
-     * @param session - The session data to store
-     */
-    set(sessionId: string, session: StoredSession): Promise<void> | void;
-    /**
-     * Delete a session
-     * @param sessionId - The session ID to delete
-     */
-    delete(sessionId: string): Promise<void> | void;
-    /**
-     * Refresh session TTL without modifying data
-     * Used for sliding expiration
-     * @param sessionId - The session ID to touch
-     * @param expiresAt - New expiration timestamp (Unix ms)
-     */
-    touch(sessionId: string, expiresAt: number): Promise<void> | void;
-    /**
-     * Clear all sessions (useful for testing and maintenance)
-     */
-    clear(): Promise<void> | void;
-    /**
-     * Get all active session IDs for a user (optional)
-     * Useful for "logout from all devices" functionality
-     * @param userId - The user ID to look up
-     * @returns Array of session IDs for the user
-     */
-    getSessionsByUser?(userId: string): Promise<string[]> | string[];
-    /**
-     * Delete all sessions for a user (optional)
-     * Useful for "logout from all devices" functionality
-     * @param userId - The user ID whose sessions to delete
-     */
-    deleteSessionsByUser?(userId: string): Promise<void> | void;
-}
-/**
- * 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 = inMemorySessionStore();
- *
- * const manager = sessionManager({
- *   store,
- *   secret: process.env.SESSION_SECRET!,
- * });
- * ```
- */
-export declare function inMemorySessionStore(): SessionStore;
+export type { SessionStore } from './session/store.js';
+export { inMemorySessionStore } from './session/store.js';
+export type { Session, SessionAuthContext, SessionContext, SessionData, SessionMiddlewareOptions, StoredSession, } from './session/types.js';
+export { DEFAULT_COOKIE_NAME, DEFAULT_SESSION_TTL, MIN_SECRET_LENGTH, SESSION_ID_BYTES, } from './session/types.js';
+import type { SessionStore } from './session/store.js';
+import type { Session, SessionAuthContext, SessionContext, SessionMiddlewareOptions } from './session/types.js';
 /**
  * Cookie configuration for sessions
  */
@@ -247,113 +102,6 @@ export interface SessionConfig {
      */
     userLoader?: (userId: string) => Promise<User | null>;
 }
-/**
- * Session handle for accessing and modifying session data
- */
-export interface Session {
-    /** Session ID */
-    readonly id: string;
-    /** Whether this is a new session */
-    readonly isNew: boolean;
-    /** Whether the session has been modified */
-    readonly isModified: boolean;
-    /** Whether the session has been destroyed */
-    readonly isDestroyed: boolean;
-    /** Session data */
-    readonly data: SessionData;
-    /**
-     * Get a session value
-     */
-    get<K extends keyof SessionData>(key: K): SessionData[K];
-    /**
-     * Set a session value
-     */
-    set<K extends keyof SessionData>(key: K, value: SessionData[K]): void;
-    /**
-     * Delete a session value
-     */
-    delete<K extends keyof SessionData>(key: K): void;
-    /**
-     * Check if a key exists
-     */
-    has<K extends keyof SessionData>(key: K): boolean;
-    /**
-     * Set flash data (persists for one request only)
-     */
-    flash(key: string, value: unknown): void;
-    /**
-     * Get flash data (clears after read)
-     */
-    getFlash<T = unknown>(key: string): T | undefined;
-    /**
-     * Get all flash data
-     */
-    getAllFlash(): Record<string, unknown>;
-    /**
-     * Regenerate session ID (for security after privilege change)
-     * Preserves session data with new ID
-     */
-    regenerate(): Promise<void>;
-    /**
-     * Destroy the session completely
-     */
-    destroy(): Promise<void>;
-    /**
-     * Save session changes
-     * Called automatically by middleware, but can be called manually
-     */
-    save(): Promise<void>;
-    /**
-     * Reload session data from store
-     */
-    reload(): Promise<void>;
-    /**
-     * Log in a user to the session
-     *
-     * Regenerates the session ID to prevent session fixation attacks,
-     * then stores the user's ID and email in the session.
-     *
-     * @example
-     * ```typescript
-     * const login = procedure()
-     *   .input(LoginSchema)
-     *   .mutation(async ({ input, ctx }) => {
-     *     const user = await verifyCredentials(input.email, input.password);
-     *     await ctx.session.login(user);
-     *     return { success: true };
-     *   });
-     * ```
-     */
-    login(user: User): Promise<void>;
-    /**
-     * Log out the current user by destroying the session
-     *
-     * @example
-     * ```typescript
-     * const logout = procedure()
-     *   .use(session.requireAuth())
-     *   .mutation(async ({ ctx }) => {
-     *     await ctx.session.logout();
-     *     return { success: true };
-     *   });
-     * ```
-     */
-    logout(): Promise<void>;
-    /**
-     * Check if the session is authenticated (has a logged-in user)
-     *
-     * @returns true if a user is logged in, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (ctx.session.check()) {
-     *   // User is authenticated
-     *   console.log('User ID:', ctx.session.get('userId'));
-     * }
-     * ```
-     */
-    check(): boolean;
-}
 /**
  * Session manager for creating and managing sessions
  */
@@ -408,22 +156,6 @@ export interface SessionManager {
  * ```
  */
 export declare function sessionManager(config: SessionConfig): SessionManager;
-/**
- * Session context added to request context
- */
-export interface SessionContext {
-    /** Current session */
-    session: Session;
-}
-/**
- * Extended context with session and optional user
- */
-export interface SessionAuthContext extends SessionContext {
-    /** Authenticated user (if logged in) */
-    user?: User;
-    /** Whether user is authenticated via session */
-    isAuthenticated: boolean;
-}
 declare module '@veloxts/core' {
     interface BaseContext {
         /** Session context - available when session middleware is used */
@@ -436,21 +168,6 @@ declare module 'fastify' {
         session?: Session;
     }
 }
-/**
- * Options for session middleware
- */
-export interface SessionMiddlewareOptions {
-    /**
-     * Create session lazily (only when data is set)
-     * @default false
-     */
-    lazy?: boolean;
-    /**
-     * Require authentication (session with userId)
-     * @default false
-     */
-    requireAuth?: boolean;
-}
 /**
  * Creates session middleware for procedures (succinct API)
  *

package/dist/session.js

@@ -11,155 +11,10 @@
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { AuthError } from './types.js';
 import { getValidatedCookieContext, } from './utils/cookie-support.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 = inMemorySessionStore();
- *
- * const manager = sessionManager({
- *   store,
- *   secret: process.env.SESSION_SECRET!,
- * });
- * ```
- */
-export function inMemorySessionStore() {
-    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);
-            }
-        },
-    };
-}
+export { inMemorySessionStore } from './session/store.js';
+export { DEFAULT_COOKIE_NAME, DEFAULT_SESSION_TTL, MIN_SECRET_LENGTH, SESSION_ID_BYTES, } from './session/types.js';
+import { inMemorySessionStore } from './session/store.js';
+import { DEFAULT_COOKIE_NAME, DEFAULT_SESSION_TTL, MIN_SECRET_LENGTH, SESSION_ID_BYTES, } from './session/types.js';
 // ============================================================================
 // Session ID Generation and Signing
 // ============================================================================

package/dist/types.d.ts

@@ -232,7 +232,33 @@ export interface AuthConfig {
     /**
      * Token blacklist checker - check if token is revoked
      * Called on every authenticated request
-     * @deprecated Use `tokenStore` with TokenStore interface instead
+     *
+     * @deprecated Since v0.5.0. Use `tokenStore` with TokenStore interface instead.
+     * This option will be removed in v1.0.0.
+     *
+     * **Migration guide:**
+     * ```typescript
+     * // Before (deprecated)
+     * authPlugin({
+     *   jwt: { secret: '...' },
+     *   isTokenRevoked: async (tokenId) => {
+     *     return await redis.sismember('revoked_tokens', tokenId);
+     *   },
+     * });
+     *
+     * // After (recommended)
+     * authPlugin({
+     *   jwt: { secret: '...' },
+     *   tokenStore: {
+     *     isRevoked: async (tokenId) => {
+     *       return await redis.sismember('revoked_tokens', tokenId);
+     *     },
+     *     revoke: async (tokenId) => {
+     *       await redis.sadd('revoked_tokens', tokenId);
+     *     },
+     *   },
+     * });
+     * ```
      */
     isTokenRevoked?: (tokenId: string) => Promise<boolean>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.6.87",
+  "version": "0.6.88",
   "description": "Authentication and authorization system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -61,8 +61,8 @@
   "dependencies": {
     "@fastify/cookie": "11.0.2",
     "fastify": "5.6.2",
-    "@veloxts/core": "0.6.87",
-    "@veloxts/router": "0.6.87"
+    "@veloxts/core": "0.6.88",
+    "@veloxts/router": "0.6.88"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -86,8 +86,8 @@
     "fastify-plugin": "5.1.0",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/validation": "0.6.87",
-    "@veloxts/testing": "0.6.87"
+    "@veloxts/testing": "0.6.88",
+    "@veloxts/validation": "0.6.88"
   },
   "keywords": [
     "velox",