@nauth-toolkit/core 0.1.0

package/src/entities/challenge-session.entity.ts

@@ -0,0 +1,116 @@
+/**
+ * Base Challenge Session Entity
+ *
+ * Stores temporary authentication challenge sessions.
+ * These are short-lived sessions used to track pending challenges
+ * that must be completed before full authentication is granted.
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @remarks
+ * Similar to AWS Cognito's challenge sessions, these are NOT full JWT tokens.
+ * They expire quickly (typically 15 minutes) and are deleted after completion.
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ *
+ * @example
+ * ```typescript
+ * // Creating a challenge session after signup
+ * const challengeSession = new ChallengeSession();
+ * challengeSession.userId = user.id;
+ * challengeSession.challengeName = 'VERIFY_EMAIL';
+ * challengeSession.sessionToken = randomUUID();
+ * challengeSession.expiresAt = new Date(Date.now() + 15 * 60 * 1000);
+ * challengeSession.metadata = { email: user.email };
+ * ```
+ */
+export class BaseChallengeSession {
+  /**
+   * Primary key
+   */
+  id!: number;
+
+  /**
+   * User ID foreign key
+   * References the user this challenge session belongs to
+   */
+  userId!: number;
+
+  /**
+   * Challenge type that must be completed
+   *
+   * @example 'VERIFY_EMAIL', 'VERIFY_PHONE', 'MFA_REQUIRED', 'FORCE_CHANGE_PASSWORD'
+   */
+  challengeName!: string;
+
+  /**
+   * Temporary session token (UUID)
+   * This is returned to the client and must be submitted when responding to challenge
+   */
+  sessionToken!: string;
+
+  /**
+   * Session expiration time
+   * Challenge sessions are short-lived (typically 15 minutes)
+   */
+  expiresAt!: Date;
+
+  /**
+   * Whether this challenge has been completed successfully
+   * Completed challenges cannot be attempted again
+   */
+  isCompleted?: boolean;
+
+  /**
+   * When the challenge was completed successfully
+   * NULL if not yet completed
+   */
+  completedAt?: Date | null;
+
+  /**
+   * Number of failed attempts to complete this challenge
+   * Used to prevent brute-force attacks on verification codes
+   */
+  attempts!: number;
+
+  /**
+   * Maximum allowed attempts before session is invalidated
+   */
+  maxAttempts!: number;
+
+  /**
+   * Challenge-specific metadata
+   * Stores information needed for challenge completion
+   *
+   * @example
+   * ```typescript
+   * {
+   *   email: 'user@example.com',
+   *   phone: '+1234567890',
+   *   verificationTokenId: 123
+   * }
+   * ```
+   */
+  challengeParameters?: Record<string, unknown> | null;
+
+  /**
+   * Additional metadata (alias for challengeParameters for backwards compatibility)
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * IP address where the challenge session was created
+   * For security auditing
+   */
+  ipAddress?: string | null;
+
+  /**
+   * User agent where the challenge session was created
+   * For security auditing
+   */
+  userAgent?: string | null;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt!: Date;
+}

package/src/entities/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Base Entity Classes
+ *
+ * Database-agnostic entity classes containing all fields and business logic.
+ * Database adapters (TypeORM, Prisma, etc.) extend these classes and add ORM-specific decorators.
+ *
+ * @remarks
+ * These base classes provide:
+ * - Field definitions
+ * - Business logic methods
+ * - JSDoc documentation
+ * - Type safety
+ *
+ * Database packages add:
+ * - ORM decorators (@Entity, @Column, etc.)
+ * - Database-specific configuration
+ * - Indexes and constraints
+ */
+export { BaseUser } from './user.entity';
+export { BaseSession } from './session.entity';
+export { BaseTrustedDevice } from './trusted-device.entity';
+export { BaseLoginAttempt } from './login-attempt.entity';
+export { BaseVerificationToken } from './verification-token.entity';
+export { BaseSocialAccount } from './social-account.entity';
+export { BaseChallengeSession } from './challenge-session.entity';
+export { BaseMFADevice } from './mfa-device.entity';
+export { BaseAuthAudit, type AuthAuditEventStatus } from './auth-audit.entity';
+export { BaseRateLimit } from './rate-limit.entity';
+export { BaseStorageLock } from './storage-lock.entity';

