@nauth-toolkit/core 0.1.0 → 0.1.5

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

@@ -1,136 +0,0 @@
-import { IsNumber, IsString, IsOptional, IsObject, MaxLength, Matches } from 'class-validator';
-
-/**
- * Standard error response format for all nauth-toolkit errors
- *
- * Provides structured error responses with error codes, metadata,
- * and consistent formatting across all authentication operations.
- *
- * @example
- * ```typescript
- * // Rate limit error response
- * {
- *   statusCode: 429,
- *   code: 'RATE_LIMIT_SMS',
- *   message: 'Too many verification SMS sent. Please try again later.',
- *   details: {
- *     retryAfter: 3600,
- *     currentCount: 4,
- *     maxAttempts: 3,
- *     resetAt: '2025-11-01T02:43:03.132Z'
- *   },
- *   timestamp: '2025-10-31T01:43:03.132Z',
- *   path: '/auth/verify-phone/send'
- * }
- * ```
- */
-export class ErrorResponseDTO {
-  /**
-   * HTTP status code
-   *
-   * Validation:
-   * - Must be a number
-   * - Valid HTTP status code range (100-599)
-   *
-   * @example 400
-   */
-  @IsNumber({}, { message: 'Status code must be a number' })
-  statusCode!: number;
-
-  /**
-   * Error code for programmatic handling
-   *
-   * Allows frontend to identify specific errors without parsing messages.
-   * Useful for i18n, specific error handling, and analytics.
-   *
-   * Validation:
-   * - Must be a string
-   * - Max 100 characters (prevents oversized error codes)
-   * - Alphanumeric and underscores only
-   *
-   * @example "RATE_LIMIT_SMS"
-   */
-  @IsString({ message: 'Error code must be a string' })
-  @MaxLength(100, { message: 'Error code must not exceed 100 characters' })
-  @Matches(/^[A-Z0-9_]+$/, {
-    message: 'Error code can only contain uppercase letters, numbers, and underscores',
-  })
-  code!: string;
-
-  /**
-   * Human-readable error message
-   *
-   * Should be clear and actionable. Can be displayed directly to users
-   * or used as fallback when error code doesn't have a translation.
-   *
-   * Validation:
-   * - Must be a string
-   * - Max 500 characters (prevents oversized messages)
-   *
-   * @example "Too many verification SMS sent. Please try again later."
-   */
-  @IsString({ message: 'Error message must be a string' })
-  @MaxLength(500, { message: 'Error message must not exceed 500 characters' })
-  message!: string;
-
-  /**
-   * Additional error details (optional)
-   *
-   * Provides context-specific metadata that can be used for:
-   * - Retry logic (retryAfter, resetAt)
-   * - Validation errors (field names, validation rules)
-   * - Rate limiting (current count, max attempts)
-   * - Debugging (correlation IDs, request IDs)
-   *
-   * Validation:
-   * - Must be an object if present
-   *
-   * @example
-   * ```typescript
-   * {
-   *   retryAfter: 3600,
-   *   currentCount: 4,
-   *   maxAttempts: 3,
-   *   resetAt: '2025-11-01T02:43:03.132Z'
-   * }
-   * ```
-   */
-  @IsOptional()
-  @IsObject({ message: 'Error details must be an object' })
-  details?: Record<string, unknown>;
-
-  /**
-   * Timestamp when error occurred
-   *
-   * ISO 8601 format for consistent timezone handling.
-   *
-   * Validation:
-   * - Must be a string
-   * - Must match ISO 8601 format
-   * - Max 30 characters (ISO 8601 timestamp length)
-   *
-   * @example "2025-10-31T01:43:03.132Z"
-   */
-  @IsString({ message: 'Timestamp must be a string' })
-  @MaxLength(30, { message: 'Timestamp must not exceed 30 characters' })
-  @Matches(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/, {
-    message: 'Timestamp must be in ISO 8601 format',
-  })
-  timestamp!: string;
-
-  /**
-   * Request path where error occurred
-   *
-   * Useful for debugging and error tracking.
-   *
-   * Validation:
-   * - Must be a string if present
-   * - Max 500 characters (prevents oversized paths)
-   *
-   * @example "/auth/verify-phone/send"
-   */
-  @IsOptional()
-  @IsString({ message: 'Path must be a string' })
-  @MaxLength(500, { message: 'Path must not exceed 500 characters' })
-  path?: string;
-}

