Data Transfer Objects (DTOs)

Package: @nauth-toolkit/core Type: Data Transfer Objects

Platform-agnostic request and response DTOs for authentication operations. All DTOs use class-validator decorators for automatic validation.

NestJS

import { SignupDTO, LoginDTO, AuthResponseDTO } from '@nauth-toolkit/nestjs';

Express

import { SignupDTO, LoginDTO, AuthResponseDTO } from '@nauth-toolkit/core';

Fastify

import { SignupDTO, LoginDTO, AuthResponseDTO } from '@nauth-toolkit/core';

Overview

DTOs provide type-safe, validated data structures for all authentication operations. They ensure:

• Type Safety - Full TypeScript support with IntelliSense
• Automatic Validation - class-validator decorators enforce rules
• Framework Integration - NestJS and Express handle validation automatically

note

All DTOs are automatically validated by framework adapters. No manual validation required.

Authentication DTOs

DTO	Description	Documentation
AuthResponseDTO	Unified authentication response	Tokens OR challenge (MFA/verification)
LoginDTO	User login request	Identifier (email/username/phone) and password
LogoutAllDTO	Logout all sessions	Revoke all user sessions
LogoutAllResponseDTO	Logout all response	Count of revoked sessions
LogoutDTO	Logout request	Session termination
LogoutResponseDTO	Logout response	Success confirmation
RefreshTokenDTO	Token refresh request	Refresh token
SignupDTO	User registration request	Email, password, optional username/phone
TrustDeviceResponseDTO	Device trust response	Device trust token
IsTrustedDeviceResponseDTO	Trusted device check response	Whether current device is trusted

Session Management DTOs

DTO	Description	Documentation
GetUserSessionsDTO	Get user sessions	Pagination and filters
GetUserSessionsResponseDTO	Sessions list response	Active sessions with details
LogoutSessionDTO	Logout specific session	Session ID
LogoutSessionResponseDTO	Session logout response	Success confirmation

Admin Operations DTOs

DTO	Description	Documentation
AdminSetPasswordDTO	Admin password reset	Set user password by sub
AdminSignupDTO	Admin user creation	Create user with override capabilities (bypass verification, force password change)
AdminSignupSocialDTO	Admin social user import	Import social users from external platforms (Cognito, Auth0) with social linkage
AdminSignupSocialResponseDTO	Admin social import response	User object and social account confirmation
DeleteUserDTO	Admin user deletion	Hard delete user with complete cascade cleanup
DeleteUserResponseDTO	Admin deletion response	Deletion confirmation with cascade counts
DisableUserDTO	Admin account locking	Permanent account lock with session revocation
DisableUserResponseDTO	Admin lock response	Lock confirmation with revoked session count
EnableUserDTO	Admin account unlocking	Clear lock fields and reset failed attempts
EnableUserResponseDTO	Admin unlock response	Unlock confirmation with updated user status
GetUsersDTO	Admin user listing	Paginated user search with advanced filtering
GetUsersResponseDTO	Admin listing response	User list with pagination metadata
AdminLogoutAllDTO	Admin global logout	Revoke all sessions for a target user
AdminUpdateUserAttributesDTO	Admin user update	Update user profile attributes with required sub
AdminResetPasswordDTO	Admin password reset request	Initiate admin-driven password reset
AdminRevokeSessionDTO	Admin session revoke	Revoke a specific session for a target user
ConfirmAdminResetPasswordDTO	Confirm admin password reset	Code, new password, and session
UpdateVerifiedStatusRequestDTO	Admin verification status	Update email/phone verified flags

Password Management DTOs

DTO	Description	Documentation
ChangePasswordDTO	Change password request	Current and new password
ChangePasswordResponseDTO	Change password response	Success confirmation
ConfirmForgotPasswordDTO	Confirm password reset	Reset code and new password
ForgotPasswordDTO	Forgot password flow	Request reset code
ResetPasswordDTO	Reset password request	Reset token and new password
SetMustChangePasswordDTO	Force password change	Admin operation
SetMustChangePasswordResponseDTO	Force password change response	Success confirmation

