@veloxts/auth 0.6.68 → 0.6.70

package/dist/token-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Enhanced Token Store for JWT Revocation
+ *
+ * Provides an enhanced in-memory token store with:
+ * - Token revocation with expiry
+ * - Refresh token reuse detection
+ * - Automatic cleanup of expired entries
+ *
+ * @module auth/token-store
+ */
+/**
+ * Enhanced token store interface
+ *
+ * Extends basic token revocation with refresh token reuse detection
+ * and automatic cleanup capabilities.
+ */
+export interface EnhancedTokenStore {
+    /** Revoke a token with optional expiry time */
+    revoke(jti: string, expiresInMs?: number): void;
+    /** Check if token is revoked */
+    isRevoked(jti: string): boolean;
+    /** Mark refresh token as used (for reuse detection) */
+    markRefreshTokenUsed(jti: string, userId: string): void;
+    /** Check if refresh token was already used, returns userId if reused */
+    isRefreshTokenUsed(jti: string): string | undefined;
+    /** Revoke all tokens for a user (placeholder for production implementation) */
+    revokeAllUserTokens(userId: string): void;
+    /** Clear all entries (useful for testing) */
+    clear(): void;
+    /** Stop cleanup interval and release resources */
+    destroy(): void;
+}
+/**
+ * Options for creating an enhanced token store
+ */
+export interface EnhancedTokenStoreOptions {
+    /** Interval for cleanup of expired entries (default: 5 minutes) */
+    cleanupIntervalMs?: number;
+    /** Default expiry for revoked tokens (default: 7 days) */
+    defaultExpiryMs?: number;
+}
+/**
+ * Creates an enhanced in-memory token store
+ *
+ * Provides token revocation with expiry tracking and refresh token
+ * reuse detection for security.
+ *
+ * **WARNING: NOT suitable for production!**
+ * Use Redis or database-backed store for:
+ * - Persistence across server restarts
+ * - Horizontal scaling (multiple server instances)
+ * - Proper token revocation across deployments
+ *
+ * @example
+ * ```typescript
+ * import { createEnhancedTokenStore } from '@veloxts/auth';
+ *
+ * // Create store with defaults
+ * const tokenStore = createEnhancedTokenStore();
+ *
+ * // Revoke token on logout
+ * tokenStore.revoke(accessTokenJti);
+ *
+ * // Detect refresh token reuse (security measure)
+ * const previousUser = tokenStore.isRefreshTokenUsed(refreshJti);
+ * if (previousUser) {
+ *   // Potential token theft - revoke all user tokens
+ *   tokenStore.revokeAllUserTokens(previousUser);
+ *   throw new SecurityError('Token reuse detected');
+ * }
+ * tokenStore.markRefreshTokenUsed(refreshJti, userId);
+ *
+ * // Clean up on shutdown
+ * process.on('SIGTERM', () => tokenStore.destroy());
+ * ```
+ */
+export declare function createEnhancedTokenStore(options?: EnhancedTokenStoreOptions): EnhancedTokenStore;
+/**
+ * Default allowed roles for role parsing
+ */
+export declare const DEFAULT_ALLOWED_ROLES: readonly ["user", "admin", "moderator", "editor"];
+/**
+ * Parses JSON-encoded roles string to array
+ *
+ * Safely parses a JSON array of role strings, filtering to only allowed roles.
+ * Returns default ['user'] role if parsing fails or no valid roles found.
+ *
+ * @param rolesJson - JSON string of roles (e.g., '["admin", "user"]')
+ * @param allowedRoles - Optional list of valid roles (defaults to DEFAULT_ALLOWED_ROLES)
+ * @returns Array of valid roles, defaults to ['user'] if parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { parseUserRoles } from '@veloxts/auth';
+ *
+ * const roles = parseUserRoles(user.roles);
+ * // Input: '["admin", "user"]' -> Output: ['admin', 'user']
+ * // Input: null -> Output: ['user']
+ * // Input: 'invalid' -> Output: ['user']
+ *
+ * // With custom allowed roles
+ * const roles = parseUserRoles(user.roles, ['admin', 'superadmin']);
+ * ```
+ */
+export declare function parseUserRoles(rolesJson: string | null, allowedRoles?: readonly string[]): string[];

