@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/dto/user-response.dto.ts

@@ -1,138 +0,0 @@
-import { IUser } from '../interfaces/entities.interface';
-
-/**
- * User Response DTO
- *
- * Sanitized user object for API responses.
- * Excludes all sensitive and internal fields.
- *
- * Security:
- * - Never exposes password hash
- * - Never exposes MFA secrets
- * - Never exposes internal tracking fields
- * - Exposes 'sub' (external UUID) instead of internal 'id'
- *
- * No validators needed - this is generated internally by the library via fromEntity().
- *
- * @example
- * ```typescript
- * const user = await userRepository.findOne({ where: { sub } });
- * return UserResponseDto.fromEntity(user);
- * ```
- */
-export class UserResponseDto {
-  /**
-   * External user identifier (UUID v4)
-   * This is the 'sub' (subject) field from JWT tokens
-   */
-  sub!: string;
-
-  /**
-   * User's email address
-   */
-  email!: string;
-
-  /**
-   * User's username (optional)
-   */
-  username?: string | null;
-
-  /**
-   * User's first name (optional)
-   */
-  firstName?: string | null;
-
-  /**
-   * User's last name (optional)
-   */
-  lastName?: string | null;
-
-  /**
-   * User's phone number (optional)
-   * E.164 format validated in service layer if present
-   */
-  phone?: string | null;
-
-  /**
-   * Email verification status
-   */
-  isEmailVerified!: boolean;
-
-  /**
-   * Phone verification status
-   */
-  isPhoneVerified!: boolean;
-
-  /**
-   * Account active status
-   */
-  isActive!: boolean;
-
-  /**
-   * MFA enabled status
-   */
-  mfaEnabled!: boolean;
-
-  /**
-   * Array of social providers linked to this account
-   *
-   * Examples: ['google', 'apple', 'facebook']
-   * null/undefined means no social auth, only password-based
-   */
-  socialProviders?: string[] | null;
-
-  /**
-   * Whether this user has a password set
-   * Used to determine if user can use password-based authentication
-   * or is a pure social signup (no password, only social auth)
-   */
-  hasPasswordHash!: boolean;
-
-  /**
-   * Account creation timestamp
-   */
-  createdAt!: Date;
-
-  /**
-   * Last account update timestamp
-   */
-  updatedAt!: Date;
-
-  /**
-   * Convert User entity to safe response DTO
-   *
-   * @param user - User entity from database
-   * @returns Sanitized user object with external identifier (sub)
-   */
-  static fromEntity(user: IUser): UserResponseDto {
-    const dto = new UserResponseDto();
-
-    // Essential fields only
-    dto.sub = user.sub; // External UUID identifier
-    dto.email = user.email;
-    dto.username = user.username;
-    dto.firstName = user.firstName;
-    dto.lastName = user.lastName;
-    dto.phone = user.phone;
-    dto.isEmailVerified = user.isEmailVerified;
-    dto.isPhoneVerified = user.isPhoneVerified;
-    dto.isActive = user.isActive;
-    dto.mfaEnabled = user.mfaEnabled;
-    dto.socialProviders = user.socialProviders;
-    dto.hasPasswordHash = !!user.passwordHash; // Check if password exists
-    dto.createdAt = user.createdAt;
-    dto.updatedAt = user.updatedAt;
-
-    return dto;
-  }
-
-  /**
-   * Convert array of User entities to safe response DTOs
-   *
-   * @param users - Array of User entities
-   * @returns Array of sanitized user objects
-   */
-  static fromEntities(users: IUser[]): UserResponseDto[] {
-    return users.map((user) => UserResponseDto.fromEntity(user));
-  }
-}

package/src/dto/user-update.dto.ts

