@nauth-toolkit/core 0.1.0

package/src/dto/verify-mfa-code.dto.ts

@@ -0,0 +1,103 @@
+/**
+ * DTO for verifying MFA code
+ *
+ * Used to verify MFA code using the appropriate provider.
+ * Routes verification to the correct provider based on method name.
+ *
+ * @example
+ * ```typescript
+ * const isValid = await mfaService.verifyCode({
+ *   sub: 'user-uuid',
+ *   methodName: 'totp',
+ *   code: '123456',
+ *   deviceId: 1
+ * });
+ * ```
+ */
+
+import { IsEnum, IsString, IsUUID, IsOptional, MaxLength, IsInt } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { MFAMethod } from '../enums/mfa-method.enum';
+
+/**
+ * DTO for verifying MFA code
+ */
+export class VerifyMFACodeDTO {
+  /**
+   * User's unique identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be a valid UUID v4 format
+   * - Matches DB constraint: char(36) or uuid
+   *
+   * Sanitization:
+   * - Trimmed
+   * - Lowercased for consistency
+   *
+   * @example "a21b654c-2746-4168-acee-c175083a65cd"
+   */
+  @IsUUID('4', { message: 'User sub must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  sub!: string;
+
+  /**
+   * MFA method name
+   *
+   * Validation:
+   * - Must be one of: totp, sms, email, passkey, backup
+   * - Max 50 characters
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   *
+   * @example "totp"
+   */
+  @IsString({ message: 'Method name must be a string' })
+  @IsEnum([MFAMethod.TOTP, MFAMethod.SMS, MFAMethod.EMAIL, MFAMethod.PASSKEY, MFAMethod.BACKUP], {
+    message: 'Method name must be one of: totp, sms, email, passkey, backup',
+  })
+  @MaxLength(50, { message: 'Method name must not exceed 50 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  methodName!: string;
+
+  /**
+   * Verification code or credential (provider-specific)
+   *
+   * Validation:
+   * - Must be a string or object depending on method
+   * - For TOTP/SMS/Email: string code
+   * - For Passkey: credential object
+   * - For Backup: string code
+   */
+  code!: string | Record<string, unknown>;
+
+  /**
+   * Optional device ID
+   *
+   * Validation:
+   * - Must be a positive integer if provided
+   */
+  @IsOptional()
+  @IsInt({ message: 'Device ID must be a number' })
+  deviceId?: number;
+}
+
+/**
+ * Response DTO for MFA code verification
+ */
+export class VerifyMFACodeResponseDTO {
+  /**
+   * Whether verification succeeded
+   */
+  valid!: boolean;
+}

package/src/dto/verify-phone-by-sub.dto.ts

@@ -0,0 +1,78 @@
+import { IsUUID, IsNumberString, Length, IsOptional, IsInt, Min } from 'class-validator';
+import { Transform } from 'class-transformer';
+
+/**
+ * Verify Phone with Code by User Sub DTO
+ *
+ * Used for phone verification with 6-digit OTP code when allowing duplicate phones.
+ * Requires user sub to identify which user's phone to verify.
+ *
+ * Security:
+ * - UUID format validated (prevents injection)
+ * - Code format validated (6 digits)
+ *
+ * @example
+ * ```typescript
+ * POST /auth/verify-phone/verify-by-sub
+ * {
+ *   "sub": "a21b654c-2746-4168-acee-c175083a65cd",
+ *   "code": "123456"
+ * }
+ * ```
+ */
+export class VerifyPhoneWithCodeBySubDTO {
+  /**
+   * User's external identifier (sub/UUID v4)
+   *
+   * Validation:
+   * - Must be a valid UUID v4 format
+   * - Matches DB constraint: char(36) or uuid
+   *
+   * Sanitization:
+   * - Trimmed and lowercased for consistency
+   *
+   * @example "a21b654c-2746-4168-acee-c175083a65cd"
+   */
+  @IsUUID('4', { message: 'Sub must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  sub!: string;
+
+  /**
+   * 6-digit verification code
+   *
+   * Validation:
+   * - Must be a numeric string
+   * - Exactly 6 digits
+   *
+   * @example "123456"
+   */
+  @IsNumberString({}, { message: 'Code must contain only digits' })
+  @Length(6, 6, { message: 'Code must be exactly 6 digits' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      const cleaned = value.replace(/\D/g, '');
+      return cleaned.length === 6 ? cleaned : value;
+    }
+    return value;
+  })
+  code!: string;
+
+  /**
+   * Challenge session ID (internal use)
+   * Optional - used internally to link verification to specific challenge session.
+   * Provides security by ensuring codes are only valid for the session they were created for.
+   *
+   * Validation:
+   * - Must be a positive integer if provided
+   * - Optional (for backward compatibility and direct verification flows)
+   */
+  @IsOptional()
+  @IsInt({ message: 'challengeSessionId must be an integer' })
+  @Min(1, { message: 'challengeSessionId must be a positive integer' })
+  challengeSessionId?: number;
+}

package/src/dto/verify-phone.dto.ts

@@ -0,0 +1,245 @@
+import {
+  IsString,
+  IsNotEmpty,
+  Length,
+  Matches,
+  MaxLength,
+  IsNumberString,
+  IsUUID,
+  IsOptional,
+  IsBoolean,
+  IsInt,
+  Min,
+} from 'class-validator';
+import { Transform } from 'class-transformer';
+
+/**
+ * Verify Phone with Code DTO
+ *
+ * Used for phone verification with 6-digit OTP code.
+ *
+ * Security:
+ * - Phone validated against E.164 format (prevents SQL injection)
+ * - Code validated for exact 6 digits
+ * - All fields match DB constraints
+ *
+ * @example
+ * ```typescript
+ * POST /auth/verify-phone/verify
+ * {
+ *   "phone": "+1234567890",
+ *   "code": "123456"
+ * }
+ * ```
+ */
+export class VerifyPhoneWithCodeDTO {
+  /**
+   * User's phone number in E.164 format
+   *
+   * Validation:
+   * - Must be a string
+   * - Must match E.164 format: +[country code][number]
+   * - Max 20 characters (matches DB constraint: varchar(20))
+   *
+   * Sanitization:
+   * - Trimmed
+   * - Whitespace removed
+   *
+   * @example "+1234567890"
+   */
+  @IsString({ message: 'Phone must be a string' })
+  @IsNotEmpty({ message: 'Phone is required' })
+  @MaxLength(20, { message: 'Phone number must not exceed 20 characters' })
+  @Matches(/^\+[1-9]\d{1,14}$/, {
+    message: 'Phone must be in E.164 format (e.g., +1234567890)',
+  })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      // Remove all whitespace and keep only digits and +
+      return value.replace(/\s/g, '');
+    }
+    return value;
+  })
+  phone!: string;
+
+  /**
+   * 6-digit verification code
+   *
+   * Validation:
+   * - Must be a string
+   * - Exactly 6 digits (numeric only)
+   * - No letters, spaces, or special characters
+   * - Fixed length prevents timing attacks
+   *
+   * Sanitization:
+   * - Removes all whitespace (users might copy "123 456")
+   * - Ensures only numeric string
+   *
+   * @example "123456"
+   */
+  @IsNumberString({}, { message: 'Code must contain only digits' })
+  @Length(6, 6, { message: 'Verification code must be exactly 6 digits' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      // Remove all whitespace and non-digit characters
+      const cleaned = value.replace(/\D/g, '');
+      return cleaned.length === 6 ? cleaned : value; // Return original if not 6 digits (let validator catch it)
+    }
+    return value;
+  })
+  code!: string;
+
+  /**
+   * Challenge session ID (internal use)
+   * Optional - used internally to link verification to specific challenge session.
+   * Provides security by ensuring codes are only valid for the session they were created for.
+   *
+   * Validation:
+   * - Must be a positive integer if provided
+   * - Optional (for backward compatibility and direct verification flows)
+   */
+  @IsOptional()
+  @IsInt({ message: 'challengeSessionId must be an integer' })
+  @Min(1, { message: 'challengeSessionId must be a positive integer' })
+  challengeSessionId?: number;
+}
+
+/**
+ * DTO for sending verification SMS
+ *
+ * Security:
+ * - User sub validated as UUID v4
+ * - Skip flag is boolean (prevents injection)
+ */
+export class SendVerificationSMSDTO {
+  /**
+   * User identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be valid UUID v4 format
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  sub!: string;
+
+  /**
+   * Skip the "already verified" check
+   * Used for MFA contexts where codes are needed even if phone is verified
+   *
+   * Validation:
+   * - Must be boolean
+   * - Optional (defaults to true)
+   */
+  @IsOptional()
+  @IsBoolean({ message: 'skipAlreadyVerifiedCheck must be a boolean' })
+  skipAlreadyVerifiedCheck?: boolean;
+
+  /**
+   * Challenge session ID to link this verification token to
+   * Optional - for linking verification tokens to specific challenge sessions.
+   * Provides security by preventing old tokens from being used with new sessions.
+   *
+   * Validation:
+   * - Must be a positive integer
+   * - Optional (for backward compatibility and non-challenge flows)
+   */
+  @IsOptional()
+  @IsInt({ message: 'challengeSessionId must be an integer' })
+  @Min(1, { message: 'challengeSessionId must be a positive integer' })
+  challengeSessionId?: number;
+}
+
+/**
+ * Response DTO for sendVerificationSMS
+ */
+export class SendVerificationSMSResponseDTO {
+  /**
+   * Verification token ID (internal integer)
+   */
+  tokenId!: number;
+}
+
+/**
+ * Response DTO for verifyPhoneWithCode and verifyPhoneWithCodeBySub
+ */
+export class VerifyPhoneResponseDTO {
+  /**
+   * Success message
+   */
+  message!: string;
+}
+
+/**
+ * DTO for resending verification SMS
+ *
+ * Supports both sub and phone-based resend
+ *
+ * Security:
+ * - Either sub or phone must be provided (conditional validation)
+ * - Rate limiting applied in service layer
+ * - Input sanitization prevents abuse
+ */
+export class ResendVerificationSMSDTO {
+  /**
+   * User identifier (UUID v4) - optional if phone provided
+   *
+   * Validation:
+   * - Must be valid UUID v4 format if provided
+   * - Required if phone is not provided
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsOptional()
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  sub?: string;
+
+  /**
+   * User's phone number - optional if sub provided
+   *
+   * Validation:
+   * - Must match E.164 format if provided
+   * - Max 20 characters (DB limit)
+   * - Required if sub is not provided
+   *
+   * Sanitization:
+   * - Whitespace removed
+   */
+  @IsOptional()
+  @IsString({ message: 'Phone must be a string' })
+  @MaxLength(20, { message: 'Phone number must not exceed 20 characters' })
+  @Matches(/^\+[1-9]\d{1,14}$/, {
+    message: 'Phone must be in E.164 format (e.g., +1234567890)',
+  })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.replace(/\s/g, '');
+    }
+    return value;
+  })
+  phone?: string;
+}
+
+/**
+ * Response DTO for resendVerificationSMS
+ */
+export class ResendVerificationSMSResponseDTO {
+  /**
+   * Verification token ID (internal integer)
+   */
+  tokenId!: number;
+}