package/dist/token-store.js

@@ -0,0 +1,159 @@
+/**
+ * Enhanced Token Store for JWT Revocation
+ *
+ * Provides an enhanced in-memory token store with:
+ * - Token revocation with expiry
+ * - Refresh token reuse detection
+ * - Automatic cleanup of expired entries
+ *
+ * @module auth/token-store
+ */
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Creates an enhanced in-memory token store
+ *
+ * Provides token revocation with expiry tracking and refresh token
+ * reuse detection for security.
+ *
+ * **WARNING: NOT suitable for production!**
+ * Use Redis or database-backed store for:
+ * - Persistence across server restarts
+ * - Horizontal scaling (multiple server instances)
+ * - Proper token revocation across deployments
+ *
+ * @example
+ * ```typescript
+ * import { createEnhancedTokenStore } from '@veloxts/auth';
+ *
+ * // Create store with defaults
+ * const tokenStore = createEnhancedTokenStore();
+ *
+ * // Revoke token on logout
+ * tokenStore.revoke(accessTokenJti);
+ *
+ * // Detect refresh token reuse (security measure)
+ * const previousUser = tokenStore.isRefreshTokenUsed(refreshJti);
+ * if (previousUser) {
+ *   // Potential token theft - revoke all user tokens
+ *   tokenStore.revokeAllUserTokens(previousUser);
+ *   throw new SecurityError('Token reuse detected');
+ * }
+ * tokenStore.markRefreshTokenUsed(refreshJti, userId);
+ *
+ * // Clean up on shutdown
+ * process.on('SIGTERM', () => tokenStore.destroy());
+ * ```
+ */
+export function createEnhancedTokenStore(options) {
+    const { cleanupIntervalMs = 5 * 60 * 1000, defaultExpiryMs = 7 * 24 * 60 * 60 * 1000 } = options ?? {};
+    const revokedTokens = new Map();
+    const usedRefreshTokens = new Map();
+    // Track pending timeouts to prevent memory leaks on destroy()
+    const pendingTimeouts = new Set();
+    const cleanup = () => {
+        const now = Date.now();
+        for (const [jti, expiry] of revokedTokens.entries()) {
+            if (now > expiry) {
+                revokedTokens.delete(jti);
+            }
+        }
+    };
+    const cleanupInterval = setInterval(cleanup, cleanupIntervalMs);
+    return {
+        revoke(jti, expiresInMs = defaultExpiryMs) {
+            revokedTokens.set(jti, Date.now() + expiresInMs);
+        },
+        isRevoked(jti) {
+            const expiry = revokedTokens.get(jti);
+            if (!expiry)
+                return false;
+            if (Date.now() > expiry) {
+                revokedTokens.delete(jti);
+                return false;
+            }
+            return true;
+        },
+        markRefreshTokenUsed(jti, userId) {
+            usedRefreshTokens.set(jti, userId);
+            // Auto-expire after default expiry, track timeout for cleanup
+            const timeout = setTimeout(() => {
+                usedRefreshTokens.delete(jti);
+                pendingTimeouts.delete(timeout);
+            }, defaultExpiryMs);
+            pendingTimeouts.add(timeout);
+        },
+        isRefreshTokenUsed(jti) {
+            return usedRefreshTokens.get(jti);
+        },
+        revokeAllUserTokens(userId) {
+            // Placeholder - in production, implement proper user->token mapping
+            console.warn(`[Security] Token reuse detected for user ${userId}. ` +
+                'All tokens should be revoked. Implement proper user->token mapping for production.');
+        },
+        clear() {
+            // Clear pending timeouts since we're clearing the tokens they reference
+            for (const timeout of pendingTimeouts) {
+                clearTimeout(timeout);
+            }
+            pendingTimeouts.clear();
+            revokedTokens.clear();
+            usedRefreshTokens.clear();
+        },
+        destroy() {
+            clearInterval(cleanupInterval);
+            // Clear all pending timeouts to prevent memory leaks
+            for (const timeout of pendingTimeouts) {
+                clearTimeout(timeout);
+            }
+            pendingTimeouts.clear();
+            revokedTokens.clear();
+            usedRefreshTokens.clear();
+        },
+    };
+}
+/**
+ * Default allowed roles for role parsing
+ */
+export const DEFAULT_ALLOWED_ROLES = ['user', 'admin', 'moderator', 'editor'];
+/**
+ * Parses JSON-encoded roles string to array
+ *
+ * Safely parses a JSON array of role strings, filtering to only allowed roles.
+ * Returns default ['user'] role if parsing fails or no valid roles found.
+ *
+ * @param rolesJson - JSON string of roles (e.g., '["admin", "user"]')
+ * @param allowedRoles - Optional list of valid roles (defaults to DEFAULT_ALLOWED_ROLES)
+ * @returns Array of valid roles, defaults to ['user'] if parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { parseUserRoles } from '@veloxts/auth';
+ *
+ * const roles = parseUserRoles(user.roles);
+ * // Input: '["admin", "user"]' -> Output: ['admin', 'user']
+ * // Input: null -> Output: ['user']
+ * // Input: 'invalid' -> Output: ['user']
+ *
+ * // With custom allowed roles
+ * const roles = parseUserRoles(user.roles, ['admin', 'superadmin']);
+ * ```
+ */
+export function parseUserRoles(rolesJson, allowedRoles = DEFAULT_ALLOWED_ROLES) {
+    if (!rolesJson)
+        return ['user'];
+    try {
+        const parsed = JSON.parse(rolesJson);
+        if (!Array.isArray(parsed)) {
+            return ['user'];
+        }
+        const validRoles = parsed
+            .filter((role) => typeof role === 'string')
+            .filter((role) => allowedRoles.includes(role));
+        return validRoles.length > 0 ? validRoles : ['user'];
+    }
+    catch {
+        return ['user'];
+    }
+}

