@nauth-toolkit/core 0.1.13 → 0.1.17

package/dist/enums/error-codes.enum.js

@@ -1,61 +1,393 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthErrorCode = void 0;
+/**
+ * Authentication Error Codes
+ *
+ * Standardized error codes for all nauth-toolkit errors.
+ * Organized by category for easy navigation and maintenance.
+ *
+ * **Benefits:**
+ * - Programmatic error handling (no string parsing)
+ * - Internationalization support
+ * - Better analytics and monitoring
+ * - Type-safe error checking
+ *
+ * @example
+ * ```typescript
+ * // Backend
+ * throw new NAuthException(
+ *   AuthErrorCode.RATE_LIMIT_SMS,
+ *   'Too many SMS sent',
+ *   HttpStatus.TOO_MANY_REQUESTS,
+ *   { retryAfter: 3600 }
+ * );
+ *
+ * // Frontend
+ * if (error.code === AuthErrorCode.RATE_LIMIT_SMS) {
+ *   showRetryTimer(error.details.retryAfter);
+ * }
+ * ```
+ */
 var AuthErrorCode;
 (function (AuthErrorCode) {
+    // ============================================================================
+    // Authentication Errors (AUTH_*)
+    // ============================================================================
+    /**
+     * Invalid username/email or password
+     *
+     * Used when credentials don't match any user or password is incorrect.
+     */
     AuthErrorCode["INVALID_CREDENTIALS"] = "AUTH_INVALID_CREDENTIALS";
+    /**
+     * Account has been locked due to too many failed attempts
+     *
+     * Temporary lockout for security. Includes lockout duration in details.
+     */
     AuthErrorCode["ACCOUNT_LOCKED"] = "AUTH_ACCOUNT_LOCKED";
+    /**
+     * Account is inactive or disabled
+     *
+     * Account exists but has been deactivated by admin or user.
+     */
     AuthErrorCode["ACCOUNT_INACTIVE"] = "AUTH_ACCOUNT_INACTIVE";
+    /**
+     * Access token has expired
+     *
+     * Client should attempt token refresh.
+     */
     AuthErrorCode["TOKEN_EXPIRED"] = "AUTH_TOKEN_EXPIRED";
+    /**
+     * Token is invalid or malformed
+     *
+     * Token signature verification failed or token format is invalid.
+     */
     AuthErrorCode["TOKEN_INVALID"] = "AUTH_TOKEN_INVALID";
+    /**
+     * Bearer tokens are not allowed in the current delivery mode
+     *
+     * Used when tokenDelivery.method is 'cookies' and an Authorization header
+     * (Bearer token) is provided, which would bypass httpOnly protections.
+     */
     AuthErrorCode["BEARER_NOT_ALLOWED"] = "AUTH_BEARER_NOT_ALLOWED";
+    /**
+     * Cookie-based tokens are not allowed in the current delivery mode
+     *
+     * Used when tokenDelivery.method is 'json' and cookie tokens are present.
+     */
     AuthErrorCode["COOKIES_NOT_ALLOWED"] = "AUTH_COOKIES_NOT_ALLOWED";
+    /**
+     * CSRF token is invalid or missing
+     *
+     * Used when CSRF protection is enabled and token validation fails.
+     */
     AuthErrorCode["CSRF_TOKEN_INVALID"] = "AUTH_CSRF_TOKEN_INVALID";
+    /**
+     * CSRF token is missing from request
+     *
+     * Used when CSRF protection is enabled but no token is provided.
+     */
     AuthErrorCode["CSRF_TOKEN_MISSING"] = "AUTH_CSRF_TOKEN_MISSING";
+    /**
+     * Refresh token reuse detected - security violation
+     *
+     * All sessions have been revoked. User must login again.
+     */
     AuthErrorCode["TOKEN_REUSE_DETECTED"] = "AUTH_TOKEN_REUSE_DETECTED";
+    /**
+     * Session not found or has been revoked
+     */
     AuthErrorCode["SESSION_NOT_FOUND"] = "AUTH_SESSION_NOT_FOUND";
+    /**
+     * Session has expired
+     */
     AuthErrorCode["SESSION_EXPIRED"] = "AUTH_SESSION_EXPIRED";
+    // ============================================================================
+    // Signup Errors (SIGNUP_*)
+    // ============================================================================
+    /**
+     * User signup is currently disabled
+     *
+     * Signups are administratively disabled.
+     */
     AuthErrorCode["SIGNUP_DISABLED"] = "SIGNUP_DISABLED";
+    /**
+     * Email address is already registered
+     *
+     * Another user account exists with this email.
+     */
     AuthErrorCode["EMAIL_EXISTS"] = "SIGNUP_EMAIL_EXISTS";
+    /**
+     * Username is already taken
+     *
+     * Another user has registered this username.
+     */
     AuthErrorCode["USERNAME_EXISTS"] = "SIGNUP_USERNAME_EXISTS";
+    /**
+     * Phone number is already registered
+     *
+     * Another user account exists with this phone number.
+     */
     AuthErrorCode["PHONE_EXISTS"] = "SIGNUP_PHONE_EXISTS";
+    /**
+     * Password doesn't meet security requirements
+     *
+     * Details include which requirements failed (length, complexity, etc.)
+     */
     AuthErrorCode["WEAK_PASSWORD"] = "SIGNUP_WEAK_PASSWORD";
+    /**
+     * Phone number is required for signup
+     *
+     * Configuration requires phone verification.
+     */
     AuthErrorCode["PHONE_REQUIRED"] = "SIGNUP_PHONE_REQUIRED";
+    /**
+     * Signup not allowed by hook or policy
+     */
     AuthErrorCode["SIGNUP_NOT_ALLOWED"] = "SIGNUP_NOT_ALLOWED";
+    // ============================================================================
+    // Verification Errors (VERIFY_*)
+    // ============================================================================
+    /**
+     * Verification code is invalid
+     *
+     * Code doesn't match or has incorrect format.
+     */
     AuthErrorCode["VERIFICATION_CODE_INVALID"] = "VERIFY_CODE_INVALID";
+    /**
+     * Verification code has expired
+     *
+     * User needs to request a new code.
+     */
     AuthErrorCode["VERIFICATION_CODE_EXPIRED"] = "VERIFY_CODE_EXPIRED";
+    /**
+     * Too many failed verification attempts
+     *
+     * User exceeded max attempts. Must request new code.
+     */
     AuthErrorCode["VERIFICATION_TOO_MANY_ATTEMPTS"] = "VERIFY_TOO_MANY_ATTEMPTS";
+    /**
+     * Email or phone is already verified
+     *
+     * No action needed.
+     */
     AuthErrorCode["ALREADY_VERIFIED"] = "VERIFY_ALREADY_VERIFIED";
+    // ============================================================================
+    // MFA Errors (MFA_*)
+    // ============================================================================
+    /**
+     * MFA setup is required before login
+     *
+     * User must set up multi-factor authentication before being allowed to login.
+     * This occurs when enforcement is 'REQUIRED' and grace period has expired (or is disabled).
+     * Details include allowedMethods array.
+     */
     AuthErrorCode["MFA_SETUP_REQUIRED"] = "MFA_SETUP_REQUIRED";
+    // ============================================================================
+    // Rate Limit Errors (RATE_LIMIT_*)
+    // ============================================================================
+    /**
+     * Too many SMS verification requests
+     *
+     * Details include retryAfter (seconds) and resetAt (timestamp).
+     */
     AuthErrorCode["RATE_LIMIT_SMS"] = "RATE_LIMIT_SMS";
+    /**
+     * Too many email verification requests
+     *
+     * Details include retryAfter (seconds) and resetAt (timestamp).
+     */
     AuthErrorCode["RATE_LIMIT_EMAIL"] = "RATE_LIMIT_EMAIL";
+    /**
+     * Too many login attempts
+     *
+     * Account may be locked. Details include retryAfter.
+     */
     AuthErrorCode["RATE_LIMIT_LOGIN"] = "RATE_LIMIT_LOGIN";
+    /**
+     * Too many resend code requests
+     *
+     * User must wait before requesting another code.
+     */
     AuthErrorCode["RATE_LIMIT_RESEND"] = "RATE_LIMIT_RESEND";
+    /**
+     * Too many password reset requests
+     *
+     * Used for forgot-password flows to prevent abuse.
+     * Details should include retryAfter (seconds).
+     */
     AuthErrorCode["RATE_LIMIT_PASSWORD_RESET"] = "RATE_LIMIT_PASSWORD_RESET";
+    // ============================================================================
+    // Social Auth Errors (SOCIAL_*)
+    // ============================================================================
+    /**
+     * Social provider token is invalid or expired
+     *
+     * Token verification failed with provider.
+     */
     AuthErrorCode["SOCIAL_TOKEN_INVALID"] = "SOCIAL_TOKEN_INVALID";
+    /**
+     * Social account is already linked to another user
+     *
+     * This social account cannot be linked because it's in use.
+     */
     AuthErrorCode["SOCIAL_ACCOUNT_LINKED"] = "SOCIAL_ACCOUNT_LINKED";
+    /**
+     * Social provider is not configured
+     *
+     * Provider credentials or settings are missing.
+     */
     AuthErrorCode["SOCIAL_CONFIG_MISSING"] = "SOCIAL_CONFIG_MISSING";
+    /**
+     * Email is required from social provider
+     *
+     * Social provider didn't return email or email is not verified.
+     */
     AuthErrorCode["SOCIAL_EMAIL_REQUIRED"] = "SOCIAL_EMAIL_REQUIRED";
+    /**
+     * Social account not found for this user
+     *
+     * User doesn't have this social provider linked.
+     */
     AuthErrorCode["SOCIAL_ACCOUNT_NOT_FOUND"] = "SOCIAL_ACCOUNT_NOT_FOUND";
+    // ============================================================================
+    // Challenge Errors (CHALLENGE_*)
+    // ============================================================================
+    /**
+     * Challenge session has expired
+     *
+     * User must restart authentication flow.
+     */
     AuthErrorCode["CHALLENGE_EXPIRED"] = "CHALLENGE_EXPIRED";
+    /**
+     * Challenge session is invalid
+     *
+     * Session token is malformed or not found.
+     */
     AuthErrorCode["CHALLENGE_INVALID"] = "CHALLENGE_INVALID";
+    /**
+     * Challenge type mismatch
+     *
+     * Client sent wrong challenge type for this session.
+     */
     AuthErrorCode["CHALLENGE_TYPE_MISMATCH"] = "CHALLENGE_TYPE_MISMATCH";
+    /**
+     * Max challenge attempts exceeded
+     *
+     * User must request new challenge session.
+     */
     AuthErrorCode["CHALLENGE_MAX_ATTEMPTS"] = "CHALLENGE_MAX_ATTEMPTS";
+    /**
+     * Challenge has already been completed
+     */
     AuthErrorCode["CHALLENGE_ALREADY_COMPLETED"] = "CHALLENGE_ALREADY_COMPLETED";
+    // ============================================================================
+    // Validation Errors (VALIDATION_*)
+    // ============================================================================
+    /**
+     * Request validation failed
+     *
+     * Details include field-specific validation errors.
+     */
     AuthErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    /**
+     * Phone number format is invalid
+     *
+     * Must be in E.164 format (e.g., +1234567890).
+     */
     AuthErrorCode["INVALID_PHONE_FORMAT"] = "VALIDATION_INVALID_PHONE";
+    /**
+     * Email format is invalid
+     */
     AuthErrorCode["INVALID_EMAIL_FORMAT"] = "VALIDATION_INVALID_EMAIL";
+    /**
+     * Password format is invalid
+     *
+     * Details include specific requirements that failed.
+     */
     AuthErrorCode["INVALID_PASSWORD_FORMAT"] = "VALIDATION_INVALID_PASSWORD";
+    // ============================================================================
+    // Password Errors (PASSWORD_*)
+    // ============================================================================
+    /**
+     * Current password is incorrect
+     *
+     * Used when changing password.
+     */
     AuthErrorCode["PASSWORD_INCORRECT"] = "PASSWORD_INCORRECT";
+    /**
+     * Cannot reuse recent passwords
+     *
+     * New password matches one of the recent passwords.
+     */
     AuthErrorCode["PASSWORD_REUSED"] = "PASSWORD_REUSED";
+    /**
+     * Password change is not allowed
+     *
+     * Social-only users cannot change password.
+     */
     AuthErrorCode["PASSWORD_CHANGE_NOT_ALLOWED"] = "PASSWORD_CHANGE_NOT_ALLOWED";
+    // ============================================================================
+    // Password Reset Errors (PASSWORD_RESET_*)
+    // ============================================================================
+    /**
+     * Password reset verification code is invalid
+     *
+     * Used when confirming a forgot-password code.
+     */
     AuthErrorCode["PASSWORD_RESET_CODE_INVALID"] = "PASSWORD_RESET_CODE_INVALID";
+    /**
+     * Password reset verification code has expired
+     *
+     * Used when confirming a forgot-password code after TTL.
+     */
     AuthErrorCode["PASSWORD_RESET_CODE_EXPIRED"] = "PASSWORD_RESET_CODE_EXPIRED";
+    /**
+     * Too many failed password reset code attempts
+     *
+     * Used when confirming a forgot-password code exceeds max attempts.
+     */
     AuthErrorCode["PASSWORD_RESET_MAX_ATTEMPTS"] = "PASSWORD_RESET_MAX_ATTEMPTS";
+    // ============================================================================
+    // General Errors (*)
+    // ============================================================================
+    /**
+     * Requested resource not found
+     */
     AuthErrorCode["NOT_FOUND"] = "RESOURCE_NOT_FOUND";
+    /**
+     * Internal server error
+     *
+     * Unexpected error occurred. Details may include correlation ID.
+     */
     AuthErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    /**
+     * Access forbidden
+     *
+     * User doesn't have permission for this action.
+     */
     AuthErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    /**
+     * Service temporarily unavailable
+     *
+     * May include retryAfter in details.
+     */
     AuthErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    // ============================================================================
+    // Adaptive MFA Errors (ADAPTIVE_*)
+    // ============================================================================
+    /**
+     * Sign-in blocked due to high risk score
+     *
+     * Adaptive MFA evaluated the login attempt and determined it exceeds
+     * the high-risk threshold. Sign-in is blocked for security.
+     *
+     * Details may include:
+     * - riskScore: The calculated risk score (0-100)
+     * - riskFactors: Array of detected risk factors
+     * - expiresAt: When the block expires (if temporary)
+     */
     AuthErrorCode["SIGNIN_BLOCKED_HIGH_RISK"] = "SIGNIN_BLOCKED_HIGH_RISK";
 })(AuthErrorCode || (exports.AuthErrorCode = AuthErrorCode = {}));
 //# sourceMappingURL=error-codes.enum.js.map

