@nauth-toolkit/core 0.1.0 → 0.1.3

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

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

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

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

@@ -1,232 +0,0 @@
-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;
-}