package/src/entities/login-attempt.entity.ts

@@ -0,0 +1,64 @@
+/**
+ * Base Login Attempt Entity
+ *
+ * Failed login tracking for security auditing and rate limiting.
+ * 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 BaseLoginAttempt {
+  /**
+   * Internal login attempt ID
+   */
+  id!: number;
+
+  /**
+   * Email/username used in login attempt
+   * May be NULL for malformed requests
+   */
+  email?: string | null;
+
+  /**
+   * Internal user ID (foreign key to users table)
+   * Nullable since login attempt might be for non-existent user
+   */
+  userId?: number | null;
+
+  /**
+   * IP address of login attempt
+   */
+  ipAddress?: string | null;
+
+  /**
+   * User agent string
+   */
+  userAgent?: string | null;
+
+  /**
+   * Whether login was successful
+   */
+  success!: boolean;
+
+  /**
+   * Reason for login failure
+   * Examples: "invalid_credentials", "account_locked", "mfa_required"
+   */
+  failureReason?: string | null;
+
+  /**
+   * Whether MFA was required for this attempt
+   */
+  mfaRequired!: boolean;
+
+  /**
+   * Additional metadata (JSON)
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Login attempt timestamp
+   */
+  createdAt!: Date;
+}

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

@@ -0,0 +1,151 @@
+import { MFADeviceMethod } from '../enums/mfa-method.enum';
+
+/**
+ * Base MFA Device Entity
+ *
+ * Stores multi-factor authentication device registrations.
+ * Supports multiple MFA methods: TOTP (authenticator apps), SMS, Email, and Passkeys (WebAuthn).
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @remarks
+ * Each user can register multiple MFA devices of different types for redundancy.
+ * Devices can be enabled/disabled without deletion for security audit purposes.
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ *
+ * @example
+ * ```typescript
+ * // Create TOTP device
+ * const totpDevice = new MFADevice();
+ * totpDevice.userId = user.id;
+ * totpDevice.type = 'totp';
+ * totpDevice.name = 'Google Authenticator';
+ * totpDevice.secret = encryptedSecret;
+ * totpDevice.isActive = true;
+ *
+ * // Create Passkey device
+ * const passkeyDevice = new MFADevice();
+ * passkeyDevice.userId = user.id;
+ * passkeyDevice.type = 'passkey';
+ * passkeyDevice.name = 'iPhone 15 Pro';
+ * passkeyDevice.credentialId = 'credential-id-here';
+ * passkeyDevice.publicKey = 'public-key-here';
+ * passkeyDevice.counter = 0;
+ * passkeyDevice.isActive = true;
+ * ```
+ */
+export class BaseMFADevice {
+  /**
+   * Internal device ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Internal user ID (foreign key to users table)
+   * References the user who owns this MFA device
+   */
+  userId!: number;
+
+  /**
+   * MFA method type
+   *
+   * - 'totp': Time-based One-Time Password (Google Authenticator, Authy, etc.)
+   * - 'sms': SMS-based verification codes
+   * - 'email': Email-based verification codes
+   * - 'passkey': WebAuthn/FIDO2 passkeys (biometric, security keys)
+   */
+  type!: MFADeviceMethod;
+
+  /**
+   * User-friendly device name
+   * Helps users identify their devices (e.g., "iPhone 15 Pro", "Google Authenticator")
+   */
+  name!: string;
+
+  /**
+   * TOTP secret (encrypted)
+   * Used only for TOTP devices
+   * ⚠️ SECURITY: Must be encrypted at rest
+   */
+  secret?: string | null;
+
+  /**
+   * Phone number for SMS MFA
+   * Used only for SMS devices
+   * Must be in E.164 format (e.g., +1234567890)
+   */
+  phoneNumber?: string | null;
+
+  /**
+   * Email address for Email MFA
+   * Used only for Email devices
+   * Must be a valid email address format
+   */
+  email?: string | null;
+
+  /**
+   * WebAuthn credential ID (base64url encoded)
+   * Unique identifier for this passkey
+   * Used only for passkey devices
+   */
+  credentialId?: string | null;
+
+  /**
+   * WebAuthn public key (base64url encoded)
+   * Used to verify passkey signatures
+   * Used only for passkey devices
+   */
+  publicKey?: string | null;
+
+  /**
+   * WebAuthn signature counter
+   * Incremented with each authentication to prevent replay attacks
+   * Used only for passkey devices
+   */
+  counter?: number | null;
+
+  /**
+   * WebAuthn transports (USB, NFC, BLE, internal)
+   * Helps browser suggest the right authentication method
+   * Used only for passkey devices
+   */
+  transports?: string[] | null;
+
+  /**
+   * Whether this device is currently active
+   * Inactive devices cannot be used for authentication but remain in database for audit
+   */
+  isActive!: boolean;
+
+  /**
+   * Whether this is the user's preferred/primary MFA method
+   * Used to pre-select MFA method during authentication
+   */
+  isPrimary!: boolean;
+
+  /**
+   * Last time this device was used for authentication
+   */
+  lastUsedAt?: Date | null;
+
+  /**
+   * Number of times this device has been used
+   * Useful for analytics and detecting suspicious patterns
+   */
+  usageCount!: number;
+
+  /**
+   * Additional device metadata (browser, OS, IP on registration, etc.)
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Device registration timestamp
+   */
+  createdAt!: Date;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt!: Date;
+}

