@nauth-toolkit/core 0.1.0

package/src/dto/get-setup-data-response.dto.ts

@@ -0,0 +1,31 @@
+/**
+ * Response DTO for getting MFA setup data
+ *
+ * Used to return method-specific setup data during MFA enrollment.
+ * Structure varies by method (TOTP returns QR code, Passkey returns options, etc.).
+ *
+ * @example
+ * ```typescript
+ * const setupData = await mfaService.getSetupData({
+ *   session: 'challenge-session-token',
+ *   method: 'totp'
+ * });
+ * // Returns: { secret: '...', qrCode: '...', manualEntryKey: '...' }
+ * ```
+ */
+
+/**
+ * Response DTO for setup data
+ */
+export class GetSetupDataResponseDTO {
+  /**
+   * Provider-specific setup data
+   *
+   * Structure varies by method:
+   * - TOTP: { secret: string, qrCode: string, manualEntryKey: string }
+   * - SMS: { maskedPhone: string }
+   * - Email: { maskedEmail: string }
+   * - Passkey: WebAuthn registration options
+   */
+  setupData!: Record<string, unknown>;
+}

package/src/dto/get-setup-data.dto.ts

@@ -0,0 +1,75 @@
+/**
+ * DTO for requesting MFA setup data
+ *
+ * Used to get method-specific setup information during MFA enrollment.
+ * For example, TOTP setup returns QR code and secret.
+ *
+ * Security:
+ * - Session token length limited (prevents DoS)
+ * - Method validated against enum (prevents injection)
+ *
+ * @example
+ * ```typescript
+ * const setupData = await authService.getSetupData({
+ *   session: 'challenge-session-token',
+ *   method: 'totp'
+ * });
+ * // Returns: { secret: '...', qrCode: '...' }
+ * ```
+ */
+
+import { IsEnum, IsUUID, IsOptional, IsObject } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { MFAMethod } from '../enums/mfa-method.enum';
+
+/**
+ * DTO for getting MFA setup data
+ */
+export class GetSetupDataDTO {
+  /**
+   * 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;
+
+  /**
+   * MFA method to set up
+   *
+   * Validation:
+   * - Must be one of: sms, email, totp, passkey
+   */
+  @IsEnum([MFAMethod.SMS, MFAMethod.EMAIL, MFAMethod.TOTP, MFAMethod.PASSKEY], {
+    message: 'Method must be one of: sms, email, totp, passkey',
+  })
+  method!: MFAMethod;
+
+  /**
+   * Optional provider-specific setup data
+   *
+   * Validation:
+   * - Must be an object if provided
+   * - Structure validated by MFA provider services
+   *
+   * @example { phoneNumber: '+1234567890' } for SMS
+   */
+  @IsOptional()
+  @IsObject({ message: 'Setup data must be an object' })
+  setupData?: Record<string, unknown>;
+}

package/src/dto/get-suspicious-activity.dto.ts

