@nauth-toolkit/core 0.1.0

package/src/dto/signup.dto.ts

@@ -0,0 +1,174 @@
+import { IsEmail, IsString, MinLength, MaxLength, IsOptional, Matches } from 'class-validator';
+import { Transform } from 'class-transformer';
+
+/**
+ * DTO for user signup with comprehensive validation
+ *
+ * Security:
+ * - All fields validated against DB constraints
+ * - Input sanitization applied automatically
+ * - Password strength enforced (8-128 chars)
+ * - Email/username uniqueness checked in service layer
+ */
+export class SignupDTO {
+  /**
+   * User email address
+   *
+   * Validation:
+   * - Valid email format (RFC 5322)
+   * - Max 255 characters (matches DB limit)
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsEmail({}, { message: 'Invalid 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;
+
+  /**
+   * User password
+   *
+   * Validation:
+   * - Min 8 characters
+   * - Max 128 characters (prevents DoS via bcrypt)
+   * - Additional policy checks in service layer
+   *
+   * Note: NOT trimmed (passwords can have leading/trailing spaces)
+   */
+  @IsString({ message: 'Password must be a string' })
+  @MinLength(8, { message: 'Password must be at least 8 characters' })
+  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
+  password!: string;
+
+  /**
+   * Optional username
+   *
+   * Validation:
+   * - 3-50 characters
+   * - Alphanumeric, underscores, and hyphens only
+   * - Max 255 characters (DB limit)
+   *
+   * Sanitization:
+   * - Trimmed
+   * - Case preserved (username can be case-sensitive per config)
+   */
+  @IsOptional()
+  @IsString({ message: 'Username must be a string' })
+  @MinLength(3, { message: 'Username must be at least 3 characters' })
+  @MaxLength(255, { message: 'Username must not exceed 255 characters' })
+  @Matches(/^[a-zA-Z0-9_-]+$/, {
+    message: 'Username can only contain letters, numbers, underscores, and hyphens',
+  })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  username?: string;
+
+  /**
+   * Optional first name
+   *
+   * Validation:
+   * - 1-100 characters
+   * - Letters, spaces, hyphens, and apostrophes only
+   * - Max 100 characters (DB limit)
+   *
+   * Sanitization:
+   * - Trimmed
+   * - Title case preserved
+   */
+  @IsOptional()
+  @IsString({ message: 'First name must be a string' })
+  @MinLength(1, { message: 'First name must be at least 1 character' })
+  @MaxLength(100, { message: 'First name must not exceed 100 characters' })
+  @Matches(/^[a-zA-Z\s\-']+$/, {
+    message: 'First name can only contain letters, spaces, hyphens, and apostrophes',
+  })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  firstName?: string;
+
+  /**
+   * Optional last name
+   *
+   * Validation:
+   * - 1-100 characters
+   * - Letters, spaces, hyphens, and apostrophes only
+   * - Max 100 characters (DB limit)
+   *
+   * Sanitization:
+   * - Trimmed
+   * - Title case preserved
+   */
+  @IsOptional()
+  @IsString({ message: 'Last name must be a string' })
+  @MinLength(1, { message: 'Last name must be at least 1 character' })
+  @MaxLength(100, { message: 'Last name must not exceed 100 characters' })
+  @Matches(/^[a-zA-Z\s\-']+$/, {
+    message: 'Last name can only contain letters, spaces, hyphens, and apostrophes',
+  })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  lastName?: string;
+
+  /**
+   * Optional phone number
+   *
+   * Validation:
+   * - E.164 format (international standard)
+   * - MUST start with + (required for security)
+   * - Max 20 characters (DB limit)
+   * - Example: +14155552671, +61444567890
+   *
+   * Sanitization:
+   * - Whitespace removed
+   * - Only digits and leading + preserved
+   *
+   * Security:
+   * - Strict E.164 validation prevents SQL injection
+   * - Max length prevents oversized inputs
+   *
+   * Note: Using regex for E.164 format as IsPhoneNumber requires specific country codes
+   * and doesn't support international E.164 format validation directly
+   */
+  @IsOptional()
+  @IsString({ message: 'Phone must be a string' })
+  @MaxLength(20, { message: 'Phone must not exceed 20 characters' })
+  @Matches(/^\+[1-9]\d{1,14}$/, {
+    message: 'Phone must be in E.164 format with + prefix (e.g., +14155552671)',
+  })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      // Remove all whitespace and keep only digits and +
+      return value.replace(/\s/g, '');
+    }
+    return value;
+  })
+  phone?: string;
+
+  /**
+   * Optional metadata (custom fields)
+   *
+   * Security:
+   * - Validated in service layer if used
+   * - Max depth/size limits should be enforced
+   */
+  @IsOptional()
+  metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,422 @@
+import { IsString, IsUUID, IsOptional, MaxLength, MinLength } from 'class-validator';
+import { Transform } from 'class-transformer';
+
+/**
+ * DTO for getting social authentication URL
+ *
+ * Security:
+ * - Provider name validated as string
+ * - State parameter validated for length (CSRF protection)
+ */
+export class GetSocialAuthUrlDTO {
+  /**
+   * Social provider name (e.g., 'google', 'apple', 'facebook')
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 50 characters
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsString({ message: 'Provider must be a string' })
+  @MaxLength(50, { message: 'Provider name must not exceed 50 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  provider!: string;
+
+  /**
+   * Optional CSRF state parameter
+   *
+   * Validation:
+   * - Max 500 characters (typical state token length)
+   * - Optional field
+   *
+   * Sanitization:
+   * - Trimmed
+   */
+  @IsOptional()
+  @IsString({ message: 'State must be a string' })
+  @MaxLength(500, { message: 'State must not exceed 500 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  state?: string;
+}
+
+/**
+ * Response DTO for getSocialAuthUrl
+ */
+export class GetSocialAuthUrlResponseDTO {
+  /**
+   * OAuth authorization URL
+   */
+  url!: string;
+}
+
+/**
+ * DTO for handling social authentication callback
+ *
+ * Security:
+ * - Provider name validated
+ * - Code validated for length
+ * - State validated for CSRF protection
+ */
+export class HandleSocialCallbackDTO {
+  /**
+   * Social provider name (e.g., 'google', 'apple', 'facebook')
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 50 characters
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsString({ message: 'Provider must be a string' })
+  @MaxLength(50, { message: 'Provider name must not exceed 50 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  provider!: string;
+
+  /**
+   * Authorization code from OAuth callback
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 1000 characters (OAuth codes can be long)
+   *
+   * Sanitization:
+   * - Trimmed
+   */
+  @IsString({ message: 'Code must be a string' })
+  @MaxLength(1000, { message: 'Authorization code must not exceed 1000 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  code!: string;
+
+  /**
+   * State parameter from OAuth callback (for CSRF validation)
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 500 characters
+   *
+   * Sanitization:
+   * - Trimmed
+   */
+  @IsString({ message: 'State must be a string' })
+  @MaxLength(500, { message: 'State must not exceed 500 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  state!: string;
+}
+
+/**
+ * DTO for linking social account
+ *
+ * Security:
+ * - User ID validated as UUID v4
+ * - Provider name validated
+ * - Code and state validated for length
+ */
+export class LinkSocialAccountDTO {
+  /**
+   * User identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be valid UUID v4 format
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  userId!: string;
+
+  /**
+   * Social provider name (e.g., 'google', 'apple', 'facebook')
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 50 characters
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsString({ message: 'Provider must be a string' })
+  @MaxLength(50, { message: 'Provider name must not exceed 50 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  provider!: string;
+
+  /**
+   * Authorization code from OAuth callback
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 1000 characters
+   *
+   * Sanitization:
+   * - Trimmed
+   */
+  @IsString({ message: 'Code must be a string' })
+  @MaxLength(1000, { message: 'Authorization code must not exceed 1000 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  code!: string;
+
+  /**
+   * State parameter from OAuth callback (for CSRF validation)
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 500 characters
+   *
+   * Sanitization:
+   * - Trimmed
+   */
+  @IsString({ message: 'State must be a string' })
+  @MaxLength(500, { message: 'State must not exceed 500 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  })
+  state!: string;
+}
+
+/**
+ * Response DTO for linkSocialAccount
+ */
+export class LinkSocialAccountResponseDTO {
+  /**
+   * Success message
+   */
+  message!: string;
+
+  /**
+   * Provider name
+   */
+  provider!: string;
+}
+
+/**
+ * DTO for getting linked social accounts
+ *
+ * Security:
+ * - User ID validated as UUID v4
+ */
+export class GetLinkedAccountsDTO {
+  /**
+   * User identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be valid UUID v4 format
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  userId!: string;
+}
+
+/**
+ * Response DTO for getLinkedAccounts
+ */
+export class GetLinkedAccountsResponseDTO {
+  /**
+   * Array of linked social accounts
+   */
+  accounts!: Array<{
+    provider: string;
+    providerEmail?: string;
+    linkedAt: Date;
+    lastUsedAt?: Date;
+  }>;
+}
+
+/**
+ * DTO for unlinking social account
+ *
+ * Security:
+ * - User ID validated as UUID v4
+ * - Provider name validated
+ */
+export class UnlinkSocialAccountDTO {
+  /**
+   * User identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be valid UUID v4 format
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  userId!: string;
+
+  /**
+   * Social provider name (e.g., 'google', 'apple', 'facebook')
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Max 50 characters
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsString({ message: 'Provider must be a string' })
+  @MaxLength(50, { message: 'Provider name must not exceed 50 characters' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  provider!: string;
+}
+
+/**
+ * Response DTO for unlinkSocialAccount
+ */
+export class UnlinkSocialAccountResponseDTO {
+  /**
+   * Success message
+   */
+  message!: string;
+}
+
+/**
+ * DTO for checking if user can set password
+ *
+ * Security:
+ * - User ID validated as UUID v4
+ */
+export class CanSetPasswordDTO {
+  /**
+   * User identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be valid UUID v4 format
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  userId!: string;
+}
+
+/**
+ * Response DTO for canSetPassword
+ */
+export class CanSetPasswordResponseDTO {
+  /**
+   * Whether user can set password
+   */
+  canSetPassword!: boolean;
+}
+
+/**
+ * DTO for setting password for social-only user
+ *
+ * Security:
+ * - User ID validated as UUID v4
+ * - Password validated for strength (delegated to AuthService)
+ */
+export class SetPasswordForSocialUserDTO {
+  /**
+   * User identifier (UUID v4)
+   *
+   * Validation:
+   * - Must be valid UUID v4 format
+   *
+   * Sanitization:
+   * - Trimmed and lowercased
+   */
+  @IsUUID('4', { message: 'User ID must be a valid UUID v4 format' })
+  @Transform(({ value }) => {
+    if (typeof value === 'string') {
+      return value.trim().toLowerCase();
+    }
+    return value;
+  })
+  userId!: string;
+
+  /**
+   * New password
+   *
+   * Validation:
+   * - Must be non-empty string
+   * - Min 1 character (actual validation in AuthService)
+   * - Max 128 characters (matches DB constraint)
+   *
+   * Sanitization:
+   * - Not trimmed (passwords may have leading/trailing spaces intentionally)
+   */
+  @IsString({ message: 'Password must be a string' })
+  @MinLength(1, { message: 'Password is required' })
+  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
+  password!: string;
+}
+
+/**
+ * Response DTO for setPasswordForSocialUser
+ */
+export class SetPasswordForSocialUserResponseDTO {
+  /**
+   * Success message
+   */
+  message!: string;
+}

package/src/dto/trust-device-response.dto.ts

@@ -0,0 +1,30 @@
+/**
+ * Trust Device Response DTO
+ *
+ * Response DTO for trusting a device.
+ * No validators needed - this is generated internally by the library.
+ *
+ * Security:
+ * - Device token should be stored securely on client
+ * - Used for MFA bypass on trusted devices
+ *
+ * @example
+ * ```typescript
+ * const result = await authService.trustDevice();
+ * // Returns: { deviceToken: 'device-token-string' }
+ * ```
+ */
+
+/**
+ * Response DTO for trust device
+ */
+export class TrustDeviceResponseDTO {
+  /**
+   * Device trust token
+   *
+   * Note: Store this token securely on the client device
+   *
+   * @example "device-token-uuid-string"
+   */
+  deviceToken!: string;
+}

package/src/dto/trust-device.dto.ts

@@ -0,0 +1,9 @@
+/**
+ * Trust Device DTO
+ *
+ * Note: No request DTO needed - sessionId is automatically extracted from JWT token context
+ * via ClientInfoService, similar to how IP address and user agent are handled.
+ *
+ * This file is kept for backward compatibility but TrustDeviceDTO is no longer used.
+ * The trustDevice() method now takes no parameters.
+ */

package/src/dto/update-user-attributes-request.dto.ts

@@ -0,0 +1,51 @@
+/**
+ * Update User Attributes Request DTO
+ *
+ * Request DTO for updating user profile information (includes user sub).
+ *
+ * Security:
+ * - User sub validated (UUID)
+ * - All fields validated according to UserUpdateDTO rules
+ * - Uniqueness constraints enforced
+ *
+ * @example
+ * ```typescript
+ * const result = await authService.updateUserAttributes({
+ *   sub: 'user-uuid',
+ *   username: 'newusername',
+ *   firstName: 'John',
+ *   lastName: 'Doe'
+ * });
+ * ```
+ */
+
+import { IsUUID } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { UserUpdateDTO } from './user-update.dto';
+
+/**
+ * Request DTO for updating user attributes (includes user sub)
+ */
+export class UpdateUserAttributesRequestDTO extends UserUpdateDTO {
+  /**
+   * 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;
+}