package/src/dto/get-available-methods.dto.ts

@@ -1,55 +0,0 @@
-/**
- * DTO for getting available MFA methods
- *
- * Used to retrieve all registered and allowed MFA methods that can be set up for a user.
- *
- * @example
- * ```typescript
- * const methods = await mfaService.getAvailableMethods({
- *   sub: 'user-uuid'
- * });
- * // Returns: ['totp', 'sms', 'passkey']
- * ```
- */
-
-import { IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * DTO for getting available MFA methods
- */
-export class GetAvailableMethodsDTO {
-  /**
-   * 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 available MFA methods
- */
-export class GetAvailableMethodsResponseDTO {
-  /**
-   * Array of available method names
-   *
-   * @example ['totp', 'sms', 'passkey', 'email']
-   */
-  availableMethods!: string[];
-}

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

@@ -1,28 +0,0 @@
-/**
- * Response DTO for getting MFA challenge data
- *
- * Used to return method-specific challenge data during MFA verification.
- * Currently only passkey method requires challenge data (WebAuthn options).
- *
- * @example
- * ```typescript
- * const challengeData = await mfaService.getChallengeData({
- *   session: 'challenge-session-token',
- *   method: 'passkey'
- * });
- * // Returns: { publicKey: { challenge: '...', ... } }
- * ```
- */
-
-/**
- * Response DTO for challenge data
- */
-export class GetChallengeDataResponseDTO {
-  /**
-   * Provider-specific challenge data
-   *
-   * For passkey: WebAuthn public key options
-   * Structure: { publicKey: { challenge: string, allowCredentials: [...], ... } }
-   */
-  challengeData!: Record<string, unknown>;
-}

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

@@ -1,69 +0,0 @@
-/**
- * DTO for requesting MFA challenge data
- *
- * Used to get method-specific challenge information during MFA verification.
- * Currently only passkey method requires challenge data (WebAuthn options).
- *
- * Security:
- * - Session token length limited (prevents DoS)
- * - Method validated against enum (prevents injection)
- *
- * @example
- * ```typescript
- * const challengeData = await authService.getChallengeData({
- *   session: 'challenge-session-token',
- *   method: 'passkey'
- * });
- * // Returns: { publicKey: { challenge: '...', ... } }
- * ```
- */
-
-import { IsEnum, IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-
-/**
- * MFA method enum for challenge data
- * Currently only passkey requires challenge data
- */
-export enum MFAChallengeMethod {
-  PASSKEY = 'passkey',
-}
-
-/**
- * DTO for getting MFA challenge data
- */
-export class GetChallengeDataDTO {
-  /**
-   * 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 requiring challenge data
-   *
-   * Validation:
-   * - Must be 'passkey' (only method that needs challenge data)
-   */
-  @IsEnum(MFAChallengeMethod, {
-    message: 'Method must be: passkey',
-  })
-  method!: MFAChallengeMethod;
-}

package/src/dto/get-client-info.dto.ts

@@ -1,104 +0,0 @@
-/**
- * Response DTO for getting client information
- *
- * Used to return client information extracted from the current request context.
- * Includes IP address, user agent, device info, and optional geolocation data.
- *
- * @example
- * ```typescript
- * const result = await clientInfoService.get();
- * // Returns: { ipAddress: '192.168.1.100', userAgent: 'Mozilla/5.0...', ... }
- * ```
- */
-
-import { ClientInfo } from '../interfaces/client-info.interface';
-
-/**
- * Response DTO for client information
- */
-export class GetClientInfoResponseDTO implements ClientInfo {
-  /**
-   * Client IP address
-   *
-   * Extracted from X-Forwarded-For, CF-Connecting-IP, etc.
-   * Automatically handles proxies and load balancers.
-   * Returns 'unknown' if called outside request context.
-   */
-  ipAddress!: string;
-
-  /**
-   * User agent string from the request
-   *
-   * Returns 'unknown' if called outside request context.
-   */
-  userAgent!: string;
-
-  /**
-   * Device token for trusted device feature
-   *
-   * Extracted from cookie (nauth_device_token) or header (X-Device-Token).
-   * Optional - only present if device token exists.
-   */
-  deviceToken?: string;
-
-  /**
-   * Optional device name (if provided by client)
-   */
-  deviceName?: string;
-
-  /**
-   * Optional device type (if provided by client)
-   */
-  deviceType?: 'mobile' | 'desktop' | 'tablet';
-
-  /**
-   * Optional IP country (from geolocation, if available)
-   */
-  ipCountry?: string;
-
-  /**
-   * Optional IP city (from geolocation, if available)
-   */
-  ipCity?: string;
-
-  /**
-   * Optional IP latitude (from geolocation, if available)
-   * Used for impossible travel detection
-   */
-  ipLatitude?: number;
-
-  /**
-   * Optional IP longitude (from geolocation, if available)
-   * Used for impossible travel detection
-   */
-  ipLongitude?: number;
-
-  /**
-   * Platform extracted from user agent
-   *
-   * Examples: "iOS", "Android", "Windows", "macOS"
-   */
-  platform?: string;
-
-  /**
-   * Browser extracted from user agent
-   *
-   * Examples: "Chrome", "Safari", "Firefox"
-   */
-  browser?: string;
-
-  /**
-   * Current session ID (if available from authenticated request)
-   *
-   * Extracted from JWT token payload after authentication.
-   */
-  sessionId?: number;
-
-  /**
-   * Current user ID (if available from authenticated request)
-   *
-   * Extracted from JWT token payload (sub claim) after authentication.
-   * Used to identify who performed an action (e.g., for audit trails).
-   */
-  userId?: number;
-}

package/src/dto/get-device-token-response.dto.ts

@@ -1,25 +0,0 @@
-/**
- * Response DTO for getting device token
- *
- * Used to return just the device token from the current request context.
- * Device token is used for trusted device feature.
- *
- * @example
- * ```typescript
- * const result = await clientInfoService.getDeviceToken();
- * // Returns: { deviceToken: 'device-token-123' } or { deviceToken: undefined }
- * ```
- */
-
-/**
- * Response DTO for device token
- */
-export class GetDeviceTokenResponseDTO {
-  /**
-   * Device token for trusted device feature
-   *
-   * Extracted from cookie (nauth_device_token) or header (X-Device-Token).
-   * Optional - undefined if not present.
-   */
-  deviceToken?: string;
-}

package/src/dto/get-events-by-type.dto.ts

@@ -1,76 +0,0 @@
-import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
-import { IAuthAudit } from '../interfaces/entities.interface';
-
-/**
- * Request DTO for getting events by type
- *
- * @example
- * ```typescript
- * const result = await auditService.getEventsByType({
- *   eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
- *   page: 1,
- *   limit: 100,
- *   startDate: new Date('2025-01-01'),
- * });
- * ```
- */
-export class GetEventsByTypeDTO {
-  /**
-   * Event type to filter by
-   */
-  eventType!: AuthAuditEventType;
-
-  /**
-   * 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;
-}
-
-/**
- * Response DTO for paginated events by type
- */
-export class GetEventsByTypeResponseDTO {
-  /**
-   * 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-ip-address-response.dto.ts

@@ -1,24 +0,0 @@
-/**
- * Response DTO for getting IP address
- *
- * Used to return just the IP address from the current request context.
- *
- * @example
- * ```typescript
- * const result = await clientInfoService.getIpAddress();
- * // Returns: { ipAddress: '192.168.1.100' }
- * ```
- */
-
-/**
- * Response DTO for IP address
- */
-export class GetIpAddressResponseDTO {
-  /**
-   * Client IP address
-   *
-   * Extracted from X-Forwarded-For, CF-Connecting-IP, etc.
-   * Returns 'unknown' if called outside request context.
-   */
-  ipAddress!: string;
-}

package/src/dto/get-mfa-status.dto.ts

@@ -1,94 +0,0 @@
-/**
- * DTO for getting MFA status
- *
- * Used to retrieve comprehensive MFA status for a user including enabled status,
- * configured methods, available methods, backup codes, and exemption information.
- *
- * @example
- * ```typescript
- * const status = await mfaService.getMFAStatus({
- *   sub: 'user-uuid'
- * });
- * ```
- */
-
-import { IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-import { MFADeviceMethod } from '../enums/mfa-method.enum';
-
-/**
- * DTO for getting MFA status
- */
-export class GetMFAStatusDTO {
-  /**
-   * 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 MFA status
- */
-export class GetMFAStatusResponseDTO {
-  /**
-   * Whether MFA is enabled for the user
-   */
-  enabled!: boolean;
-
-  /**
-   * Whether MFA is required (enabled and has configured devices)
-   */
-  required!: boolean;
-
-  /**
-   * Array of configured MFA device methods
-   */
-  configuredMethods!: Array<MFADeviceMethod>;
-
-  /**
-   * Array of available MFA methods that can be set up
-   */
-  availableMethods!: Array<string>;
-
-  /**
-   * Whether user has backup codes
-   */
-  hasBackupCodes!: boolean;
-
-  /**
-   * Preferred MFA method (if set)
-   */
-  preferredMethod?: MFADeviceMethod;
-
-  /**
-   * Whether user is exempt from MFA requirements
-   */
-  mfaExempt!: boolean;
-
-  /**
-   * Reason for MFA exemption (if exempt)
-   */
-  mfaExemptReason!: string | null;
-
-  /**
-   * Date when MFA exemption was granted (if exempt)
-   */
-  mfaExemptGrantedAt!: Date | null;
-}

package/src/dto/get-risk-assessment-history.dto.ts

@@ -1,39 +0,0 @@
-import { IAuthAudit } from '../interfaces/entities.interface';
-
-/**
- * Request DTO for getting risk assessment history
- *
- * Returns events where risk assessment was performed (ADAPTIVE_MFA_RISK_ASSESSED,
- * ADAPTIVE_MFA_TRIGGERED, ADAPTIVE_MFA_BYPASSED).
- *
- * @example
- * ```typescript
- * const result = await auditService.getRiskAssessmentHistory({
- *   userSub: 'user-uuid',
- *   limit: 50,
- * });
- * ```
- */
-export class GetRiskAssessmentHistoryDTO {
-  /**
-   * User identifier
-   */
-  userSub!: string;
-
-  /**
-   * Maximum number of records to return
-   *
-   * @default 100
-   */
-  limit?: number;
-}
-
-/**
- * Response DTO for risk assessment history
- */
-export class GetRiskAssessmentHistoryResponseDTO {
-  /**
-   * Array of risk assessment audit events
-   */
-  data!: IAuthAudit[];
-}

package/src/dto/get-session-id-response.dto.ts

@@ -1,25 +0,0 @@
-/**
- * Response DTO for getting session ID
- *
- * Used to return just the session ID from the current request context.
- * Session ID is extracted from JWT token payload after authentication.
- *
- * @example
- * ```typescript
- * const result = await clientInfoService.getSessionId();
- * // Returns: { sessionId: 123 } or { sessionId: undefined }
- * ```
- */
-
-/**
- * Response DTO for session ID
- */
-export class GetSessionIdResponseDTO {
-  /**
-   * Current session ID (if available from authenticated request)
-   *
-   * Extracted from JWT token payload after authentication.
-   * Optional - undefined if not available.
-   */
-  sessionId?: number;
-}