package/dist/enums/error-codes.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-codes.enum.js","sourceRoot":"","sources":["../../src/enums/error-codes.enum.ts"],"names":[],"mappings":";;;AA4BA,IAAY,aAwaX;AAxaD,WAAY,aAAa;IAUvB,iEAAgD,CAAA;IAOhD,uDAAsC,CAAA;IAOtC,2DAA0C,CAAA;IAO1C,qDAAoC,CAAA;IAOpC,qDAAoC,CAAA;IAQpC,+DAA8C,CAAA;IAO9C,iEAAgD,CAAA;IAOhD,+DAA8C,CAAA;IAO9C,+DAA8C,CAAA;IAO9C,mEAAkD,CAAA;IAKlD,6DAA4C,CAAA;IAK5C,yDAAwC,CAAA;IAWxC,oDAAmC,CAAA;IAOnC,qDAAoC,CAAA;IAOpC,2DAA0C,CAAA;IAO1C,qDAAoC,CAAA;IAOpC,uDAAsC,CAAA;IAOtC,yDAAwC,CAAA;IAKxC,0DAAyC,CAAA;IAWzC,kEAAiD,CAAA;IAOjD,kEAAiD,CAAA;IAOjD,4EAA2D,CAAA;IAO3D,6DAA4C,CAAA;IAa5C,0DAAyC,CAAA;IAWzC,kDAAiC,CAAA;IAOjC,sDAAqC,CAAA;IAOrC,sDAAqC,CAAA;IAOrC,wDAAuC,CAAA;IAQvC,wEAAuD,CAAA;IAWvD,8DAA6C,CAAA;IAO7C,gEAA+C,CAAA;IAO/C,gEAA+C,CAAA;IAO/C,gEAA+C,CAAA;IAO/C,sEAAqD,CAAA;IAWrD,wDAAuC,CAAA;IAOvC,wDAAuC,CAAA;IAOvC,oEAAmD,CAAA;IAOnD,kEAAiD,CAAA;IAKjD,4EAA2D,CAAA;IAW3D,wDAAuC,CAAA;IAOvC,kEAAiD,CAAA;IAKjD,kEAAiD,CAAA;IAOjD,wEAAuD,CAAA;IAWvD,0DAAyC,CAAA;IAOzC,oDAAmC,CAAA;IAOnC,4EAA2D,CAAA;IAW3D,4EAA2D,CAAA;IAO3D,4EAA2D,CAAA;IAO3D,4EAA2D,CAAA;IAS3D,iDAAgC,CAAA;IAOhC,kDAAiC,CAAA;IAOjC,wCAAuB,CAAA;IAOvB,4DAA2C,CAAA;IAiB3C,sEAAqD,CAAA;AACvD,CAAC,EAxaW,aAAa,6BAAb,aAAa,QAwaxB"}
+{"version":3,"file":"error-codes.enum.js","sourceRoot":"","sources":["../../src/enums/error-codes.enum.ts"],"names":[],"mappings":"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"}

