@nauth-toolkit/core 0.1.0

package/src/entities/storage-lock.entity.ts

@@ -0,0 +1,39 @@
+/**
+ * Base Storage Lock Entity
+ *
+ * Stores distributed locks for transient state management.
+ * Used by DatabaseStorageAdapter for token refresh locks and other distributed operations.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ */
+export class BaseStorageLock {
+  /**
+   * Internal lock record ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Unique key identifier for the lock
+   * Format: <lock-type>:<identifier> (e.g., "refresh-lock:token-hash-123")
+   */
+  key!: string;
+
+  /**
+   * Lock value (stored as string, typically timestamp or lock holder identifier)
+   */
+  value!: string;
+
+  /**
+   * Lock expiration timestamp
+   * Used for TTL-based cleanup and automatic lock release
+   * Can be null for locks that don't expire
+   */
+  expiresAt!: Date | null;
+
+  /**
+   * Lock creation timestamp
+   */
+  createdAt!: Date;
+}

package/src/entities/trusted-device.entity.ts

@@ -0,0 +1,112 @@
+/**
+ * Base Trusted Device Entity
+ *
+ * Stores trusted device information for MFA "remember device" feature.
+ * Devices marked as trusted can skip MFA verification for a configured period.
+ * Uses HttpOnly cookies for secure device token storage.
+ *
+ * @remarks
+ * Each user can have multiple trusted devices. Each record represents one device
+ * that has been marked as trusted after successful MFA verification.
+ * Trust persists across logouts and session expiration.
+ *
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @example
+ * ```typescript
+ * // Trust a device after MFA verification
+ * const trustedDevice = new TrustedDevice();
+ * trustedDevice.userId = user.id;
+ * trustedDevice.deviceTokenHash = hashToken(deviceToken);
+ * trustedDevice.trustedUntil = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+ * trustedDevice.deviceName = 'iPhone 15 Pro';
+ * trustedDevice.deviceType = 'mobile';
+ * ```
+ */
+export class BaseTrustedDevice {
+  /**
+   * Internal device ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Internal user ID (foreign key to users table)
+   * References the user who trusted this device
+   */
+  userId!: number;
+
+  /**
+   * Hashed device token (SHA-256)
+   * The actual token is stored in HttpOnly cookie, only hash stored in DB
+   * Used for validation and lookup
+   *
+   * ⚠️ SECURITY: Never store the actual token, only the hash
+   */
+  deviceTokenHash!: string;
+
+  /**
+   * Device identifier (UUID from client or generated)
+   * Used for additional validation and device management
+   * Can be used to identify the same device across different tokens
+   */
+  deviceId?: string | null;
+
+  /**
+   * User-friendly device name
+   * Examples: "iPhone 15 Pro", "Chrome on MacBook", "Firefox on Windows"
+   */
+  deviceName?: string | null;
+
+  /**
+   * Device type
+   * Examples: "mobile", "desktop", "tablet"
+   */
+  deviceType?: string | null;
+
+  /**
+   * IP address when device was trusted
+   * Used for audit and security monitoring
+   */
+  ipAddress?: string | null;
+
+  /**
+   * User agent string when device was trusted
+   * Used for audit and device identification
+   */
+  userAgent?: string | null;
+
+  /**
+   * Platform extracted from user agent
+   * Examples: "iOS", "Android", "Windows", "macOS"
+   */
+  platform?: string | null;
+
+  /**
+   * Browser extracted from user agent
+   * Examples: "Chrome", "Safari", "Firefox"
+   */
+  browser?: string | null;
+
+  /**
+   * When trust expires
+   * After this date, device is no longer trusted and MFA is required
+   * Calculated as: createdAt + rememberDeviceDays
+   */
+  trustedUntil!: Date;
+
+  /**
+   * When this device was last used for login
+   * Updated on each successful login from this trusted device
+   */
+  lastUsedAt?: Date | null;
+
+  /**
+   * Device creation timestamp
+   */
+  createdAt!: Date;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt!: Date;
+}

package/src/entities/user.entity.ts

