@nauth-toolkit/core 0.1.0

package/src/enums/error-codes.enum.ts

@@ -0,0 +1,420 @@
+/**
+ * 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);
+ * }
+ * ```
+ */
+export enum AuthErrorCode {
+  // ============================================================================
+  // Authentication Errors (AUTH_*)
+  // ============================================================================
+
+  /**
+   * Invalid username/email or password
+   *
+   * Used when credentials don't match any user or password is incorrect.
+   */
+  INVALID_CREDENTIALS = 'AUTH_INVALID_CREDENTIALS',
+
+  /**
+   * Account has been locked due to too many failed attempts
+   *
+   * Temporary lockout for security. Includes lockout duration in details.
+   */
+  ACCOUNT_LOCKED = 'AUTH_ACCOUNT_LOCKED',
+
+  /**
+   * Account is inactive or disabled
+   *
+   * Account exists but has been deactivated by admin or user.
+   */
+  ACCOUNT_INACTIVE = 'AUTH_ACCOUNT_INACTIVE',
+
+  /**
+   * Access token has expired
+   *
+   * Client should attempt token refresh.
+   */
+  TOKEN_EXPIRED = 'AUTH_TOKEN_EXPIRED',
+
+  /**
+   * Token is invalid or malformed
+   *
+   * Token signature verification failed or token format is invalid.
+   */
+  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.
+   */
+  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.
+   */
+  COOKIES_NOT_ALLOWED = 'AUTH_COOKIES_NOT_ALLOWED',
+
+  /**
+   * CSRF token is invalid or missing
+   *
+   * Used when CSRF protection is enabled and token validation fails.
+   */
+  CSRF_TOKEN_INVALID = 'AUTH_CSRF_TOKEN_INVALID',
+
+  /**
+   * CSRF token is missing from request
+   *
+   * Used when CSRF protection is enabled but no token is provided.
+   */
+  CSRF_TOKEN_MISSING = 'AUTH_CSRF_TOKEN_MISSING',
+
+  /**
+   * Refresh token reuse detected - security violation
+   *
+   * All sessions have been revoked. User must login again.
+   */
+  TOKEN_REUSE_DETECTED = 'AUTH_TOKEN_REUSE_DETECTED',
+
+  /**
+   * Session not found or has been revoked
+   */
+  SESSION_NOT_FOUND = 'AUTH_SESSION_NOT_FOUND',
+
+  /**
+   * Session has expired
+   */
+  SESSION_EXPIRED = 'AUTH_SESSION_EXPIRED',
+
+  // ============================================================================
+  // Signup Errors (SIGNUP_*)
+  // ============================================================================
+
+  /**
+   * User signup is currently disabled
+   *
+   * Signups are administratively disabled.
+   */
+  SIGNUP_DISABLED = 'SIGNUP_DISABLED',
+
+  /**
+   * Email address is already registered
+   *
+   * Another user account exists with this email.
+   */
+  EMAIL_EXISTS = 'SIGNUP_EMAIL_EXISTS',
+
+  /**
+   * Username is already taken
+   *
+   * Another user has registered this username.
+   */
+  USERNAME_EXISTS = 'SIGNUP_USERNAME_EXISTS',
+
+  /**
+   * Phone number is already registered
+   *
+   * Another user account exists with this phone number.
+   */
+  PHONE_EXISTS = 'SIGNUP_PHONE_EXISTS',
+
+  /**
+   * Password doesn't meet security requirements
+   *
+   * Details include which requirements failed (length, complexity, etc.)
+   */
+  WEAK_PASSWORD = 'SIGNUP_WEAK_PASSWORD',
+
+  /**
+   * Phone number is required for signup
+   *
+   * Configuration requires phone verification.
+   */
+  PHONE_REQUIRED = 'SIGNUP_PHONE_REQUIRED',
+
+  /**
+   * Signup not allowed by hook or policy
+   */
+  SIGNUP_NOT_ALLOWED = 'SIGNUP_NOT_ALLOWED',
+
+  // ============================================================================
+  // Verification Errors (VERIFY_*)
+  // ============================================================================
+
+  /**
+   * Verification code is invalid
+   *
+   * Code doesn't match or has incorrect format.
+   */
+  VERIFICATION_CODE_INVALID = 'VERIFY_CODE_INVALID',
+
+  /**
+   * Verification code has expired
+   *
+   * User needs to request a new code.
+   */
+  VERIFICATION_CODE_EXPIRED = 'VERIFY_CODE_EXPIRED',
+
+  /**
+   * Too many failed verification attempts
+   *
+   * User exceeded max attempts. Must request new code.
+   */
+  VERIFICATION_TOO_MANY_ATTEMPTS = 'VERIFY_TOO_MANY_ATTEMPTS',
+
+  /**
+   * Email or phone is already verified
+   *
+   * No action needed.
+   */
+  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.
+   */
+  MFA_SETUP_REQUIRED = 'MFA_SETUP_REQUIRED',
+
+  // ============================================================================
+  // Rate Limit Errors (RATE_LIMIT_*)
+  // ============================================================================
+
+  /**
+   * Too many SMS verification requests
+   *
+   * Details include retryAfter (seconds) and resetAt (timestamp).
+   */
+  RATE_LIMIT_SMS = 'RATE_LIMIT_SMS',
+
+  /**
+   * Too many email verification requests
+   *
+   * Details include retryAfter (seconds) and resetAt (timestamp).
+   */
+  RATE_LIMIT_EMAIL = 'RATE_LIMIT_EMAIL',
+
+  /**
+   * Too many login attempts
+   *
+   * Account may be locked. Details include retryAfter.
+   */
+  RATE_LIMIT_LOGIN = 'RATE_LIMIT_LOGIN',
+
+  /**
+   * Too many resend code requests
+   *
+   * User must wait before requesting another code.
+   */
+  RATE_LIMIT_RESEND = 'RATE_LIMIT_RESEND',
+
+  // ============================================================================
+  // Social Auth Errors (SOCIAL_*)
+  // ============================================================================
+
+  /**
+   * Social provider token is invalid or expired
+   *
+   * Token verification failed with provider.
+   */
+  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.
+   */
+  SOCIAL_ACCOUNT_LINKED = 'SOCIAL_ACCOUNT_LINKED',
+
+  /**
+   * Social provider is not configured
+   *
+   * Provider credentials or settings are missing.
+   */
+  SOCIAL_CONFIG_MISSING = 'SOCIAL_CONFIG_MISSING',
+
+  /**
+   * Email is required from social provider
+   *
+   * Social provider didn't return email or email is not verified.
+   */
+  SOCIAL_EMAIL_REQUIRED = 'SOCIAL_EMAIL_REQUIRED',
+
+  /**
+   * Social account not found for this user
+   *
+   * User doesn't have this social provider linked.
+   */
+  SOCIAL_ACCOUNT_NOT_FOUND = 'SOCIAL_ACCOUNT_NOT_FOUND',
+
+  // ============================================================================
+  // Challenge Errors (CHALLENGE_*)
+  // ============================================================================
+
+  /**
+   * Challenge session has expired
+   *
+   * User must restart authentication flow.
+   */
+  CHALLENGE_EXPIRED = 'CHALLENGE_EXPIRED',
+
+  /**
+   * Challenge session is invalid
+   *
+   * Session token is malformed or not found.
+   */
+  CHALLENGE_INVALID = 'CHALLENGE_INVALID',
+
+  /**
+   * Challenge type mismatch
+   *
+   * Client sent wrong challenge type for this session.
+   */
+  CHALLENGE_TYPE_MISMATCH = 'CHALLENGE_TYPE_MISMATCH',
+
+  /**
+   * Max challenge attempts exceeded
+   *
+   * User must request new challenge session.
+   */
+  CHALLENGE_MAX_ATTEMPTS = 'CHALLENGE_MAX_ATTEMPTS',
+
+  /**
+   * Challenge has already been completed
+   */
+  CHALLENGE_ALREADY_COMPLETED = 'CHALLENGE_ALREADY_COMPLETED',
+
+  // ============================================================================
+  // Validation Errors (VALIDATION_*)
+  // ============================================================================
+
+  /**
+   * Request validation failed
+   *
+   * Details include field-specific validation errors.
+   */
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+
+  /**
+   * Phone number format is invalid
+   *
+   * Must be in E.164 format (e.g., +1234567890).
+   */
+  INVALID_PHONE_FORMAT = 'VALIDATION_INVALID_PHONE',
+
+  /**
+   * Email format is invalid
+   */
+  INVALID_EMAIL_FORMAT = 'VALIDATION_INVALID_EMAIL',
+
+  /**
+   * Password format is invalid
+   *
+   * Details include specific requirements that failed.
+   */
+  INVALID_PASSWORD_FORMAT = 'VALIDATION_INVALID_PASSWORD',
+
+  // ============================================================================
+  // Password Errors (PASSWORD_*)
+  // ============================================================================
+
+  /**
+   * Current password is incorrect
+   *
+   * Used when changing password.
+   */
+  PASSWORD_INCORRECT = 'PASSWORD_INCORRECT',
+
+  /**
+   * Cannot reuse recent passwords
+   *
+   * New password matches one of the recent passwords.
+   */
+  PASSWORD_REUSED = 'PASSWORD_REUSED',
+
+  /**
+   * Password change is not allowed
+   *
+   * Social-only users cannot change password.
+   */
+  PASSWORD_CHANGE_NOT_ALLOWED = 'PASSWORD_CHANGE_NOT_ALLOWED',
+
+  // ============================================================================
+  // General Errors (*)
+  // ============================================================================
+
+  /**
+   * Requested resource not found
+   */
+  NOT_FOUND = 'RESOURCE_NOT_FOUND',
+
+  /**
+   * Internal server error
+   *
+   * Unexpected error occurred. Details may include correlation ID.
+   */
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+
+  /**
+   * Access forbidden
+   *
+   * User doesn't have permission for this action.
+   */
+  FORBIDDEN = 'FORBIDDEN',
+
+  /**
+   * Service temporarily unavailable
+   *
+   * May include retryAfter in details.
+   */
+  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)
+   */
+  SIGNIN_BLOCKED_HIGH_RISK = 'SIGNIN_BLOCKED_HIGH_RISK',
+}

package/src/enums/mfa-method.enum.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 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 const MFADeviceMethods: readonly MFADeviceMethod[] = [
+  MFAMethod.TOTP,
+  MFAMethod.SMS,
+  MFAMethod.EMAIL,
+  MFAMethod.PASSKEY,
+] as const;

package/src/enums/risk-factor.enum.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 enum RiskFactor {
+  // ============================================================================
+  // Standard Risk Factors (from RiskDetectionService)
+  // ============================================================================
+
+  /**
+   * 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',
+
+  // ============================================================================
+  // Security Event Risk Factors
+  // ============================================================================
+
+  /**
+   * 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',
+}