@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/dto/login.dto.ts

@@ -1,95 +0,0 @@
-import { IsString, MinLength, MaxLength, IsOptional } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * DTO for user login with security-focused validation
- *
- * Security:
- * - Identifier validated (email, username, or phone)
- * - Password length enforced
- * - Input sanitization applied
- * - DeviceId validated if provided
- */
-export class LoginDTO {
-  /**
-   * Login identifier (email, username, or phone)
-   *
-   * Validation:
-   * - At least 1 character
-   * - Max 255 characters (prevents attacks)
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased if it looks like email
-   */
-  @IsString({ message: 'Identifier must be a string' })
-  @MinLength(1, { message: 'Identifier is required' })
-  @MaxLength(255, { message: 'Identifier must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      const trimmed = value.trim();
-      // If it contains @, treat as email and lowercase
-      if (trimmed.includes('@')) {
-        return trimmed.toLowerCase();
-      }
-      return trimmed;
-    }
-    return value;
-  })
-  identifier!: string; // email, username, or phone
-
-  /**
-   * User password
-   *
-   * Validation:
-   * - At least 1 character (lenient for login)
-   * - Max 128 characters (prevents DoS)
-   *
-   * Note: NOT trimmed (passwords can have spaces)
-   */
-  @IsString({ message: 'Password must be a string' })
-  @MinLength(1, { message: 'Password is required' })
-  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
-  password!: string;
-
-  /**
-   * Optional device name for session identification
-   *
-   * Validation:
-   * - Max 255 characters (matches DB constraint: varchar(255))
-   *
-   * Sanitization:
-   * - Trimmed
-   */
-  @IsOptional()
-  @IsString({ message: 'DeviceName must be a string' })
-  @MaxLength(255, { message: 'DeviceName must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  deviceName?: string;
-
-  /**
-   * Optional device type
-   *
-   * Validation:
-   * - Must be one of: mobile, desktop, tablet
-   * - Max 50 characters (matches DB constraint: varchar(50))
-   *
-   * Sanitization:
-   * - Trimmed and lowercased
-   */
-  @IsOptional()
-  @IsString({ message: 'DeviceType must be a string' })
-  @MaxLength(50, { message: 'DeviceType must not exceed 50 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  deviceType?: 'mobile' | 'desktop' | 'tablet';
-}

package/src/dto/logout-all-response.dto.ts

@@ -1,24 +0,0 @@
-/**
- * Logout All Response DTO
- *
- * Response DTO for logging out from all sessions.
- * No validators needed - this is generated internally by the library.
- *
- * @example
- * ```typescript
- * const result = await authService.logoutAll({ sub: 'user-uuid' });
- * // Returns: { revokedCount: 5 }
- * ```
- */
-
-/**
- * Response DTO for logout all sessions
- */
-export class LogoutAllResponseDTO {
-  /**
-   * Number of sessions revoked
-   *
-   * @example 5
-   */
-  revokedCount!: number;
-}

package/src/dto/logout-all.dto.ts

@@ -1,65 +0,0 @@
-/**
- * Logout All DTO
- *
- * Request DTO for logging out a user from all sessions (global logout).
- *
- * Security:
- * - User sub validated (UUID)
- * - Prevents unauthorized logout attempts
- *
- * @example
- * ```typescript
- * const result = await authService.logoutAll({
- *   sub: 'user-uuid'
- * });
- * ```
- */
-
-import { IsUUID, IsOptional, IsBoolean } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * Request DTO for logout all sessions
- */
-export class LogoutAllDTO {
-  /**
-   * 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;
-
-  /**
-   * Whether to also forget/revoke all trusted devices
-   *
-   * If true, all trusted devices for this user will be revoked,
-   * requiring MFA on next login from any device.
-   *
-   * Default: false (devices remain trusted)
-   *
-   * @example false
-   */
-  @IsOptional()
-  @IsBoolean()
-  @Transform(({ value }) => {
-    if (value === 'true' || value === '1') return true;
-    if (value === 'false' || value === '0') return false;
-    return value;
-  })
-  forgetDevices?: boolean;
-}

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

@@ -1,25 +0,0 @@
-/**
- * Logout Response DTO
- *
- * Response DTO for logging out from a specific session.
- * No validators needed - this is generated internally by the library.
- *
- * @example
- * ```typescript
- * await authService.logout({ forgetMe: false });
- * // Returns: { success: true }
- * ```
- */
-
-/**
- * Response DTO for logout
- */
-export class LogoutResponseDTO {
-  /**
-   * Success indicator
-   * Always true on successful logout
-   *
-   * @example true
-   */
-  success!: boolean;
-}

package/src/dto/logout.dto.ts

@@ -1,64 +0,0 @@
-/**
- * Logout DTO
- *
- * Request DTO for logging out a user from the current authenticated session.
- *
- * Security:
- * - Session ID is automatically extracted from JWT token context (via ClientInfoService)
- * - User sub validated (UUID) - optional, for additional verification
- * - Prevents unauthorized logout attempts
- *
- * @example
- * ```typescript
- * await authService.logout({
- *   forgetMe: false
- * });
- * ```
- */
-
-import { IsOptional, IsBoolean, IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * Request DTO for logout
- */
-export class LogoutDTO {
-  /**
-   * User's unique identifier (UUID v4) - Optional
-   *
-   * If provided, validates that the authenticated user matches this sub.
-   * Session ID is automatically extracted from JWT token context.
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format if provided
-   * - Matches DB constraint: char(36) or uuid
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  @IsOptional()
-  @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;
-
-  /**
-   * If true, also removes trusted device
-   *
-   * Validation:
-   * - Must be a boolean if present
-   * - Default: false
-   *
-   * @example false
-   */
-  @IsOptional()
-  @IsBoolean({ message: 'forgetMe must be a boolean' })
-  forgetMe?: boolean;
-}

package/src/dto/refresh-token.dto.ts

@@ -1,36 +0,0 @@
-import { IsString, MinLength, MaxLength } from 'class-validator';
-
-/**
- * Refresh Token DTO
- *
- * Used for refreshing access tokens with a valid refresh token.
- *
- * Security:
- * - Token length validated (prevents DoS)
- * - JWT tokens can be long, but we validate input length
- * - Token is validated in service layer for format and signature
- *
- * @example
- * ```typescript
- * POST /auth/refresh
- * {
- *   "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
- * }
- * ```
- */
-export class RefreshTokenDTO {
-  /**
-   * JWT refresh token
-   *
-   * Validation:
-   * - Must be a string
-   * - Min 10 characters (minimum valid JWT length)
-   * - Max 2048 characters (prevents DoS, typical JWT is 200-500 chars)
-   *
-   * Note: Token format and signature validated in service layer
-   */
-  @IsString({ message: 'Refresh token must be a string' })
-  @MinLength(10, { message: 'Refresh token is required' })
-  @MaxLength(2048, { message: 'Refresh token must not exceed 2048 characters' })
-  refreshToken!: string;
-}

package/src/dto/remove-devices.dto.ts

@@ -1,85 +0,0 @@
-/**
- * DTO for removing MFA devices
- *
- * Used to remove all MFA devices of a specific method type for a user.
- * Automatically disables MFA if this was the last device.
- *
- * @example
- * ```typescript
- * const result = await mfaService.removeDevices({
- *   userSub: 'user-uuid',
- *   methodType: 'totp'
- * });
- * ```
- */
-
-import { IsEnum, IsString, IsUUID, MaxLength } from 'class-validator';
-import { Transform } from 'class-transformer';
-import { MFAMethod } from '../enums/mfa-method.enum';
-
-/**
- * DTO for removing MFA devices
- */
-export class RemoveDevicesDTO {
-  /**
-   * 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;
-  })
-  userSub!: string;
-
-  /**
-   * MFA method type to remove
-   *
-   * Validation:
-   * - Must be one of: totp, sms, email, passkey
-   * - Max 50 characters
-   *
-   * Sanitization:
-   * - Trimmed and lowercased
-   *
-   * @example "totp"
-   */
-  @IsString({ message: 'Method type must be a string' })
-  @IsEnum([MFAMethod.TOTP, MFAMethod.SMS, MFAMethod.EMAIL, MFAMethod.PASSKEY], {
-    message: 'Method type must be one of: totp, sms, email, passkey',
-  })
-  @MaxLength(50, { message: 'Method type must not exceed 50 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  methodType!: string;
-}
-
-/**
- * Response DTO for removing devices
- */
-export class RemoveDevicesResponseDTO {
-  /**
-   * Number of devices deleted
-   */
-  deletedCount!: number;
-
-  /**
-   * Whether MFA was disabled (if this was the last device)
-   */
-  mfaDisabled!: boolean;
-}

package/src/dto/resend-code-response.dto.ts

@@ -1,32 +0,0 @@
-/**
- * Resend Code Response DTO
- *
- * Response DTO for resending verification codes.
- * No validators needed - this is generated internally by the library.
- *
- * Security:
- * - Email/phone masked for privacy
- * - Only shows destination, not full details
- *
- * @example
- * ```typescript
- * const result = await authService.resendCode({ session: 'session-uuid' });
- * // Returns: { destination: 'u***r@example.com' }
- * ```
- */
-
-/**
- * Response DTO for resend code
- */
-export class ResendCodeResponseDTO {
-  /**
-   * Masked destination where code was sent
-   *
-   * Format:
-   * - Email: "u***r@example.com"
-   * - Phone: "+1***5678"
-   *
-   * @example "u***r@example.com"
-   */
-  destination!: string;
-}

package/src/dto/resend-code.dto.ts

@@ -1,51 +0,0 @@
-/**
- * DTO for resending verification code
- *
- * Used to resend email/SMS verification codes during challenges:
- * - Email verification (VERIFY_EMAIL)
- * - Phone verification (VERIFY_PHONE)
- * - MFA verification (MFA_REQUIRED with SMS/Email method)
- *
- * Security:
- * - Session token length limited (prevents DoS)
- * - Rate limiting enforced in service layer
- *
- * @example
- * ```typescript
- * const result = await authService.resendCode({
- *   session: 'challenge-session-token'
- * });
- * // Returns: { destination: 'u***r@example.com' }
- * ```
- */
-
-import { IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * DTO for resending verification code
- */
-export class ResendCodeDTO {
-  /**
-   * Challenge session token (UUID v4)
-   *
-   * Validation:
-   * - Must be a valid UUID v4 format
-   * - Generated using randomUUID() in challenge service
-   * - Matches DB constraint: varchar(255) but UUID format enforced
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased for consistency
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  @IsUUID('4', { message: 'Session token must be a valid UUID v4 format' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim().toLowerCase();
-    }
-    return value;
-  })
-  session!: string;
-}

package/src/dto/reset-password.dto.ts

@@ -1,115 +0,0 @@
-import { IsString, MinLength, MaxLength, IsNotEmpty } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * Reset Password Request DTO
- *
- * Used to request a password reset token via email or phone.
- *
- * Security:
- * - Identifier validated (email or phone)
- * - Input sanitization applied
- *
- * @example
- * ```typescript
- * POST /auth/reset-password/request
- * {
- *   "identifier": "user@example.com"
- * }
- * ```
- */
-export class ResetPasswordRequestDTO {
-  /**
-   * User identifier (email or phone)
-   *
-   * Validation:
-   * - Must be a string
-   * - Min 1 character
-   * - Max 255 characters (matches DB constraint for email)
-   *
-   * Sanitization:
-   * - Trimmed
-   * - Lowercased if email format detected
-   */
-  @IsString({ message: 'Identifier must be a string' })
-  @IsNotEmpty({ message: 'Identifier is required' })
-  @MinLength(1, { message: 'Identifier is required' })
-  @MaxLength(255, { message: 'Identifier must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      const trimmed = value.trim();
-      // If it contains @, treat as email and lowercase
-      if (trimmed.includes('@')) {
-        return trimmed.toLowerCase();
-      }
-      return trimmed;
-    }
-    return value;
-  })
-  identifier!: string; // email or phone
-}
-
-/**
- * Reset Password DTO
- *
- * Used to reset password with a valid reset token.
- *
- * Security:
- * - Token length validated (matches DB constraint: varchar(255))
- * - Password strength enforced (8-128 chars)
- * - Token format validated in service layer
- *
- * @example
- * ```typescript
- * POST /auth/reset-password
- * {
- *   "token": "reset-token-from-email",
- *   "newPassword": "NewSecurePassword123!"
- * }
- * ```
- */
-export class ResetPasswordDTO {
-  /**
-   * Password reset token from email
-   *
-   * Validation:
-   * - Must be a string
-   * - Min 1 character (prevents empty strings)
-   * - Max 255 characters (matches DB constraint: varchar(255))
-   *
-   * Sanitization:
-   * - Trimmed
-   *
-   * Note: Token format and validity validated in service layer
-   */
-  @IsString({ message: 'Token must be a string' })
-  @IsNotEmpty({ message: 'Token is required' })
-  @MinLength(1, { message: 'Token is required' })
-  @MaxLength(255, { message: 'Token must not exceed 255 characters' })
-  @Transform(({ value }) => {
-    if (typeof value === 'string') {
-      return value.trim();
-    }
-    return value;
-  })
-  token!: string;
-
-  /**
-   * New password
-   *
-   * Validation:
-   * - Must be a string
-   * - Min 8 characters (security requirement)
-   * - Max 128 characters (prevents DoS via bcrypt)
-   *
-   * Note: NOT trimmed (passwords can have leading/trailing spaces)
-   * Additional checks in service layer:
-   * - Password strength (if configured)
-   * - Password history (prevent reuse)
-   */
-  @IsString({ message: 'New password must be a string' })
-  @IsNotEmpty({ message: 'New password is required' })
-  @MinLength(8, { message: 'Password must be at least 8 characters' })
-  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
-  newPassword!: string;
-}