package/dist/types.d.ts

@@ -24,25 +24,36 @@ export declare class AuthError extends Error {
 /**
  * Base user interface for authenticated requests
  *
- * Applications should extend this via declaration merging:
+ * Applications should extend this via declaration merging to add
+ * custom properties without using index signatures:
+ *
  * @example
  * ```typescript
  * declare module '@veloxts/auth' {
  *   interface User {
- *     roles: ('admin' | 'user')[];
- *     permissions: string[];
+ *     name?: string;
+ *     avatarUrl?: string;
+ *     tenantId?: string;
  *   }
  * }
  * ```
+ *
+ * This approach provides:
+ * - Full type safety (no implicit `unknown` properties)
+ * - Better IDE autocomplete
+ * - Compile-time errors for typos
  */
 export interface User {
+    /** Unique user identifier */
     id: string;
+    /** User email address */
     email: string;
+    /** Whether the user's email has been verified */
+    emailVerified?: boolean;
     /** User roles for authorization */
     roles?: string[];
     /** User permissions for fine-grained access control */
     permissions?: string[];
-    [key: string]: unknown;
 }
 /**
  * Payload stored in JWT tokens
@@ -120,25 +131,6 @@ export interface HashConfig {
     /** argon2 parallelism (default: 4) */
     argon2Parallelism?: number;
 }
