@nauth-toolkit/core 0.1.14 → 0.1.17

package/dist/enums/risk-factor.enum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"risk-factor.enum.d.ts","sourceRoot":"","sources":["../../src/enums/risk-factor.enum.ts"],"names":[],"mappings":"AAkCA,oBAAY,UAAU;IASpB,UAAU,eAAe;IAOzB,MAAM,WAAW;IAMjB,WAAW,gBAAgB;IAM3B,iBAAiB,sBAAsB;IAMvC,mBAAmB,wBAAwB;IAO3C,wBAAwB,6BAA6B;IAarD,qBAAqB,0BAA0B;IAU/C,mBAAmB,wBAAwB;IAM3C,qCAAqC,0CAA0C;IAM/E,mBAAmB,wBAAwB;IAM3C,qBAAqB,0BAA0B;IAM/C,kBAAkB,uBAAuB;CAC1C"}
+{"version":3,"file":"risk-factor.enum.d.ts","sourceRoot":"","sources":["../../src/enums/risk-factor.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oBAAY,UAAU;IAKpB;;;OAGG;IACH,UAAU,eAAe;IAEzB;;;;OAIG;IACH,MAAM,WAAW;IAEjB;;;OAGG;IACH,WAAW,gBAAgB;IAE3B;;;OAGG;IACH,iBAAiB,sBAAsB;IAEvC;;;OAGG;IACH,mBAAmB,wBAAwB;IAE3C;;;;OAIG;IACH,wBAAwB,6BAA6B;IAErD;;;;;;;;;;OAUG;IACH,qBAAqB,0BAA0B;IAM/C;;;OAGG;IACH,mBAAmB,wBAAwB;IAE3C;;;OAGG;IACH,qCAAqC,0CAA0C;IAE/E;;;OAGG;IACH,mBAAmB,wBAAwB;IAE3C;;;OAGG;IACH,qBAAqB,0BAA0B;IAE/C;;;OAGG;IACH,kBAAkB,uBAAuB;CAC1C"}

package/dist/enums/risk-factor.enum.js

@@ -1,19 +1,116 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RiskFactor = void 0;
+/**
+ * Risk Factor Enum
+ *
+ * Defines all possible risk factors that can be detected during authentication
+ * and security events. Used for type safety in risk scoring and audit logging.
+ *
+ * **Standard Risk Factors (from RiskDetectionService):**
+ * - `new_device`: First login from unknown device
+ * - `new_ip`: Login from new IP address
+ * - `new_country`: Login from different country
+ * - `impossible_travel`: Geographic distance/time anomaly
+ * - `suspicious_activity`: Unusual behavior patterns
+ *
+ * **Security Event Risk Factors:**
+ * - `token_theft_attempt`: Token theft detected
+ * - `refresh_token_reuse_different_session`: Refresh token reused from different session
+ * - `token_reuse_attempt`: Token reuse attempt detected
+ * - `tampered_device_token`: Device token tampering detected
+ * - `mfa_bypass_attempt`: MFA bypass attempt detected
+ *
+ * @example
+ * ```typescript
+ * // Type-safe risk factors
+ * const riskFactors: RiskFactor[] = [
+ *   RiskFactor.NEW_DEVICE,
+ *   RiskFactor.NEW_COUNTRY
+ * ];
+ *
+ * // Pass to audit service
+ * await auditService.recordEvent({
+ *   riskFactors: [RiskFactor.NEW_DEVICE, RiskFactor.TOKEN_REUSE_ATTEMPT],
+ * });
+ * ```
+ */
 var RiskFactor;
 (function (RiskFactor) {
+    // ============================================================================
+    // Standard Risk Factors (from RiskDetectionService)
+    // ============================================================================
+    /**
+     * First login from unknown device
+     * Weight: 25 points (default)
+     */
     RiskFactor["NEW_DEVICE"] = "new_device";
+    /**
+     * Login from new IP address
+     * Weight: 15 points (default)
+     * Note: Automatically excluded if new_country or impossible_travel is detected
+     */
     RiskFactor["NEW_IP"] = "new_ip";
+    /**
+     * Login from different country
+     * Weight: 25 points (default)
+     */
     RiskFactor["NEW_COUNTRY"] = "new_country";
+    /**
+     * Geographic distance/time anomaly (impossible travel)
+     * Weight: 40 points (default)
+     */
     RiskFactor["IMPOSSIBLE_TRAVEL"] = "impossible_travel";
+    /**
+     * Unusual behavior patterns (suspicious activity)
+     * Weight: 30 points (default)
+     */
     RiskFactor["SUSPICIOUS_ACTIVITY"] = "suspicious_activity";
+    /**
+     * Incomplete location data (missing city/coordinates)
+     * Weight: 20 points (default)
+     * Added when location detection is impaired, reducing confidence in risk assessment
+     */
     RiskFactor["INCOMPLETE_LOCATION_DATA"] = "incomplete_location_data";
+    /**
+     * Password was reset/changed after the user's last successful login
+     * Weight: 40 points (default)
+     *
+     * This is a strong signal of account recovery activity. Industry-leading providers
+     * typically treat \"post-reset sign-in\" as higher risk and require step-up auth
+     * when adaptive MFA is enabled.
+     *
+     * Detection strategy (implementation detail):
+     * - If passwordChangedAt > lastLoginAt, user has not logged in since the reset.
+     */
     RiskFactor["RECENT_PASSWORD_RESET"] = "recent_password_reset";
+    // ============================================================================
+    // Security Event Risk Factors
+    // ============================================================================
+    /**
+     * Token theft detected
+     * Used when refresh token reuse is detected from different session
+     */
     RiskFactor["TOKEN_THEFT_ATTEMPT"] = "token_theft_attempt";
+    /**
+     * Refresh token reused from different session
+     * Indicates potential token theft or session hijacking
+     */
     RiskFactor["REFRESH_TOKEN_REUSE_DIFFERENT_SESSION"] = "refresh_token_reuse_different_session";
+    /**
+     * Token reuse attempt detected
+     * Used when token reuse is blocked via atomic operations
+     */
     RiskFactor["TOKEN_REUSE_ATTEMPT"] = "token_reuse_attempt";
+    /**
+     * Device token tampering detected
+     * Used when device token is provided but not found in trusted devices
+     */
     RiskFactor["TAMPERED_DEVICE_TOKEN"] = "tampered_device_token";
+    /**
+     * MFA bypass attempt detected
+     * Used when invalid/tampered device token is provided during MFA verification
+     */
     RiskFactor["MFA_BYPASS_ATTEMPT"] = "mfa_bypass_attempt";
 })(RiskFactor || (exports.RiskFactor = RiskFactor = {}));
 //# sourceMappingURL=risk-factor.enum.js.map

package/dist/enums/risk-factor.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"risk-factor.enum.js","sourceRoot":"","sources":["../../src/enums/risk-factor.enum.ts"],"names":[],"mappings":";;;AAkCA,IAAY,UAyFX;AAzFD,WAAY,UAAU;IASpB,uCAAyB,CAAA;IAOzB,+BAAiB,CAAA;IAMjB,yCAA2B,CAAA;IAM3B,qDAAuC,CAAA;IAMvC,yDAA2C,CAAA;IAO3C,mEAAqD,CAAA;IAarD,6DAA+C,CAAA;IAU/C,yDAA2C,CAAA;IAM3C,6FAA+E,CAAA;IAM/E,yDAA2C,CAAA;IAM3C,6DAA+C,CAAA;IAM/C,uDAAyC,CAAA;AAC3C,CAAC,EAzFW,UAAU,0BAAV,UAAU,QAyFrB"}
+{"version":3,"file":"risk-factor.enum.js","sourceRoot":"","sources":["../../src/enums/risk-factor.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,IAAY,UAyFX;AAzFD,WAAY,UAAU;IACpB,+EAA+E;IAC/E,oDAAoD;IACpD,+EAA+E;IAE/E;;;OAGG;IACH,uCAAyB,CAAA;IAEzB;;;;OAIG;IACH,+BAAiB,CAAA;IAEjB;;;OAGG;IACH,yCAA2B,CAAA;IAE3B;;;OAGG;IACH,qDAAuC,CAAA;IAEvC;;;OAGG;IACH,yDAA2C,CAAA;IAE3C;;;;OAIG;IACH,mEAAqD,CAAA;IAErD;;;;;;;;;;OAUG;IACH,6DAA+C,CAAA;IAE/C,+EAA+E;IAC/E,8BAA8B;IAC9B,+EAA+E;IAE/E;;;OAGG;IACH,yDAA2C,CAAA;IAE3C;;;OAGG;IACH,6FAA+E,CAAA;IAE/E;;;OAGG;IACH,yDAA2C,CAAA;IAE3C;;;OAGG;IACH,6DAA+C,CAAA;IAE/C;;;OAGG;IACH,uDAAyC,CAAA;AAC3C,CAAC,EAzFW,UAAU,0BAAV,UAAU,QAyFrB"}

package/dist/exceptions/nauth.exception.d.ts

@@ -1,12 +1,142 @@
 import { AuthErrorCode } from '../enums/error-codes.enum';
+/**
+ * Custom exception for nauth-toolkit
+ *
+ * **Framework-Agnostic Design:**
+ * This exception extends standard `Error`, not `HttpException`, making it
+ * usable in any context:
+ * - HTTP APIs (REST, NestJS)
+ * - WebSocket connections
+ * - GraphQL resolvers
+ * - gRPC services
+ * - Message queue workers
+ * - CLI tools
+ * - Standalone services
+ *
+ * **Consumer Responsibility:**
+ * The consumer application decides how to map these domain exceptions
+ * to their transport layer (HTTP status codes, WebSocket events, etc.)
+ *
+ * **Structured Error Data:**
+ * Provides error code, message, and optional metadata. Consumer can
+ * transform this into any response format needed.
+ *
+ * @example
+ * ```typescript
+ * // Throw domain exception
+ * throw new NAuthException(
+ *   AuthErrorCode.RATE_LIMIT_SMS,
+ *   'Too many verification SMS sent',
+ *   { retryAfter: 3600, maxAttempts: 3 }
+ * );
+ *
+ * // Consumer maps to HTTP (if using HTTP)
+ * catch (error) {
+ *   if (error instanceof NAuthException) {
+ *     const statusCode = this.mapErrorCodeToHttpStatus(error.code);
+ *     return res.status(statusCode).json({
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details,
+ *       timestamp: new Date().toISOString()
+ *     });
+ *   }
+ * }
+ *
+ * // Or map to WebSocket
+ * catch (error) {
+ *   if (error instanceof NAuthException) {
+ *     socket.emit('error', {
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class NAuthException extends Error {
+    /**
+     * Error code for programmatic handling
+     */
     readonly code: AuthErrorCode;
+    /**
+     * Additional error details/metadata
+     */
     readonly details?: Record<string, unknown>;
+    /**
+     * Timestamp when error was created
+     */
     readonly timestamp: string;
+    /**
+     * Create a new NAuthException
+     *
+     * @param code - Error code from AuthErrorCode enum
+     * @param message - Human-readable error message
+     * @param details - Optional metadata (retryAfter, validation errors, etc.)
+     *
+     * @example
+     * ```typescript
+     * throw new NAuthException(
+     *   AuthErrorCode.INVALID_CREDENTIALS,
+     *   'Invalid email or password'
+     * );
+     *
+     * throw new NAuthException(
+     *   AuthErrorCode.RATE_LIMIT_SMS,
+     *   'Too many SMS sent',
+     *   { retryAfter: 3600, currentCount: 4 }
+     * );
+     * ```
+     */
     constructor(code: AuthErrorCode, message: string, details?: Record<string, unknown>);
+    /**
+     * Get the error code
+     *
+     * @returns Error code
+     */
     getCode(): AuthErrorCode;
+    /**
+     * Get error details/metadata
+     *
+     * @returns Error details or undefined
+     */
     getDetails(): Record<string, unknown> | undefined;
+    /**
+     * Check if error is a specific code
+     *
+     * @param code - Error code to check
+     * @returns True if error matches code
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await sendSMS();
+     * } catch (error) {
+     *   if (error instanceof NAuthException && error.isCode(AuthErrorCode.RATE_LIMIT_SMS)) {
+     *     // Handle rate limit specifically
+     *   }
+     * }
+     * ```
+     */
     isCode(code: AuthErrorCode): boolean;
+    /**
+     * Serialize error to plain object
+     *
+     * Useful for logging, HTTP responses, or any serialization needs.
+     *
+     * @returns Plain object representation
+     *
+     * @example
+     * ```typescript
+     * catch (error) {
+     *   if (error instanceof NAuthException) {
+     *     console.log(error.toJSON());
+     *     // { code: 'RATE_LIMIT_SMS', message: '...', details: {...}, timestamp: '...' }
+     *   }
+     * }
+     * ```
+     */
     toJSON(): {
         code: string;
         message: string;
@@ -14,5 +144,24 @@ export declare class NAuthException extends Error {
         timestamp: string;
     };
 }
+/**
+ * Helper function to map error codes to suggested HTTP status codes
+ *
+ * **Optional** - Consumer can use this or define their own mapping.
+ * Provided as a convenience for HTTP-based applications.
+ *
+ * @param code - Error code
+ * @returns Suggested HTTP status code
+ *
+ * @example
+ * ```typescript
+ * // In NestJS exception filter
+ * catch (exception: NAuthException, host: ArgumentsHost) {
+ *   const statusCode = getHttpStatusForErrorCode(exception.code);
+ *   const response = host.switchToHttp().getResponse();
+ *   response.status(statusCode).json(exception.toJSON());
+ * }
+ * ```
+ */
 export declare function getHttpStatusForErrorCode(code: AuthErrorCode): number;
 //# sourceMappingURL=nauth.exception.d.ts.map

package/dist/exceptions/nauth.exception.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nauth.exception.d.ts","sourceRoot":"","sources":["../../src/exceptions/nauth.exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA0D1D,qBAAa,cAAe,SAAQ,KAAK;IAIvC,SAAgB,IAAI,EAAE,aAAa,CAAC;IAKpC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAKlD,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAuBtB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAsBnF,OAAO,IAAI,aAAa;IASxB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAqBjD,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAqBpC,MAAM,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAQlG;AAqBD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiCrE"}
+{"version":3,"file":"nauth.exception.d.ts","sourceRoot":"","sources":["../../src/exceptions/nauth.exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC;;OAEG;IACH,SAAgB,IAAI,EAAE,aAAa,CAAC;IAEpC;;OAEG;IACH,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElD;;OAEG;IACH,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;OAoBG;gBACS,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAiBnF;;;;OAIG;IACH,OAAO,IAAI,aAAa;IAIxB;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAIjD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAIpC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAQlG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiCrE"}

package/dist/exceptions/nauth.exception.js

@@ -3,30 +3,162 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NAuthException = void 0;
 exports.getHttpStatusForErrorCode = getHttpStatusForErrorCode;
 const error_codes_enum_1 = require("../enums/error-codes.enum");
+/**
+ * Custom exception for nauth-toolkit
+ *
+ * **Framework-Agnostic Design:**
+ * This exception extends standard `Error`, not `HttpException`, making it
+ * usable in any context:
+ * - HTTP APIs (REST, NestJS)
+ * - WebSocket connections
+ * - GraphQL resolvers
+ * - gRPC services
+ * - Message queue workers
+ * - CLI tools
+ * - Standalone services
+ *
+ * **Consumer Responsibility:**
+ * The consumer application decides how to map these domain exceptions
+ * to their transport layer (HTTP status codes, WebSocket events, etc.)
+ *
+ * **Structured Error Data:**
+ * Provides error code, message, and optional metadata. Consumer can
+ * transform this into any response format needed.
+ *
+ * @example
+ * ```typescript
+ * // Throw domain exception
+ * throw new NAuthException(
+ *   AuthErrorCode.RATE_LIMIT_SMS,
+ *   'Too many verification SMS sent',
+ *   { retryAfter: 3600, maxAttempts: 3 }
+ * );
+ *
+ * // Consumer maps to HTTP (if using HTTP)
+ * catch (error) {
+ *   if (error instanceof NAuthException) {
+ *     const statusCode = this.mapErrorCodeToHttpStatus(error.code);
+ *     return res.status(statusCode).json({
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details,
+ *       timestamp: new Date().toISOString()
+ *     });
+ *   }
+ * }
+ *
+ * // Or map to WebSocket
+ * catch (error) {
+ *   if (error instanceof NAuthException) {
+ *     socket.emit('error', {
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class NAuthException extends Error {
+    /**
+     * Error code for programmatic handling
+     */
     code;
+    /**
+     * Additional error details/metadata
+     */
     details;
+    /**
+     * Timestamp when error was created
+     */
     timestamp;
+    /**
+     * Create a new NAuthException
+     *
+     * @param code - Error code from AuthErrorCode enum
+     * @param message - Human-readable error message
+     * @param details - Optional metadata (retryAfter, validation errors, etc.)
+     *
+     * @example
+     * ```typescript
+     * throw new NAuthException(
+     *   AuthErrorCode.INVALID_CREDENTIALS,
+     *   'Invalid email or password'
+     * );
+     *
+     * throw new NAuthException(
+     *   AuthErrorCode.RATE_LIMIT_SMS,
+     *   'Too many SMS sent',
+     *   { retryAfter: 3600, currentCount: 4 }
+     * );
+     * ```
+     */
     constructor(code, message, details) {
         super(message);
         this.code = code;
         this.details = details;
         this.timestamp = new Date().toISOString();
         this.name = 'NAuthException';
+        // Ensure proper prototype chain for instanceof checks
         Object.setPrototypeOf(this, NAuthException.prototype);
+        // Capture stack trace (excluding constructor call)
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, this.constructor);
         }
     }