Email Verification DTOs

DTO	Description	Documentation
ResendVerificationEmailDTO	Resend verification email	User sub or email
ResendVerificationEmailResponseDTO	Resend email response	Token ID
SendVerificationEmailDTO	Send verification email	User sub and optional base URL
SendVerificationEmailResponseDTO	Send email response	Token ID
VerifyEmailResponseDTO	Verify email response	Success message
VerifyEmailWithCodeDTO	Verify email with code	Email address and 6-digit verification code
VerifyEmailWithTokenDTO	Verify email with token	Verification token from URL

Phone Verification DTOs

DTO	Description	Documentation
ResendVerificationSMSDTO	Resend verification SMS	User sub or phone
ResendVerificationSMSResponseDTO	Resend SMS response	Token ID
SendVerificationSMSDTO	Send verification SMS	User sub
SendVerificationSMSResponseDTO	Send SMS response	Token ID
VerifyPhoneResponseDTO	Verify phone response	Success message
VerifyPhoneWithCodeBySubDTO	Verify phone by sub	User sub and code
VerifyPhoneWithCodeDTO	Verify phone with code	Phone number and code

Challenge Flow DTOs

DTO	Description	Documentation
AuthChallengeDTO	Challenge details	Challenge type enum and parameters
ChallengeResponseData	Challenge response types	TypeScript discriminated union types
GetChallengeDataDTO	Get challenge data	Challenge session token
GetChallengeDataResponseDTO	Challenge data response	Challenge information
RespondChallengeDTO	Respond to challenge	Challenge session and response data
AuthChallengeResponseDTO	Challenge response	Challenge type, session, and parameters

MFA DTOs

DTO	Description	Documentation
AdminGetMFAStatusDTO	Admin get MFA status	Target user sub
AdminGetUserDevicesDTO	Admin get user MFA devices	Target user sub
AdminRemoveDeviceDTO	Admin remove MFA device by ID	Device ID
AdminSetPreferredDeviceDTO	Admin set preferred MFA device	User sub and device ID
GetAvailableMethodsDTO	Get available MFA methods	User sub
GetMFAStatusResponseDTO	MFA status response	Status fields
GetSetupDataDTO	Get MFA setup data	Challenge session and method
GetSetupDataResponseDTO	Setup data response	Provider-specific setup data
GetUserDevicesDTO	Get user MFA devices (self-service)	User from context
RemoveDeviceDTO	Remove MFA device by ID	Device ID
SetMFAExemptionDTO	Set MFA exemption	User sub, exempt flag, reason
SetPreferredDeviceDTO	Set preferred MFA device	Device ID
SetupMFADTO	Setup MFA device	Method name, setup data
VerifyMFACodeDTO	Verify MFA code	Method, code

Social Authentication DTOs

DTO	Description	Documentation
CanSetPasswordDTO	Check if password can be set	User sub
CanSetPasswordResponseDTO	Can set password response	Boolean flag
GetLinkedAccountsDTO	Get linked accounts	User sub
GetLinkedAccountsResponseDTO	Linked accounts response	Array of linked providers
LinkSocialAccountDTO	Link social account	Provider, code, state
LinkSocialAccountResponseDTO	Link account response	Success confirmation
SetPasswordForSocialUserDTO	Set password for social user	User sub and new password
SetPasswordForSocialUserResponseDTO	Set password response	Success confirmation
SocialCallbackFormDTO	OAuth callback form data (POST)	Apple form_post callbacks
SocialCallbackQueryDTO	OAuth callback query params (GET)	Google, Facebook callbacks
SocialExchangeDTO	Exchange social redirect token	One-time exchange token
SocialRedirectCallbackResponseDTO	Callback redirect response	url for @Redirect()
StartSocialRedirectQueryDTO	Start social redirect flow	returnTo, appState, action
StartSocialRedirectResponseDTO	Start redirect response	url for @Redirect()
UnlinkSocialAccountDTO	Unlink social account	User sub and provider
UnlinkSocialAccountResponseDTO	Unlink account response	Success confirmation
VerifyTokenDTO	Verify native social token	Provider, ID token, access token
HandleCallbackDTO	Handle OAuth callback	Provider callback data