package/dist/enums/mfa-method.enum.d.ts

@@ -1,11 +1,85 @@
+/**
+ * MFA Method Enum
+ *
+ * Defines all supported Multi-Factor Authentication methods.
+ * Used throughout the codebase to ensure type safety and consistency.
+ *
+ * **Device Methods** (require device setup):
+ * - TOTP: Time-based One-Time Password (authenticator apps)
+ * - SMS: SMS verification codes
+ * - EMAIL: Email verification codes
+ * - PASSKEY: WebAuthn/FIDO2 passkeys (biometric, security keys)
+ *
+ * **Verification Methods** (available for verification):
+ * - Includes all device methods
+ * - BACKUP: Backup recovery codes (single-use codes, not a device)
+ *
+ * @example
+ * ```typescript
+ * import { MFAMethod, MFADeviceMethod, MFAVerificationMethod } from '@nauth-toolkit/core';
+ *
+ * // Device methods only
+ * const deviceMethod: MFADeviceMethod = MFAMethod.TOTP;
+ *
+ * // Verification methods (includes backup)
+ * const verificationMethod: MFAVerificationMethod = MFAMethod.BACKUP;
+ *
+ * // Check if method is a device method
+ * if (method !== MFAMethod.BACKUP) {
+ *   // This is a device method
+ * }
+ * ```
+ */
+/**
+ * All supported MFA methods
+ *
+ * Use this enum instead of string literals throughout the codebase.
+ */
 export declare enum MFAMethod {
+    /**
+     * Time-based One-Time Password
+     * Authenticator apps (Google Authenticator, Authy, Microsoft Authenticator, etc.)
+     */
     TOTP = "totp",
+    /**
+     * SMS verification codes
+     * Sends one-time codes via text message
+     */
     SMS = "sms",
+    /**
+     * Email verification codes
+     * Sends one-time codes via email
+     */
     EMAIL = "email",
+    /**
+     * WebAuthn/FIDO2 passkeys
+     * Biometric authentication (Face ID, Touch ID, Windows Hello)
+     * Hardware security keys (YubiKey, etc.)
+     */
     PASSKEY = "passkey",
+    /**
+     * Backup recovery codes
+     * Single-use recovery codes when MFA devices are unavailable
+     * Not a device method - only available for verification
+     */
     BACKUP = "backup"
 }
