@nauth-toolkit/core 0.1.0 → 0.1.3

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

@@ -1,253 +0,0 @@
-import { AuthChallenge } from './auth-challenge.dto';
-
-/**
- * Unified Authentication Response DTO
- *
- * Used for ALL authentication operations:
- * - Email/password login
- * - User signup
- * - Social authentication (Google, Apple, Facebook)
- * - Token refresh
- * - Challenge completions
- *
- * This provides a consistent interface regardless of authentication method,
- * improving developer experience and code maintainability.
- *
- * When challenges are present, tokens will not be issued until all challenges
- * are completed. This ensures proper verification and security enforcement.
- *
- * No validators needed - this is generated internally by the library.
- *
- * @example
- * ```typescript
- * // Successful auth with no challenges
- * const loginResult = await authService.login(dto);
- * // { accessToken: '...', refreshToken: '...', user: {...} }
- *
- * // Auth with pending challenge
- * const signupResult = await authService.signup(dto);
- * // { challengeName: 'VERIFY_EMAIL', session: '...', challengeParameters: {...} }
- * ```
- */
-export class AuthResponseDTO {
-  /**
-   * JWT access token for API authentication
-   * Short-lived (typically 15 minutes)
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   */
-  accessToken?: string;
-
-  /**
-   * JWT refresh token for obtaining new access tokens
-   * Long-lived (typically 30 days)
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   */
-  refreshToken?: string;
-
-  /**
-   * Access token expiration timestamp
-   * Unix timestamp in seconds
-   *
-   * @example 1730000000 (represents a specific date/time)
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   */
-  accessTokenExpiresAt?: number;
-
-  /**
-   * Refresh token expiration timestamp
-   * Unix timestamp in seconds
-   *
-   * @example 1732592000 (30 days after access token)
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   */
-  refreshTokenExpiresAt?: number;
-
-  /**
-   * Whether the current device is already trusted
-   *
-   * When true, the device has a valid trusted device token and UI should NOT show
-   * "trust device" popup.
-   *
-   * When false and rememberDevices === 'user_opt_in', UI can show popup after login
-   * to allow user to opt-in for device trust.
-   *
-   * When rememberDevices === 'always', this will always be true after successful login.
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   */
-  trusted?: boolean;
-
-  /**
-   * Device token for trusted device feature (UUID v4)
-   *
-   * Server-generated UUID token for identifying trusted devices.
-   * Only returned when rememberDevices is not 'never' and device is trusted.
-   *
-   * Delivery by mode:
-   * - **cookies mode**: Token set as `nauth_device_token` httpOnly cookie (not in response body)
-   * - **json/hybrid mode**: Token returned in response body for mobile apps
-   *
-   * Mobile apps should:
-   * - Store token in secure storage (iOS Keychain / Android EncryptedSharedPreferences)
-   * - Send token in `X-Device-Token` header on subsequent logins
-   * - Token persists across app restarts and survives logout
-   *
-   * Web apps:
-   * - Token automatically handled via httpOnly cookie (cookies mode)
-   * - No manual handling required
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   * WARNING: For JSON mode, ensure secure storage - token in response body can be intercepted
-   */
-  deviceToken?: string;
-
-  /**
-   * User information
-   * Standardized across all authentication methods
-   *
-   * NOTE: Only present when authentication is complete (no pending challenges)
-   */
-  user?: {
-    /**
-     * User's unique identifier (UUID v4)
-     * External identifier safe to expose in JWTs and APIs
-     */
-    sub: string;
-
-    /**
-     * User's email address
-     */
-    email: string;
-
-    /**
-     * User's first name (optional)
-     */
-    firstName?: string | null;
-
-    /**
-     * User's last name (optional)
-     */
-    lastName?: string | null;
-
-    /**
-     * User's phone number (optional)
-     * E.164 format
-     */
-    phone?: string;
-
-    /**
-     * Email verification status
-     */
-    isEmailVerified: boolean;
-
-    /**
-     * Phone verification status
-     */
-    isPhoneVerified?: boolean;
-
-    /**
-     * List of linked social providers
-     * @example ['google', 'apple']
-     */
-    socialProviders?: string[];
-
-    /**
-     * 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;
-  };
-
-  // ============================================================================
-  // Challenge System (Similar to AWS Cognito)
-  // ============================================================================
-
-  /**
-   * Challenge that must be completed before authentication is granted
-   *
-   * When present, the user must complete this challenge using the
-   * challenge completion endpoint before they can access the system.
-   *
-   * Tokens (accessToken, refreshToken) will NOT be present when a challenge exists.
-   *
-   * @example 'VERIFY_EMAIL' | 'VERIFY_PHONE' | 'MFA_REQUIRED'
-   */
-  challengeName?: AuthChallenge;
-
-  /**
-   * Temporary session identifier for challenge completion (UUID v4)
-   *
-   * This is NOT a JWT token - it's a temporary identifier that must be
-   * submitted when completing the challenge. It expires after a short time
-   * (typically 15 minutes) or after successful challenge completion.
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   *
-   * NOTE: Only present when challengeName is set
-   */
-  session?: string;
-
-  /**
-   * Challenge-specific parameters
-   *
-   * Contains information needed to complete the challenge, such as:
-   * - Masked email/phone for delivery confirmation
-   * - Challenge type details
-   * - Instructions for the user
-   *
-   * NOTE: Only present when challengeName is set
-   *
-   * @example
-   * ```typescript
-   * {
-   *   email: 'user@example.com',
-   *   codeDeliveryDestination: 'u***@example.com'
-   * }
-   * ```
-   */
-  challengeParameters?: Record<string, unknown>;
-
-  /**
-   * User's unique identifier (UUID v4)
-   * Present in both successful auth and challenge responses
-   * Helps the client track which user is authenticating
-   *
-   * @example "a21b654c-2746-4168-acee-c175083a65cd"
-   */
-  userSub?: string;
-}
-
-/**
- * Token Response DTO
- *
- * Returned by token refresh operations
- * Contains new access and refresh tokens with expiration times
- */
-export interface TokenResponse {
-  /**
-   * New JWT access token
-   */
-  accessToken: string;
-
-  /**
-   * New JWT refresh token
-   */
-  refreshToken: string;
-
-  /**
-   * Access token expiration (Unix timestamp in seconds)
-   */
-  accessTokenExpiresAt: number;
-
-  /**
-   * Refresh token expiration (Unix timestamp in seconds)
-   */
-  refreshTokenExpiresAt: number;
-}

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

@@ -1,234 +0,0 @@
-/**
- * Challenge Response DTOs for Unified Challenge System
- *
- * Discriminated union types for responding to authentication challenges.
- * Each challenge type has specific required parameters.
- *
- * @module ChallengeResponseDTO
- */
-
-// ============================================================================
-// Base Types
-// ============================================================================
-
-/**
- * Base interface for all challenge responses
- */
-export interface BaseChallengeResponse {
-  /** Challenge session token */
-  session: string;
-}
-
-// ============================================================================
-// Email Verification Challenge
-// ============================================================================
-
-/**
- * Response for email verification challenge
- *
- * @example
- * ```typescript
- * const response: VerifyEmailResponse = {
- *   session: 'challenge-session-token',
- *   type: 'VERIFY_EMAIL',
- *   code: '123456'
- * };
- * ```
- */
-export interface VerifyEmailResponse extends BaseChallengeResponse {
-  type: 'VERIFY_EMAIL';
-  /** 6-digit verification code sent to email */
-  code: string;
-}
-
-// ============================================================================
-// Phone Verification Challenge
-// ============================================================================
-
-/**
- * Response for collecting phone number (first step)
- *
- * @example
- * ```typescript
- * const response: CollectPhoneResponse = {
- *   session: 'challenge-session-token',
- *   type: 'VERIFY_PHONE',
- *   phone: '+1234567890'
- * };
- * ```
- */
-export interface CollectPhoneResponse extends BaseChallengeResponse {
-  type: 'VERIFY_PHONE';
-  /** Phone number in E.164 format */
-  phone: string;
-}
-
-/**
- * Response for verifying phone with code (second step)
- *
- * @example
- * ```typescript
- * const response: VerifyPhoneResponse = {
- *   session: 'challenge-session-token',
- *   type: 'VERIFY_PHONE',
- *   code: '123456'
- * };
- * ```
- */
-export interface VerifyPhoneResponse extends BaseChallengeResponse {
-  type: 'VERIFY_PHONE';
-  /** 6-digit verification code sent to phone */
-  code: string;
-}
-
-// ============================================================================
-// MFA Verification Challenge
-// ============================================================================
-
-/**
- * Response for MFA verification with code (SMS/TOTP/Backup)
- *
- * @example
- * ```typescript
- * const response: VerifyMFACodeResponse = {
- *   session: 'challenge-session-token',
- *   type: 'MFA_REQUIRED',
- *   method: 'totp',
- *   code: '123456'
- * };
- * ```
- */
-export interface VerifyMFACodeResponse extends BaseChallengeResponse {
-  type: 'MFA_REQUIRED';
-  /** MFA method being used */
-  method: 'sms' | 'totp' | 'backup';
-  /** Verification code */
-  code: string;
-}
-
-/**
- * Response for MFA verification with passkey
- *
- * @example
- * ```typescript
- * const response: VerifyMFAPasskeyResponse = {
- *   session: 'challenge-session-token',
- *   type: 'MFA_REQUIRED',
- *   method: 'passkey',
- *   credential: { id: '...', rawId: '...', response: {...} }
- * };
- * ```
- */
-export interface VerifyMFAPasskeyResponse extends BaseChallengeResponse {
-  type: 'MFA_REQUIRED';
-  /** Passkey method */
-  method: 'passkey';
-  /** WebAuthn credential from navigator.credentials.get() */
-  credential: Record<string, unknown>;
-}
-
-// ============================================================================
-// Force Password Change Challenge
-// ============================================================================
-
-/**
- * Response for forced password change challenge
- *
- * @example
- * ```typescript
- * const response: ForceChangePasswordResponse = {
- *   session: 'challenge-session-token',
- *   type: 'FORCE_CHANGE_PASSWORD',
- *   newPassword: 'NewSecurePassword123!'
- * };
- * ```
- */
-export interface ForceChangePasswordResponse extends BaseChallengeResponse {
-  type: 'FORCE_CHANGE_PASSWORD';
-  /** New password meeting security requirements */
-  newPassword: string;
-}
-
-// ============================================================================
-// MFA Setup Challenge
-// ============================================================================
-
-/**
- * Response for MFA setup during challenge
- *
- * @example
- * ```typescript
- * // SMS setup
- * const smsResponse: MFASetupResponse = {
- *   session: 'challenge-session-token',
- *   type: 'MFA_SETUP_REQUIRED',
- *   method: 'sms',
- *   setupData: { phone: '+1234567890', code: '123456' }
- * };
- *
- * // TOTP setup
- * const totpResponse: MFASetupResponse = {
- *   session: 'challenge-session-token',
- *   type: 'MFA_SETUP_REQUIRED',
- *   method: 'totp',
- *   setupData: { code: '123456' }
- * };
- *
- * // Passkey setup
- * const passkeyResponse: MFASetupResponse = {
- *   session: 'challenge-session-token',
- *   type: 'MFA_SETUP_REQUIRED',
- *   method: 'passkey',
- *   setupData: { credential: {...} }
- * };
- * ```
- */
-export interface MFASetupResponse extends BaseChallengeResponse {
-  type: 'MFA_SETUP_REQUIRED';
-  /** MFA method being set up */
-  method: 'sms' | 'email' | 'totp' | 'passkey';
-  /**
-   * Method-specific setup data
-   * - SMS: { phone: string, code: string }
-   * - TOTP: { code: string }
-   * - Passkey: { credential: Record<string, unknown> }
-   */
-  setupData: Record<string, unknown>;
-}
-
-// ============================================================================
-// Union Type
-// ============================================================================
-
-/**
- * Discriminated union of all challenge response types
- *
- * Use this type for the unified respondToChallenge() API.
- * TypeScript will narrow the type based on the 'type' discriminator.
- *
- * @example
- * ```typescript
- * async function handleChallenge(response: ChallengeResponseData) {
- *   switch (response.type) {
- *     case 'VERIFY_EMAIL':
- *       // TypeScript knows response.code is available
- *       break;
- *     case 'MFA_REQUIRED':
- *       if (response.method === 'passkey') {
- *         // TypeScript knows response.credential is available
- *       } else {
- *         // TypeScript knows response.code is available
- *       }
- *       break;
- *   }
- * }
- * ```
- */
-export type ChallengeResponseData =
-  | VerifyEmailResponse
-  | CollectPhoneResponse
-  | VerifyPhoneResponse
-  | VerifyMFACodeResponse
-  | VerifyMFAPasskeyResponse
-  | ForceChangePasswordResponse
-  | MFASetupResponse;

package/src/dto/change-password-request.dto.ts

@@ -1,50 +0,0 @@
-/**
- * Change Password Request DTO
- *
- * Request DTO for changing a user's password (includes user sub).
- *
- * Security:
- * - User sub validated (UUID)
- * - Password validation enforced
- * - Current password required for security
- *
- * @example
- * ```typescript
- * await authService.changePassword({
- *   sub: 'user-uuid',
- *   currentPassword: 'OldPass123!',
- *   newPassword: 'NewPass456!'
- * });
- * ```
- */
-
-import { IsUUID } from 'class-validator';
-import { Transform } from 'class-transformer';
-import { ChangePasswordDTO } from './change-password.dto';
-
-/**
- * Request DTO for changing password (includes user sub)
- */
-export class ChangePasswordRequestDTO extends ChangePasswordDTO {
-  /**
-   * 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/change-password-response.dto.ts

@@ -1,29 +0,0 @@
-/**
- * Change Password Response DTO
- *
- * Response DTO for changing password.
- * No validators needed - this is generated internally by the library.
- *
- * @example
- * ```typescript
- * await authService.changePassword({
- *   sub: 'user-uuid',
- *   oldPassword: 'OldPass123!',
- *   newPassword: 'NewPass456!'
- * });
- * // Returns: { success: true }
- * ```
- */
-
-/**
- * Response DTO for change password
- */
-export class ChangePasswordResponseDTO {
-  /**
-   * Success indicator
-   * Always true on successful password change
-   *
-   * @example true
-   */
-  success!: boolean;
-}

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

@@ -1,57 +0,0 @@
-/**
- * Change Password DTO
- *
- * Used for authenticated password changes.
- * User must provide their current password for security verification.
- *
- * Security:
- * - Old password verified before allowing change
- * - New password validated for minimum strength
- * - Password history checked (configurable)
- * - Max length prevents DoS via bcrypt
- *
- * @example
- * ```typescript
- * POST /auth/change-password
- * Authorization: Bearer <access-token>
- * {
- *   "oldPassword": "currentPassword123",
- *   "newPassword": "newSecurePassword456"
- * }
- * ```
- */
-
-import { IsString, MinLength, MaxLength } from 'class-validator';
-
-export class ChangePasswordDTO {
-  /**
-   * Current password
-   *
-   * Validation:
-   * - Must be a string
-   *
-   * Note: NOT trimmed (passwords can have leading/trailing spaces)
-   */
-  @IsString({ message: 'Old password must be a string' })
-  oldPassword!: 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 history (prevent reuse of recent passwords)
-   * - Password strength (if configured)
-   * - Not same as old password
-   */
-  @IsString({ message: 'New password must be a string' })
-  @MinLength(8, { message: 'Password must be at least 8 characters' })
-  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
-  newPassword!: string;
-}