@@ -0,0 +1,42 @@
+import { IAuthAudit } from '../interfaces/entities.interface';
+
+/**
+ * Request DTO for getting suspicious activity
+ *
+ * @example
+ * ```typescript
+ * // Get all suspicious activity
+ * const result = await auditService.getSuspiciousActivity({});
+ *
+ * // Get suspicious activity for specific user
+ * const result = await auditService.getSuspiciousActivity({
+ *   userSub: 'user-uuid',
+ *   limit: 50,
+ * });
+ * ```
+ */
+export class GetSuspiciousActivityDTO {
+  /**
+   * Optional user identifier to filter by specific user
+   *
+   * If not provided, returns suspicious activity for all users.
+   */
+  userSub?: string;
+
+  /**
+   * Maximum number of records to return
+   *
+   * @default 100
+   */
+  limit?: number;
+}
+
+/**
+ * Response DTO for suspicious activity
+ */
+export class GetSuspiciousActivityResponseDTO {
+  /**
+   * Array of suspicious audit events
+   */
+  data!: IAuthAudit[];
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Response DTO for getting user agent
+ *
+ * Used to return just the user agent string from the current request context.
+ *
+ * @example
+ * ```typescript
+ * const result = await clientInfoService.getUserAgent();
+ * // Returns: { userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)...' }
+ * ```
+ */
+
+/**
+ * Response DTO for user agent
+ */
+export class GetUserAgentResponseDTO {
+  /**
+   * User agent string from the request
+   *
+   * Returns 'unknown' if called outside request context.
+   */
+  userAgent!: string;
+}

package/src/dto/get-user-auth-history.dto.ts

@@ -0,0 +1,95 @@
+import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+import { AuthAuditEventStatus } from '../entities/auth-audit.entity';
+import { IAuthAudit } from '../interfaces/entities.interface';
+
+/**
+ * Request DTO for getting user authentication history
+ *
+ * @example
+ * ```typescript
+ * const result = await auditService.getUserAuthHistory({
+ *   userSub: 'user-uuid',
+ *   page: 1,
+ *   limit: 50,
+ *   eventTypes: [AuthAuditEventType.LOGIN_SUCCESS],
+ *   startDate: new Date('2025-01-01'),
+ * });
+ * ```
+ */
+export class GetUserAuthHistoryDTO {
+  /**
+   * External user identifier (UUID)
+   *
+   * The service will automatically resolve this to the internal userId
+   * for efficient database queries.
+   */
+  userSub!: string;
+
+  /**
+   * Page number (1-indexed)
+   *
+   * @default 1
+   */
+  page?: number;
+
+  /**
+   * Number of records per page
+   *
+   * @default 50
+   */
+  limit?: number;
+
+  /**
+   * Filter events from this date onwards
+   */
+  startDate?: Date;
+
+  /**
+   * Filter events up to this date
+   */
+  endDate?: Date;
+
+  /**
+   * Filter by specific event types
+   *
+   * If provided, only events matching these types will be returned.
+   */
+  eventTypes?: AuthAuditEventType[];
+
+  /**
+   * Filter by event status
+   *
+   * If provided, only events matching these statuses will be returned.
+   */
+  eventStatus?: AuthAuditEventStatus[];
+}
+
+/**
+ * Response DTO for paginated user authentication history
+ */
+export class GetUserAuthHistoryResponseDTO {
+  /**
+   * Array of audit records
+   */
+  data!: IAuthAudit[];
+
+  /**
+   * Total number of records matching the query
+   */
+  total!: number;
+
+  /**
+   * Current page number
+   */
+  page!: number;
+
+  /**
+   * Number of records per page
+   */
+  limit!: number;
+
+  /**
+   * Total number of pages
+   */
+  totalPages!: number;
+}

package/src/dto/get-user-by-email.dto.ts

@@ -0,0 +1,61 @@
+/**
+ * Get User By Email DTO
+ *
+ * Request DTO for retrieving a user by email address.
+ *
+ * Security:
+ * - Email format validated
+ * - Max length enforced
+ *
+ * @example
+ * ```typescript
+ * const user = await authService.getUserByEmail({
+ *   email: 'user@example.com',
+ *   requireEmailVerified: true
+ * });
+ * ```
+ */
+
+import { IsEmail, IsOptional, IsBoolean, MaxLength } from 'class-validator';
+import { Transform } from 'class-transformer';
+
+/**
+ * Request DTO for getting user by email
+ */
+export class GetUserByEmailDTO {
+  /**
+   * Email address to search for
+   *
+   * Validation:
+   * - Must be a valid email format
+   * - Max 255 characters (matches DB constraint)
+   *
+   * Sanitization:
+   * - Trimmed
+   * - Lowercased for consistency
+   *
+   * @example "user@example.com"
+   */
+  @IsEmail({}, { message: 'Email must be a valid 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;
+
+  /**
+   * Only return user if email is verified
+   *
+   * Validation:
+   * - Must be a boolean if present
+   * - Default: false
+   *
+   * @example true
+   */
+  @IsOptional()
+  @IsBoolean({ message: 'requireEmailVerified must be a boolean' })
+  requireEmailVerified?: boolean;
+}

package/src/dto/get-user-by-id.dto.ts

@@ -0,0 +1,46 @@
+/**
+ * Get User By ID DTO
+ *
+ * Request DTO for retrieving a user by their unique identifier (sub).
+ *
+ * Security:
+ * - UUID format validated
+ * - Prevents injection attacks
+ *
+ * @example
+ * ```typescript
+ * const user = await authService.getUserById({
+ *   sub: 'a21b654c-2746-4168-acee-c175083a65cd'
+ * });
+ * ```
+ */
+
+import { IsUUID } from 'class-validator';
+import { Transform } from 'class-transformer';
+
+/**
+ * Request DTO for getting user by ID
+ */
+export class GetUserByIdDTO {
+  /**
+   * 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;
+}

package/src/dto/get-user-devices.dto.ts

@@ -0,0 +1,53 @@
+/**
+ * DTO for getting user MFA devices
+ *
+ * Used to retrieve all MFA devices configured for a user.
+ *
+ * @example
+ * ```typescript
+ * const devices = await mfaService.getUserDevices({
+ *   sub: 'user-uuid'
+ * });
+ * ```
+ */
+
+import { IsUUID } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { IMFADevice } from '../interfaces/entities.interface';
+
+/**
+ * DTO for getting user MFA devices
+ */
+export class GetUserDevicesDTO {
+  /**
+   * 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;
+}
+
+/**
+ * Response DTO for user MFA devices
+ */
+export class GetUserDevicesResponseDTO {
+  /**
+   * Array of user's MFA devices
+   */
+  devices!: IMFADevice[];
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Get User Response DTO
+ *
+ * Response DTO for user retrieval operations.
+ *
+ * Note: Methods like getUserById and getUserByEmail return UserResponseDto | null directly.
+ * This file exists for type consistency but UserResponseDto is used directly.
+ *
+ * @example
+ * ```typescript
+ * const user = await authService.getUserById({ sub: 'user-uuid' });
+ * // Returns: UserResponseDto | null
+ * ```
+ */
+
+// Re-export UserResponseDto for consistency
+export { UserResponseDto as GetUserResponseDTO } from './user-response.dto';

package/src/dto/has-provider.dto.ts

@@ -0,0 +1,56 @@
+/**
+ * DTO for checking if MFA provider is registered
+ *
+ * Used to check if a specific MFA provider is registered and available.
+ *
+ * @example
+ * ```typescript
+ * const hasTotp = await mfaService.hasProvider({
+ *   methodName: 'totp'
+ * });
+ * ```
+ */
+
+import { IsEnum, IsString, MaxLength } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { MFAMethod } from '../enums/mfa-method.enum';
+
+/**
+ * DTO for checking if MFA provider is registered
+ */
+export class HasProviderDTO {
+  /**
+   * Provider method name
+   *
+   * Validation:
+   * - Must be one of: totp, sms, email, passkey
+   * - Max 50 characters
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   *
+   * @example "totp"
+   */
+  @IsString({ message: 'Method name must be a string' })
+  @IsEnum(MFAMethod, {
+    message: 'Method name must be one of: totp, sms, email, passkey',
+  })
+  @MaxLength(50, { message: 'Method name must not exceed 50 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  methodName!: string;
+}
+
+/**
+ * Response DTO for has provider check
+ */
+export class HasProviderResponseDTO {
+  /**
+   * Whether provider is registered
+   */
+  hasProvider!: boolean;
+}

package/src/dto/index.ts

@@ -0,0 +1,57 @@
+// Core Auth DTOs
+export * from './signup.dto';
+export * from './login.dto';
+export * from './change-password.dto';
+export * from './change-password-request.dto';
+export * from './change-password-response.dto';
+export * from './user-response.dto';
+export * from './user-update.dto';
+export * from './update-user-attributes-request.dto';
+export * from './verify-email.dto';
+export * from './verify-phone.dto';
+export * from './verify-phone-by-sub.dto';
+export * from './reset-password.dto';
+export * from './refresh-token.dto';
+export * from './auth-response.dto';
+export * from './auth-challenge.dto';
+export * from './challenge-response.dto';
+export * from './respond-challenge.dto';
+export * from './get-setup-data.dto';
+export * from './get-setup-data-response.dto';
+export * from './get-challenge-data.dto';
+export * from './get-challenge-data-response.dto';
+export * from './get-available-methods.dto';
+export * from './get-mfa-status.dto';
+export * from './get-user-devices.dto';
+export * from './has-provider.dto';
+export * from './list-providers-response.dto';
+export * from './remove-devices.dto';
+export * from './set-mfa-exemption.dto';
+export * from './set-preferred-method.dto';
+export * from './setup-mfa.dto';
+export * from './verify-mfa-code.dto';
+export * from './get-client-info.dto';
+export * from './get-ip-address-response.dto';
+export * from './get-user-agent-response.dto';
+export * from './get-device-token-response.dto';
+export * from './get-session-id-response.dto';
+export * from './resend-code.dto';
+export * from './resend-code-response.dto';
+export * from './get-user-by-email.dto';
+export * from './get-user-by-id.dto';
+export * from './get-user-response.dto';
+export * from './logout.dto';
+export * from './logout-response.dto';
+export * from './logout-all.dto';
+export * from './logout-all-response.dto';
+export * from './set-must-change-password.dto';
+export * from './set-must-change-password-response.dto';
+// Note: trust-device.dto.ts removed - trustDevice() no longer takes parameters
+export * from './trust-device-response.dto';
+export * from './is-trusted-device-response.dto';
+
+export * from './social-auth.dto';
+
+// Note: Social and MFA DTOs moved to their respective packages
+// - social-login.dto → @nauth-toolkit/social-*
+// - mfa.dto → @nauth-toolkit/mfa-*

package/src/dto/is-trusted-device-response.dto.ts

@@ -0,0 +1,34 @@
+/**
+ * Is Trusted Device Response DTO
+ *
+ * Response DTO for checking if the current device is trusted.
+ * No validators needed - this is generated internally by the library.
+ *
+ * Security:
+ * - Works in both cookies mode (reads from httpOnly cookie) and JSON mode (reads from X-Device-Token header)
+ * - Returns server-validated trusted status
+ * - Does not expose device token value for security
+ *
+ * @example
+ * ```typescript
+ * const result = await authService.isTrustedDevice();
+ * // Returns: { trusted: true }
+ * ```
+ */
+
+/**
+ * Response DTO for checking trusted device status
+ */
+export class IsTrustedDeviceResponseDTO {
+  /**
+   * Whether the current device is trusted
+   *
+   * True if the device has a valid trusted device token and trust has not expired.
+   * False if no device token exists, device token is invalid, or trust has expired.
+   *
+   * @example true
+   */
+  trusted!: boolean;
+}
+
+

package/src/dto/list-providers-response.dto.ts

@@ -0,0 +1,23 @@
+/**
+ * Response DTO for listing MFA providers
+ *
+ * Used to return all registered MFA provider method names.
+ *
+ * @example
+ * ```typescript
+ * const providers = await mfaService.listProviders();
+ * // Returns: { providers: ['totp', 'sms', 'passkey'] }
+ * ```
+ */
+
+/**
+ * Response DTO for listing providers
+ */
+export class ListProvidersResponseDTO {
+  /**
+   * Array of registered provider method names
+   *
+   * @example ['totp', 'sms', 'passkey']
+   */
+  providers!: string[];
+}