-/**
- * Legacy session cookie configuration (used by AuthConfig)
- *
- * @deprecated Use SessionConfig from session.ts for full session management
- */
-export interface LegacySessionConfig {
-    /** Cookie name (default: 'velox.session') */
-    cookieName?: string;
-    /** Session expiration in seconds (default: 86400 = 24h) */
-    maxAge?: number;
-    /** Cookie path (default: '/') */
-    path?: string;
-    /** HTTP only flag (default: true) */
-    httpOnly?: boolean;
-    /** Secure flag - use HTTPS only (default: true in production) */
-    secure?: boolean;
-    /** SameSite policy (default: 'lax') */
-    sameSite?: 'strict' | 'lax' | 'none';
-}
 /**
  * Rate limiting configuration
  */
@@ -162,11 +154,6 @@ export interface AuthConfig {
     jwt: JwtConfig;
     /** Password hashing configuration */
     hash?: HashConfig;
-    /**
-     * Legacy session cookie configuration
-     * @deprecated Use createSessionMiddleware from session.ts for full session management
-     */
-    session?: LegacySessionConfig;
     /** Rate limiting configuration */
     rateLimit?: RateLimitConfig;
     /**
@@ -177,6 +164,7 @@ export interface AuthConfig {
     /**
      * Token blacklist checker - check if token is revoked
      * Called on every authenticated request
+     * @deprecated Use `tokenStore` with TokenStore interface instead
      */
     isTokenRevoked?: (tokenId: string) => Promise<boolean>;
     /**
@@ -234,16 +222,65 @@ export interface AuthMiddlewareOptions {
     guards?: Array<GuardDefinition | string>;
 }
 /**
- * Authenticated request context extension
+ * Base auth context shared by all auth modes
+ */
+export interface BaseAuthContext {
+    /** Whether the request is authenticated */
+    isAuthenticated: boolean;
+}
+/**
+ * Auth context for native JWT authentication (authPlugin)
+ *
+ * This context is set when using the built-in authPlugin with JWT tokens.
+ * Provides access to the decoded token payload.
  */
-export interface AuthContext {
+export interface NativeAuthContext extends BaseAuthContext {
+    /** Discriminant for native JWT auth mode */
+    authMode: 'native';
     /** Authenticated user (undefined if optional auth and no token) */
     user?: User;
+    /** Raw JWT token string (if extracted from request) */
+    token?: string;
     /** Decoded token payload */
-    token?: TokenPayload;
-    /** Check if user is authenticated */
-    isAuthenticated: boolean;
+    payload?: TokenPayload;
 }
+/**
+ * Auth context for external authentication adapters
+ *
+ * This context is set when using an AuthAdapter (BetterAuth, Clerk, Auth0, etc.).
+ * Provides access to the provider's session data.
+ */
+export interface AdapterAuthContext extends BaseAuthContext {
+    /** Discriminant for adapter auth mode */
+    authMode: 'adapter';
+    /** Authenticated user (undefined if not authenticated) */
+    user?: User;
+    /** Provider identifier (e.g., 'better-auth', 'clerk', 'auth0') */
+    providerId: string;
+    /** Provider-specific session data */
+    session?: unknown;
+}
+/**
+ * Authenticated request context extension
+ *
+ * This is a discriminated union based on `authMode`:
+ * - `'native'`: Built-in JWT authentication via authPlugin
+ * - `'adapter'`: External provider via AuthAdapter
+ *
+ * Use the `authMode` discriminant for type-safe access to mode-specific properties:
+ *
+ * @example
+ * ```typescript
+ * if (ctx.auth?.authMode === 'native') {
+ *   // Access JWT-specific properties
+ *   console.log(ctx.auth.payload?.sub);
+ * } else if (ctx.auth?.authMode === 'adapter') {
+ *   // Access adapter-specific properties
+ *   console.log(ctx.auth.providerId);
+ * }
+ * ```
+ */
+export type AuthContext = NativeAuthContext | AdapterAuthContext;
 declare module '@veloxts/core' {
     interface BaseContext {
         /** Auth context - available when auth middleware is used */

package/package.json

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