@@ -0,0 +1,243 @@
+/**
+ * Base User Entity
+ *
+ * Core user authentication record with all fields and business logic.
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ */
+export class BaseUser {
+  /**
+   * Internal database ID (auto-increment integer)
+   * Used for foreign key relationships and internal queries
+   * NOT exposed externally
+   */
+  id!: number;
+
+  /**
+   * External user identifier (UUID)
+   * Exposed in API responses and JWT tokens as 'sub' (subject)
+   * This is what consuming applications should use
+   */
+  sub!: string;
+
+  /**
+   * User's username (optional, unique if set)
+   */
+  username?: string | null;
+
+  /**
+   * User's first name
+   */
+  firstName?: string | null;
+
+  /**
+   * User's last name
+   */
+  lastName?: string | null;
+
+  /**
+   * User's email address (required, unique)
+   */
+  email!: string;
+
+  /**
+   * User's phone number in E.164 format (optional)
+   */
+  phone?: string | null;
+
+  /**
+   * Hashed password (Argon2)
+   * NULL for social-only accounts
+   */
+  passwordHash?: string | null;
+
+  /**
+   * When password was last changed
+   * Used for password expiry policies
+   */
+  passwordChangedAt?: Date | null;
+
+  /**
+   * Password history (hashed)
+   * Used to prevent password reuse
+   */
+  passwordHistory?: string[] | null;
+
+  /**
+   * Flag to force password change on next login
+   * When true, user must complete FORCE_CHANGE_PASSWORD challenge
+   * Can be set by admin or by password expiration policy
+   */
+  mustChangePassword!: boolean;
+
+  /**
+   * Email verification status
+   */
+  isEmailVerified!: boolean;
+
+  /**
+   * Phone verification status
+   */
+  isPhoneVerified!: boolean;
+
+  /**
+   * Account active status
+   * Inactive accounts cannot login
+   */
+  isActive!: boolean;
+
+  /**
+   * Account lock status
+   * Locked accounts cannot login until unlocked
+   */
+  isLocked!: boolean;
+
+  /**
+   * Reason for account lock
+   */
+  lockReason?: string | null;
+
+  /**
+   * When account was locked
+   */
+  lockedAt?: Date | null;
+
+  /**
+   * When account lock expires (NULL = permanent)
+   */
+  lockedUntil?: Date | null;
+
+  /**
+   * Number of consecutive failed login attempts
+   */
+  failedLoginAttempts!: number;
+
+  /**
+   * When last failed login occurred
+   */
+  lastFailedLoginAt?: Date | null;
+
+  /**
+   * When user last successfully logged in
+   */
+  lastLoginAt?: Date | null;
+
+  /**
+   * IP address of last successful login
+   */
+  lastLoginIp?: string | null;
+
+  /**
+   * MFA enabled status
+   */
+  mfaEnabled!: boolean;
+
+  /**
+   * List of enabled MFA methods
+   * Examples: ['totp', 'sms', 'passkey']
+   */
+  mfaMethods?: string[] | null;
+
+  /**
+   * When MFA was enforced for this user
+   */
+  mfaEnforcedAt?: Date | null;
+
+  /**
+   * TOTP secret (encrypted)
+   * ⚠️ DEPRECATED: Use MFADevice entity instead
+   */
+  totpSecret?: string | null;
+
+  /**
+   * Backup recovery codes (hashed)
+   * Single-use codes for account recovery
+   */
+  backupCodes?: string[] | null;
+
+  /**
+   * User's preferred MFA method
+   * Used to pre-select MFA method during authentication
+   */
+  preferredMfaMethod?: string | null;
+
+  /**
+   * MFA exemption status
+   *
+   * When true, user is exempt from MFA requirements (both setup and verification).
+   * This is an admin-only field and should only be set through admin functions.
+   *
+   * SECURITY: Exemption only affects MFA - other security measures (account lock,
+   * email verification, password change) still apply normally.
+   *
+   * @default false
+   */
+  mfaExempt?: boolean;
+
+  /**
+   * Reason for MFA exemption (optional, for audit trail)
+   *
+   * Admin should provide reason when granting exemption (e.g., "Internal service account",
+   * "Legacy system integration", "Special access approval")
+   *
+   * @default null
+   */
+  mfaExemptReason?: string | null;
+
+  /**
+   * When MFA exemption was granted
+   *
+   * Used for audit trail and potentially for expiration logic in future.
+   *
+   * @default null
+   */
+  mfaExemptGrantedAt?: Date | null;
+
+  /**
+   * Who granted the MFA exemption (optional, admin identifier)
+   *
+   * For audit trail - store admin user ID or identifier who granted exemption.
+   *
+   * @default null
+   */
+  mfaExemptGrantedBy?: string | null;
+
+  /**
+   * Optimization flag: indicates if user has any social authentication methods
+   * Prevents unnecessary joins for password-only users (80%+ of users)
+   * Updated automatically when social accounts are linked/unlinked
+   */
+  hasSocialAuth!: boolean;
+
+  /**
+   * Array of social providers linked to this account
+   * Examples: ['google', 'apple', 'facebook']
+   * Updated automatically when social accounts are linked/unlinked
+   */
+  socialProviders?: string[] | null;
+
+  /**
+   * Additional user metadata (JSON)
+   * For custom application-specific data
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Account creation timestamp
+   */
+  createdAt!: Date;
+
+  /**
+   * Last account update timestamp
+   */
+  updatedAt!: Date;
+
+  /**
+   * Soft delete timestamp
+   * NULL if account is not deleted
+   */
+  deletedAt?: Date | null;
+}