User Management DTOs

DTO	Description	Documentation
GetUserByEmailDTO	Get user by email	Email address
GetUserByIdDTO	Get user by ID	User sub (UUID)
UpdateUserAttributesDTO	Update user attributes	User attributes (self-service)
UserResponseDTO	User profile data	User information (excludes sensitive fields)
UserUpdateDTO	User update request	User profile fields

Audit & Client Info DTOs

DTO	Description	Documentation
GetClientInfoDTO	Get client information	No parameters (from context)
GetDeviceTokenResponseDTO	Device token response	Device trust token
GetEventsByTypeDTO	Get events by type	Event type, pagination, date range
GetIpAddressResponseDTO	IP address response	Client IP address
GetRiskAssessmentHistoryDTO	Get risk assessment history	User sub, limit
GetSessionIdResponseDTO	Session ID response	JWT session ID
GetSuspiciousActivityDTO	Get suspicious activity	User sub (optional), limit
GetUserAgentResponseDTO	User agent response	Client user agent
GetUserAuthHistoryDTO	Get auth history	User sub, pagination, filters
GetUserAuthHistoryResponseDTO	Auth history response	Paginated event list
GetEventsByTypeResponseDTO	Events by type response	Filtered event list
GetRiskAssessmentHistoryResponseDTO	Risk assessment response	Risk scores and factors
GetSuspiciousActivityResponseDTO	Suspicious activity response	Flagged events

Token Validation DTOs

DTO	Description	Documentation
ValidateAccessTokenDTO	Validate access token	Token string
ValidateAccessTokenResponseDTO	Validation response	Decoded JWT payload

Error & Utility DTOs

DTO	Description	Documentation
ErrorResponseDTO	Standardized error format	Error code, message, details
HasProviderDTO	Check if provider exists	Provider name
ListProvidersResponseDTO	List providers response	Array of provider names
ResendCodeDTO	Resend verification code	Challenge session
ResendCodeResponseDTO	Resend code response	Success confirmation

Usage

All DTOs are automatically validated by framework adapters:

NestJS

import { Controller, Post, Body } from '@nestjs/common';
import { AuthService, SignupDTO, AuthResponseDTO } from '@nauth-toolkit/nestjs';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('/signup')
  async signup(@Body() dto: SignupDTO): Promise<AuthResponseDTO> {
    // DTO automatically validated by NestJS
    return this.authService.signup(dto);
  }
}

Express

import express from 'express';
import { createNAuth, SignupDTO } from '@nauth-toolkit/core';

const app = express();
const nauth = await createNAuth(config, dataSource);

app.post('/signup', async (req, res) => {
  // DTO automatically validated by Express adapter
  const result = await nauth.authService.signup(req.body as SignupDTO);
  res.json(result);
});

Fastify

import { SignupDTO, LoginDTO, AuthResponseDTO } from '@nauth-toolkit/core';

Validation

All DTOs use class-validator decorators for automatic validation:

• Email - @IsEmail() validates email format
• UUID - @IsUUID('4') validates UUID v4 format
• Phone - @Matches() validates E.164 format
• Length - @Length(), @MinLength(), @MaxLength() enforce string length
• Numbers - @IsNumberString() for numeric strings
• Required - @IsNotEmpty() for required fields
• Optional - @IsOptional() for optional fields

Validation errors are automatically converted to NAuthException with VALIDATION_FAILED code.

Related Documentation

• AuthService - Authentication methods
• MFAService - MFA operations
• SocialAuthService - Social authentication
• NAuthException - Error handling
• Error Handling Guide - Best practices