@nauth-toolkit/core 0.1.14 → 0.1.18

package/dist/handlers/auth.handler.js

@@ -1,7 +1,22 @@
 "use strict";
+/**
+ * Authentication Handler
+ *
+ * Validates JWT tokens and attaches user to request.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context is managed by the adapter, not this handler.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthHandler = void 0;
 const index_1 = require("../index");
+/**
+ * AuthHandler
+ *
+ * Validates JWT tokens and populates user context.
+ * Performs optional authentication by default (doesn't reject unauthenticated requests).
+ */
 class AuthHandler {
     jwtService;
     sessionService;
@@ -15,14 +30,21 @@ class AuthHandler {
         this.config = config;
         this.logger = logger;
     }
+    /**
+     * Handle request - validate token and attach user
+     *
+     * Note: Context is managed by adapter. This handler assumes context is available.
+     */
     async handle(req, _res, next) {
         try {
+            // Skip if route is marked as public
             if (req.attributes.nauthPublic) {
                 await next();
                 return;
             }
             const token = this.extractToken(req);
             if (!token) {
+                // No token - continue without authentication (optional auth)
                 await next();
                 return;
             }
@@ -32,8 +54,9 @@ class AuthHandler {
                 await next();
                 return;
             }
+            // Validate session
             const sessionId = validation.payload.sessionId;
-            const userId = validation.payload.sub;
+            const userId = validation.payload.sub; // Extract userId from token sub claim
             const session = await this.sessionService.findByIdLight(sessionId);
             if (!session) {
                 this.logger?.debug?.('Session not found:', sessionId);
@@ -51,6 +74,7 @@ class AuthHandler {
                 await next();
                 return;
             }
+            // Load user
             const user = await this.userRepository.findOne({
                 select: this.getUserSelectFields(),
                 where: { sub: validation.payload.sub },
@@ -65,18 +89,22 @@ class AuthHandler {
                 await next();
                 return;
             }
+            // Optimistic locking check - ensure session wasn't modified during request
             const revalidated = await this.sessionService.findByIdLight(sessionId);
             if (!revalidated || revalidated.version !== initialVersion || revalidated.isRevoked) {
                 this.logger?.error?.('Session was modified during request - possible security breach');
                 await next();
                 return;
             }
+            // Attach to request attributes
             req.attributes.user = user;
             req.attributes.token = validation.payload;
+            // Store in ContextStorage for service access
             index_1.ContextStorage.set('CURRENT_USER', user);
             index_1.ContextStorage.set('JWT_PAYLOAD', validation.payload);
             index_1.ContextStorage.set('CURRENT_SESSION', sessionId);
             this.logger?.debug?.(`User ${user.sub} authenticated successfully`);
+            // Update CLIENT_INFO with sessionId and userId
             this.updateClientInfoSessionId(sessionId);
             this.updateClientInfoUserId(userId);
             await next();
@@ -86,34 +114,46 @@ class AuthHandler {
             await next();
         }
     }
+    /**
+     * Extract token from request based on delivery mode
+     */
     extractToken(req) {
         const method = this.config.tokenDelivery?.method || 'json';
+        // Get token from header
         const authHeader = req.getHeader('authorization');
         const headerToken = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
+        // Get token from cookie
         const accessTokenCookieName = (0, index_1.getAccessTokenCookieName)(this.config);
         const cookieToken = req.cookies[accessTokenCookieName];
+        // Check for route-level override
         const routeMode = req.attributes.nauthTokenDelivery;
         let effective = 'json';
         if (routeMode) {
             effective = routeMode;
         }
         else if (method === 'hybrid') {
+            // Determine mode based on request characteristics
             effective = (0, index_1.resolveDeliveryForRequest)(req.raw, this.config.tokenDelivery?.hybridPolicy);
         }
         else {
             effective = method === 'cookies' ? 'cookies' : 'json';
         }
         if (effective === 'cookies') {
+            // Cookie mode: Reject if Bearer header present
             if (headerToken && !cookieToken) {
                 throw new index_1.NAuthException(index_1.AuthErrorCode.BEARER_NOT_ALLOWED, 'Bearer tokens are not allowed in cookie-only path.');
             }
             return cookieToken || null;
         }
+        // JSON mode: Reject if cookie present
         if (cookieToken && !headerToken) {
             throw new index_1.NAuthException(index_1.AuthErrorCode.COOKIES_NOT_ALLOWED, 'Cookie tokens are not allowed in JSON-only path.');
         }
         return headerToken || null;
     }
+    /**
+     * Update CLIENT_INFO with session ID from token
+     */
     updateClientInfoSessionId(sessionId) {
         const clientInfo = index_1.ContextStorage.get('CLIENT_INFO');
         if (clientInfo) {
@@ -124,6 +164,9 @@ class AuthHandler {
             }
         }
     }
+    /**
+     * Update CLIENT_INFO with user ID from token
+     */
     updateClientInfoUserId(userId) {
         const clientInfo = index_1.ContextStorage.get('CLIENT_INFO');
         if (clientInfo) {
@@ -134,6 +177,9 @@ class AuthHandler {
             }
         }
     }
+    /**
+     * Get fields to select when loading user
+     */
     getUserSelectFields() {
         return [
             'id',

package/dist/handlers/auth.handler.js.map

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

package/dist/handlers/client-info.handler.d.ts

@@ -1,12 +1,37 @@
+/**
+ * Client Info Handler
+ *
+ * Extracts client information (IP, user agent, device info) from NAuthRequest
+ * and stores in AsyncLocalStorage context.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context initialization is handled by the adapter, not this handler.
+ */
 import { ClientInfoService, NAuthLogger } from '../index';
 import { GeoLocationService } from '../internal';
 import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
+/**
+ * ClientInfoHandler
+ *
+ * First handler in the chain. Extracts client information and stores it
+ * in the context for downstream handlers and services.
+ */
 export declare class ClientInfoHandler {
     private clientInfoService;
     private geoLocationService?;
     private logger?;
     constructor(clientInfoService: ClientInfoService, geoLocationService?: GeoLocationService | undefined, logger?: NAuthLogger | undefined);
+    /**
+     * Handle request - extract and store client info
+     *
+     * Context initialization is handled by the adapter.
+     * This handler assumes context is already available.
+     */
     handle(req: NAuthRequest, res: NAuthResponse, next: () => Promise<void> | void): Promise<void>;
+    /**
+     * Extract client information and store in context
+     */
     private extractAndStore;
 }
 //# sourceMappingURL=client-info.handler.d.ts.map

package/dist/handlers/client-info.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-info.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/client-info.handler.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,iBAAiB,EAAe,WAAW,EAA4B,MAAM,UAAU,CAAC;AACjH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAQrE,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,kBAAkB,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC;gBAFP,iBAAiB,EAAE,iBAAiB,EACpC,kBAAkB,CAAC,EAAE,kBAAkB,YAAA,EACvC,MAAM,CAAC,EAAE,WAAW,YAAA;IASjB,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAa7F,eAAe;CAqD9B"}
+{"version":3,"file":"client-info.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/client-info.handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAkB,iBAAiB,EAAe,WAAW,EAA4B,MAAM,UAAU,CAAC;AACjH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAErE;;;;;GAKG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,kBAAkB,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC;gBAFP,iBAAiB,EAAE,iBAAiB,EACpC,kBAAkB,CAAC,EAAE,kBAAkB,YAAA,EACvC,MAAM,CAAC,EAAE,WAAW,YAAA;IAG9B;;;;;OAKG;IACU,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3G;;OAEG;YACW,eAAe;CAqD9B"}

package/dist/handlers/client-info.handler.js

@@ -1,7 +1,23 @@
 "use strict";
+/**
+ * Client Info Handler
+ *
+ * Extracts client information (IP, user agent, device info) from NAuthRequest
+ * and stores in AsyncLocalStorage context.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context initialization is handled by the adapter, not this handler.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientInfoHandler = void 0;
 const index_1 = require("../index");
+/**
+ * ClientInfoHandler
+ *
+ * First handler in the chain. Extracts client information and stores it
+ * in the context for downstream handlers and services.
+ */
 class ClientInfoHandler {
     clientInfoService;
     geoLocationService;
@@ -11,6 +27,12 @@ class ClientInfoHandler {
         this.geoLocationService = geoLocationService;
         this.logger = logger;
     }
+    /**
+     * Handle request - extract and store client info
+     *
+     * Context initialization is handled by the adapter.
+     * This handler assumes context is already available.
+     */
     async handle(req, res, next) {
         try {
             await this.extractAndStore(req, res);
@@ -20,11 +42,19 @@ class ClientInfoHandler {
         }
         await next();
     }
+    /**
+     * Extract client information and store in context
+     */
     async extractAndStore(req, res) {
+        // Extract user agent
         const userAgent = req.getHeader('user-agent') || 'unknown';
+        // Parse user agent for device/browser info
         const parsedUA = this.clientInfoService.parseUserAgent(userAgent);
+        // Extract device token from cookie or header
+        // Use default cookie name (nauth_device_token) if config not available
         const deviceTokenCookieName = (0, index_1.getDeviceTokenCookieName)();
         const deviceToken = req.cookies[deviceTokenCookieName] || req.getHeader('x-device-token');
+        // Build client info object
         const clientInfo = {
             ipAddress: req.ip,
             userAgent,
@@ -33,13 +63,14 @@ class ClientInfoHandler {
             deviceType: (req.body.deviceType || parsedUA.deviceType || undefined),
             platform: parsedUA.platform || undefined,
             browser: parsedUA.browser || undefined,
-            sessionId: undefined,
-            userId: undefined,
+            sessionId: undefined, // Set later by AuthHandler
+            userId: undefined, // Set later by AuthHandler
             ipCountry: undefined,
             ipCity: undefined,
             ipLatitude: undefined,
             ipLongitude: undefined,
         };
+        // Populate geolocation if service available
         if (this.geoLocationService && clientInfo.ipAddress && clientInfo.ipAddress !== '0.0.0.0') {
             try {
                 const geo = await this.geoLocationService.getIpGeolocation(clientInfo.ipAddress);
@@ -49,11 +80,14 @@ class ClientInfoHandler {
                 clientInfo.ipLongitude = geo.longitude;
             }
             catch (error) {
+                // Log error instead of silently failing
                 this.logger?.error?.(`Geolocation lookup failed for IP ${clientInfo.ipAddress}:`, error instanceof Error ? error.message : 'Unknown error');
             }
         }
+        // Store in context
         index_1.ContextStorage.set('CLIENT_INFO', clientInfo);
         index_1.ContextStorage.set('HTTP_RESPONSE', res.raw);
+        // Also attach to request attributes for handler access
         req.attributes.clientInfo = clientInfo;
     }
 }

package/dist/handlers/client-info.handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-info.handler.js","sourceRoot":"","sources":["../../src/handlers/client-info.handler.ts"],"names":[],"mappings":";;;AAWA,oCAAiH;AAUjH,MAAa,iBAAiB;IAElB;IACA;IACA;IAHV,YACU,iBAAoC,EACpC,kBAAuC,EACvC,MAAoB;QAFpB,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,uBAAkB,GAAlB,kBAAkB,CAAqB;QACvC,WAAM,GAAN,MAAM,CAAc;IAC3B,CAAC;IAQG,KAAK,CAAC,MAAM,CAAC,GAAiB,EAAE,GAAkB,EAAE,IAAgC;QACzF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;IAKO,KAAK,CAAC,eAAe,CAAC,GAAiB,EAAE,GAAkB;QAEjE,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC;QAG3D,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAIlE,MAAM,qBAAqB,GAAG,IAAA,gCAAwB,GAAE,CAAC;QACzD,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,qBAAqB,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QAG1F,MAAM,UAAU,GAAgB;YAC9B,SAAS,EAAE,GAAG,CAAC,EAAE;YACjB,SAAS;YACT,WAAW;YACX,UAAU,EAAG,GAAG,CAAC,IAAI,CAAC,UAAqB,IAAI,QAAQ,CAAC,UAAU,IAAI,SAAS;YAC/E,UAAU,EAAE,CAAE,GAAG,CAAC,IAAI,CAAC,UAAqB,IAAI,QAAQ,CAAC,UAAU,IAAI,SAAS,CAA8B;YAC9G,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,SAAS;YACxC,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,SAAS;YACtC,SAAS,EAAE,SAAS;YACpB,MAAM,EAAE,SAAS;YACjB,SAAS,EAAE,SAAS;YACpB,MAAM,EAAE,SAAS;YACjB,UAAU,EAAE,SAAS;YACrB,WAAW,EAAE,SAAS;SACvB,CAAC;QAGF,IAAI,IAAI,CAAC,kBAAkB,IAAI,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1F,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;gBACjF,UAAU,CAAC,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC;gBACnC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC;gBAC7B,UAAU,CAAC,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC;gBACrC,UAAU,CAAC,WAAW,GAAG,GAAG,CAAC,SAAS,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAEf,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAClB,oCAAoC,UAAU,CAAC,SAAS,GAAG,EAC3D,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CACzD,CAAC;YACJ,CAAC;QACH,CAAC;QAGD,sBAAc,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QAC9C,sBAAc,CAAC,GAAG,CAAC,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QAG7C,GAAG,CAAC,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC;IACzC,CAAC;CACF;AA/ED,8CA+EC"}
+{"version":3,"file":"client-info.handler.js","sourceRoot":"","sources":["../../src/handlers/client-info.handler.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,oCAAiH;AAIjH;;;;;GAKG;AACH,MAAa,iBAAiB;IAElB;IACA;IACA;IAHV,YACU,iBAAoC,EACpC,kBAAuC,EACvC,MAAoB;QAFpB,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,uBAAkB,GAAlB,kBAAkB,CAAqB;QACvC,WAAM,GAAN,MAAM,CAAc;IAC3B,CAAC;IAEJ;;;;;OAKG;IACI,KAAK,CAAC,MAAM,CAAC,GAAiB,EAAE,GAAkB,EAAE,IAAgC;QACzF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAAC,GAAiB,EAAE,GAAkB;QACjE,qBAAqB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC;QAE3D,2CAA2C;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAElE,6CAA6C;QAC7C,uEAAuE;QACvE,MAAM,qBAAqB,GAAG,IAAA,gCAAwB,GAAE,CAAC;QACzD,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,qBAAqB,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QAE1F,2BAA2B;QAC3B,MAAM,UAAU,GAAgB;YAC9B,SAAS,EAAE,GAAG,CAAC,EAAE;YACjB,SAAS;YACT,WAAW;YACX,UAAU,EAAG,GAAG,CAAC,IAAI,CAAC,UAAqB,IAAI,QAAQ,CAAC,UAAU,IAAI,SAAS;YAC/E,UAAU,EAAE,CAAE,GAAG,CAAC,IAAI,CAAC,UAAqB,IAAI,QAAQ,CAAC,UAAU,IAAI,SAAS,CAA8B;YAC9G,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,SAAS;YACxC,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,SAAS;YACtC,SAAS,EAAE,SAAS,EAAE,2BAA2B;YACjD,MAAM,EAAE,SAAS,EAAE,2BAA2B;YAC9C,SAAS,EAAE,SAAS;YACpB,MAAM,EAAE,SAAS;YACjB,UAAU,EAAE,SAAS;YACrB,WAAW,EAAE,SAAS;SACvB,CAAC;QAEF,4CAA4C;QAC5C,IAAI,IAAI,CAAC,kBAAkB,IAAI,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1F,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;gBACjF,UAAU,CAAC,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC;gBACnC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC;gBAC7B,UAAU,CAAC,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC;gBACrC,UAAU,CAAC,WAAW,GAAG,GAAG,CAAC,SAAS,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wCAAwC;gBACxC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAClB,oCAAoC,UAAU,CAAC,SAAS,GAAG,EAC3D,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CACzD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,sBAAc,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QAC9C,sBAAc,CAAC,GAAG,CAAC,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QAE7C,uDAAuD;QACvD,GAAG,CAAC,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC;IACzC,CAAC;CACF;AA/ED,8CA+EC"}

package/dist/handlers/csrf.handler.d.ts

@@ -1,13 +1,45 @@
+/**
+ * CSRF Handler
+ *
+ * Generates and validates CSRF tokens for cookie-based authentication.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context is managed by the adapter, not this handler.
+ *
+ * **Lazy Validation:**
+ * CSRF errors are stored in request attributes instead of thrown immediately.
+ * This allows public routes and requireAuth() to decide how to handle them.
+ */
 import { NAuthConfig, NAuthLogger } from '../index';
 import { CsrfService } from '../services/csrf.service';
 import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
+/**
+ * CsrfHandler
+ *
+ * Handles CSRF token generation and validation for cookie-based authentication.
+ */
 export declare class CsrfHandler {
     private readonly csrfService;
     private readonly config;
     private readonly logger?;
     constructor(csrfService: CsrfService, config: NAuthConfig, logger?: NAuthLogger | undefined);
+    /**
+     * Handle request - generate or validate CSRF token
+     *
+     * Note: Context is managed by adapter. This handler assumes context is available.
+     */
     handle(req: NAuthRequest, res: NAuthResponse, next: () => Promise<void> | void): Promise<void>;
+    /**
+     * Generate CSRF token if not present in cookies
+     */
     private generateTokenIfMissing;
+    /**
+     * Validate CSRF token from request
+     *
+     * Uses lazy validation - stores error in attributes instead of throwing.
+     * requireAuth() helper will throw if error exists.
+     */
     private validateToken;
 }
 //# sourceMappingURL=csrf.handler.d.ts.map

package/dist/handlers/csrf.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csrf.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/csrf.handler.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,WAAW,EAAiC,WAAW,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAUrE,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAFP,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,YAAA;IAQ1B,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAqC7F,sBAAsB;YAsCtB,aAAa;CA0C5B"}
+{"version":3,"file":"csrf.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/csrf.handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAiC,WAAW,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAKrE;;;;GAIG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAFP,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,YAAA;IAGvC;;;;OAIG;IACU,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkC3G;;OAEG;YACW,sBAAsB;IAgCpC;;;;;OAKG;YACW,aAAa;CA0C5B"}

package/dist/handlers/csrf.handler.js

@@ -1,8 +1,27 @@
 "use strict";
+/**
+ * CSRF Handler
+ *
+ * Generates and validates CSRF tokens for cookie-based authentication.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context is managed by the adapter, not this handler.
+ *
+ * **Lazy Validation:**
+ * CSRF errors are stored in request attributes instead of thrown immediately.
+ * This allows public routes and requireAuth() to decide how to handle them.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CsrfHandler = void 0;
 const index_1 = require("../index");
+/** HTTP methods that don't require CSRF validation */
 const SAFE_METHODS = ['GET', 'HEAD', 'OPTIONS'];
+/**
+ * CsrfHandler
+ *
+ * Handles CSRF token generation and validation for cookie-based authentication.
+ */
 class CsrfHandler {
     csrfService;
     config;
@@ -12,58 +31,86 @@ class CsrfHandler {
         this.config = config;
         this.logger = logger;
     }
+    /**
+     * Handle request - generate or validate CSRF token
+     *
+     * Note: Context is managed by adapter. This handler assumes context is available.
+     */
     async handle(req, res, next) {
+        // Skip if token delivery is not cookies or hybrid
         const method = this.config.tokenDelivery?.method || 'json';
         if (method !== 'cookies' && method !== 'hybrid') {
             await next();
             return;
         }
+        // Safe methods: Generate token if missing
         if (SAFE_METHODS.includes(req.method)) {
             await this.generateTokenIfMissing(req, res);
             await next();
             return;
         }
+        // Skip public routes (CSRF not required)
         if (req.attributes.nauthPublic) {
             await next();
             return;
         }
+        // Skip excluded paths
         const excludedPaths = this.config.security?.csrf?.excludedPaths || [];
         if (excludedPaths.some((p) => req.path.startsWith(p))) {
             await next();
             return;
         }
+        // Validate CSRF token for unsafe methods (POST, PUT, DELETE, etc.)
         await this.validateToken(req);
         await next();
     }
+    /**
+     * Generate CSRF token if not present in cookies
+     */
     async generateTokenIfMissing(req, res) {
         const cookieName = this.csrfService.getCookieName();
         const existingToken = req.cookies[cookieName];
         if (existingToken) {
+            // Token exists, clear any previous error state
             delete req.attributes.nauthCsrfError;
             return;
         }
+        // Generate new token
         const token = this.csrfService.generateToken();
+        // Build cookie options
         const cookieOptions = {
-            httpOnly: true,
+            httpOnly: true, // Prevents XSS access to token
             secure: this.config.tokenDelivery?.cookieOptions?.secure ?? true,
             sameSite: (this.config.tokenDelivery?.cookieOptions?.sameSite || 'strict'),
             domain: this.config.tokenDelivery?.cookieOptions?.domain,
             path: '/',
             ...this.csrfService.getCookieOptions(),
         };
+        // Set cookie
         res.setCookie(cookieName, token, cookieOptions);
+        // Also expose token in response header (since cookie is httpOnly)
         res.header(this.csrfService.getHeaderName(), token);
         this.logger?.debug?.('CSRF token generated and set');
     }
+    /**
+     * Validate CSRF token from request
+     *
+     * Uses lazy validation - stores error in attributes instead of throwing.
+     * requireAuth() helper will throw if error exists.
+     */
     async validateToken(req) {
         const headerName = this.csrfService.getHeaderName();
         const cookieName = this.csrfService.getCookieName();
+        // Get token from header or body
         let tokenFromRequest = req.getHeader(headerName);
         if (!tokenFromRequest && req.body) {
+            // Check common body fields
             const body = req.body;
             tokenFromRequest = (body[headerName] || body['_csrf'] || body['csrfToken']);
         }
+        // Get token from cookie
         const cookieToken = req.cookies[cookieName];
+        // Validate - store errors lazily
         if (!tokenFromRequest) {
             req.attributes.nauthCsrfError = new index_1.NAuthException(index_1.AuthErrorCode.CSRF_TOKEN_MISSING, `CSRF token required. Include ${headerName} header or _csrf/csrfToken in body with the value from ${cookieName} cookie.`);
             return;
@@ -72,6 +119,7 @@ class CsrfHandler {
             req.attributes.nauthCsrfError = new index_1.NAuthException(index_1.AuthErrorCode.CSRF_TOKEN_MISSING, 'CSRF cookie missing. Make a GET request first to obtain a token.');
             return;
         }
+        // Validate token matches
         const isValid = this.csrfService.validateToken(String(tokenFromRequest), cookieToken);
         if (!isValid) {
             req.attributes.nauthCsrfError = new index_1.NAuthException(index_1.AuthErrorCode.CSRF_TOKEN_INVALID, 'CSRF token mismatch.');

package/dist/handlers/csrf.handler.js.map

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

package/dist/handlers/token-delivery.handler.d.ts

@@ -1,10 +1,26 @@
+/**
+ * Token Delivery Handler
+ *
+ * Handles response interception to deliver tokens via Cookies or JSON.
+ */
 import { NAuthConfig, NAuthLogger } from '../index';
 import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
 export declare class TokenDeliveryHandler {
     private config;
     private logger?;
     constructor(config: NAuthConfig, logger?: NAuthLogger | undefined);
+    /**
+     * Type guard for detecting an auth response payload.
+     *
+     * We intentionally validate types at runtime because the handler receives `unknown`
+     * response bodies from framework adapters.
+     */
     private isAuthResponseBody;
+    /**
+     * Process the response body.
+     * If it contains tokens, handle delivery and return sanitized body.
+     * If not, return original body.
+     */
     handleResponse(req: NAuthRequest, res: NAuthResponse, body: unknown): Promise<unknown>;
     private resolveDeliveryMode;
     private setTokenCookies;

package/dist/handlers/token-delivery.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-delivery.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/token-delivery.handler.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,WAAW,EAIX,WAAW,EACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAsB,MAAM,wBAAwB,CAAC;AAEzF,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM,CAAC;gBADP,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,YAAA;IAS9B,OAAO,CAAC,kBAAkB;IAab,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BnG,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,WAAW;CAsBpB"}
+{"version":3,"file":"token-delivery.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/token-delivery.handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EAIX,WAAW,EACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAsB,MAAM,wBAAwB,CAAC;AAEzF,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM,CAAC;gBADP,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,YAAA;IAG9B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;OAIG;IACU,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BnG,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,WAAW;CAsBpB"}

package/dist/handlers/token-delivery.handler.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Token Delivery Handler
+ *
+ * Handles response interception to deliver tokens via Cookies or JSON.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TokenDeliveryHandler = void 0;
 const index_1 = require("../index");
@@ -9,17 +14,31 @@ class TokenDeliveryHandler {
         this.config = config;
         this.logger = logger;
     }
+    /**
+     * Type guard for detecting an auth response payload.
+     *
+     * We intentionally validate types at runtime because the handler receives `unknown`
+     * response bodies from framework adapters.
+     */
     isAuthResponseBody(body) {
         if (!body || typeof body !== 'object')
             return false;
         const rec = body;
         return typeof rec.accessToken === 'string' && typeof rec.refreshToken === 'string';
     }
+    /**
+     * Process the response body.
+     * If it contains tokens, handle delivery and return sanitized body.
+     * If not, return original body.
+     */
     async handleResponse(req, res, body) {
+        // Check if this is an auth response
         if (this.isAuthResponseBody(body)) {
             const deliveryMode = this.resolveDeliveryMode(req);
             if (deliveryMode === 'cookies') {
                 this.setTokenCookies(res, body);
+                // Remove tokens and expiration fields from body
+                // Expiration is managed by cookie maxAge, so these fields are not needed
                 const sanitizedBody = { ...body };
                 delete sanitizedBody.accessToken;
                 delete sanitizedBody.refreshToken;
@@ -37,9 +56,11 @@ class TokenDeliveryHandler {
     }
     resolveDeliveryMode(req) {
         const method = this.config.tokenDelivery?.method || 'json';
+        // Route override
         if (req.attributes['nauthTokenDelivery']) {
             return req.attributes['nauthTokenDelivery'];
         }
+        // Hybrid mode
         if (method === 'hybrid') {
             return (0, index_1.resolveDeliveryForRequest)(req.raw, this.config.tokenDelivery?.hybridPolicy);
         }
@@ -71,7 +92,7 @@ class TokenDeliveryHandler {
             return expiry;
         const match = expiry.match(/^(\d+)([smhd])$/);
         if (!match)
-            return 900;
+            return 900; // Default 15m
         const value = parseInt(match[1], 10);
         const unit = match[2];
         switch (unit) {

package/dist/handlers/token-delivery.handler.js.map

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