package/src/entities/rate-limit.entity.ts

@@ -0,0 +1,44 @@
+/**
+ * Base Rate Limit Entity
+ *
+ * Stores rate limiting counters for transient state management.
+ * Used by DatabaseStorageAdapter to track rate limits across multiple servers.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ */
+export class BaseRateLimit {
+  /**
+   * Internal rate limit record ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Unique key identifier for the rate limit counter
+   * Format: <endpoint>:<identifier> (e.g., "email-verification:user:123")
+   */
+  key!: string;
+
+  /**
+   * Counter value (stored as string, parsed as integer)
+   */
+  value!: string;
+
+  /**
+   * Expiration timestamp
+   * Used for TTL-based cleanup via scheduled jobs
+   * Can be null for records that don't expire immediately
+   */
+  expiresAt!: Date | null;
+
+  /**
+   * Record creation timestamp
+   */
+  createdAt!: Date;
+
+  /**
+   * Record last update timestamp
+   */
+  updatedAt!: Date;
+}

package/src/entities/session.entity.ts

@@ -0,0 +1,180 @@
+/**
+ * Base Session Entity
+ *
+ * JWT session tracking with device information and security features.
+ * 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 BaseSession {
+  /**
+   * Internal session ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Version for optimistic locking
+   * Automatically incremented on each update by the ORM
+   * Used to detect race conditions and concurrent modifications
+   *
+   * ⚠️ SECURITY CRITICAL: Prevents TOCTOU vulnerabilities
+   */
+  version!: number;
+
+  /**
+   * Internal user ID (foreign key to users table)
+   * Uses integer for optimal performance in joins and lookups
+   */
+  userId!: number;
+
+  /**
+   * Access token hash (SHA-256)
+   * Used for token revocation and session tracking
+   */
+  accessTokenHash!: string;
+
+  /**
+   * Refresh token hash (SHA-256)
+   * Used for token rotation and reuse detection
+   */
+  refreshTokenHash!: string;
+
+  /**
+   * Token family identifier
+   * Used for refresh token rotation and reuse detection
+   */
+  tokenFamily?: string | null;
+
+  /**
+   * Device identifier (UUID)
+   * Unique identifier for the device/browser
+   */
+  deviceId?: string | null;
+
+  /**
+   * User-friendly device name
+   * Examples: "iPhone 15 Pro", "Chrome on MacBook"
+   */
+  deviceName?: string | null;
+
+  /**
+   * Device type
+   * Examples: "mobile", "desktop", "tablet"
+   */
+  deviceType?: string | null;
+
+  /**
+   * Device fingerprint hash
+   * Combination of device characteristics for additional security
+   */
+  deviceFingerprint?: string | null;
+
+  /**
+   * IP address when session was created
+   */
+  ipAddress?: string | null;
+
+  /**
+   * Country from IP geolocation (optional)
+   */
+  ipCountry?: string | null;
+
+  /**
+   * City from IP geolocation (optional)
+   */
+  ipCity?: string | null;
+
+  /**
+   * Latitude from IP geolocation (optional)
+   * Used for impossible travel detection
+   */
+  ipLatitude?: number | null;
+
+  /**
+   * Longitude from IP geolocation (optional)
+   * Used for impossible travel detection
+   */
+  ipLongitude?: number | null;
+
+  /**
+   * ISP from IP geolocation (optional)
+   */
+  ipIsp?: string | null;
+
+  /**
+   * User agent string
+   */
+  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;
+
+  /**
+   * Authentication method used to create this session
+   * Examples: "password", "google", "facebook", "github", "apple"
+   * null for legacy sessions
+   */
+  authMethod?: string | null;
+
+  /**
+   * "Remember me" flag
+   * Longer expiration for remembered sessions
+   */
+  isRemembered!: boolean;
+
+  /**
+   * Trusted device flag
+   * Trusted devices may skip MFA
+   */
+  isTrustedDevice!: boolean;
+
+  /**
+   * Session expiration timestamp
+   * After this time, session is invalid
+   */
+  expiresAt!: Date;
+
+  /**
+   * Last activity timestamp
+   * Updated on each API request
+   */
+  lastActivityAt?: Date | null;
+
+  /**
+   * Session revocation status
+   * Revoked sessions cannot be used
+   */
+  isRevoked!: boolean;
+
+  /**
+   * When session was revoked
+   */
+  revokedAt?: Date | null;
+
+  /**
+   * Reason for session revocation
+   * Examples: "user_logout", "token_reuse_detected", "admin_revoked"
+   */
+  revokeReason?: string | null;
+
+  /**
+   * Additional session metadata (JSON)
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Session creation timestamp
+   */
+  createdAt!: Date;
+}