@@ -1,222 +0,0 @@
-import { IsEmail, IsString, MinLength, MaxLength, IsOptional, Matches, IsBoolean, IsEnum } from 'class-validator';
-import { Transform } from 'class-transformer';
-import { MFADeviceMethod, MFAMethod } from '../enums/mfa-method.enum';
-
-/**
- * DTO for updating user attributes
- *
- * Security:
- * - All fields validated against DB constraints
- * - Input sanitization applied automatically
- * - Email uniqueness checked in service layer
- * - Phone uniqueness checked in service layer
- * - Username uniqueness checked in service layer
- *
- * @example
- * ```typescript
- * const updateData: UserUpdateDTO = {
- *   firstName: 'John',
- *   lastName: 'Doe',
- *   email: 'john.doe@example.com',
- *   phone: '+61444567890'
- * };
- * ```
- */
-export class UserUpdateDTO {
-  /**
-   * Optional username update
-   *
-   * Validation:
-   * - 3-50 characters
-   * - Alphanumeric, underscores, and hyphens only
-   * - Max 255 characters (DB limit)
-   * - Uniqueness checked in service layer
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Case preserved (username can be case-sensitive per config)
-   */
-  @IsOptional()
-  @IsString({ message: 'Username must be a string' })
-  @MinLength(3, { message: 'Username must be at least 3 characters' })
-  @MaxLength(255, { message: 'Username must not exceed 255 characters' })
-  @Matches(/^[a-zA-Z0-9_-]+$/, {
-    message: 'Username can only contain letters, numbers, underscores, and hyphens',
-  })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  username?: string;
-
-  /**
-   * Optional first name update
-   *
-   * Validation:
-   * - 1-100 characters
-   * - Letters, spaces, hyphens, and apostrophes only
-   * - Max 100 characters (DB limit)
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Title case preserved
-   */
-  @IsOptional()
-  @IsString({ message: 'First name must be a string' })
-  @MinLength(1, { message: 'First name must be at least 1 character' })
-  @MaxLength(100, { message: 'First name must not exceed 100 characters' })
-  @Matches(/^[a-zA-Z\s\-']+$/, {
-    message: 'First name can only contain letters, spaces, hyphens, and apostrophes',
-  })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  firstName?: string;
-
-  /**
-   * Optional last name update
-   *
-   * Validation:
-   * - 1-100 characters
-   * - Letters, spaces, hyphens, and apostrophes only
-   * - Max 100 characters (DB limit)
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Title case preserved
-   */
-  @IsOptional()
-  @IsString({ message: 'Last name must be a string' })
-  @MinLength(1, { message: 'Last name must be at least 1 character' })
-  @MaxLength(100, { message: 'Last name must not exceed 100 characters' })
-  @Matches(/^[a-zA-Z\s\-']+$/, {
-    message: 'Last name can only contain letters, spaces, hyphens, and apostrophes',
-  })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  lastName?: string;
-
-  /**
-   * Optional email address update
-   *
-   * Validation:
-   * - Valid email format (RFC 5322)
-   * - Max 255 characters (matches DB limit)
-   * - Uniqueness checked in service layer
-   *
-   * Sanitization:
-   * - Trimmed and lowercased
-   */
-  @IsOptional()
-  @IsEmail({}, { message: 'Invalid email format' })
-  @MaxLength(255, { message: 'Email must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  email?: string;
-
-  /**
-   * Optional phone number update
-   *
-   * Validation:
-   * - E.164 format (international standard)
-   * - MUST start with + (required for security)
-   * - Max 20 characters (DB limit)
-   * - Uniqueness checked in service layer
-   *
-   * Sanitization:
-   * - Whitespace removed
-   * - Only digits and leading + preserved
-   *
-   * Security:
-   * - Strict E.164 validation prevents SQL injection
-   * - Max length prevents oversized inputs
-   */
-  @IsOptional()
-  @IsString({ message: 'Phone must be a string' })
-  @MaxLength(20, { message: 'Phone must not exceed 20 characters' })
-  @Matches(/^\+[1-9]\d{1,14}$/, {
-    message: 'Phone must be in E.164 format with + prefix (e.g., +14155552671)',
-  })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      // Remove all whitespace and keep only digits and +
-      return value.replace(/\s/g, '');
-    }
-    return value;
-  })
-  phone?: string;
-
-  /**
-   * Optional metadata update (custom fields)
-   *
-   * Security:
-   * - Validated in service layer if used
-   * - Max depth/size limits should be enforced
-   * - Existing metadata merged with new values
-   */
-  @IsOptional()
-  metadata?: Record<string, unknown>;
-
-  /**
-   * Optional preferred MFA method
-   *
-   * Sets the user's preferred MFA method for authentication.
-   * Must be one of the MFA device methods the user has configured.
-   *
-   * Validation:
-   * - Must be one of: totp, sms, email, passkey
-   * - Max 50 characters (matches typical method name length)
-   *
-   * @example
-   * ```typescript
-   * await authService.updateUserAttributes(userId, {
-   *   preferredMfaMethod: 'totp'
-   * });
-   * ```
-   */
-  @IsOptional()
-  @IsEnum([MFAMethod.TOTP, MFAMethod.SMS, MFAMethod.EMAIL, MFAMethod.PASSKEY], {
-    message: 'Preferred MFA method must be one of: totp, sms, email, passkey',
-  })
-  @MaxLength(50, { message: 'Preferred MFA method must not exceed 50 characters' })
-  preferredMfaMethod?: MFADeviceMethod;
-
-  /**
-   * Optional flag to retain verification status when updating email/phone
-   *
-   * When true:
-   * - Email verification status is preserved when email is updated
-   * - Phone verification status is preserved when phone is updated
-   * - Useful when verification was done externally or outside nauth-toolkit
-   *
-   * When false or undefined (default):
-   * - Email verification is reset to false when email is updated
-   * - Phone verification is reset to false when phone is updated
-   * - User must re-verify the new email/phone
-   *
-   * @example
-   * ```typescript
-   * // Update email but keep verification status (external verification)
-   * await authService.updateUserAttributes(userId, {
-   *   email: 'new@example.com',
-   *   retainVerification: true
-   * });
-   * ```
-   */
-  @IsOptional()
-  @IsBoolean({ message: 'retainVerification must be a boolean' })
-  retainVerification?: boolean;
-}

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