package/src/entities/auth-audit.entity.ts

@@ -0,0 +1,232 @@
+import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+
+/**
+ * Authentication Audit Event Status
+ *
+ * Classification of event outcomes for filtering and analysis.
+ */
+export type AuthAuditEventStatus = 'SUCCESS' | 'FAILURE' | 'INFO' | 'SUSPICIOUS';
+
+/**
+ * Base Authentication Audit Entity
+ *
+ * Core audit 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.
+ *
+ * **Design Notes:**
+ * - Only stores `userId` (integer internal ID) - no `userSub` duplication
+ * - Risk tracking fields are infrastructure for future adaptive MFA (no business logic)
+ * - All audit integrations are non-blocking (errors logged, don't throw)
+ */
+export class BaseAuthAudit {
+  /**
+   * Internal audit record ID (auto-increment integer)
+   */
+  id!: number;
+
+  /**
+   * Internal user ID (foreign key to users table)
+   * Uses integer for optimal performance in joins and lookups.
+   * API methods accepting userSub will resolve to userId before querying.
+   *
+   * @remarks
+   * No userSub field to avoid duplication. All queries use userId
+   * for efficient database operations.
+   */
+  userId!: number;
+
+  /**
+   * Type of authentication/security event
+   */
+  eventType!: AuthAuditEventType;
+
+  /**
+   * Event classification status
+   * - SUCCESS: Operation completed successfully
+   * - FAILURE: Operation failed (login failed, verification failed, etc.)
+   * - INFO: Informational event (profile update, device added, etc.)
+   * - SUSPICIOUS: Security violation or suspicious activity detected
+   */
+  eventStatus!: AuthAuditEventStatus;
+
+  // ============================================================================
+  // Risk Assessment Fields (Infrastructure for Future Adaptive MFA)
+  // ============================================================================
+
+  /**
+   * Risk factor score (0-100)
+   * Calculated during adaptive MFA evaluation (future implementation).
+   * null if not applicable (non-adaptive flows).
+   *
+   * @remarks
+   * This is infrastructure for future adaptive MFA. The audit service
+   * records risk data but does NOT calculate risk scores. Risk calculation
+   * and adaptive MFA business logic will be implemented in future phases.
+   */
+  riskFactor?: number | null;
+
+  /**
+   * Risk factors that contributed to the risk score
+   * Examples: ['new_device', 'new_ip', 'new_country', 'impossible_travel']
+   *
+   * @remarks
+   * Infrastructure field for future adaptive MFA implementation.
+   */
+  riskFactors?: string[] | null;
+
+  /**
+   * Whether adaptive MFA was triggered for this event
+   * true if MFA was conditionally required based on risk (future implementation).
+   * null if not applicable.
+   *
+   * @remarks
+   * Infrastructure field for future adaptive MFA implementation.
+   */
+  adaptiveMfaTriggered?: boolean | null;
+
+  // ============================================================================
+  // Client Information
+  // ============================================================================
+
+  /**
+   * IP address where event occurred
+   */
+  ipAddress?: string | null;
+
+  /**
+   * Country from IP geolocation (optional, for geographic risk assessment)
+   */
+  ipCountry?: string | null;
+
+  /**
+   * City from IP geolocation (optional, for geographic risk assessment)
+   */
+  ipCity?: string | null;
+
+  /**
+   * Latitude from IP geolocation (optional, for impossible travel detection)
+   */
+  ipLatitude?: number | null;
+
+  /**
+   * Longitude from IP geolocation (optional, for impossible travel detection)
+   */
+  ipLongitude?: number | 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;
+
+  /**
+   * 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;
+
+  // ============================================================================
+  // Context Information
+  // ============================================================================
+
+  /**
+   * Session ID (if event is related to a session)
+   * Foreign key to sessions table
+   */
+  sessionId?: number | null;
+
+  /**
+   * Challenge session ID (if event is related to a challenge)
+   * Foreign key to challenge_sessions table
+   */
+  challengeSessionId?: number | null;
+
+  /**
+   * Authentication method used
+   * Examples: "password", "google", "apple", "facebook"
+   * Used for social login provider tracking
+   */
+  authMethod?: string | null;
+
+  /**
+   * Who performed this action (for admin/CLI/automated operations)
+   * - Admin user ID or email for manual admin actions
+   * - CLI identifier for command-line operations
+   * - 'system' for automated actions
+   * - null for user-initiated actions
+   *
+   * @example
+   * performedBy: 'admin@example.com'
+   * performedBy: 'cli-migration-2025'
+   * performedBy: 'system'
+   */
+  performedBy?: string | null;
+
+  // ============================================================================
+  // Event Details
+  // ============================================================================
+
+  /**
+   * Reason for the event (optional)
+   * Used for security events, account locks, etc.
+   */
+  reason?: string | null;
+
+  /**
+   * Detailed description of the event
+   */
+  description?: string | null;
+
+  /**
+   * Rich metadata (JSON)
+   * Event-specific data stored without requiring schema changes.
+   *
+   * @example
+   * ```typescript
+   * // Social login
+   * metadata: { provider: 'google', isNewUser: true }
+   *
+   * // Challenge event
+   * metadata: { challengeName: 'VERIFY_EMAIL', challengeSessionId: 123 }
+   *
+   * // MFA device
+   * metadata: { deviceType: 'totp', deviceName: 'iPhone Authenticator' }
+   *
+   * // Token reuse
+   * metadata: { tokenFamily: 'abc123', action: 'token_family_revoked' }
+   * ```
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Timestamp when event occurred
+   */
+  createdAt!: Date;
+}