package/src/entities/social-account.entity.ts

@@ -0,0 +1,96 @@
+/**
+ * Base Social Account Entity
+ *
+ * Stores OAuth provider linkage (no token storage, one-time attribute import).
+ * Each record represents a user's account linked to a specific social provider.
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * // User has Google and Apple accounts linked
+ * const socialAccounts = [
+ *   { provider: 'google', providerId: 'google_123', providerEmail: 'user@gmail.com' },
+ *   { provider: 'apple', providerId: 'apple_456', providerEmail: 'user@icloud.com' }
+ * ];
+ * ```
+ */
+export class BaseSocialAccount {
+  /**
+   * Internal database ID (auto-increment integer)
+   * Used for foreign key relationships and internal queries
+   * NOT exposed externally
+   */
+  id!: number;
+
+  /**
+   * Foreign key to users table
+   * References the user who owns this social account
+   */
+  userId!: number;
+
+  /**
+   * Social provider name
+   * Examples: 'google', 'apple', 'facebook'
+   */
+  provider!: string;
+
+  /**
+   * Provider's unique identifier for this user
+   * This is the ID that the OAuth provider uses to identify the user
+   * Examples: Google sub, Apple user ID, Facebook ID
+   */
+  providerId!: string;
+
+  /**
+   * Email address from the provider (for audit/debugging)
+   * May be different from user's primary email if they have multiple emails
+   * Used for account linking by email verification
+   */
+  providerEmail?: string | null;
+
+  /**
+   * When this social account was linked to the user
+   * Used for audit trails and account management
+   */
+  linkedAt!: Date;
+
+  /**
+   * When this social account was last used for authentication
+   * Updated on each successful social login
+   * Used for analytics and account cleanup
+   */
+  lastUsedAt?: Date | null;
+
+  /**
+   * Raw OAuth profile data from provider (for debugging)
+   * Contains the full response from the OAuth provider
+   * Useful for troubleshooting and attribute mapping
+   *
+   * @example
+   * ```json
+   * {
+   *   "sub": "google_123",
+   *   "email": "user@gmail.com",
+   *   "given_name": "John",
+   *   "family_name": "Doe",
+   *   "picture": "https://...",
+   *   "locale": "en"
+   * }
+   * ```
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Account creation timestamp
+   */
+  createdAt!: Date;
+
+  /**
+   * Last account update timestamp
+   */
+  updatedAt!: Date;
+}