@nauth-toolkit/nestjs 0.1.13 → 0.1.17

package/dist/factories/storage-adapter.factory.js

@@ -1,8 +1,37 @@
 "use strict";
+/**
+ * Storage Adapter Factory Functions
+ *
+ * Provides clean factory functions for creating storage adapters.
+ * These factories handle proper initialization and simplify configuration.
+ *
+ * @example
+ * ```typescript
+ * import { createDatabaseStorageAdapter, createRedisStorageAdapter } from '@nauth-toolkit/nestjs';
+ *
+ * export const authConfig = {
+ *   // Database adapter (uses existing TypeORM connection)
+ *   storageAdapter: createDatabaseStorageAdapter(),
+ *
+ *   // Or Redis adapter
+ *   storageAdapter: createRedisStorageAdapter(process.env.REDIS_URL),
+ * };
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDatabaseStorageAdapter = createDatabaseStorageAdapter;
 exports.createRedisStorageAdapter = createRedisStorageAdapter;
 exports.createRedisClusterAdapter = createRedisClusterAdapter;
+/**
+ * Check whether an unknown error is a Node "MODULE_NOT_FOUND" for a specific module.
+ *
+ * We intentionally match by both error code and the module name inside the message to avoid
+ * incorrectly catching nested missing modules.
+ *
+ * @param error - Unknown caught error
+ * @param moduleName - The module name we expect to be missing (e.g. '@nauth-toolkit/storage-database')
+ * @returns True if this error represents "moduleName is not installed"
+ */
 function isModuleNotFoundFor(error, moduleName) {
     if (!(error instanceof Error)) {
         return false;
@@ -11,9 +40,37 @@ function isModuleNotFoundFor(error, moduleName) {
     if (errno.code !== 'MODULE_NOT_FOUND') {
         return false;
     }
+    // Node error messages usually contain: "Cannot find module '<name>'"
     return typeof error.message === 'string' && error.message.includes(`'${moduleName}'`);
 }
+/**
+ * Create a database storage adapter
+ *
+ * Uses the existing TypeORM connection. Make sure storage entities are included
+ * in your TypeORM.forRoot() configuration:
+ *
+ * ```typescript
+ * import { getNAuthTransientStorageEntities } from '@nauth-toolkit/database-typeorm-postgres';
+ * TypeOrmModule.forRoot({
+ *   entities: [...getNAuthEntities(), ...getNAuthTransientStorageEntities()],
+ * });
+ * ```
+ *
+ * @returns DatabaseStorageAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createDatabaseStorageAdapter } from '@nauth-toolkit/nestjs';
+ *
+ * export const authConfig = {
+ *   storageAdapter: createDatabaseStorageAdapter(),
+ *   // ... other config
+ * };
+ * ```
+ */
 function createDatabaseStorageAdapter() {
+    // Lazy import to avoid bundling if not used.
+    // ⚠️ Note: This adapter lives in a separate package and must be installed by the consumer app.
     let DatabaseStorageAdapterCtor;
     try {
         const mod = require('@nauth-toolkit/storage-database');
@@ -32,9 +89,45 @@ function createDatabaseStorageAdapter() {
         }
         throw error;
     }
+    // Repositories are injected by AuthModule via setRepositories (when available).
     return new DatabaseStorageAdapterCtor(null, null, null);
 }
+/**
+ * Create a Redis storage adapter
+ *
+ * Creates and connects a Redis client automatically using the `redis` package (node-redis).
+ * The client connection is managed internally by the adapter.
+ *
+ * Supports both single-instance Redis and Redis Cluster configurations.
+ *
+ * @param url - Redis connection URL (default: 'redis://localhost:6379')
+ *   Supports authentication in URL format:
+ *   - redis://localhost:6379 (no auth)
+ *   - redis://:password@localhost:6379 (password only)
+ *   - redis://username:password@localhost:6379 (username + password)
+ *   - rediss://localhost:6379 (TLS/SSL, with optional auth)
+ * @returns RedisStorageAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createRedisStorageAdapter, createRedisClusterAdapter } from '@nauth-toolkit/nestjs';
+ *
+ * export const authConfig = {
+ *   // Single-instance Redis
+ *   storageAdapter: createRedisStorageAdapter(process.env.REDIS_URL),
+ *
+ *   // Or Redis Cluster (for production high-availability)
+ *   storageAdapter: createRedisClusterAdapter([
+ *     { url: 'redis://redis-node-1:6379' },
+ *     { url: 'redis://redis-node-2:6379' },
+ *     { url: 'redis://redis-node-3:6379' },
+ *   ]),
+ * };
+ * ```
+ */
 function createRedisStorageAdapter(url = 'redis://localhost:6379') {
+    // Lazy import to avoid bundling if not used.
+    // ⚠️ Note: This adapter + the redis client are separate deps that must be installed by the consumer app.
     let RedisStorageAdapterCtor;
     try {
         const mod = require('@nauth-toolkit/storage-redis');
@@ -72,9 +165,43 @@ function createRedisStorageAdapter(url = 'redis://localhost:6379') {
         throw error;
     }
     const redisClient = createClientFn({ url });
+    // Don't connect here - let adapter.initialize() handle connection
+    // This ensures proper error handling and allows initialize() to wait for connection
     return new RedisStorageAdapterCtor(redisClient);
 }
+/**
+ * Create a Redis Cluster storage adapter
+ *
+ * Creates and connects a Redis Cluster client automatically using the `redis` package (node-redis).
+ * The cluster client handles automatic topology discovery, command routing, and failover.
+ *
+ * **Production Use:**
+ * Use Redis Cluster for high-availability production deployments. The cluster automatically:
+ * - Discovers cluster topology
+ * - Routes commands to correct nodes based on key hash slots
+ * - Handles node failures and redirects (MOVED/ASK errors)
+ * - Provides high availability and horizontal scaling
+ *
+ * @param nodes - Array of cluster node URLs
+ * @returns RedisStorageAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createRedisClusterAdapter } from '@nauth-toolkit/nestjs';
+ *
+ * export const authConfig = {
+ *   // Redis Cluster with 3 nodes
+ *   storageAdapter: createRedisClusterAdapter([
+ *     { url: 'redis://redis-node-1:6379' },
+ *     { url: 'redis://redis-node-2:6379' },
+ *     { url: 'redis://redis-node-3:6379' },
+ *   ]),
+ * };
+ * ```
+ */
 function createRedisClusterAdapter(nodes) {
+    // Lazy import to avoid bundling if not used.
+    // ⚠️ Note: This adapter + the redis client are separate deps that must be installed by the consumer app.
     let RedisStorageAdapterCtor;
     try {
         const mod = require('@nauth-toolkit/storage-redis');
@@ -114,6 +241,8 @@ function createRedisClusterAdapter(nodes) {
     const clusterClient = createClusterFn({
         rootNodes: nodes,
     });
+    // Don't connect here - let adapter.initialize() handle connection
+    // This ensures proper error handling and allows initialize() to wait for connection
     return new RedisStorageAdapterCtor(clusterClient);
 }
 //# sourceMappingURL=storage-adapter.factory.js.map

package/dist/factories/storage-adapter.factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage-adapter.factory.js","sourceRoot":"","sources":["../../src/factories/storage-adapter.factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage-adapter.factory.js","sourceRoot":"","sources":["../../src/factories/storage-adapter.factory.ts"],"names":[],"mappings":"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"}

package/dist/filters/nauth-http-exception.filter.d.ts

@@ -1,7 +1,87 @@
 import { ExceptionFilter, ArgumentsHost } from '@nestjs/common';
 import { NAuthException } from '@nauth-toolkit/core';
+/**
+ * HTTP Exception Filter for NAuthException
+ *
+ * **Utility filter provided by nauth-toolkit** to properly map `NAuthException` domain exceptions
+ * to appropriate HTTP status codes and response formats.
+ *
+ * **Purpose:**
+ * This filter automatically converts `NAuthException` errors to HTTP responses with correct
+ * status codes using the `getHttpStatusForErrorCode()` helper function:
+ * - `AUTH_INVALID_CREDENTIALS` → 401 Unauthorized
+ * - `RATE_LIMIT_*` → 429 Too Many Requests
+ * - `VALIDATION_FAILED` → 400 Bad Request
+ * - `NOT_FOUND` → 404 Not Found
+ * - `INTERNAL_ERROR` → 500 Internal Server Error
+ * - etc.
+ *
+ * **Usage:**
+ * This filter is **recommended** for most applications as it ensures proper HTTP status codes.
+ * You can use it as-is, or extend it with custom logic (logging, monitoring, etc.).
+ *
+ * **Important:** This filter ONLY catches `NAuthException`. It will NOT interfere with
+ * your application's other exception filters or error handling.
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Use nauth-toolkit's filter for proper HTTP status codes
+ * import { NAuthHttpExceptionFilter } from '@nauth-toolkit/nestjs';
+ * app.useGlobalFilters(new NAuthHttpExceptionFilter());
+ *
+ * // Optional: Extend with custom logic
+ * @Catch(NAuthException)
+ * export class CustomNAuthFilter extends NAuthHttpExceptionFilter {
+ *   catch(exception: NAuthException, host: ArgumentsHost) {
+ *     // Add custom logging/monitoring
+ *     this.logger.error('Auth error', exception);
+ *     // Call parent for standard error handling
+ *     super.catch(exception, host);
+ *   }
+ * }
+ * ```
+ *
+ * **Response format:**
+ * ```json
+ * {
+ *   "statusCode": 429,
+ *   "code": "RATE_LIMIT_SMS",
+ *   "message": "Too many verification SMS sent",
+ *   "details": {
+ *     "retryAfter": 3600,
+ *     "currentCount": 4
+ *   },
+ *   "timestamp": "2025-10-31T12:00:00.000Z",
+ *   "path": "/auth/verify-phone"
+ * }
+ * ```
+ *
+ * **Customization:**
+ * If you need custom behavior, extend this class or create your own filter:
+ * ```typescript
+ * @Catch(NAuthException)
+ * export class CustomNAuthFilter extends NAuthHttpExceptionFilter {
+ *   catch(exception: NAuthException, host: ArgumentsHost) {
+ *     // Add additional logging
+ *     this.logger.error(exception);
+ *
+ *     // Call parent or implement custom logic
+ *     super.catch(exception, host);
+ *   }
+ * }
+ * ```
+ */
 export declare class NAuthHttpExceptionFilter implements ExceptionFilter<NAuthException> {
     private readonly logger;
+    /**
+     * Catch and process NAuthException
+     *
+     * Converts the exception to an HTTP response with appropriate status code.
+     * Logs errors for debugging and monitoring.
+     *
+     * @param exception - The NAuthException instance
+     * @param host - ArgumentsHost for accessing request/response
+     */
     catch(exception: NAuthException, host: ArgumentsHost): void;
 }
 //# sourceMappingURL=nauth-http-exception.filter.d.ts.map

package/dist/filters/nauth-http-exception.filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nauth-http-exception.filter.d.ts","sourceRoot":"","sources":["../../src/filters/nauth-http-exception.filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAS,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAA6B,MAAM,qBAAqB,CAAC;AAyEhF,qBACa,wBAAyB,YAAW,eAAe,CAAC,cAAc,CAAC;IAC9E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IAWpE,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;CAgG5D"}
+{"version":3,"file":"nauth-http-exception.filter.d.ts","sourceRoot":"","sources":["../../src/filters/nauth-http-exception.filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAS,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAA6B,MAAM,qBAAqB,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,qBACa,wBAAyB,YAAW,eAAe,CAAC,cAAc,CAAC;IAC9E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IAEpE;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;CAgG5D"}

package/dist/filters/nauth-http-exception.filter.js

@@ -10,13 +10,97 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NAuthHttpExceptionFilter = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nauth-toolkit/core");
+/**
+ * HTTP Exception Filter for NAuthException
+ *
+ * **Utility filter provided by nauth-toolkit** to properly map `NAuthException` domain exceptions
+ * to appropriate HTTP status codes and response formats.
+ *
+ * **Purpose:**
+ * This filter automatically converts `NAuthException` errors to HTTP responses with correct
+ * status codes using the `getHttpStatusForErrorCode()` helper function:
+ * - `AUTH_INVALID_CREDENTIALS` → 401 Unauthorized
+ * - `RATE_LIMIT_*` → 429 Too Many Requests
+ * - `VALIDATION_FAILED` → 400 Bad Request
+ * - `NOT_FOUND` → 404 Not Found
+ * - `INTERNAL_ERROR` → 500 Internal Server Error
+ * - etc.
+ *
+ * **Usage:**
+ * This filter is **recommended** for most applications as it ensures proper HTTP status codes.
+ * You can use it as-is, or extend it with custom logic (logging, monitoring, etc.).
+ *
+ * **Important:** This filter ONLY catches `NAuthException`. It will NOT interfere with
+ * your application's other exception filters or error handling.
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Use nauth-toolkit's filter for proper HTTP status codes
+ * import { NAuthHttpExceptionFilter } from '@nauth-toolkit/nestjs';
+ * app.useGlobalFilters(new NAuthHttpExceptionFilter());
+ *
+ * // Optional: Extend with custom logic
+ * @Catch(NAuthException)
+ * export class CustomNAuthFilter extends NAuthHttpExceptionFilter {
+ *   catch(exception: NAuthException, host: ArgumentsHost) {
+ *     // Add custom logging/monitoring
+ *     this.logger.error('Auth error', exception);
+ *     // Call parent for standard error handling
+ *     super.catch(exception, host);
+ *   }
+ * }
+ * ```
+ *
+ * **Response format:**
+ * ```json
+ * {
+ *   "statusCode": 429,
+ *   "code": "RATE_LIMIT_SMS",
+ *   "message": "Too many verification SMS sent",
+ *   "details": {
+ *     "retryAfter": 3600,
+ *     "currentCount": 4
+ *   },
+ *   "timestamp": "2025-10-31T12:00:00.000Z",
+ *   "path": "/auth/verify-phone"
+ * }
+ * ```
+ *
+ * **Customization:**
+ * If you need custom behavior, extend this class or create your own filter:
+ * ```typescript
+ * @Catch(NAuthException)
+ * export class CustomNAuthFilter extends NAuthHttpExceptionFilter {
+ *   catch(exception: NAuthException, host: ArgumentsHost) {
+ *     // Add additional logging
+ *     this.logger.error(exception);
+ *
+ *     // Call parent or implement custom logic
+ *     super.catch(exception, host);
+ *   }
+ * }
+ * ```
+ */
 let NAuthHttpExceptionFilter = NAuthHttpExceptionFilter_1 = class NAuthHttpExceptionFilter {
     logger = new common_1.Logger(NAuthHttpExceptionFilter_1.name);
+    /**
+     * Catch and process NAuthException
+     *
+     * Converts the exception to an HTTP response with appropriate status code.
+     * Logs errors for debugging and monitoring.
+     *
+     * @param exception - The NAuthException instance
+     * @param host - ArgumentsHost for accessing request/response
+     */
     catch(exception, host) {
         const ctx = host.switchToHttp();
+        // Platform-agnostic: Use generic types that work with any HTTP adapter (Express, Fastify, etc.)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const response = ctx.getResponse();
         const request = ctx.getRequest();
+        // Get HTTP status code from error code
         const statusCode = (0, core_1.getHttpStatusForErrorCode)(exception.code);
+        // Build error response
         const errorResponse = {
             statusCode,
             code: exception.code,
@@ -25,26 +109,36 @@ let NAuthHttpExceptionFilter = NAuthHttpExceptionFilter_1 = class NAuthHttpExcep
             timestamp: exception.timestamp,
             path: request.url || 'unknown',
         };
+        // Log error for debugging and monitoring
+        // Use appropriate log level based on status code
         if (statusCode >= 500) {
+            // Server errors - log as error with full details
             this.logger.error(`[${exception.code}] ${exception.message} - Path: ${request.url || 'unknown'} - Method: ${request.method || 'unknown'}`, exception.stack, 'NAuthHttpExceptionFilter');
         }
         else if (statusCode >= 400) {
+            // Client errors - log as warn (less critical)
             this.logger.warn(`[${exception.code}] ${exception.message} - Path: ${request.url || 'unknown'} - Method: ${request.method || 'unknown'}`, 'NAuthHttpExceptionFilter');
         }
         else {
+            // Other status codes - log as debug
             this.logger.debug(`[${exception.code}] ${exception.message} - Path: ${request.url || 'unknown'}`, 'NAuthHttpExceptionFilter');
         }
+        // Send response (platform-agnostic - works with Express, Fastify, etc.)
+        // Set status code first, then send JSON (avoid chaining for better compatibility)
         try {
+            // Method 1: Express pattern - set status then json
             if (response.status && typeof response.status === 'function' && typeof response.json === 'function') {
                 response.status(statusCode);
                 response.json(errorResponse);
                 return;
             }
+            // Method 2: Fastify pattern - use code() method
             if (response.code && typeof response.code === 'function' && typeof response.send === 'function') {
                 response.code(statusCode);
                 response.send(errorResponse);
                 return;
             }
+            // Method 3: Direct statusCode property (Express/Fastify fallback)
             if (typeof response.statusCode !== 'undefined') {
                 response.statusCode = statusCode;
             }
@@ -56,6 +150,7 @@ let NAuthHttpExceptionFilter = NAuthHttpExceptionFilter_1 = class NAuthHttpExcep
                 response.send(errorResponse);
                 return;
             }
+            // Method 4: Last resort - try to set status and send
             if (response.status && typeof response.status === 'function') {
                 response.status(statusCode);
             }
@@ -70,6 +165,7 @@ let NAuthHttpExceptionFilter = NAuthHttpExceptionFilter_1 = class NAuthHttpExcep
             }
         }
         catch (error) {
+            // If all else fails, log the error but don't crash
             this.logger.error(`Failed to send error response: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error.stack : undefined, 'NAuthHttpExceptionFilter');
         }
     }

package/dist/filters/nauth-http-exception.filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"nauth-http-exception.filter.js","sourceRoot":"","sources":["../../src/filters/nauth-http-exception.filter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nauth-http-exception.filter.js","sourceRoot":"","sources":["../../src/filters/nauth-http-exception.filter.ts"],"names":[],"mappings":"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"}

package/dist/guards/auth.guard.d.ts

@@ -3,6 +3,22 @@ import { Reflector } from '@nestjs/core';
 import { Repository } from 'typeorm';
 import { NAuthConfig, BaseUser } from '@nauth-toolkit/core';
 import { JwtService, SessionService } from '@nauth-toolkit/core/internal';
+/**
+ * Native Auth Guard (NO Passport dependency)
+ *
+ * Validates JWT tokens from Authorization header
+ * and attaches user to request. Supports API clients.
+ *
+ * Security Features:
+ * - JWT token validation with session-based revocation
+ * - Session expiration checking
+ * - Token reuse detection via session management
+ * - Automatic session activity updates
+ *
+ * @example
+ * // Works with Authorization header (API clients)
+ * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ */
 export declare class AuthGuard implements CanActivate {
     private readonly reflector;
     private readonly jwtService;
@@ -11,6 +27,16 @@ export declare class AuthGuard implements CanActivate {
     private readonly config;
     constructor(reflector: Reflector, jwtService: JwtService, sessionService: SessionService, userRepository: Repository<BaseUser>, config: NAuthConfig);
     canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Extract JWT token from request with strict source validation based on configuration
+     *
+     * Security rules:
+     * - JSON mode: Only Authorization header (reject cookies if present)
+     * - Cookies mode: Only httpOnly cookies (reject Bearer header if present)
+     * - Hybrid mode: Cookies first (web), then Authorization header (mobile)
+     *
+     * @param request - HTTP request
+     */
     private extractToken;
 }
 //# sourceMappingURL=auth.guard.d.ts.map

package/dist/guards/auth.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.guard.d.ts","sourceRoot":"","sources":["../../src/guards/auth.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,WAAW,EAAE,gBAAgB,EAAU,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,WAAW,EAIX,QAAQ,EAET,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAoB1E,qBACa,SAAU,YAAW,WAAW;IAEzC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAE/B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBANN,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAE9B,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EAEpC,MAAM,EAAE,WAAW;IAGhC,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IA8H9D,OAAO,CAAC,YAAY;CAwCrB"}
+{"version":3,"file":"auth.guard.d.ts","sourceRoot":"","sources":["../../src/guards/auth.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,WAAW,EAAE,gBAAgB,EAAU,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,WAAW,EAIX,QAAQ,EAET,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAI1E;;;;;;;;;;;;;;;GAeG;AACH,qBACa,SAAU,YAAW,WAAW;IAEzC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAE/B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBANN,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAE9B,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EAEpC,MAAM,EAAE,WAAW;IAGhC,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoH9D;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;CAwCrB"}

package/dist/guards/auth.guard.js

@@ -20,6 +20,22 @@ const core_2 = require("@nauth-toolkit/core");
 const internal_1 = require("@nauth-toolkit/core/internal");
 const public_decorator_1 = require("../decorators/public.decorator");
 const token_delivery_decorator_1 = require("../decorators/token-delivery.decorator");
+/**
+ * Native Auth Guard (NO Passport dependency)
+ *
+ * Validates JWT tokens from Authorization header
+ * and attaches user to request. Supports API clients.
+ *
+ * Security Features:
+ * - JWT token validation with session-based revocation
+ * - Session expiration checking
+ * - Token reuse detection via session management
+ * - Automatic session activity updates
+ *
+ * @example
+ * // Works with Authorization header (API clients)
+ * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ */
 let AuthGuard = class AuthGuard {
     reflector;
     jwtService;
@@ -34,6 +50,7 @@ let AuthGuard = class AuthGuard {
         this.config = config;
     }
     async canActivate(context) {
+        // Check if route is public
         const isPublic = this.reflector.getAllAndOverride(public_decorator_1.IS_PUBLIC_KEY, [
             context.getHandler(),
             context.getClass(),
@@ -42,26 +59,38 @@ let AuthGuard = class AuthGuard {
             return true;
         }
         const request = context.switchToHttp().getRequest();
+        // Extract token according to configured delivery mode
         const token = this.extractToken(context);
         if (!token) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.TOKEN_INVALID, 'No token provided');
         }
+        // Validate token
         const validation = await this.jwtService.validateAccessToken(token);
         if (!validation.valid) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.TOKEN_INVALID, validation.error || 'Invalid token');
         }
+        // ============================================================================
+        // CRITICAL SECURITY FIX #3: Optimistic Locking for TOCTOU Prevention
+        // ============================================================================
+        // Check if session is revoked
         const sessionId = validation.payload.sessionId;
         const session = await this.sessionService.findByIdLight(sessionId);
         if (!session) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.SESSION_NOT_FOUND, 'Session not found');
         }
+        // Store initial version for optimistic locking check
         const initialVersion = session.version;
         if (session.isRevoked) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.TOKEN_REUSE_DETECTED, 'Session has been revoked');
         }
+        // Check if session is expired
         if (session.expiresAt < new Date()) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.SESSION_EXPIRED, 'Session has expired');
         }
+        // Load user by sub (external identifier from JWT payload)
+        // Include all non-sensitive fields needed by endpoints (profile, MFA status, etc.)
+        // Excludes: passwordHash, passwordHistory, totpSecret, backupCodes (sensitive)
+        //  TODO: SHIT Work. NEEDS TO BE FIXED.
         const user = await this.userRepository.findOne({
             select: [
                 'id',
@@ -103,14 +132,27 @@ let AuthGuard = class AuthGuard {
         if (!user.isActive) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.ACCOUNT_INACTIVE, 'Account is not active');
         }
+        // SECURITY CRITICAL: Re-check session hasn't been modified (optimistic locking)
+        // Prevents TOCTOU (Time-of-Check-Time-of-Use) vulnerabilities
         const revalidated = await this.sessionService.findByIdLight(sessionId);
         if (!revalidated || revalidated.version !== initialVersion || revalidated.isRevoked) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.TOKEN_INVALID, 'Session was modified during request - possible security breach');
         }
+        // Attach user to request
         request.user = user;
         request.token = validation.payload;
         return true;
     }
+    /**
+     * Extract JWT token from request with strict source validation based on configuration
+     *
+     * Security rules:
+     * - JSON mode: Only Authorization header (reject cookies if present)
+     * - Cookies mode: Only httpOnly cookies (reject Bearer header if present)
+     * - Hybrid mode: Cookies first (web), then Authorization header (mobile)
+     *
+     * @param request - HTTP request
+     */
     extractToken(context) {
         const request = context.switchToHttp().getRequest();
         const cfg = this.config.tokenDelivery;
@@ -119,6 +161,7 @@ let AuthGuard = class AuthGuard {
         const headerToken = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
         const accessTokenCookieName = (0, core_2.getAccessTokenCookieName)(this.config);
         const cookieToken = request.cookies?.[accessTokenCookieName];
+        // Resolve per-request delivery. Route override > hybrid policy > method fallback
         const routeMode = this.reflector.get(token_delivery_decorator_1.TOKEN_DELIVERY_KEY, context.getHandler());
         let effective = 'json';
         if (routeMode) {
@@ -139,6 +182,7 @@ let AuthGuard = class AuthGuard {
             }
             return cookieToken || null;
         }
+        // effective === 'json'
         if (cookieToken && !headerToken) {
             throw new core_2.NAuthException(core_2.AuthErrorCode.COOKIES_NOT_ALLOWED, 'Cookie tokens are not allowed in JSON-only path.');
         }

package/dist/guards/auth.guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.guard.js","sourceRoot":"","sources":["../../src/guards/auth.guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.guard.js","sourceRoot":"","sources":["../../src/guards/auth.guard.ts"],"names":[],"mappings":"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"}

package/dist/guards/csrf.guard.d.ts

@@ -2,6 +2,27 @@ import { CanActivate, ExecutionContext } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { NAuthConfig } from '@nauth-toolkit/core';
 import { CsrfService } from '../services/csrf.service';
+/**
+ * CSRF Guard
+ *
+ * Validates CSRF tokens for state-changing requests when using cookie-based token delivery.
+ * CSRF protection prevents Cross-Site Request Forgery attacks.
+ *
+ * Security Rules:
+ * - Only enforces for cookie-based token delivery (cookies or hybrid with web origins)
+ * - Skips safe HTTP methods (GET, HEAD, OPTIONS)
+ * - Skips excluded paths from configuration
+ * - Validates CSRF token from header matches cookie value
+ *
+ * @example
+ * ```typescript
+ * // Applied globally via AuthModule when tokenDelivery.method === 'cookies' or 'hybrid'
+ * // Or applied per-route:
+ * @UseGuards(CsrfGuard)
+ * @Post('sensitive-action')
+ * async sensitiveAction() { ... }
+ * ```
+ */
 export declare class CsrfGuard implements CanActivate {
     private readonly config;
     private readonly csrfService;