package/src/entities/verification-token.entity.ts

@@ -0,0 +1,141 @@
+/**
+ * Base Verification Token Entity
+ *
+ * Stores email/phone verification codes and password reset tokens.
+ * Supports multiple verification types with expiry and attempt tracking.
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ */
+export class BaseVerificationToken {
+  /**
+   * Internal verification token ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Internal user ID (foreign key to users table)
+   * Uses integer for optimal performance
+   */
+  userId!: number;
+
+  /**
+   * Challenge session ID (foreign key to challenge sessions table)
+   * Links verification token to specific challenge session for security.
+   * Prevents old tokens from being used with new challenge sessions.
+   * NULL for password reset tokens (not tied to challenges)
+   */
+  challengeSessionId?: number | null;
+
+  /**
+   * Token type
+   * - 'email': Email verification
+   * - 'phone': Phone verification
+   * - 'password_reset': Password reset
+   */
+  type!: 'email' | 'phone' | 'password_reset';
+
+  /**
+   * Verification token (hashed for security)
+   * Used for magic links and password reset
+   */
+  token!: string;
+
+  /**
+   * Verification code (for email/SMS OTP)
+   * Usually 6 digits, stored as string for flexibility
+   */
+  code?: string | null;
+
+  /**
+   * Token expiration timestamp
+   * After this time, token/code is invalid
+   */
+  expiresAt!: Date;
+
+  /**
+   * Number of failed verification attempts
+   * Used to prevent brute force attacks
+   */
+  attempts!: number;
+
+  /**
+   * When token was successfully used
+   * NULL if not yet used
+   */
+  usedAt?: Date | null;
+
+  /**
+   * IP address when token was created
+   * For security auditing
+   */
+  ipAddress?: string | null;
+
+  /**
+   * User agent when token was created
+   * For security auditing
+   */
+  userAgent?: string | null;
+
+  /**
+   * Additional metadata (JSON)
+   * For storing additional verification-specific data
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt!: Date;
+
+  /**
+   * Check if token is expired
+   *
+   * @returns true if token is expired
+   *
+   * @example
+   * ```typescript
+   * if (token.isExpired()) {
+   *   throw new Error('Verification code has expired');
+   * }
+   * ```
+   */
+  isExpired(): boolean {
+    return new Date() > this.expiresAt;
+  }
+
+  /**
+   * Check if token has been used
+   *
+   * @returns true if token has been used
+   *
+   * @example
+   * ```typescript
+   * if (token.isUsed()) {
+   *   throw new Error('Verification code has already been used');
+   * }
+   * ```
+   */
+  isUsed(): boolean {
+    return this.usedAt !== null && this.usedAt !== undefined;
+  }
+
+  /**
+   * Check if max attempts exceeded
+   *
+   * @param maxAttempts - Maximum allowed attempts
+   * @returns true if max attempts exceeded
+   *
+   * @example
+   * ```typescript
+   * if (token.maxAttemptsExceeded(3)) {
+   *   throw new Error('Too many failed attempts');
+   * }
+   * ```
+   */
+  maxAttemptsExceeded(maxAttempts: number): boolean {
+    return this.attempts >= maxAttempts;
+  }
+}