@@ -1,313 +0,0 @@
-import {
-  IsEmail,
-  IsString,
-  IsNumberString,
-  IsUrl,
-  MaxLength,
-  Length,
-  Matches,
-  IsBoolean,
-  IsOptional,
-  IsUUID,
-  IsInt,
-  Min,
-} from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * DTO for verifying email with code (6-digit OTP)
- *
- * Security:
- * - Email must be valid format and match DB limits
- * - Code must be exactly 6 digits (no more, no less)
- * - All fields are required (no optional fields to prevent attacks)
- * - Input sanitization applied automatically
- */
-export class VerifyEmailWithCodeDTO {
-  /**
-   * User's email address
-   * Must match the email used during signup
-   *
-   * Validation:
-   * - Valid email format (RFC 5322)
-   * - Max 255 characters (matches DB column limit)
-   * - Automatically trimmed and lowercased
-   *
-   * Sanitization:
-   * - Removes leading/trailing whitespace
-   * - Converts to lowercase for case-insensitive matching
-   */
-  @IsEmail({}, { message: 'Invalid email format' })
-  @MaxLength(255, { message: 'Email must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  email!: string;
-
-  /**
-   * 6-digit verification code from email
-   *
-   * Validation:
-   * - Must be numeric string (digits only)
-   * - Exactly 6 characters long
-   * - Fixed length prevents timing attacks
-   *
-   * Sanitization:
-   * - Removes all whitespace (users might copy "123 456")
-   * - Removes non-digit characters
-   */
-  @IsNumberString({}, { message: 'Verification code must contain only digits' })
-  @MaxLength(6, { message: 'Verification code must be exactly 6 digits' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      // Remove all whitespace and non-digit characters, then validate length
-      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 verifying email with URL token
- *
- * Security:
- * - Token must be valid hex format
- * - Exact length enforced (64 chars = 32 bytes SHA-256 hash)
- * - No SQL injection or XSS possible
- * - Input sanitization prevents malformed tokens
- */
-export class VerifyEmailWithTokenDTO {
-  /**
-   * Verification token from email link
-   *
-   * Validation:
-   * - Exactly 64 hexadecimal characters (SHA-256 hash output)
-   * - Only 0-9 and a-f characters allowed
-   * - Case-insensitive
-   *
-   * Sanitization:
-   * - Removes whitespace
-   * - Converts to lowercase for consistent hashing
-   */
-  @IsString({ message: 'Token must be a string' })
-  @Length(64, 64, { message: 'Invalid token format' })
-  @Matches(/^[a-f0-9]{64}$/i, {
-    message: 'Token must be a valid hexadecimal string',
-  })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  token!: string;
-}
-
-/**
- * DTO for sending a verification email
- *
- * Security:
- * - User sub validated as UUID v4
- * - BaseURL validated as max length
- * - Skip flag is boolean (prevents injection)
- */
-export class SendVerificationEmailDTO {
-  /**
-   * 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;
-
-  /**
-   * Base URL for verification link (optional)
-   *
-   * Validation:
-   * - Must be valid URL format (http:// or https://)
-   * - Max 2048 characters (typical URL length limit)
-   * - Optional field
-   *
-   * Sanitization:
-   * - Trimmed
-   */
-  @IsOptional()
-  @IsUrl(
-    { require_protocol: true, protocols: ['http', 'https'] },
-    { message: 'Base URL must be a valid URL with http:// or https://' },
-  )
-  @MaxLength(2048, { message: 'Base URL must not exceed 2048 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  baseUrl?: string;
-
-  /**
-   * Skip the "already verified" check
-   * Used for MFA contexts where codes are needed even if email is verified
-   *
-   * Validation:
-   * - Must be boolean
-   * - Optional (defaults to false)
-   */
-  @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 like password reset)
-   */
-  @IsOptional()
-  @IsInt({ message: 'challengeSessionId must be an integer' })
-  @Min(1, { message: 'challengeSessionId must be a positive integer' })
-  challengeSessionId?: number;
-}
-
-/**
- * Response DTO for sendVerificationEmail
- */
-export class SendVerificationEmailResponseDTO {
-  /**
-   * Verification token ID (internal integer)
-   */
-  tokenId!: number;
-}
-
-/**
- * DTO for requesting a verification email resend
- *
- * Supports both overload patterns:
- * 1. Resend by user sub (string)
- * 2. Resend by email address (object with email property)
- *
- * Security:
- * - Either sub or email must be provided (conditional validation)
- * - Rate limiting applied in service layer
- * - Input sanitization prevents abuse
- */
-export class ResendVerificationEmailDTO {
-  /**
-   * User identifier (UUID v4) - optional if email provided
-   *
-   * Validation:
-   * - Must be valid UUID v4 format if provided
-   * - Required if email 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 email address - optional if sub provided
-   *
-   * Validation:
-   * - Valid email format if provided
-   * - Max 255 characters (DB limit)
-   * - Required if sub is not provided
-   *
-   * Sanitization:
-   * - Trimmed and lowercased
-   */
-  @IsOptional()
-  @IsEmail({}, { message: 'Invalid email format' })
-  @MaxLength(255, { message: 'Email must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  email?: string;
-
-  /**
-   * Base URL for verification link (optional)
-   *
-   * Validation:
-   * - Must be valid URL format (http:// or https://)
-   * - Max 2048 characters
-   * - Optional field
-   *
-   * Sanitization:
-   * - Trimmed
-   */
-  @IsOptional()
-  @IsUrl(
-    { require_protocol: true, protocols: ['http', 'https'] },
-    { message: 'Base URL must be a valid URL with http:// or https://' },
-  )
-  @MaxLength(2048, { message: 'Base URL must not exceed 2048 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  baseUrl?: string;
-}
-
-/**
- * Response DTO for resendVerificationEmail
- */
-export class ResendVerificationEmailResponseDTO {
-  /**
-   * Verification token ID (internal integer)
-   */
-  tokenId!: number;
-}
-
-/**
- * Response DTO for verifyEmailWithCode and verifyEmailWithToken
- */
-export class VerifyEmailResponseDTO {
-  /**
-   * Success message
-   */
-  message!: string;
-}