+/**
+ * Device MFA methods (methods that require device setup)
+ *
+ * Excludes BACKUP as it's not a device method.
+ */
 export type MFADeviceMethod = MFAMethod.TOTP | MFAMethod.SMS | MFAMethod.EMAIL | MFAMethod.PASSKEY;
+/**
+ * Verification MFA methods (all methods available for verification)
+ *
+ * Includes all device methods plus BACKUP codes.
+ */
 export type MFAVerificationMethod = MFADeviceMethod | MFAMethod.BACKUP;
+/**
+ * Array of all device methods
+ *
+ * Useful for defaults and iteration.
+ */
 export declare const MFADeviceMethods: readonly MFADeviceMethod[];
 //# sourceMappingURL=mfa-method.enum.d.ts.map

package/dist/enums/mfa-method.enum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mfa-method.enum.d.ts","sourceRoot":"","sources":["../../src/enums/mfa-method.enum.ts"],"names":[],"mappings":"AAsCA,oBAAY,SAAS;IAKnB,IAAI,SAAS;IAMb,GAAG,QAAQ;IAMX,KAAK,UAAU;IAOf,OAAO,YAAY;IAOnB,MAAM,WAAW;CAClB;AAOD,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,IAAI,GAAG,SAAS,CAAC,GAAG,GAAG,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC;AAOnG,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC;AAOvE,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAK7C,CAAC"}
+{"version":3,"file":"mfa-method.enum.d.ts","sourceRoot":"","sources":["../../src/enums/mfa-method.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;GAIG;AACH,oBAAY,SAAS;IACnB;;;OAGG;IACH,IAAI,SAAS;IAEb;;;OAGG;IACH,GAAG,QAAQ;IAEX;;;OAGG;IACH,KAAK,UAAU;IAEf;;;;OAIG;IACH,OAAO,YAAY;IAEnB;;;;OAIG;IACH,MAAM,WAAW;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,IAAI,GAAG,SAAS,CAAC,GAAG,GAAG,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC;AAEnG;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG,SAAS,CAAC,MAAM,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAK7C,CAAC"}

package/dist/enums/mfa-method.enum.js

@@ -1,14 +1,78 @@
 "use strict";
+/**
+ * MFA Method Enum
+ *
+ * Defines all supported Multi-Factor Authentication methods.
+ * Used throughout the codebase to ensure type safety and consistency.
+ *
+ * **Device Methods** (require device setup):
+ * - TOTP: Time-based One-Time Password (authenticator apps)
+ * - SMS: SMS verification codes
+ * - EMAIL: Email verification codes
+ * - PASSKEY: WebAuthn/FIDO2 passkeys (biometric, security keys)
+ *
+ * **Verification Methods** (available for verification):
+ * - Includes all device methods
+ * - BACKUP: Backup recovery codes (single-use codes, not a device)
+ *
+ * @example
+ * ```typescript
+ * import { MFAMethod, MFADeviceMethod, MFAVerificationMethod } from '@nauth-toolkit/core';
+ *
+ * // Device methods only
+ * const deviceMethod: MFADeviceMethod = MFAMethod.TOTP;
+ *
+ * // Verification methods (includes backup)
+ * const verificationMethod: MFAVerificationMethod = MFAMethod.BACKUP;
+ *
+ * // Check if method is a device method
+ * if (method !== MFAMethod.BACKUP) {
+ *   // This is a device method
+ * }
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MFADeviceMethods = exports.MFAMethod = void 0;
+/**
+ * All supported MFA methods
+ *
+ * Use this enum instead of string literals throughout the codebase.
+ */
 var MFAMethod;
 (function (MFAMethod) {
+    /**
+     * Time-based One-Time Password
+     * Authenticator apps (Google Authenticator, Authy, Microsoft Authenticator, etc.)
+     */
     MFAMethod["TOTP"] = "totp";
+    /**
+     * SMS verification codes
+     * Sends one-time codes via text message
+     */
     MFAMethod["SMS"] = "sms";
+    /**
+     * Email verification codes
+     * Sends one-time codes via email
+     */
     MFAMethod["EMAIL"] = "email";
+    /**
+     * WebAuthn/FIDO2 passkeys
+     * Biometric authentication (Face ID, Touch ID, Windows Hello)
+     * Hardware security keys (YubiKey, etc.)
+     */
     MFAMethod["PASSKEY"] = "passkey";
+    /**
+     * Backup recovery codes
+     * Single-use recovery codes when MFA devices are unavailable
+     * Not a device method - only available for verification
+     */
     MFAMethod["BACKUP"] = "backup";
 })(MFAMethod || (exports.MFAMethod = MFAMethod = {}));
+/**
+ * Array of all device methods
+ *
+ * Useful for defaults and iteration.
+ */
 exports.MFADeviceMethods = [
     MFAMethod.TOTP,
     MFAMethod.SMS,

package/dist/enums/mfa-method.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"mfa-method.enum.js","sourceRoot":"","sources":["../../src/enums/mfa-method.enum.ts"],"names":[],"mappings":";;;AAsCA,IAAY,SAgCX;AAhCD,WAAY,SAAS;IAKnB,0BAAa,CAAA;IAMb,wBAAW,CAAA;IAMX,4BAAe,CAAA;IAOf,gCAAmB,CAAA;IAOnB,8BAAiB,CAAA;AACnB,CAAC,EAhCW,SAAS,yBAAT,SAAS,QAgCpB;AAqBY,QAAA,gBAAgB,GAA+B;IAC1D,SAAS,CAAC,IAAI;IACd,SAAS,CAAC,GAAG;IACb,SAAS,CAAC,KAAK;IACf,SAAS,CAAC,OAAO;CACT,CAAC"}
+{"version":3,"file":"mfa-method.enum.js","sourceRoot":"","sources":["../../src/enums/mfa-method.enum.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AAEH;;;;GAIG;AACH,IAAY,SAgCX;AAhCD,WAAY,SAAS;IACnB;;;OAGG;IACH,0BAAa,CAAA;IAEb;;;OAGG;IACH,wBAAW,CAAA;IAEX;;;OAGG;IACH,4BAAe,CAAA;IAEf;;;;OAIG;IACH,gCAAmB,CAAA;IAEnB;;;;OAIG;IACH,8BAAiB,CAAA;AACnB,CAAC,EAhCW,SAAS,yBAAT,SAAS,QAgCpB;AAgBD;;;;GAIG;AACU,QAAA,gBAAgB,GAA+B;IAC1D,SAAS,CAAC,IAAI;IACd,SAAS,CAAC,GAAG;IACb,SAAS,CAAC,KAAK;IACf,SAAS,CAAC,OAAO;CACT,CAAC"}

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

@@ -1,15 +1,106 @@
+/**
+ * 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],
+ * });
+ * ```
+ */
 export declare enum RiskFactor {
+    /**
+     * First login from unknown device
+     * Weight: 25 points (default)
+     */
     NEW_DEVICE = "new_device",
+    /**
+     * Login from new IP address
+     * Weight: 15 points (default)
+     * Note: Automatically excluded if new_country or impossible_travel is detected
+     */
     NEW_IP = "new_ip",
+    /**
+     * Login from different country
+     * Weight: 25 points (default)
+     */
     NEW_COUNTRY = "new_country",
+    /**
+     * Geographic distance/time anomaly (impossible travel)
+     * Weight: 40 points (default)
+     */
     IMPOSSIBLE_TRAVEL = "impossible_travel",
+    /**
+     * Unusual behavior patterns (suspicious activity)
+     * Weight: 30 points (default)
+     */
     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
+     */
     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.
+     */
     RECENT_PASSWORD_RESET = "recent_password_reset",
+    /**
+     * Token theft detected
+     * Used when refresh token reuse is detected from different session
+     */
     TOKEN_THEFT_ATTEMPT = "token_theft_attempt",
+    /**
+     * Refresh token reused from different session
+     * Indicates potential token theft or session hijacking
+     */
     REFRESH_TOKEN_REUSE_DIFFERENT_SESSION = "refresh_token_reuse_different_session",
+    /**
+     * Token reuse attempt detected
+     * Used when token reuse is blocked via atomic operations
+     */
     TOKEN_REUSE_ATTEMPT = "token_reuse_attempt",
+    /**
+     * Device token tampering detected
+     * Used when device token is provided but not found in trusted devices
+     */
     TAMPERED_DEVICE_TOKEN = "tampered_device_token",
+    /**
+     * MFA bypass attempt detected
+     * Used when invalid/tampered device token is provided during MFA verification
+     */
     MFA_BYPASS_ATTEMPT = "mfa_bypass_attempt"
 }
 //# sourceMappingURL=risk-factor.enum.d.ts.map