+    /**
+     * Get the error code
+     *
+     * @returns Error code
+     */
     getCode() {
         return this.code;
     }
+    /**
+     * Get error details/metadata
+     *
+     * @returns Error details or undefined
+     */
     getDetails() {
         return this.details;
     }
+    /**
+     * Check if error is a specific code
+     *
+     * @param code - Error code to check
+     * @returns True if error matches code
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await sendSMS();
+     * } catch (error) {
+     *   if (error instanceof NAuthException && error.isCode(AuthErrorCode.RATE_LIMIT_SMS)) {
+     *     // Handle rate limit specifically
+     *   }
+     * }
+     * ```
+     */
     isCode(code) {
         return this.code === code;
     }
+    /**
+     * Serialize error to plain object
+     *
+     * Useful for logging, HTTP responses, or any serialization needs.
+     *
+     * @returns Plain object representation
+     *
+     * @example
+     * ```typescript
+     * catch (error) {
+     *   if (error instanceof NAuthException) {
+     *     console.log(error.toJSON());
+     *     // { code: 'RATE_LIMIT_SMS', message: '...', details: {...}, timestamp: '...' }
+     *   }
+     * }
+     * ```
+     */
     toJSON() {
         return {
             code: this.code,
@@ -37,28 +169,55 @@ class NAuthException extends Error {
     }
 }
 exports.NAuthException = NAuthException;
+/**
+ * Helper function to map error codes to suggested HTTP status codes
+ *
+ * **Optional** - Consumer can use this or define their own mapping.
+ * Provided as a convenience for HTTP-based applications.
+ *
+ * @param code - Error code
+ * @returns Suggested HTTP status code
+ *
+ * @example
+ * ```typescript
+ * // In NestJS exception filter
+ * catch (exception: NAuthException, host: ArgumentsHost) {
+ *   const statusCode = getHttpStatusForErrorCode(exception.code);
+ *   const response = host.switchToHttp().getResponse();
+ *   response.status(statusCode).json(exception.toJSON());
+ * }
+ * ```
+ */
 function getHttpStatusForErrorCode(code) {
+    // Rate limits
     if (code.startsWith('RATE_LIMIT_'))
         return 429;
+    // Authentication errors
     if (code.startsWith('AUTH_')) {
         if (code === error_codes_enum_1.AuthErrorCode.ACCOUNT_INACTIVE || code === error_codes_enum_1.AuthErrorCode.ACCOUNT_LOCKED)
             return 403;
         return 401;
     }
+    // Signup conflicts
     if (code === error_codes_enum_1.AuthErrorCode.EMAIL_EXISTS ||
         code === error_codes_enum_1.AuthErrorCode.USERNAME_EXISTS ||
         code === error_codes_enum_1.AuthErrorCode.PHONE_EXISTS)
         return 409;
     if (code === error_codes_enum_1.AuthErrorCode.SIGNUP_DISABLED)
         return 403;
+    // Validation errors
     if (code.startsWith('VALIDATION_') || code.startsWith('INVALID_'))
         return 400;
+    // Not found
     if (code === error_codes_enum_1.AuthErrorCode.NOT_FOUND)
         return 404;
+    // Forbidden
     if (code === error_codes_enum_1.AuthErrorCode.FORBIDDEN)
         return 403;
+    // Server errors
     if (code === error_codes_enum_1.AuthErrorCode.INTERNAL_ERROR || code === error_codes_enum_1.AuthErrorCode.SERVICE_UNAVAILABLE)
         return 500;
+    // Default to 400
     return 400;
 }
 //# sourceMappingURL=nauth.exception.js.map

package/dist/exceptions/nauth.exception.js.map

@@ -1 +1 @@
-{"version":3,"file":"nauth.exception.js","sourceRoot":"","sources":["../../src/exceptions/nauth.exception.ts"],"names":[],"mappings":";;;AAqMA,8DAiCC;AAtOD,gEAA0D;AA0D1D,MAAa,cAAe,SAAQ,KAAK;IAIvB,IAAI,CAAgB;IAKpB,OAAO,CAA2B;IAKlC,SAAS,CAAS;IAuBlC,YAAY,IAAmB,EAAE,OAAe,EAAE,OAAiC;QACjF,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAG7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;QAGtD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAOD,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAOD,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAmBD,MAAM,CAAC,IAAmB;QACxB,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;IAC5B,CAAC;IAmBD,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;CACF;AAtHD,wCAsHC;AAqBD,SAAgB,yBAAyB,CAAC,IAAmB;IAE3D,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,GAAG,CAAC;IAG/C,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,IAAI,IAAI,KAAK,gCAAa,CAAC,gBAAgB,IAAI,IAAI,KAAK,gCAAa,CAAC,cAAc;YAAE,OAAO,GAAG,CAAC;QACjG,OAAO,GAAG,CAAC;IACb,CAAC;IAGD,IACE,IAAI,KAAK,gCAAa,CAAC,YAAY;QACnC,IAAI,KAAK,gCAAa,CAAC,eAAe;QACtC,IAAI,KAAK,gCAAa,CAAC,YAAY;QAEnC,OAAO,GAAG,CAAC;IACb,IAAI,IAAI,KAAK,gCAAa,CAAC,eAAe;QAAE,OAAO,GAAG,CAAC;IAGvD,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,GAAG,CAAC;IAG9E,IAAI,IAAI,KAAK,gCAAa,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAGjD,IAAI,IAAI,KAAK,gCAAa,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAGjD,IAAI,IAAI,KAAK,gCAAa,CAAC,cAAc,IAAI,IAAI,KAAK,gCAAa,CAAC,mBAAmB;QAAE,OAAO,GAAG,CAAC;IAGpG,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"nauth.exception.js","sourceRoot":"","sources":["../../src/exceptions/nauth.exception.ts"],"names":[],"mappings":";;;AAqMA,8DAiCC;AAtOD,gEAA0D;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAa,cAAe,SAAQ,KAAK;IACvC;;OAEG;IACa,IAAI,CAAgB;IAEpC;;OAEG;IACa,OAAO,CAA2B;IAElD;;OAEG;IACa,SAAS,CAAS;IAElC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,IAAmB,EAAE,OAAe,EAAE,OAAiC;QACjF,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAE7B,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;QAEtD,mDAAmD;QACnD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAmB;QACxB,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;CACF;AAtHD,wCAsHC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,yBAAyB,CAAC,IAAmB;IAC3D,cAAc;IACd,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,GAAG,CAAC;IAE/C,wBAAwB;IACxB,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,IAAI,IAAI,KAAK,gCAAa,CAAC,gBAAgB,IAAI,IAAI,KAAK,gCAAa,CAAC,cAAc;YAAE,OAAO,GAAG,CAAC;QACjG,OAAO,GAAG,CAAC;IACb,CAAC;IAED,mBAAmB;IACnB,IACE,IAAI,KAAK,gCAAa,CAAC,YAAY;QACnC,IAAI,KAAK,gCAAa,CAAC,eAAe;QACtC,IAAI,KAAK,gCAAa,CAAC,YAAY;QAEnC,OAAO,GAAG,CAAC;IACb,IAAI,IAAI,KAAK,gCAAa,CAAC,eAAe;QAAE,OAAO,GAAG,CAAC;IAEvD,oBAAoB;IACpB,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,GAAG,CAAC;IAE9E,YAAY;IACZ,IAAI,IAAI,KAAK,gCAAa,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAEjD,YAAY;IACZ,IAAI,IAAI,KAAK,gCAAa,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAEjD,gBAAgB;IAChB,IAAI,IAAI,KAAK,gCAAa,CAAC,cAAc,IAAI,IAAI,KAAK,gCAAa,CAAC,mBAAmB;QAAE,OAAO,GAAG,CAAC;IAEpG,iBAAiB;IACjB,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -1,7 +1,22 @@
+/**
+ * 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.
+ */
 import { Repository } from 'typeorm';
 import { NAuthConfig, BaseUser, NAuthLogger } from '../index';
 import { JwtService, SessionService } from '../internal';
 import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
+/**
+ * AuthHandler
+ *
+ * Validates JWT tokens and populates user context.
+ * Performs optional authentication by default (doesn't reject unauthenticated requests).
+ */
 export declare class AuthHandler {
     private jwtService;
     private sessionService;
@@ -9,10 +24,27 @@ export declare class AuthHandler {
     private config;
     private logger?;
     constructor(jwtService: JwtService, sessionService: SessionService, userRepository: Repository<BaseUser>, config: NAuthConfig, logger?: NAuthLogger | undefined);
+    /**
+     * Handle request - validate token and attach user
+     *
+     * Note: Context is managed by adapter. This handler assumes context is available.
+     */
     handle(req: NAuthRequest, _res: NAuthResponse, next: () => Promise<void> | void): Promise<void>;
+    /**
+     * Extract token from request based on delivery mode
+     */
     private extractToken;
+    /**
+     * Update CLIENT_INFO with session ID from token
+     */
     private updateClientInfoSessionId;
+    /**
+     * Update CLIENT_INFO with user ID from token
+     */
     private updateClientInfoUserId;
+    /**
+     * Get fields to select when loading user
+     */
     private getUserSelectFields;
 }
 //# sourceMappingURL=auth.handler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/auth.handler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,WAAW,EAIX,QAAQ,EAER,WAAW,EAGZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAQrE,qBAAa,WAAW;IAEpB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM,CAAC;gBAJP,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,YAAA;IAQjB,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAwG5G,OAAO,CAAC,YAAY;IA8CpB,OAAO,CAAC,yBAAyB;IAejC,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,mBAAmB;CAkC5B"}
+{"version":3,"file":"auth.handler.d.ts","sourceRoot":"","sources":["../../src/handlers/auth.handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,WAAW,EAIX,QAAQ,EAER,WAAW,EAGZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAErE;;;;;GAKG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM,CAAC;gBAJP,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,YAAA;IAG9B;;;;OAIG;IACU,MAAM,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAqG5G;;OAEG;IACH,OAAO,CAAC,YAAY;IA2CpB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAYjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAkC5B"}