@nauth-toolkit/core 0.1.0 → 0.1.3

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

@@ -1,116 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-/**
- * 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

@@ -1,64 +0,0 @@
-/**
- * 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

@@ -1,151 +0,0 @@
-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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,180 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-/**
- * 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;
-}