@nauth-toolkit/core 0.1.98 → 0.1.99

package/dist/openapi/components.schemas.json

@@ -0,0 +1,4109 @@
+{
+  "openapi": "3.0.3",
+  "components": {
+    "schemas": {
+      "AdminGetMFAStatusDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Admin request DTO for getting MFA status (includes target user sub)"
+      },
+      "AdminGetUserAuthHistoryDTO": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "type": "number",
+            "description": "Page number (1-indexed)",
+            "default": 1
+          },
+          "limit": {
+            "type": "number",
+            "description": "Number of records per page",
+            "default": 50
+          },
+          "startDate": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events from this date onwards"
+          },
+          "endDate": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events up to this date"
+          },
+          "eventTypes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AuthAuditEventType"
+            },
+            "description": "Filter by specific event types\n\nIf provided, only events matching these types will be returned."
+          },
+          "eventStatus": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AuthAuditEventStatus"
+            },
+            "description": "Filter by event status\n\nIf provided, only events matching these statuses will be returned."
+          },
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency\n\nRequired for admin operations.",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for getting user authentication history (admin-only)\n\nAdmin DTO - requires sub field. Used by AdminAuthService."
+      },
+      "AuthAuditEventType": {
+        "type": "string",
+        "enum": [
+          "LOGIN_ATTEMPT",
+          "LOGIN_SUCCESS",
+          "LOGIN_FAILED",
+          "LOGIN_BLOCKED",
+          "SESSION_CREATED",
+          "SESSION_REVOKED",
+          "GLOBAL_SIGNOUT",
+          "PASSWORD_CHANGED",
+          "PASSWORD_RESET_REQUESTED",
+          "PASSWORD_RESET_COMPLETED",
+          "PASSWORD_FORCE_CHANGE_SET",
+          "PASSWORD_FORCE_CHANGE_COMPLETED",
+          "ADMIN_PASSWORD_RESET_INITIATED",
+          "ADMIN_PASSWORD_RESET_COMPLETED",
+          "ADMIN_PASSWORD_RESET_FAILED",
+          "MFA_ENABLED",
+          "MFA_DISABLED",
+          "MFA_DEVICE_ADDED",
+          "MFA_DEVICE_REMOVED",
+          "MFA_DEVICE_UPDATED",
+          "MFA_VERIFICATION_SUCCESS",
+          "MFA_VERIFICATION_FAILED",
+          "MFA_EXEMPTION_GRANTED",
+          "MFA_EXEMPTION_REVOKED",
+          "MFA_BACKUP_CODES_GENERATED",
+          "MFA_BACKUP_CODE_USED",
+          "MFA_PREFERRED_METHOD_UPDATED",
+          "DEVICE_TRUSTED",
+          "DEVICE_UNTRUSTED",
+          "ADAPTIVE_MFA_RISK_ASSESSED",
+          "ADAPTIVE_MFA_TRIGGERED",
+          "ADAPTIVE_MFA_BYPASSED",
+          "EMAIL_VERIFIED",
+          "EMAIL_VERIFICATION_REQUESTED",
+          "EMAIL_VERIFICATION_FAILED",
+          "PHONE_VERIFIED",
+          "PHONE_VERIFICATION_REQUESTED",
+          "PHONE_VERIFICATION_FAILED",
+          "ACCOUNT_CREATED",
+          "ACCOUNT_ACTIVATED",
+          "ACCOUNT_DEACTIVATED",
+          "ACCOUNT_LOCKED",
+          "ACCOUNT_UNLOCKED",
+          "ACCOUNT_DISABLED",
+          "ACCOUNT_ENABLED",
+          "ACCOUNT_DELETED",
+          "PROFILE_UPDATED",
+          "EMAIL_CHANGED",
+          "PHONE_CHANGED",
+          "USERNAME_CHANGED",
+          "SOCIAL_LOGIN",
+          "SOCIAL_ACCOUNT_LINKED",
+          "SOCIAL_ACCOUNT_UNLINKED",
+          "CHALLENGE_CREATED",
+          "CHALLENGE_COMPLETED",
+          "CHALLENGE_ATTEMPT_FAILED",
+          "SUSPICIOUS_ACTIVITY"
+        ],
+        "description": "Authentication Audit Event Types\n\nComprehensive enumeration of all authentication and security events that are recorded in the audit trail.\n\n**Organization:**\n- Login events (success, failure, blocked)\n- Session management events\n- Password operations\n- Multi-Factor Authentication (MFA) events\n- Adaptive MFA events (risk-based)\n- Verification events (email, phone)\n- Account management events\n- Profile update events\n- Social authentication events\n- Challenge flow events\n- Security violation events\n\n**Note:** TOKEN_REFRESHED is intentionally excluded as it occurs too frequently and would create excessive audit noise. Only security-relevant token operations are audited."
+      },
+      "AuthAuditEventStatus": {
+        "type": "string",
+        "enum": [
+          "SUCCESS",
+          "FAILURE",
+          "INFO",
+          "SUSPICIOUS"
+        ],
+        "description": "Authentication Audit Event Status\n\nClassification of event outcomes for filtering and analysis."
+      },
+      "AdminLogoutAllDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "forgetDevices": {
+            "type": "boolean",
+            "description": "Whether to also forget/revoke all trusted devices\n\nIf true, all trusted devices for this user will be revoked, requiring MFA on next login from any device.\n\nDefault: false (devices remain trusted)",
+            "examples": [
+              false
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for admin logout all sessions"
+      },
+      "AdminRemoveDevicesDTO": {
+        "type": "object",
+        "properties": {
+          "methodType": {
+            "type": "string",
+            "description": "MFA method type to remove\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          },
+          "sub": {
+            "type": "string",
+            "description": "Target user's unique identifier (UUID v4)",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "methodType",
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Admin DTO for removing MFA devices for a specific user\n\nAdmin APIs must explicitly target a user via `sub`. This DTO mirrors  {@link  RemoveDevicesDTO }  but adds `sub`."
+      },
+      "AdminResetPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User sub (UUID)\n\nValidation:\n- Must be a valid UUID v4\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "deliveryMethod": {
+            "type": "string",
+            "enum": [
+              "email",
+              "sms"
+            ],
+            "description": "Delivery method for reset code\n\nValidation:\n- Must be 'email' or 'sms'\n- Optional (defaults to 'email')",
+            "default": "email"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Base URL for building reset link\n\nValidation:\n- Must be valid URL with http:// or https://\n- Supports localhost URLs (e.g., http://localhost:4200)\n- Max 2048 characters\n- Optional\n\nSanitization:\n- Trimmed\n\nWHY: Allows consumer apps to build custom reset UI (e.g., myapp.com/reset-password?token=xxx) Like email verification, supports both code AND link delivery",
+            "examples": [
+              "https://myapp.com/reset-password",
+              "http://localhost:4200"
+            ]
+          },
+          "codeExpiresIn": {
+            "type": "number",
+            "description": "Code expiry in seconds\n\nValidation:\n- Must be number\n- Min 300 seconds (5 minutes)\n- Max 86400 seconds (24 hours)\n- Optional",
+            "examples": [
+              3600
+            ],
+            "default": "3600 (1 hour - longer than user-initiated 15min)"
+          },
+          "revokeSessions": {
+            "type": "boolean",
+            "description": "Revoke all active sessions immediately (before sending email)\n\nValidation:\n- Must be boolean\n- Optional\n\nWHY: Admin can lock user out immediately while sending reset email Different from confirmAdminResetPassword which always revokes on completion",
+            "examples": [
+              true
+            ],
+            "default": false
+          },
+          "reason": {
+            "type": "string",
+            "description": "Reason for admin-initiated reset (for audit trail)\n\nValidation:\n- Must be string\n- Max 500 characters\n- Optional\n\nSanitization:\n- Trimmed",
+            "examples": [
+              "User reported account compromise"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for admin password reset"
+      },
+      "AdminResetPasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Success indicator Always true on successful request"
+          },
+          "destination": {
+            "type": "string",
+            "description": "Masked destination where code was sent"
+          },
+          "deliveryMedium": {
+            "type": "string",
+            "enum": [
+              "email",
+              "sms"
+            ],
+            "description": "Delivery medium used"
+          },
+          "expiresIn": {
+            "type": "number",
+            "description": "Code expiry in seconds",
+            "examples": [
+              3600
+            ]
+          },
+          "sessionsRevoked": {
+            "type": "number",
+            "description": "Number of sessions revoked (if revokeSessions was true)",
+            "examples": [
+              3
+            ]
+          }
+        },
+        "required": [
+          "success"
+        ],
+        "additionalProperties": false,
+        "description": "Admin Reset Password Response DTO\n\nResponse DTO for admin-initiated password reset request."
+      },
+      "AdminRevokeSessionDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User sub (UUID) - must match the session owner"
+          },
+          "sessionId": {
+            "type": "string",
+            "description": "Session ID to revoke"
+          }
+        },
+        "required": [
+          "sub",
+          "sessionId"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for revoking a specific user session (admin-only)"
+      },
+      "AdminSetPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User sub (UUID)\n\nValidation:\n- Must be a valid UUID v4\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password\n\nValidation:\n- Must be a string\n- Min 8 characters (security requirement)\n- Max 128 characters (prevents DoS)\n\nNote: NOT trimmed (passwords can have leading/trailing spaces) Additional checks in service layer:\n- Password strength (if configured)\n- Password history (prevent reuse)"
+          },
+          "mustChangePassword": {
+            "type": "boolean",
+            "description": "Require user to change password on next login\n\nDefault: true (security best practice)",
+            "examples": [
+              true
+            ]
+          },
+          "revokeSessions": {
+            "type": "boolean",
+            "description": "Revoke all active sessions after password reset\n\nDefault: true (security best practice)",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "sub",
+          "newPassword"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for admin password reset"
+      },
+      "AdminSetPasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Success indicator Always true on successful password reset"
+          },
+          "mustChangePassword": {
+            "type": "boolean",
+            "description": "Whether user must change password on next login"
+          },
+          "sessionsRevoked": {
+            "type": "number",
+            "description": "Number of sessions revoked"
+          }
+        },
+        "required": [
+          "success",
+          "mustChangePassword",
+          "sessionsRevoked"
+        ],
+        "additionalProperties": false,
+        "description": "Admin Set Password Response DTO\n\nResponse DTO for admin password reset operation."
+      },
+      "AdminSetPreferredMethodDTO": {
+        "type": "object",
+        "properties": {
+          "methodType": {
+            "type": "string",
+            "description": "MFA method type to set as preferred\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          },
+          "sub": {
+            "type": "string",
+            "description": "Target user's unique identifier (UUID v4)",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "methodType",
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Admin DTO for setting preferred MFA method for a specific user\n\nAdmin APIs must explicitly target a user via `sub`. This DTO mirrors  {@link  SetPreferredMethodDTO }  but adds `sub`."
+      },
+      "AdminSignupDTO": {
+        "type": "object",
+        "properties": {
+          "email": {
+            "type": "string",
+            "description": "User email address\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB limit)\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "password": {
+            "type": "string",
+            "description": "User password\n\nRequired unless `generatePassword` is true.\n\nValidation:\n- Min 8 characters\n- Max 128 characters (prevents DoS via bcrypt)\n- Additional policy checks in service layer\n\nNote: NOT trimmed (passwords can have leading/trailing spaces)"
+          },
+          "username": {
+            "type": "string",
+            "description": "Optional username\n\nValidation:\n- 3-50 characters\n- Alphanumeric, underscores, and hyphens only\n- Max 255 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Case preserved (username can be case-sensitive per config)"
+          },
+          "firstName": {
+            "type": "string",
+            "description": "Optional first name\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "lastName": {
+            "type": "string",
+            "description": "Optional last name\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Optional phone number\n\nValidation:\n- E.164 format (international standard)\n- MUST start with + (required for security)\n- Max 20 characters (DB limit)\n- Example: +14155552671, +61444567890\n\nSanitization:\n- Whitespace removed\n- Only digits and leading + preserved\n\nSecurity:\n- Strict E.164 validation prevents SQL injection\n- Max length prevents oversized inputs"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional metadata (custom fields)\n\nSecurity:\n- Validated in service layer if used\n- Max depth/size limits should be enforced"
+          },
+          "isEmailVerified": {
+            "type": "boolean",
+            "description": "Bypass email verification requirement\n\nIf true, user's email is marked as verified without sending verification email. If false (default), user must verify email through normal flow.\n\nDefault: false"
+          },
+          "isPhoneVerified": {
+            "type": "boolean",
+            "description": "Bypass phone verification requirement\n\nIf true, user's phone is marked as verified without sending verification SMS. If false (default), user must verify phone through normal flow.\n\nDefault: false"
+          },
+          "mustChangePassword": {
+            "type": "boolean",
+            "description": "Force password change on first login\n\nIf true, user will be required to change password on next login. Useful when auto-generating passwords or when admin sets temporary passwords.\n\nDefault: false"
+          },
+          "generatePassword": {
+            "type": "boolean",
+            "description": "Auto-generate secure password\n\nIf true, a cryptographically secure random password will be generated. The generated password will be returned in the response (returned once only). Password field is not required when this is true.\n\nDefault: false\n\nSecurity: Generated passwords are 16 characters, mixed case, numbers, and special characters. They are returned once in the response and never stored in plain text."
+          }
+        },
+        "required": [
+          "email"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for administrative user creation with override capabilities\n\nAllows administrators to create user accounts with:\n- Bypass email/phone verification requirements\n- Force password change on first login\n- Auto-generate secure passwords\n\nSecurity:\n- All fields validated against DB constraints\n- Input sanitization applied automatically\n- Password strength enforced (8-128 chars) unless auto-generated\n- Email/username uniqueness checked in service layer\n- Audit trail records admin-created accounts\n\nWarning: This endpoint should be protected by admin authentication. The service does not enforce authorization - it is the responsibility of the framework adapter (NestJS/Express/Fastify) to protect the endpoint."
+      },
+      "Record<string,unknown>": {
+        "type": "object",
+        "additionalProperties": {}
+      },
+      "AdminSignupResponseDTO": {
+        "type": "object",
+        "properties": {
+          "user": {
+            "$ref": "#/components/schemas/UserResponseDto",
+            "description": "Created user object (sanitized)\n\nUses UserResponseDto which excludes sensitive fields:\n- No passwordHash\n- No internal database ID (uses 'sub' UUID instead)\n- No MFA secrets\n- No internal tracking fields"
+          },
+          "generatedPassword": {
+            "type": "string",
+            "description": "Generated password (only present if generatePassword was true)\n\nSecurity: This is returned once and never stored in plain text. The admin should securely deliver this to the user."
+          }
+        },
+        "required": [
+          "user"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for admin signup\n\nReturns the created user object (sanitized, excludes sensitive fields like passwordHash) and optionally the generated password (only if generatePassword was true in the request)."
+      },
+      "UserResponseDto": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "External user identifier (UUID v4) This is the 'sub' (subject) field from JWT tokens"
+          },
+          "email": {
+            "type": "string",
+            "description": "User's email address"
+          },
+          "username": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User's username (optional)"
+          },
+          "firstName": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User's first name (optional)"
+          },
+          "lastName": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User's last name (optional)"
+          },
+          "phone": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User's phone number (optional) E.164 format validated in service layer if present"
+          },
+          "isEmailVerified": {
+            "type": "boolean",
+            "description": "Email verification status"
+          },
+          "isPhoneVerified": {
+            "type": "boolean",
+            "description": "Phone verification status"
+          },
+          "isActive": {
+            "type": "boolean",
+            "description": "Account active status"
+          },
+          "isLocked": {
+            "type": "boolean",
+            "description": "Account lock status Locked accounts cannot login until unlocked"
+          },
+          "mfaEnabled": {
+            "type": "boolean",
+            "description": "MFA enabled status"
+          },
+          "mfaExempt": {
+            "type": "boolean",
+            "description": "MFA exemption status (admin-granted bypass of MFA at login)"
+          },
+          "socialProviders": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Array of social providers linked to this account\n\nExamples: ['google', 'apple', 'facebook'] null/undefined means no social auth, only password-based"
+          },
+          "hasPasswordHash": {
+            "type": "boolean",
+            "description": "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)"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Account creation timestamp"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Last account update timestamp"
+          }
+        },
+        "required": [
+          "sub",
+          "email",
+          "isEmailVerified",
+          "isPhoneVerified",
+          "isActive",
+          "isLocked",
+          "mfaEnabled",
+          "mfaExempt",
+          "hasPasswordHash",
+          "createdAt",
+          "updatedAt"
+        ],
+        "additionalProperties": false,
+        "description": "User Response DTO\n\nSanitized user object for API responses. Excludes all sensitive and internal fields.\n\nSecurity:\n- Never exposes password hash\n- Never exposes MFA secrets\n- Never exposes internal tracking fields\n- Exposes 'sub' (external UUID) instead of internal 'id'\n\nNo validators needed - this is generated internally by the library via fromEntity()."
+      },
+      "AdminSignupSocialDTO": {
+        "type": "object",
+        "properties": {
+          "email": {
+            "type": "string",
+            "description": "User email address\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB limit)\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "firstName": {
+            "type": "string",
+            "description": "Optional first name\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "isPhoneVerified": {
+            "type": "boolean",
+            "description": "Bypass phone verification requirement\n\nIf true, user's phone is marked as verified without sending verification SMS. If false (default), user must verify phone through normal flow.\n\nDefault: false"
+          },
+          "lastName": {
+            "type": "string",
+            "description": "Optional last name\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional metadata (custom fields)\n\nSecurity:\n- Validated in service layer if used\n- Max depth/size limits should be enforced"
+          },
+          "mustChangePassword": {
+            "type": "boolean",
+            "description": "Force password change on first login\n\nIf true, user will be required to change password on next login. Only relevant if password is provided (hybrid social+password account).\n\nDefault: false"
+          },
+          "password": {
+            "type": "string",
+            "description": "Optional password for hybrid social+password accounts\n\nValidation:\n- Min 8 characters\n- Max 128 characters (prevents DoS via bcrypt)\n- Additional policy checks in service layer\n\nNote: NOT trimmed (passwords can have leading/trailing spaces)\n\nSecurity: If not provided, user will be social-only (no password login). Password can be set later via setPasswordForSocialUser()."
+          },
+          "phone": {
+            "type": "string",
+            "description": "Optional phone number\n\nValidation:\n- E.164 format (international standard)\n- MUST start with + (required for security)\n- Max 20 characters (DB limit)\n- Example: +14155552671, +61444567890\n\nSanitization:\n- Whitespace removed\n- Only digits and leading + preserved\n\nSecurity:\n- Strict E.164 validation prevents SQL injection\n- Max length prevents oversized inputs"
+          },
+          "provider": {
+            "type": "string",
+            "enum": [
+              "google",
+              "apple",
+              "facebook"
+            ],
+            "description": "Social provider name\n\nThe OAuth provider that the user authenticated with. Must match one of the supported providers.\n\nValidation:\n- Must be 'google', 'apple', or 'facebook'\n- Required field"
+          },
+          "providerEmail": {
+            "type": "string",
+            "description": "Provider's email address\n\nThe email address associated with the user's social account. May differ from primary email if user has multiple email addresses. Used for audit trails and account linking verification.\n\nValidation:\n- Valid email format\n- Max 255 characters\n\nOptional: Some providers (like Apple with private relay) may not expose email."
+          },
+          "providerId": {
+            "type": "string",
+            "description": "Provider's unique user identifier\n\nThe unique ID assigned by the OAuth provider (e.g., Google sub, Apple user ID). Used to link the social account to the user record.\n\nValidation:\n- Required field\n- Max 255 characters (DB limit)\n- Unique per provider (enforced at DB level)\n\nSecurity: provider+providerId combination must be unique across all users."
+          },
+          "socialMetadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Raw OAuth profile data from provider\n\nStores the complete OAuth profile response from the provider. Useful for debugging, audit trails, and extracting additional user attributes.\n\nSecurity:\n- Stored as JSON in database\n- Not exposed in public APIs\n- Used internally for troubleshooting"
+          },
+          "username": {
+            "type": "string",
+            "description": "Optional username\n\nValidation:\n- 3-50 characters\n- Alphanumeric, underscores, and hyphens only\n- Max 255 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Lowercased"
+          }
+        },
+        "required": [
+          "email",
+          "provider",
+          "providerId"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for administrative social user import with override capabilities\n\nAllows administrators to import existing social users from external platforms (e.g., Cognito, Auth0) into nauth with:\n- Automatic email verification (like normal social signup)\n- Optional phone verification bypass\n- Optional password for hybrid social+password accounts\n- Social account linkage (provider + providerId)\n- Automatic user flag updates (hasSocialAuth)\n\nUse case: Migrating users from external authentication platforms while preserving their social login connections for transparent future logins.\n\nSecurity:\n- All fields validated against DB constraints\n- Input sanitization applied automatically\n- Email/username uniqueness checked in service layer\n- Provider+providerId uniqueness enforced (one social account per provider per user)\n- Audit trail records admin-imported social accounts\n\nWarning: This endpoint should be protected by admin authentication. The service does not enforce authorization - it is the responsibility of the framework adapter (NestJS/Express/Fastify) to protect the endpoint."
+      },
+      "AdminSignupSocialResponseDTO": {
+        "type": "object",
+        "properties": {
+          "socialAccount": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string",
+                "description": "Social provider name"
+              },
+              "providerId": {
+                "type": "string",
+                "description": "Provider's unique user identifier"
+              },
+              "providerEmail": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Provider's email address (if available)"
+              }
+            },
+            "required": [
+              "provider",
+              "providerId",
+              "providerEmail"
+            ],
+            "additionalProperties": false,
+            "description": "Social account information\n\nConfirms the social account linkage for the imported user."
+          },
+          "user": {
+            "$ref": "#/components/schemas/UserResponseDto",
+            "description": "Created user object (sanitized)\n\nUses UserResponseDto which excludes sensitive fields:\n- No passwordHash\n- No internal database ID (uses 'sub' UUID instead)\n- No MFA secrets\n- No internal tracking fields"
+          }
+        },
+        "required": [
+          "socialAccount",
+          "user"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for admin social signup\n\nReturns the created user object (sanitized, excludes sensitive fields like passwordHash) and social account information for confirmation."
+      },
+      "AdminUpdateUserAttributesDTO": {
+        "type": "object",
+        "properties": {
+          "username": {
+            "type": "string",
+            "description": "Optional username update\n\nValidation:\n- 3-50 characters\n- Alphanumeric, underscores, and hyphens only\n- Max 255 characters (DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Trimmed\n- Case preserved (username can be case-sensitive per config)"
+          },
+          "firstName": {
+            "type": "string",
+            "description": "Optional first name update\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "lastName": {
+            "type": "string",
+            "description": "Optional last name update\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "email": {
+            "type": "string",
+            "description": "Optional email address update\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Optional phone number update\n\nValidation:\n- E.164 format (international standard)\n- MUST start with + (required for security)\n- Max 20 characters (DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Whitespace removed\n- Only digits and leading + preserved\n\nSecurity:\n- Strict E.164 validation prevents SQL injection\n- Max length prevents oversized inputs"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional metadata update (custom fields)\n\nBehavior:\n- Existing metadata is merged with new values\n- To delete a metadata key, set it to null\n- To update a value, provide the new value\n- To add a new key, include it in the object\n\nSecurity:\n- Validated in service layer if used\n- Max depth/size limits should be enforced"
+          },
+          "preferredMfaMethod": {
+            "$ref": "#/components/schemas/MFADeviceMethod",
+            "description": "Optional preferred MFA method\n\nSets the user's preferred MFA method for authentication. Must be one of the MFA device methods the user has configured.\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters (matches typical method name length)"
+          },
+          "retainVerification": {
+            "type": "boolean",
+            "description": "Optional flag to retain verification status when updating email/phone\n\nWhen true:\n- Email verification status is preserved when email is updated\n- Phone verification status is preserved when phone is updated\n- Useful when verification was done externally or outside nauth-toolkit\n\nWhen false or undefined (default):\n- Email verification is reset to false when email is updated\n- Phone verification is reset to false when phone is updated\n- User must re-verify the new email/phone"
+          },
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for admin updating user attributes (includes sub)"
+      },
+      "MFADeviceMethod": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/MFAMethod.TOTP"
+          },
+          {
+            "$ref": "#/components/schemas/MFAMethod.SMS"
+          },
+          {
+            "$ref": "#/components/schemas/MFAMethod.EMAIL"
+          },
+          {
+            "$ref": "#/components/schemas/MFAMethod.PASSKEY"
+          }
+        ],
+        "description": "Device MFA methods (methods that require device setup)\n\nExcludes BACKUP as it's not a device method."
+      },
+      "MFAMethod.TOTP": {
+        "type": "string",
+        "const": "totp",
+        "description": "Time-based One-Time Password Authenticator apps (Google Authenticator, Authy, Microsoft Authenticator, etc.)"
+      },
+      "MFAMethod.SMS": {
+        "type": "string",
+        "const": "sms",
+        "description": "SMS verification codes Sends one-time codes via text message"
+      },
+      "MFAMethod.EMAIL": {
+        "type": "string",
+        "const": "email",
+        "description": "Email verification codes Sends one-time codes via email"
+      },
+      "MFAMethod.PASSKEY": {
+        "type": "string",
+        "const": "passkey",
+        "description": "WebAuthn/FIDO2 passkeys Biometric authentication (Face ID, Touch ID, Windows Hello) Hardware security keys (YubiKey, etc.)"
+      },
+      "AuthChallenge": {
+        "type": "string",
+        "enum": [
+          "VERIFY_EMAIL",
+          "VERIFY_PHONE",
+          "MFA_REQUIRED",
+          "MFA_SETUP_REQUIRED",
+          "FORCE_CHANGE_PASSWORD"
+        ],
+        "description": "Authentication Challenge Types\n\nRepresents different challenges that must be completed before a user can gain full access to the system. This is similar to AWS Cognito's challenge system."
+      },
+      "AuthChallengeResponseDTO": {
+        "type": "object",
+        "properties": {
+          "challengeName": {
+            "$ref": "#/components/schemas/AuthChallenge",
+            "description": "The challenge that must be completed\n\nValidation:\n- Must be a valid AuthChallenge enum value"
+          },
+          "session": {
+            "type": "string",
+            "description": "Temporary session identifier for challenge completion (UUID v4) This is NOT a full JWT token - only used for challenge verification\n\nValidation:\n- Must be a valid UUID v4 format\n- Generated using randomUUID() in challenge service",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "challengeParameters": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Challenge-specific parameters Contains information needed to complete the challenge\n\nValidation:\n- Must be an object"
+          },
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4) Provided so the client knows which user is completing challenges\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "challengeName",
+          "session",
+          "challengeParameters",
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Challenge Response DTO\n\nUsed when a user's authentication is incomplete due to pending challenges. Contains minimal information about the user and what challenges they must complete.\n\nNote: This is primarily a response DTO, but validation is included for completeness."
+      },
+      "AuthResponseDTO": {
+        "type": "object",
+        "properties": {
+          "accessToken": {
+            "type": "string",
+            "description": "JWT access token for API authentication Short-lived (typically 15 minutes)\n\nNOTE: Only present when authentication is complete (no pending challenges)"
+          },
+          "refreshToken": {
+            "type": "string",
+            "description": "JWT refresh token for obtaining new access tokens Long-lived (typically 30 days)\n\nNOTE: Only present when authentication is complete (no pending challenges)"
+          },
+          "accessTokenExpiresAt": {
+            "type": "number",
+            "description": "Access token expiration timestamp Unix timestamp in seconds"
+          },
+          "refreshTokenExpiresAt": {
+            "type": "number",
+            "description": "Refresh token expiration timestamp Unix timestamp in seconds"
+          },
+          "authMethod": {
+            "type": "string",
+            "description": "Authentication method used to create the current session (when authentication succeeds).\n\nSemantics:\n- `password`: email/username/phone + password login, or password-first flows\n- `<provider>`: social login provider that created the session (e.g., `google`, `apple`, `facebook`)\n\nNotes:\n- This is session-scoped state (not account capability). Account capabilities are expressed via:   - `user.hasPasswordHash`   - `user.socialProviders`\n- Only present when authentication is complete (no pending challenges)."
+          },
+          "trusted": {
+            "type": "boolean",
+            "description": "Whether the current device is already trusted\n\nWhen true, the device has a valid trusted device token and UI should NOT show \"trust device\" popup.\n\nWhen false and rememberDevices === 'user_opt_in', UI can show popup after login to allow user to opt-in for device trust.\n\nWhen rememberDevices === 'always', this will always be true after successful login.\n\nNOTE: Only present when authentication is complete (no pending challenges)"
+          },
+          "deviceToken": {
+            "type": "string",
+            "description": "Device token for trusted device feature (UUID v4)\n\nServer-generated UUID token for identifying trusted devices. Only returned when rememberDevices is not 'never' and device is trusted.\n\nDelivery by mode:\n- **cookies mode**: Token set as `nauth_device_token` httpOnly cookie (not in response body)\n- **json/hybrid mode**: Token returned in response body for mobile apps\n\nMobile apps should:\n- Store token in secure storage (iOS Keychain / Android EncryptedSharedPreferences)\n- Send token in `X-Device-Token` header on subsequent logins\n- Token persists across app restarts and survives logout\n\nWeb apps:\n- Token automatically handled via httpOnly cookie (cookies mode)\n- No manual handling required"
+          },
+          "user": {
+            "$ref": "#/components/schemas/AuthResponseUser",
+            "description": "User information Standardized across all authentication methods\n\nNOTE: Only present when authentication is complete (no pending challenges)"
+          },
+          "challengeName": {
+            "$ref": "#/components/schemas/AuthChallenge",
+            "description": "Challenge that must be completed before authentication is granted\n\nWhen present, the user must complete this challenge using the challenge completion endpoint before they can access the system.\n\nTokens (accessToken, refreshToken) will NOT be present when a challenge exists."
+          },
+          "session": {
+            "type": "string",
+            "description": "Temporary session identifier for challenge completion (UUID v4)\n\nThis 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."
+          },
+          "challengeParameters": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Challenge-specific parameters\n\nContains information needed to complete the challenge, such as:\n- Masked email/phone for delivery confirmation\n- Challenge type details\n- Instructions for the user\n\nNOTE: Only present when challengeName is set"
+          },
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4) Present in both successful auth and challenge responses Helps the client track which user is authenticating",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "additionalProperties": false,
+        "description": "Unified Authentication Response DTO\n\nUsed for ALL authentication operations:\n- Email/password login\n- User signup\n- Social authentication (Google, Apple, Facebook)\n- Token refresh\n- Challenge completions\n\nThis provides a consistent interface regardless of authentication method, improving developer experience and code maintainability.\n\nWhen challenges are present, tokens will not be issued until all challenges are completed. This ensures proper verification and security enforcement.\n\nNo validators needed - this is generated internally by the library."
+      },
+      "AuthResponseUser": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4) External identifier safe to expose in JWTs and APIs"
+          },
+          "email": {
+            "type": "string",
+            "description": "User's email address"
+          },
+          "firstName": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User's first name (optional)"
+          },
+          "lastName": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "User's last name (optional)"
+          },
+          "phone": {
+            "type": "string",
+            "description": "User's phone number (optional) E.164 format"
+          },
+          "isEmailVerified": {
+            "type": "boolean",
+            "description": "Email verification status"
+          },
+          "isPhoneVerified": {
+            "type": "boolean",
+            "description": "Phone verification status"
+          },
+          "socialProviders": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "List of linked social providers"
+          },
+          "hasPasswordHash": {
+            "type": "boolean",
+            "description": "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)"
+          }
+        },
+        "required": [
+          "sub",
+          "email",
+          "isEmailVerified"
+        ],
+        "additionalProperties": false,
+        "description": "User information in authentication responses\n\nMinimal user object returned in AuthResponseDTO. Contains only essential fields needed for client applications."
+      },
+      "BaseChallengeResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          }
+        },
+        "required": [
+          "session"
+        ],
+        "additionalProperties": false,
+        "description": "Base interface for all challenge responses"
+      },
+      "CanSetPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User identifier (UUID v4)\n\nValidation:\n- Must be valid UUID v4 format\n\nSanitization:\n- Trimmed and lowercased"
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for checking if user can set password\n\nSecurity:\n- User sub validated as UUID v4"
+      },
+      "CanSetPasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "canSetPassword": {
+            "type": "boolean",
+            "description": "Whether user can set password"
+          }
+        },
+        "required": [
+          "canSetPassword"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for canSetPassword"
+      },
+      "ChallengeResponseData": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/VerifyEmailResponse"
+          },
+          {
+            "$ref": "#/components/schemas/CollectPhoneResponse"
+          },
+          {
+            "$ref": "#/components/schemas/VerifyPhoneResponse"
+          },
+          {
+            "$ref": "#/components/schemas/VerifyMFACodeResponse"
+          },
+          {
+            "$ref": "#/components/schemas/VerifyMFAPasskeyResponse"
+          },
+          {
+            "$ref": "#/components/schemas/ForceChangePasswordResponse"
+          },
+          {
+            "$ref": "#/components/schemas/MFASetupResponse"
+          }
+        ],
+        "description": "Discriminated union of all challenge response types\n\nUse this type for the unified respondToChallenge() API. TypeScript will narrow the type based on the 'type' discriminator."
+      },
+      "VerifyEmailResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "VERIFY_EMAIL"
+          },
+          "code": {
+            "type": "string",
+            "description": "6-digit verification code sent to email"
+          }
+        },
+        "required": [
+          "code",
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for email verification challenge"
+      },
+      "CollectPhoneResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "VERIFY_PHONE"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Phone number in E.164 format"
+          }
+        },
+        "required": [
+          "phone",
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for collecting phone number (first step)"
+      },
+      "VerifyPhoneResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "VERIFY_PHONE"
+          },
+          "code": {
+            "type": "string",
+            "description": "6-digit verification code sent to phone"
+          }
+        },
+        "required": [
+          "code",
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for verifying phone with code (second step)"
+      },
+      "VerifyMFACodeResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "MFA_REQUIRED"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "sms",
+              "totp",
+              "backup"
+            ],
+            "description": "MFA method being used"
+          },
+          "code": {
+            "type": "string",
+            "description": "Verification code"
+          }
+        },
+        "required": [
+          "code",
+          "method",
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for MFA verification with code (SMS/TOTP/Backup)"
+      },
+      "VerifyMFAPasskeyResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "MFA_REQUIRED"
+          },
+          "method": {
+            "type": "string",
+            "const": "passkey",
+            "description": "Passkey method"
+          },
+          "credential": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "WebAuthn credential from navigator.credentials.get()"
+          }
+        },
+        "required": [
+          "credential",
+          "method",
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for MFA verification with passkey"
+      },
+      "ForceChangePasswordResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "FORCE_CHANGE_PASSWORD"
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password meeting security requirements"
+          }
+        },
+        "required": [
+          "newPassword",
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for forced password change challenge"
+      },
+      "MFASetupResponse": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token"
+          },
+          "type": {
+            "type": "string",
+            "const": "MFA_SETUP_REQUIRED"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "sms",
+              "email",
+              "totp",
+              "passkey"
+            ],
+            "description": "MFA method being set up"
+          },
+          "setupData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Method-specific setup data\n- SMS: { phone: string, code: string }\n- TOTP: { code: string }\n- Passkey: { credential: Record<string, unknown> }"
+          }
+        },
+        "required": [
+          "method",
+          "session",
+          "setupData",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Response for MFA setup during challenge"
+      },
+      "ChallengeResponseRequestDTO": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Temporary session from initial auth response (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Generated using randomUUID() in challenge service\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "challengeName": {
+            "$ref": "#/components/schemas/AuthChallenge",
+            "description": "The challenge being responded to\n\nValidation:\n- Must be a valid AuthChallenge enum value"
+          },
+          "challengeResponses": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Challenge-specific responses\n\nValidation:\n- Must be an object\n- Structure validated in service layer based on challenge type"
+          }
+        },
+        "required": [
+          "session",
+          "challengeName",
+          "challengeResponses"
+        ],
+        "additionalProperties": false,
+        "description": "Challenge Completion Request DTO\n\nUsed to submit a response to an authentication challenge.\n\nNote: This is a legacy DTO. The codebase now uses RespondChallengeDTO for the unified API. This DTO is kept for backwards compatibility.\n\nSecurity:\n- Session token validated as UUID v4 format\n- Challenge name validated against enum\n- Challenge responses validated as object"
+      },
+      "ChallengeType": {
+        "type": "string",
+        "enum": [
+          "VERIFY_EMAIL",
+          "VERIFY_PHONE",
+          "MFA_REQUIRED",
+          "FORCE_CHANGE_PASSWORD",
+          "MFA_SETUP_REQUIRED"
+        ],
+        "description": "Challenge type enum for validation"
+      },
+      "ChangePasswordDTO": {
+        "type": "object",
+        "properties": {
+          "oldPassword": {
+            "type": "string",
+            "description": "Current password\n\nValidation:\n- Must be a string\n\nNote: NOT trimmed (passwords can have leading/trailing spaces)"
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password\n\nValidation:\n- Must be a string\n- Min 8 characters (security requirement)\n- Max 128 characters (prevents DoS via bcrypt)\n\nNote: NOT trimmed (passwords can have leading/trailing spaces)\n\nAdditional checks in service layer:\n- Password history (prevent reuse of recent passwords)\n- Password strength (if configured)\n- Not same as old password"
+          }
+        },
+        "required": [
+          "oldPassword",
+          "newPassword"
+        ],
+        "additionalProperties": false
+      },
+      "ChangePasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Success indicator Always true on successful password change",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "success"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for change password"
+      },
+      "ConfirmAdminResetPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User sub (UUID)\n\nValidation:\n- Must be a valid UUID v4\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "code": {
+            "type": "string",
+            "description": "Verification code from email/SMS (6-10 digits)\n\nValidation:\n- Must be string\n- Length 6-10 characters\n- Required\n\nSanitization:\n- Trimmed\n\nWHY: Short code for manual entry, subject to attempt tracking",
+            "examples": [
+              "123456"
+            ]
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password\n\nValidation:\n- Must be string\n- Min 8 characters (security requirement)\n- Max 128 characters (prevents DoS)\n\nNote: NOT trimmed (passwords can have leading/trailing spaces) Additional checks in service layer:\n- Password strength (if configured)\n- Password history (prevent reuse)",
+            "examples": [
+              "NewSecurePassword123!"
+            ]
+          }
+        },
+        "required": [
+          "sub",
+          "code",
+          "newPassword"
+        ],
+        "additionalProperties": false,
+        "description": "Confirm Admin Reset Password DTO\n\nUser completes admin-initiated password reset with a verification code.\n\nNOTE:\n- Link support is optional, but links carry the same verification `code` as a query parameter   (e.g., `...?code=123456`) to keep consumer apps consistent (code-only).\n\nSecurity:\n- Code is required\n- Attempt tracking enforced (max attempts configured in password reset service)\n- Always revokes all sessions on completion\n- Always sets mustChangePassword flag"
+      },
+      "ConfirmAdminResetPasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Success indicator Always true on successful reset"
+          }
+        },
+        "required": [
+          "success"
+        ],
+        "additionalProperties": false,
+        "description": "Confirm Admin Reset Password Response DTO\n\nResponse DTO for successful admin password reset completion."
+      },
+      "ConfirmForgotPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "identifier": {
+            "type": "string",
+            "description": "User identifier used to locate the account.\n\nSanitization:\n- Trimmed\n- Lowercased when email format detected (contains '@')"
+          },
+          "code": {
+            "type": "string",
+            "description": "Verification code delivered via email/SMS.\n\nValidation:\n- Numeric string\n- Exact length 6 (default). If a deployment changes length, the service layer   can also validate against config for backward compatibility."
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password to set on the account.\n\nValidation:\n- 8-128 characters (baseline)\n- NOT trimmed (passwords may intentionally contain leading/trailing spaces)"
+          }
+        },
+        "required": [
+          "identifier",
+          "code",
+          "newPassword"
+        ],
+        "additionalProperties": false,
+        "description": "Confirm Forgot Password DTO\n\nConfirms a password reset request by validating the verification code and setting a new password.\n\nSecurity:\n- Code format validated (numeric string + fixed length).\n- Password policy is enforced in the service layer."
+      },
+      "ConfirmForgotPasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "True when reset was confirmed and password updated."
+          },
+          "mustChangePassword": {
+            "type": "boolean",
+            "description": "Whether user must change password on next sign-in.\n\nFor forgot-password flows this should typically be false (password is just set)."
+          }
+        },
+        "required": [
+          "success",
+          "mustChangePassword"
+        ],
+        "additionalProperties": false,
+        "description": "Confirm Forgot Password Response DTO\n\nResponse for a confirmed password reset."
+      },
+      "DateFilterDTO": {
+        "type": "object",
+        "properties": {
+          "operator": {
+            "type": "string",
+            "enum": [
+              "gt",
+              "gte",
+              "lt",
+              "lte",
+              "eq"
+            ],
+            "description": "Comparison operator\n\n- gt: greater than\n- gte: greater than or equal\n- lt: less than\n- lte: less than or equal\n- eq: equal"
+          },
+          "value": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Date value to compare against"
+          }
+        },
+        "required": [
+          "operator",
+          "value"
+        ],
+        "additionalProperties": false,
+        "description": "Date filter with operator support\n\nSupports gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal), eq (equal) operators for date comparisons."
+      },
+      "DeleteUserDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User UUID (sub) to delete\n\nMust be valid UUID format"
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for administrative user deletion\n\nPermanently deletes user and ALL associated data:\n- Sessions, verification tokens, MFA devices, trusted devices\n- Social accounts, login attempts, challenge sessions, audit logs\n\nWarning: IRREVERSIBLE - All user data permanently removed from database."
+      },
+      "DeleteUserResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Deletion success flag"
+          },
+          "deletedUserId": {
+            "type": "string",
+            "description": "Deleted user's UUID"
+          },
+          "deletedRecords": {
+            "type": "object",
+            "properties": {
+              "sessions": {
+                "type": "number"
+              },
+              "verificationTokens": {
+                "type": "number"
+              },
+              "mfaDevices": {
+                "type": "number"
+              },
+              "trustedDevices": {
+                "type": "number"
+              },
+              "socialAccounts": {
+                "type": "number"
+              },
+              "loginAttempts": {
+                "type": "number"
+              },
+              "challengeSessions": {
+                "type": "number"
+              },
+              "auditLogs": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "sessions",
+              "verificationTokens",
+              "mfaDevices",
+              "trustedDevices",
+              "socialAccounts",
+              "loginAttempts",
+              "challengeSessions",
+              "auditLogs"
+            ],
+            "additionalProperties": false,
+            "description": "Count of cascade-deleted records by table"
+          }
+        },
+        "required": [
+          "success",
+          "deletedUserId",
+          "deletedRecords"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for administrative user deletion\n\nConfirms deletion and provides counts of cascade-deleted records."
+      },
+      "DisableUserDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User UUID (sub) to disable\n\nMust be valid UUID format"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Optional reason for locking account\n\nRecorded in lockReason field and audit trail. Max 500 characters."
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for administrative permanent account locking\n\nLocks user account permanently (lockedUntil=NULL) and revokes all active sessions. Uses existing rate-limit lock fields (isLocked, lockReason, lockedAt, lockedUntil).\n\nPermanent vs Temporary locks:\n- Rate limiting: lockedUntil = future date (temporary auto-unlock)\n- Admin disableUser: lockedUntil = NULL (permanent manual lock)"
+      },
+      "DisableUserResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Lock success flag"
+          },
+          "user": {
+            "$ref": "#/components/schemas/UserResponseDto",
+            "description": "Sanitized user object with updated lock status"
+          },
+          "revokedSessions": {
+            "type": "number",
+            "description": "Number of sessions revoked (forced logout)"
+          }
+        },
+        "required": [
+          "success",
+          "user",
+          "revokedSessions"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for administrative account locking"
+      },
+      "EnableUserDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User UUID (sub) to enable\n\nMust be valid UUID format"
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for administrative account unlocking\n\nUnlocks a previously locked user account by clearing lock fields. This reverses the effect of disableUser() or rate-limit lockouts."
+      },
+      "EnableUserResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Unlock success flag"
+          },
+          "user": {
+            "$ref": "#/components/schemas/UserResponseDto",
+            "description": "Sanitized user object with updated lock status"
+          }
+        },
+        "required": [
+          "success",
+          "user"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for administrative account unlocking"
+      },
+      "ForgotPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "identifier": {
+            "type": "string",
+            "description": "User identifier used to locate the account.\n\nAccepts email, username, or phone depending on application login policy.\n\nSanitization:\n- Trimmed\n- Lowercased when email format detected (contains '@')"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Base URL for building reset link\n\nValidation:\n- Must be valid URL with http:// or https://\n- Supports localhost URLs (e.g., http://localhost:4200)\n- Max 2048 characters\n- Optional\n\nSanitization:\n- Trimmed\n\nWHY: Allows consumer apps to build custom reset UI (e.g., myapp.com/reset-password?token=xxx) Like email verification and admin reset, supports both code AND link delivery",
+            "examples": [
+              "https://myapp.com/reset-password",
+              "http://localhost:4200"
+            ]
+          }
+        },
+        "required": [
+          "identifier"
+        ],
+        "additionalProperties": false,
+        "description": "Forgot Password DTO\n\nRequest a password reset code for a user account.\n\nSecurity:\n- This endpoint should not reveal whether an account exists.\n- Identifier is sanitized (trimmed, email lowercased when detected)."
+      },
+      "ForgotPasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Always true when request accepted (regardless of account existence)."
+          },
+          "destination": {
+            "type": "string",
+            "description": "Masked delivery destination (email or phone) when available.\n\nExamples:\n- `j***@example.com`\n- `+1***1234`"
+          },
+          "deliveryMedium": {
+            "type": "string",
+            "enum": [
+              "email",
+              "sms"
+            ],
+            "description": "Delivery channel used."
+          },
+          "expiresIn": {
+            "type": "number",
+            "description": "Code expiry in seconds."
+          }
+        },
+        "required": [
+          "success"
+        ],
+        "additionalProperties": false,
+        "description": "Forgot Password Response DTO\n\nResponse for a password reset request.\n\nSecurity:\n- `success` should be true even when the identifier does not map to any user,   to prevent account enumeration."
+      },
+      "GetAvailableMethodsDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for getting available MFA methods"
+      },
+      "GetAvailableMethodsResponseDTO": {
+        "type": "object",
+        "properties": {
+          "availableMethods": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of available method names",
+            "examples": [
+              [
+                "totp",
+                "sms",
+                "passkey",
+                "email"
+              ]
+            ]
+          }
+        },
+        "required": [
+          "availableMethods"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for available MFA methods"
+      },
+      "GetChallengeDataDTO": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Generated using randomUUID() in challenge service\n- Matches DB constraint: varchar(255) but UUID format enforced\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "method": {
+            "$ref": "#/components/schemas/MFAChallengeMethod",
+            "description": "MFA method requiring challenge data\n\nValidation:\n- Must be 'passkey' (WebAuthn options), 'sms' (sends code), or 'email' (sends code)"
+          }
+        },
+        "required": [
+          "session",
+          "method"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for getting MFA challenge data"
+      },
+      "MFAChallengeMethod": {
+        "type": "string",
+        "enum": [
+          "passkey",
+          "sms",
+          "email"
+        ],
+        "description": "MFA method enum for challenge data Supports passkey (WebAuthn options), SMS (sends code), and Email (sends code)"
+      },
+      "GetChallengeDataResponseDTO": {
+        "type": "object",
+        "properties": {
+          "challengeData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Provider-specific challenge data\n\nType varies by method:\n- Passkey: WebAuthn public key options object   Structure: { publicKey: { challenge: string, allowCredentials: [...], ... } }\n- SMS: Masked phone number string (e.g., '***-***-1234')\n- Email: Masked email address string (e.g., 'u***r@example.com')\n\nNote: Type is `Record<string, unknown>` which accommodates both object and string types. Frontend should check `typeof challengeData === 'string'` to determine if it's SMS/Email (string) or Passkey (object)."
+          }
+        },
+        "required": [
+          "challengeData"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for challenge data"
+      },
+      "GetClientInfoResponseDTO": {
+        "type": "object",
+        "properties": {
+          "ipAddress": {
+            "type": "string",
+            "description": "Client IP address\n\nExtracted from X-Forwarded-For, CF-Connecting-IP, etc. Automatically handles proxies and load balancers. Returns 'unknown' if called outside request context."
+          },
+          "userAgent": {
+            "type": "string",
+            "description": "User agent string from the request\n\nReturns 'unknown' if called outside request context."
+          },
+          "deviceToken": {
+            "type": "string",
+            "description": "Device token for trusted device feature\n\nExtracted from cookie (nauth_device_token) or header (X-Device-Token). Optional - only present if device token exists."
+          },
+          "deviceName": {
+            "type": "string",
+            "description": "Optional device name (if provided by client)"
+          },
+          "deviceType": {
+            "type": "string",
+            "enum": [
+              "mobile",
+              "desktop",
+              "tablet"
+            ],
+            "description": "Optional device type (if provided by client)"
+          },
+          "ipCountry": {
+            "type": "string",
+            "description": "Optional IP country (from geolocation, if available)"
+          },
+          "ipCity": {
+            "type": "string",
+            "description": "Optional IP city (from geolocation, if available)"
+          },
+          "ipLatitude": {
+            "type": "number",
+            "description": "Optional IP latitude (from geolocation, if available) Used for impossible travel detection"
+          },
+          "ipLongitude": {
+            "type": "number",
+            "description": "Optional IP longitude (from geolocation, if available) Used for impossible travel detection"
+          },
+          "platform": {
+            "type": "string",
+            "description": "Platform extracted from user agent\n\nExamples: \"iOS\", \"Android\", \"Windows\", \"macOS\""
+          },
+          "browser": {
+            "type": "string",
+            "description": "Browser extracted from user agent\n\nExamples: \"Chrome\", \"Safari\", \"Firefox\""
+          },
+          "sessionId": {
+            "type": "number",
+            "description": "Current session ID (if available from authenticated request)\n\nExtracted from JWT token payload after authentication."
+          },
+          "userId": {
+            "type": "number",
+            "description": "Current user ID (if available from authenticated request)\n\nExtracted from JWT token payload (sub claim) after authentication. Used to identify who performed an action (e.g., for audit trails)."
+          },
+          "sub": {
+            "type": "string",
+            "description": "Current user's sub (UUID, if available from authenticated request). Prefer this over userId for performedBy in audit and mfaExemptGrantedBy."
+          }
+        },
+        "required": [
+          "ipAddress",
+          "userAgent"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for client information"
+      },
+      "GetDeviceTokenResponseDTO": {
+        "type": "object",
+        "properties": {
+          "deviceToken": {
+            "type": "string",
+            "description": "Device token for trusted device feature\n\nExtracted from cookie (nauth_device_token) or header (X-Device-Token). Optional - undefined if not present."
+          }
+        },
+        "additionalProperties": false,
+        "description": "Response DTO for device token"
+      },
+      "GetIpAddressResponseDTO": {
+        "type": "object",
+        "properties": {
+          "ipAddress": {
+            "type": "string",
+            "description": "Client IP address\n\nExtracted from X-Forwarded-For, CF-Connecting-IP, etc. Returns 'unknown' if called outside request context."
+          }
+        },
+        "required": [
+          "ipAddress"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for IP address"
+      },
+      "GetLinkedAccountsDTO": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "DTO for getting linked social accounts\n\nSecurity:\n- User ID validated as UUID v4"
+      },
+      "GetLinkedAccountsResponseDTO": {
+        "type": "object",
+        "properties": {
+          "accounts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "provider": {
+                  "type": "string"
+                },
+                "providerEmail": {
+                  "type": "string"
+                },
+                "linkedAt": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "lastUsedAt": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              },
+              "required": [
+                "provider",
+                "linkedAt"
+              ],
+              "additionalProperties": false
+            },
+            "description": "Array of linked social accounts"
+          }
+        },
+        "required": [
+          "accounts"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for getLinkedAccounts"
+      },
+      "GetMFAStatusResponseDTO": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether MFA is enabled for the user"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether MFA is required (enabled and has configured devices)"
+          },
+          "configuredMethods": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MFADeviceMethod"
+            },
+            "description": "Array of configured MFA device methods"
+          },
+          "availableMethods": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of available MFA methods that can be set up"
+          },
+          "hasBackupCodes": {
+            "type": "boolean",
+            "description": "Whether user has backup codes"
+          },
+          "preferredMethod": {
+            "$ref": "#/components/schemas/MFADeviceMethod",
+            "description": "Preferred MFA method (if set)"
+          },
+          "mfaExempt": {
+            "type": "boolean",
+            "description": "Whether user is exempt from MFA requirements"
+          },
+          "mfaExemptReason": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Reason for MFA exemption (if exempt)"
+          },
+          "mfaExemptGrantedAt": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Date when MFA exemption was granted (if exempt)"
+          }
+        },
+        "required": [
+          "enabled",
+          "required",
+          "configuredMethods",
+          "availableMethods",
+          "hasBackupCodes",
+          "mfaExempt",
+          "mfaExemptReason",
+          "mfaExemptGrantedAt"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for MFA status\n\nReturned by MFAService.getMfaStatus() (user self-service) and MFAService.adminGetMfaStatus() (admin operation)."
+      },
+      "GetSessionIdResponseDTO": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "number",
+            "description": "Current session ID (if available from authenticated request)\n\nExtracted from JWT token payload after authentication. Optional - undefined if not available."
+          }
+        },
+        "additionalProperties": false,
+        "description": "Response DTO for session ID"
+      },
+      "GetSetupDataDTO": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Generated using randomUUID() in challenge service\n- Matches DB constraint: varchar(255) but UUID format enforced\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "method": {
+            "$ref": "#/components/schemas/MFAMethod",
+            "description": "MFA method to set up\n\nValidation:\n- Must be one of: sms, email, totp, passkey"
+          },
+          "setupData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional provider-specific setup data\n\nValidation:\n- Must be an object if provided\n- Structure validated by MFA provider services"
+          }
+        },
+        "required": [
+          "session",
+          "method"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for getting MFA setup data"
+      },
+      "MFAMethod": {
+        "type": "string",
+        "enum": [
+          "totp",
+          "sms",
+          "email",
+          "passkey",
+          "backup"
+        ],
+        "description": "All supported MFA methods\n\nUse this enum instead of string literals throughout the codebase."
+      },
+      "GetSetupDataResponseDTO": {
+        "type": "object",
+        "properties": {
+          "setupData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Provider-specific setup data\n\nStructure varies by method:\n- TOTP: { secret: string, qrCode: string, manualEntryKey: string }\n- SMS: { maskedPhone: string }\n- Email: { maskedEmail: string }\n- Passkey: WebAuthn registration options"
+          }
+        },
+        "required": [
+          "setupData"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for setup data"
+      },
+      "GetUserAgentResponseDTO": {
+        "type": "object",
+        "properties": {
+          "userAgent": {
+            "type": "string",
+            "description": "User agent string from the request\n\nReturns 'unknown' if called outside request context."
+          }
+        },
+        "required": [
+          "userAgent"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for user agent"
+      },
+      "GetUserAuthHistoryDTO": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "type": "number",
+            "description": "Page number (1-indexed)",
+            "default": 1
+          },
+          "limit": {
+            "type": "number",
+            "description": "Number of records per page",
+            "default": 50
+          },
+          "startDate": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events from this date onwards"
+          },
+          "endDate": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events up to this date"
+          },
+          "eventTypes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AuthAuditEventType"
+            },
+            "description": "Filter by specific event types\n\nIf provided, only events matching these types will be returned."
+          },
+          "eventStatus": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AuthAuditEventStatus"
+            },
+            "description": "Filter by event status\n\nIf provided, only events matching these statuses will be returned."
+          }
+        },
+        "additionalProperties": false,
+        "description": "Request DTO for getting user authentication history (user self-service)\n\nUser self-service DTO - no userSub field. Service gets user from authenticated context."
+      },
+      "GetUserAuthHistoryResponseDTO": {
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/IAuthAudit"
+            },
+            "description": "Array of audit records"
+          },
+          "total": {
+            "type": "number",
+            "description": "Total number of records matching the query"
+          },
+          "page": {
+            "type": "number",
+            "description": "Current page number"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Number of records per page"
+          },
+          "totalPages": {
+            "type": "number",
+            "description": "Total number of pages"
+          }
+        },
+        "required": [
+          "data",
+          "total",
+          "page",
+          "limit",
+          "totalPages"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for paginated user authentication history"
+      },
+      "IAuthAudit": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number"
+          },
+          "userId": {
+            "type": "number"
+          },
+          "eventType": {
+            "type": "string"
+          },
+          "eventStatus": {
+            "type": "string",
+            "enum": [
+              "SUCCESS",
+              "FAILURE",
+              "INFO",
+              "SUSPICIOUS"
+            ]
+          },
+          "riskFactor": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "riskFactors": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "adaptiveMfaTriggered": {
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "ipAddress": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "ipCountry": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "ipCity": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "userAgent": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "platform": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "browser": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "deviceId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "deviceName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "deviceType": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sessionId": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "challengeSessionId": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "authMethod": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "performedBy": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "metadata": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "id",
+          "userId",
+          "eventType",
+          "eventStatus",
+          "createdAt"
+        ],
+        "additionalProperties": false,
+        "description": "Authentication Audit Entity Interface\n\nAudit trail record for authentication and security events"
+      },
+      "GetUserByEmailDTO": {
+        "type": "object",
+        "properties": {
+          "email": {
+            "type": "string",
+            "description": "Email address to search for\n\nValidation:\n- Must be a valid email format\n- Max 255 characters (matches DB constraint)\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "user@example.com"
+            ]
+          },
+          "requireEmailVerified": {
+            "type": "boolean",
+            "description": "Only return user if email is verified\n\nValidation:\n- Must be a boolean if present\n- Default: false",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "email"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for getting user by email"
+      },
+      "GetUserByIdDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for getting user by ID"
+      },
+      "GetUserDevicesDTO": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "DTO for getting user MFA devices\n\nUser self-service DTO - no sub field. Service gets user from authenticated context."
+      },
+      "GetUserDevicesResponseDTO": {
+        "type": "object",
+        "properties": {
+          "devices": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/IMFADevice"
+            },
+            "description": "Array of user's MFA devices"
+          }
+        },
+        "required": [
+          "devices"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for user MFA devices"
+      },
+      "IMFADevice": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number"
+          },
+          "userId": {
+            "type": "number"
+          },
+          "type": {
+            "$ref": "#/components/schemas/MFADeviceMethod"
+          },
+          "name": {
+            "type": "string"
+          },
+          "secret": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "credentialId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "publicKey": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "counter": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "transports": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "phoneNumber": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "email": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "isPrimary": {
+            "type": "boolean"
+          },
+          "isActive": {
+            "type": "boolean"
+          },
+          "lastUsedAt": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "id",
+          "userId",
+          "type",
+          "name",
+          "secret",
+          "credentialId",
+          "publicKey",
+          "counter",
+          "transports",
+          "isActive",
+          "lastUsedAt",
+          "createdAt"
+        ],
+        "additionalProperties": false
+      },
+      "GetUserSessionsDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User sub (UUID)"
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for getting user sessions"
+      },
+      "GetUserSessionsResponseDTO": {
+        "type": "object",
+        "properties": {
+          "sessions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UserSessionInfo"
+            },
+            "description": "Array of user sessions"
+          }
+        },
+        "required": [
+          "sessions"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for getting user sessions"
+      },
+      "UserSessionInfo": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string",
+            "description": "Session ID"
+          },
+          "deviceId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Device ID"
+          },
+          "deviceName": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Device name"
+          },
+          "deviceType": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Device type"
+          },
+          "platform": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Platform"
+          },
+          "browser": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Browser"
+          },
+          "ipAddress": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "IP address"
+          },
+          "ipCountry": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "IP country"
+          },
+          "ipCity": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "IP city"
+          },
+          "lastActivityAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Last activity timestamp"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Session creation timestamp"
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Session expiration timestamp"
+          },
+          "isRemembered": {
+            "type": "boolean",
+            "description": "Whether session is remembered"
+          },
+          "isCurrent": {
+            "type": "boolean",
+            "description": "Whether this is the current session"
+          },
+          "authMethod": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Authentication method used for this session Examples: 'password', 'social', 'admin', 'admin-social' For social logins, check authProvider for the specific OAuth provider"
+          },
+          "authProvider": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "OAuth provider name (only present for social logins) Examples: 'google', 'facebook', 'github', 'apple'"
+          }
+        },
+        "required": [
+          "sessionId",
+          "deviceId",
+          "deviceName",
+          "deviceType",
+          "platform",
+          "browser",
+          "ipAddress",
+          "ipCountry",
+          "ipCity",
+          "lastActivityAt",
+          "createdAt",
+          "expiresAt",
+          "isRemembered",
+          "isCurrent",
+          "authMethod",
+          "authProvider"
+        ],
+        "additionalProperties": false,
+        "description": "Session information in user sessions response"
+      },
+      "GetUsersDTO": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "type": "number",
+            "description": "Page number (1-indexed)\n\nDefault: 1"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Number of records per page\n\nDefault: 10, Max: 100"
+          },
+          "email": {
+            "type": "string",
+            "description": "Filter by email address (partial match)\n\nSupports partial matching using LIKE query. Example: \"john\" will match \"john@example.com\", \"johnny@test.com\", etc."
+          },
+          "phone": {
+            "type": "string",
+            "description": "Filter by phone number (partial match)\n\nSupports partial matching using LIKE query. Example: \"+1\" will match \"+14155552671\", \"+12025551234\", etc."
+          },
+          "isEmailVerified": {
+            "type": "boolean",
+            "description": "Filter by email verification status"
+          },
+          "isPhoneVerified": {
+            "type": "boolean",
+            "description": "Filter by phone verification status"
+          },
+          "hasSocialAuth": {
+            "type": "boolean",
+            "description": "Filter by social auth presence"
+          },
+          "isLocked": {
+            "type": "boolean",
+            "description": "Filter by account lock status"
+          },
+          "mfaEnabled": {
+            "type": "boolean",
+            "description": "Filter by MFA enabled status"
+          },
+          "createdAt": {
+            "$ref": "#/components/schemas/DateFilterDTO",
+            "description": "Filter by account creation date\n\nSupports operators: gt, gte, lt, lte, eq"
+          },
+          "updatedAt": {
+            "$ref": "#/components/schemas/DateFilterDTO",
+            "description": "Filter by last update date\n\nSupports operators: gt, gte, lt, lte, eq"
+          },
+          "sortBy": {
+            "type": "string",
+            "enum": [
+              "email",
+              "createdAt",
+              "updatedAt",
+              "username",
+              "phone"
+            ],
+            "description": "Field to sort by\n\nDefault: createdAt"
+          },
+          "sortOrder": {
+            "type": "string",
+            "enum": [
+              "ASC",
+              "DESC"
+            ],
+            "description": "Sort order\n\nDefault: DESC"
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for paginated user listing with advanced filtering\n\nSupports pagination, boolean filters, exact match filters, date filters with operators, and flexible sorting."
+      },
+      "GetUsersResponseDTO": {
+        "type": "object",
+        "properties": {
+          "users": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UserResponseDto"
+            },
+            "description": "Array of sanitized user objects"
+          },
+          "pagination": {
+            "type": "object",
+            "properties": {
+              "page": {
+                "type": "number"
+              },
+              "limit": {
+                "type": "number"
+              },
+              "total": {
+                "type": "number"
+              },
+              "totalPages": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "page",
+              "limit",
+              "total",
+              "totalPages"
+            ],
+            "additionalProperties": false,
+            "description": "Pagination metadata"
+          }
+        },
+        "required": [
+          "users",
+          "pagination"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for paginated user listing"
+      },
+      "HandleCallbackDTO": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Authorization code from OAuth callback\n\nValidation:\n- Must be non-empty string\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "state": {
+            "type": "string",
+            "description": "State parameter from OAuth callback (for CSRF validation)\n\nValidation:\n- Must be non-empty string\n- Max 500 characters\n\nSanitization:\n- Trimmed"
+          }
+        },
+        "required": [
+          "code",
+          "state"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for handling OAuth callback\n\nUsed when processing OAuth callback from social providers after user authorization.\n\nSecurity:\n- Code validated for length\n- State validated for CSRF protection"
+      },
+      "HasProviderDTO": {
+        "type": "object",
+        "properties": {
+          "methodName": {
+            "type": "string",
+            "description": "Provider method name\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          }
+        },
+        "required": [
+          "methodName"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for checking if MFA provider is registered"
+      },
+      "HasProviderResponseDTO": {
+        "type": "object",
+        "properties": {
+          "hasProvider": {
+            "type": "boolean",
+            "description": "Whether provider is registered"
+          }
+        },
+        "required": [
+          "hasProvider"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for has provider check"
+      },
+      "IsTrustedDeviceResponseDTO": {
+        "type": "object",
+        "properties": {
+          "trusted": {
+            "type": "boolean",
+            "description": "Whether the current device is trusted\n\nTrue 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.",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "trusted"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for checking trusted device status"
+      },
+      "JwtPayload": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User ID (subject)"
+          },
+          "email": {
+            "type": "string",
+            "description": "User email"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "access",
+              "refresh"
+            ],
+            "description": "Token type - always 'access' for access tokens"
+          },
+          "sessionId": {
+            "type": "string",
+            "description": "Session ID"
+          },
+          "tokenFamily": {
+            "type": "string",
+            "description": "Token family ID (for rotation detection)"
+          },
+          "iat": {
+            "type": "number",
+            "description": "Issued at timestamp (Unix epoch)"
+          },
+          "exp": {
+            "type": "number",
+            "description": "Expiration timestamp (Unix epoch)"
+          },
+          "iss": {
+            "type": "string",
+            "description": "Issuer"
+          },
+          "aud": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ],
+            "description": "Audience"
+          },
+          "deviceId": {
+            "type": "string",
+            "description": "Device ID"
+          }
+        },
+        "required": [
+          "sub",
+          "email",
+          "type",
+          "sessionId",
+          "iat",
+          "exp"
+        ],
+        "additionalProperties": false,
+        "description": "JWT Payload structure for validated tokens\n\nContains all claims present in a valid access token."
+      },
+      "LinkSocialAccountDTO": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "Social provider name (e.g., 'google', 'apple', 'facebook')\n\nValidation:\n- Must be non-empty string\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "code": {
+            "type": "string",
+            "description": "Authorization code from OAuth callback\n\nValidation:\n- Must be non-empty string\n- Max 1000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "state": {
+            "type": "string",
+            "description": "State parameter from OAuth callback (for CSRF validation)\n\nValidation:\n- Must be non-empty string\n- Max 500 characters\n\nSanitization:\n- Trimmed"
+          }
+        },
+        "required": [
+          "provider",
+          "code",
+          "state"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for linking social account\n\nSecurity:\n- User ID validated as UUID v4\n- Provider name validated\n- Code and state validated for length"
+      },
+      "LinkSocialAccountResponseDTO": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Success message"
+          },
+          "provider": {
+            "type": "string",
+            "description": "Provider name"
+          }
+        },
+        "required": [
+          "message",
+          "provider"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for linkSocialAccount"
+      },
+      "ListProvidersResponseDTO": {
+        "type": "object",
+        "properties": {
+          "providers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of registered provider method names",
+            "examples": [
+              [
+                "totp",
+                "sms",
+                "passkey"
+              ]
+            ]
+          }
+        },
+        "required": [
+          "providers"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for listing providers"
+      },
+      "LoginDTO": {
+        "type": "object",
+        "properties": {
+          "identifier": {
+            "type": "string",
+            "description": "Login identifier (email, username, or phone)\n\nValidation:\n- At least 1 character\n- Max 255 characters (prevents attacks)\n\nSanitization:\n- Trimmed\n- Lowercased if it looks like email"
+          },
+          "password": {
+            "type": "string",
+            "description": "User password\n\nValidation:\n- At least 1 character (lenient for login)\n- Max 128 characters (prevents DoS)\n\nNote: NOT trimmed (passwords can have spaces)"
+          },
+          "deviceName": {
+            "type": "string",
+            "description": "Optional device name for session identification\n\nValidation:\n- Max 255 characters (matches DB constraint: varchar(255))\n\nSanitization:\n- Trimmed"
+          },
+          "deviceType": {
+            "type": "string",
+            "enum": [
+              "mobile",
+              "desktop",
+              "tablet"
+            ],
+            "description": "Optional device type\n\nValidation:\n- Must be one of: mobile, desktop, tablet\n- Max 50 characters (matches DB constraint: varchar(50))\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "recaptchaToken": {
+            "type": "string",
+            "description": "Optional reCAPTCHA token\n\nRequired when server has reCAPTCHA enabled and enforces validation for the current token delivery mode (typically 'cookies' for web).\n\nValidation:\n- Must be a string\n- Token is single-use and expires after 2 minutes\n- Token must be generated for correct action (e.g., 'login')\n\nSecurity:\n- Token validation happens server-side only\n- Invalid/expired tokens result in RECAPTCHA_VALIDATION_FAILED error\n- Low scores (v3) result in RECAPTCHA_SCORE_TOO_LOW error"
+          }
+        },
+        "required": [
+          "identifier",
+          "password"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for user login with security-focused validation\n\nSecurity:\n- Identifier validated (email, username, or phone)\n- Password length enforced\n- Input sanitization applied\n- DeviceId validated if provided"
+      },
+      "LogoutAllDTO": {
+        "type": "object",
+        "properties": {
+          "forgetDevices": {
+            "type": "boolean",
+            "description": "Whether to also forget/revoke all trusted devices\n\nIf true, all trusted devices for this user will be revoked, requiring MFA on next login from any device.\n\nDefault: false (devices remain trusted)",
+            "examples": [
+              false
+            ]
+          }
+        },
+        "additionalProperties": false,
+        "description": "Request DTO for logout all sessions"
+      },
+      "LogoutAllResponseDTO": {
+        "type": "object",
+        "properties": {
+          "revokedCount": {
+            "type": "number",
+            "description": "Number of sessions revoked",
+            "examples": [
+              5
+            ]
+          }
+        },
+        "required": [
+          "revokedCount"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for logout all sessions"
+      },
+      "LogoutDTO": {
+        "type": "object",
+        "properties": {
+          "forgetMe": {
+            "type": "boolean",
+            "description": "If true, also removes trusted device\n\nValidation:\n- Must be a boolean if present\n- Default: false",
+            "examples": [
+              false
+            ]
+          }
+        },
+        "additionalProperties": false,
+        "description": "Request DTO for logout"
+      },
+      "LogoutResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Success indicator Always true on successful logout",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "success"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for logout"
+      },
+      "LogoutSessionDTO": {
+        "type": "object",
+        "properties": {
+          "sessionId": {
+            "type": "string",
+            "description": "Session ID to revoke"
+          }
+        },
+        "required": [
+          "sessionId"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for logging out a specific session"
+      },
+      "LogoutSessionResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Whether the session was successfully revoked"
+          },
+          "wasCurrentSession": {
+            "type": "boolean",
+            "description": "Whether the revoked session was the current session"
+          }
+        },
+        "required": [
+          "success",
+          "wasCurrentSession"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for logging out a specific session"
+      },
+      "MFAMethodType": {
+        "type": "string",
+        "enum": [
+          "sms",
+          "email",
+          "totp",
+          "passkey",
+          "backup"
+        ],
+        "description": "MFA method enum for validation"
+      },
+      "RefreshTokenDTO": {
+        "type": "object",
+        "properties": {
+          "refreshToken": {
+            "type": "string",
+            "description": "JWT refresh token\n\nOptional to support cookies mode where token is read from cookie. If provided, must be a valid string with min 10 characters.\n\nValidation:\n- Optional (allows cookies mode with empty body)\n- If provided, must be a string\n- If provided, min 10 characters (minimum valid JWT length)\n- If provided, max 2048 characters (prevents DoS, typical JWT is 200-500 chars)\n\nNote: Token format and signature validated in service layer Note: Controller fills this from cookies if empty in cookies mode"
+          }
+        },
+        "additionalProperties": false,
+        "description": "Refresh Token DTO\n\nUsed for refreshing access tokens with a valid refresh token.\n\nSupports both JSON and cookies token delivery modes:\n- JSON mode: refreshToken must be provided in request body\n- Cookies mode: refreshToken is optional in body (read from cookie by controller)\n\nSecurity:\n- Token length validated (prevents DoS)\n- JWT tokens can be long, but we validate input length\n- Token is validated in service layer for format and signature"
+      },
+      "RemoveDevicesDTO": {
+        "type": "object",
+        "properties": {
+          "methodType": {
+            "type": "string",
+            "description": "MFA method type to remove\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          }
+        },
+        "required": [
+          "methodType"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for removing MFA devices\n\nUser self-service DTO - no userSub field. Service gets user from authenticated context."
+      },
+      "RemoveDevicesResponseDTO": {
+        "type": "object",
+        "properties": {
+          "deletedCount": {
+            "type": "number",
+            "description": "Number of devices deleted"
+          },
+          "mfaDisabled": {
+            "type": "boolean",
+            "description": "Whether MFA was disabled (if this was the last device)"
+          }
+        },
+        "required": [
+          "deletedCount",
+          "mfaDisabled"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for removing devices"
+      },
+      "ResendCodeDTO": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Generated using randomUUID() in challenge service\n- Matches DB constraint: varchar(255) but UUID format enforced\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "session"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for resending verification code"
+      },
+      "ResendCodeResponseDTO": {
+        "type": "object",
+        "properties": {
+          "destination": {
+            "type": "string",
+            "description": "Masked destination where code was sent\n\nFormat:\n- Email: \"u***r@example.com\"\n- Phone: \"+1***5678\"",
+            "examples": [
+              "u***r@example.com"
+            ]
+          }
+        },
+        "required": [
+          "destination"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for resend code"
+      },
+      "ResendVerificationEmailDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User identifier (UUID v4) - optional if email provided\n\nValidation:\n- Must be valid UUID v4 format if provided\n- Required if email is not provided\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "email": {
+            "type": "string",
+            "description": "User's email address - optional if sub provided\n\nValidation:\n- Valid email format if provided\n- Max 255 characters (DB limit)\n- Required if sub is not provided\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Base URL for verification link (optional)\n\nValidation:\n- Must be valid URL format (http:// or https://)\n- Max 2048 characters\n- Optional field\n\nSanitization:\n- Trimmed"
+          },
+          "challengeSessionId": {
+            "type": "number",
+            "description": "Challenge session ID (internal use) Optional - used internally to link verification to specific challenge session. Provides security by ensuring codes are only valid for the session they were created for.\n\nValidation:\n- Must be a positive integer if provided\n- Optional (for backward compatibility and direct verification flows)"
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for requesting a verification email resend\n\nSupports both overload patterns: 1. Resend by user sub (string) 2. Resend by email address (object with email property)\n\nSecurity:\n- Either sub or email must be provided (conditional validation)\n- Rate limiting applied in service layer\n- Input sanitization prevents abuse"
+      },
+      "ResendVerificationEmailResponseDTO": {
+        "type": "object",
+        "properties": {
+          "tokenId": {
+            "type": "number",
+            "description": "Verification token ID (internal integer)"
+          }
+        },
+        "required": [
+          "tokenId"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for resendVerificationEmail"
+      },
+      "ResendVerificationSMSDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User identifier (UUID v4) - optional if phone provided\n\nValidation:\n- Must be valid UUID v4 format if provided\n- Required if phone is not provided\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "phone": {
+            "type": "string",
+            "description": "User's phone number - optional if sub provided\n\nValidation:\n- Must match E.164 format if provided\n- Max 20 characters (DB limit)\n- Required if sub is not provided\n\nSanitization:\n- Whitespace removed"
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for resending verification SMS\n\nSupports both sub and phone-based resend\n\nSecurity:\n- Either sub or phone must be provided (conditional validation)\n- Rate limiting applied in service layer\n- Input sanitization prevents abuse"
+      },
+      "ResendVerificationSMSResponseDTO": {
+        "type": "object",
+        "properties": {
+          "tokenId": {
+            "type": "number",
+            "description": "Verification token ID (internal integer)"
+          }
+        },
+        "required": [
+          "tokenId"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for resendVerificationSMS"
+      },
+      "ResetPasswordDTO": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "description": "Password reset token from email\n\nValidation:\n- Must be a string\n- Min 1 character (prevents empty strings)\n- Max 255 characters (matches DB constraint: varchar(255))\n\nSanitization:\n- Trimmed\n\nNote: Token format and validity validated in service layer"
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password\n\nValidation:\n- Must be a string\n- Min 8 characters (security requirement)\n- Max 128 characters (prevents DoS via bcrypt)\n\nNote: NOT trimmed (passwords can have leading/trailing spaces) Additional checks in service layer:\n- Password strength (if configured)\n- Password history (prevent reuse)"
+          }
+        },
+        "required": [
+          "token",
+          "newPassword"
+        ],
+        "additionalProperties": false,
+        "description": "Reset Password DTO\n\nUsed to reset password with a valid reset token.\n\nSecurity:\n- Token length validated (matches DB constraint: varchar(255))\n- Password strength enforced (8-128 chars)\n- Token format validated in service layer"
+      },
+      "ResetPasswordRequestDTO": {
+        "type": "object",
+        "properties": {
+          "identifier": {
+            "type": "string",
+            "description": "User identifier (email or phone)\n\nValidation:\n- Must be a string\n- Min 1 character\n- Max 255 characters (matches DB constraint for email)\n\nSanitization:\n- Trimmed\n- Lowercased if email format detected"
+          }
+        },
+        "required": [
+          "identifier"
+        ],
+        "additionalProperties": false,
+        "description": "Reset Password Request DTO\n\nUsed to request a password reset token via email or phone.\n\nSecurity:\n- Identifier validated (email or phone)\n- Input sanitization applied"
+      },
+      "RespondChallengeDTO": {
+        "type": "object",
+        "properties": {
+          "session": {
+            "type": "string",
+            "description": "Challenge session token (UUID v4) Always required\n\nValidation:\n- Must be a valid UUID v4 format\n- Generated using randomUUID() in challenge service\n- Matches DB constraint: varchar(255) but UUID format enforced\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "type": {
+            "$ref": "#/components/schemas/ChallengeType",
+            "description": "Challenge type being responded to Always required"
+          },
+          "code": {
+            "type": "string",
+            "description": "Verification code Required for:\n- VERIFY_EMAIL\n- VERIFY_PHONE (when verifying code)\n- MFA_REQUIRED (for SMS/Email/TOTP/Backup methods)\n\nValidation:\n- Must be a string\n- Length 4-10 characters (covers all code types)\n- Alphanumeric only\n\nNote: NOT trimmed (codes should be exact)"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Phone number in E.164 format Required for VERIFY_PHONE when collecting phone number (first step)\n\nValidation:\n- Must be a string\n- Must match E.164 format: +[country code][number]\n- Example: +14155552671\n- Max 20 characters (matches DB limit)\n\nSanitization:\n- Trimmed\n- Only digits and leading + allowed"
+          },
+          "newPassword": {
+            "type": "string",
+            "description": "New password Required for FORCE_CHANGE_PASSWORD challenge\n\nValidation:\n- Must be a string\n- Min 8 characters (security requirement)\n- Max 128 characters (prevents DoS via bcrypt)\n\nNote: NOT trimmed (passwords can have leading/trailing spaces)"
+          },
+          "method": {
+            "$ref": "#/components/schemas/MFAMethodType",
+            "description": "MFA method being used or set up Required for:\n- MFA_REQUIRED challenge (method being used for verification)\n- MFA_SETUP_REQUIRED challenge (method being set up)\n\nValidation:\n- Must be one of: sms, email, totp, passkey, backup"
+          },
+          "credential": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Passkey credential Required for MFA_REQUIRED when method is 'passkey'\n\nValidation:\n- Must be an object\n- Contains WebAuthn credential from navigator.credentials.get()"
+          },
+          "setupData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "MFA setup data (method-specific) Required for MFA_SETUP_REQUIRED challenge\n\nExpected structure by method:\n- SMS: { phone: string, code: string }\n- Email: { code: string }\n- TOTP: { code: string }\n- Passkey: { credential: Record<string, unknown> }\n\nValidation:\n- Must be an object\n- Structure validated by MFA provider services"
+          }
+        },
+        "required": [
+          "session",
+          "type"
+        ],
+        "additionalProperties": false,
+        "description": "Unified DTO for responding to authentication challenges\n\nUses conditional validation (@ValidateIf) to validate fields based on challenge type. This ensures proper validation while maintaining a single endpoint for all challenge types.\n\nSecurity:\n- All strings have max length constraints matching DB limits\n- Phone numbers validated against E.164 format (prevents SQL injection)\n- Verification codes validated for length (4-10 chars)\n- Passwords validated for strength requirements\n- Session tokens validated as UUID v4 format (prevents injection)"
+      },
+      "SendVerificationEmailDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User identifier (UUID v4)\n\nValidation:\n- Must be valid UUID v4 format\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Base URL for verification link (optional)\n\nValidation:\n- Must be valid URL format (http:// or https://)\n- Supports localhost URLs (e.g., http://localhost:4200)\n- Max 2048 characters (typical URL length limit)\n- Optional field\n\nSanitization:\n- Trimmed"
+          },
+          "skipAlreadyVerifiedCheck": {
+            "type": "boolean",
+            "description": "Skip the \"already verified\" check Used for MFA contexts where codes are needed even if email is verified\n\nValidation:\n- Must be boolean\n- Optional (defaults to false)"
+          },
+          "challengeSessionId": {
+            "type": "number",
+            "description": "Challenge session ID to link this verification token to Optional - for linking verification tokens to specific challenge sessions. Provides security by preventing old tokens from being used with new sessions.\n\nValidation:\n- Must be a positive integer\n- Optional (for backward compatibility and non-challenge flows like password reset)"
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for sending a verification email\n\nSecurity:\n- User sub validated as UUID v4\n- BaseURL validated as max length\n- Skip flag is boolean (prevents injection)"
+      },
+      "SendVerificationEmailResponseDTO": {
+        "type": "object",
+        "properties": {
+          "tokenId": {
+            "type": "number",
+            "description": "Verification token ID (internal integer)"
+          }
+        },
+        "required": [
+          "tokenId"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for sendVerificationEmail"
+      },
+      "SendVerificationSMSDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User identifier (UUID v4)\n\nValidation:\n- Must be valid UUID v4 format\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "skipAlreadyVerifiedCheck": {
+            "type": "boolean",
+            "description": "Skip the \"already verified\" check Used for MFA contexts where codes are needed even if phone is verified\n\nValidation:\n- Must be boolean\n- Optional (defaults to true)"
+          },
+          "challengeSessionId": {
+            "type": "number",
+            "description": "Challenge session ID to link this verification token to Optional - for linking verification tokens to specific challenge sessions. Provides security by preventing old tokens from being used with new sessions.\n\nValidation:\n- Must be a positive integer\n- Optional (for backward compatibility and non-challenge flows)"
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for sending verification SMS\n\nSecurity:\n- User sub validated as UUID v4\n- Skip flag is boolean (prevents injection)"
+      },
+      "SendVerificationSMSResponseDTO": {
+        "type": "object",
+        "properties": {
+          "tokenId": {
+            "type": "number",
+            "description": "Verification token ID (internal integer)"
+          }
+        },
+        "required": [
+          "tokenId"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for sendVerificationSMS"
+      },
+      "SetMFAExemptionDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "exempt": {
+            "type": "boolean",
+            "description": "Whether to grant exemption (true) or revoke exemption (false)"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional reason for the exemption status change\n\nValidation:\n- Max 500 characters\n\nSanitization:\n- Trimmed"
+          },
+          "grantedBy": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional identifier of the admin performing this action. Typically the admin's sub (UUID) when set from authenticated context. Used for mfaExemptGrantedBy on the user and for audit performedBy.\n\nValidation:\n- Max 255 characters\n\nSanitization:\n- Trimmed"
+          }
+        },
+        "required": [
+          "sub",
+          "exempt"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for setting MFA exemption\n\nSECURITY: This DTO targets an arbitrary user; it must only be accepted by admin-protected APIs."
+      },
+      "SetMFAExemptionResponseDTO": {
+        "type": "object",
+        "properties": {
+          "mfaExempt": {
+            "type": "boolean",
+            "description": "Whether user is exempt from MFA requirements"
+          },
+          "mfaExemptReason": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Reason for MFA exemption (if exempt)"
+          },
+          "mfaExemptGrantedAt": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Date when MFA exemption was granted (if exempt)"
+          }
+        },
+        "required": [
+          "mfaExempt",
+          "mfaExemptReason",
+          "mfaExemptGrantedAt"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for setting MFA exemption"
+      },
+      "SetMustChangePasswordDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for setting must change password flag"
+      },
+      "SetMustChangePasswordResponseDTO": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Success indicator Always true on successful flag set",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "success"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for set must change password"
+      },
+      "SetPasswordForSocialUserDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User identifier (UUID v4)\n\nValidation:\n- Must be valid UUID v4 format\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "password": {
+            "type": "string",
+            "description": "New password\n\nValidation:\n- Must be non-empty string\n- Min 1 character (actual validation in AuthService)\n- Max 128 characters (matches DB constraint)\n\nSanitization:\n- Not trimmed (passwords may have leading/trailing spaces intentionally)"
+          }
+        },
+        "required": [
+          "sub",
+          "password"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for setting password for social-only user\n\nSecurity:\n- User sub validated as UUID v4\n- Password validated for strength (delegated to AuthService)"
+      },
+      "SetPasswordForSocialUserResponseDTO": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Success message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for setPasswordForSocialUser"
+      },
+      "SetPreferredMethodDTO": {
+        "type": "object",
+        "properties": {
+          "methodType": {
+            "type": "string",
+            "description": "MFA method type to set as preferred\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          }
+        },
+        "required": [
+          "methodType"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for setting preferred MFA method\n\nUser self-service DTO - no userSub field. Service gets user from authenticated context."
+      },
+      "SetPreferredMethodResponseDTO": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Success message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for setting preferred method"
+      },
+      "SetupMFADTO": {
+        "type": "object",
+        "properties": {
+          "methodName": {
+            "type": "string",
+            "description": "MFA method name\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          },
+          "setupData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional provider-specific setup data\n\nValidation:\n- Must be an object if provided\n- Structure validated by MFA provider services"
+          }
+        },
+        "required": [
+          "methodName"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for setting up MFA device\n\nUser self-service DTO - no sub field. Service gets user from authenticated context."
+      },
+      "SetupMFAResponseDTO": {
+        "type": "object",
+        "properties": {
+          "setupData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Provider-specific setup response\n\nStructure varies by method:\n- TOTP: { secret, qrCode, manualEntryKey }\n- SMS: { maskedPhone }\n- Passkey: WebAuthn registration options"
+          }
+        },
+        "required": [
+          "setupData"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for MFA setup"
+      },
+      "SignupDTO": {
+        "type": "object",
+        "properties": {
+          "email": {
+            "type": "string",
+            "description": "User email address\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB limit)\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "password": {
+            "type": "string",
+            "description": "User password\n\nValidation:\n- Min 8 characters\n- Max 128 characters (prevents DoS via bcrypt)\n- Additional policy checks in service layer\n\nNote: NOT trimmed (passwords can have leading/trailing spaces)"
+          },
+          "username": {
+            "type": "string",
+            "description": "Optional username\n\nValidation:\n- 3-50 characters\n- Alphanumeric, underscores, and hyphens only\n- Max 255 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Case preserved (username can be case-sensitive per config)"
+          },
+          "firstName": {
+            "type": "string",
+            "description": "Optional first name\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "lastName": {
+            "type": "string",
+            "description": "Optional last name\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Optional phone number\n\nValidation:\n- E.164 format (international standard)\n- MUST start with + (required for security)\n- Max 20 characters (DB limit)\n- Example: +14155552671, +61444567890\n\nSanitization:\n- Whitespace removed\n- Only digits and leading + preserved\n\nSecurity:\n- Strict E.164 validation prevents SQL injection\n- Max length prevents oversized inputs\n\nNote: Using regex for E.164 format as IsPhoneNumber requires specific country codes and doesn't support international E.164 format validation directly"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional metadata (custom fields)\n\nSecurity:\n- Validated in service layer if used\n- Max depth/size limits should be enforced"
+          },
+          "recaptchaToken": {
+            "type": "string",
+            "description": "Optional reCAPTCHA token\n\nRequired when server has reCAPTCHA enabled and enforces validation for the current token delivery mode (typically 'cookies' for web).\n\nValidation:\n- Must be a string\n- Token is single-use and expires after 2 minutes\n- Token must be generated for correct action (e.g., 'signup')\n\nSecurity:\n- Token validation happens server-side only\n- Invalid/expired tokens result in RECAPTCHA_VALIDATION_FAILED error\n- Low scores (v3) result in RECAPTCHA_SCORE_TOO_LOW error"
+          }
+        },
+        "required": [
+          "email",
+          "password"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for user signup with comprehensive validation\n\nSecurity:\n- All fields validated against DB constraints\n- Input sanitization applied automatically\n- Password strength enforced (8-128 chars)\n- Email/username uniqueness checked in service layer"
+      },
+      "SocialCallbackFormDTO": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "OAuth authorization code from provider\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "state": {
+            "type": "string",
+            "description": "OAuth state parameter for CSRF protection\n\nValidation:\n- Optional field\n- Max 500 characters\n\nSanitization:\n- Trimmed"
+          },
+          "error": {
+            "type": "string",
+            "description": "Provider error code (if user cancels or error occurs)\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "error_description": {
+            "type": "string",
+            "description": "Provider error description\n\nValidation:\n- Optional field\n- Max 4000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "scope": {
+            "type": "string",
+            "description": "Provider callback extras (for validation compatibility)\n\nIncluded for parity with GET callback DTO to avoid strict validation issues.\n\nValidation:\n- Optional field\n- Max 4000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "authuser": {
+            "type": "string",
+            "description": "Provider-specific parameter\n\nValidation:\n- Optional field\n- Max 50 characters\n\nSanitization:\n- Trimmed"
+          },
+          "hd": {
+            "type": "string",
+            "description": "Provider-specific parameter\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Provider-specific parameter\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for Apple form_post OAuth callbacks\n\nApple uses POST form_post response mode instead of query parameters. This DTO handles the form data sent to the callback endpoint."
+      },
+      "SocialCallbackQueryDTO": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "OAuth authorization code from provider\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "state": {
+            "type": "string",
+            "description": "OAuth state parameter for CSRF protection\n\nValidation:\n- Optional field\n- Max 500 characters\n\nSanitization:\n- Trimmed"
+          },
+          "error": {
+            "type": "string",
+            "description": "Provider error code (if user cancels or error occurs)\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed",
+            "examples": [
+              "access_denied"
+            ]
+          },
+          "error_description": {
+            "type": "string",
+            "description": "Provider error description\n\nValidation:\n- Optional field\n- Max 4000 characters\n\nSanitization:\n- Trimmed",
+            "examples": [
+              "User cancelled the authentication request"
+            ]
+          },
+          "scope": {
+            "type": "string",
+            "description": "Google-specific: OAuth scope parameter\n\nGoogle often includes this in the callback. Explicitly allowed to avoid validation errors when using whitelist + forbidNonWhitelisted validation.\n\nValidation:\n- Optional field\n- Max 4000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "authuser": {
+            "type": "string",
+            "description": "Google-specific: Authenticated user index\n\nValidation:\n- Optional field\n- Max 50 characters\n\nSanitization:\n- Trimmed"
+          },
+          "hd": {
+            "type": "string",
+            "description": "Google-specific: Hosted domain parameter\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Google-specific: Prompt parameter\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "session_state": {
+            "type": "string",
+            "description": "Provider-specific: Session state parameter\n\nSome providers include this for session management.\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "error_uri": {
+            "type": "string",
+            "description": "Provider-specific: Error URI parameter\n\nSome providers include a URI with more error details.\n\nValidation:\n- Optional field\n- Max 4000 characters\n\nSanitization:\n- Trimmed"
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for OAuth callbacks via GET query parameters\n\nUsed by providers that redirect with query params (Google, Facebook). This DTO handles both successful callbacks and error scenarios."
+      },
+      "SocialExchangeDTO": {
+        "type": "object",
+        "properties": {
+          "exchangeToken": {
+            "type": "string",
+            "description": "One-time exchange token from callback redirect URL\n\nValidation:\n- Must be non-empty string\n- Max 500 characters\n\nSanitization:\n- Trimmed"
+          }
+        },
+        "required": [
+          "exchangeToken"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for exchanging a social redirect exchange token\n\nUsed in redirect-first social login flow. The backend redirects back to the frontend with an `exchangeToken` in the URL, and the frontend exchanges it for an AuthResponse.\n\nSecurity:\n- Exchange token validated for length\n- One-time use (consumed immediately)\n- Short TTL (default: 60 seconds)"
+      },
+      "StartSocialRedirectQueryDTO": {
+        "type": "object",
+        "properties": {
+          "returnTo": {
+            "type": "string",
+            "description": "Frontend path or absolute URL to redirect to after authentication completes\n\nValidation:\n- Optional field\n- Max 2048 characters\n\nSanitization:\n- Trimmed",
+            "examples": [
+              "/auth/callback",
+              "https://myapp.com/auth/callback"
+            ]
+          },
+          "appState": {
+            "type": "string",
+            "description": "Opaque, non-secret state to round-trip back to the frontend\n\nThis value is stored during the OAuth flow and returned to the frontend after authentication completes. Use it to maintain UI state across the redirect.\n\nValidation:\n- Optional field\n- Max 2000 characters\n\nSanitization:\n- Trimmed",
+            "examples": [
+              "12345",
+              "page=dashboard&mode=dark"
+            ]
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "login",
+              "link"
+            ],
+            "description": "Redirect action type\n\n- `login`: Standard social login/signup (default)\n- `link`: Link social account to existing authenticated user\n\nValidation:\n- Optional field\n- Must be either 'login' or 'link'",
+            "examples": [
+              "login",
+              "link"
+            ]
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for starting the redirect-first social login flow\n\nUsed when initiating a backend-first OAuth redirect flow where the provider redirects back to the backend callback endpoint."
+      },
+      "TokenResponse": {
+        "type": "object",
+        "properties": {
+          "accessToken": {
+            "type": "string",
+            "description": "New JWT access token"
+          },
+          "refreshToken": {
+            "type": "string",
+            "description": "New JWT refresh token"
+          },
+          "accessTokenExpiresAt": {
+            "type": "number",
+            "description": "Access token expiration (Unix timestamp in seconds)"
+          },
+          "refreshTokenExpiresAt": {
+            "type": "number",
+            "description": "Refresh token expiration (Unix timestamp in seconds)"
+          }
+        },
+        "required": [
+          "accessToken",
+          "refreshToken",
+          "accessTokenExpiresAt",
+          "refreshTokenExpiresAt"
+        ],
+        "additionalProperties": false,
+        "description": "Token Response DTO\n\nReturned by token refresh operations Contains new access and refresh tokens with expiration times"
+      },
+      "TrustDeviceResponseDTO": {
+        "type": "object",
+        "properties": {
+          "deviceToken": {
+            "type": "string",
+            "description": "Device trust token\n\nNote: Store this token securely on the client device",
+            "examples": [
+              "device-token-uuid-string"
+            ]
+          }
+        },
+        "required": [
+          "deviceToken"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for trust device"
+      },
+      "UnlinkSocialAccountDTO": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "Social provider name (e.g., 'google', 'apple', 'facebook')\n\nValidation:\n- Must be non-empty string\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased"
+          }
+        },
+        "required": [
+          "provider"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for unlinking social account\n\nSecurity:\n- User ID validated as UUID v4\n- Provider name validated"
+      },
+      "UnlinkSocialAccountResponseDTO": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Success message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for unlinkSocialAccount"
+      },
+      "UpdateUserAttributesDTO": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "username": {
+            "type": "string",
+            "description": "Optional username update\n\nValidation:\n- 3-50 characters\n- Alphanumeric, underscores, and hyphens only\n- Max 255 characters (DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Trimmed\n- Case preserved (username can be case-sensitive per config)"
+          },
+          "firstName": {
+            "type": "string",
+            "description": "Optional first name update\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "lastName": {
+            "type": "string",
+            "description": "Optional last name update\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "email": {
+            "type": "string",
+            "description": "Optional email address update\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Optional phone number update\n\nValidation:\n- E.164 format (international standard)\n- MUST start with + (required for security)\n- Max 20 characters (DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Whitespace removed\n- Only digits and leading + preserved\n\nSecurity:\n- Strict E.164 validation prevents SQL injection\n- Max length prevents oversized inputs"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional metadata update (custom fields)\n\nBehavior:\n- Existing metadata is merged with new values\n- To delete a metadata key, set it to null\n- To update a value, provide the new value\n- To add a new key, include it in the object\n\nSecurity:\n- Validated in service layer if used\n- Max depth/size limits should be enforced"
+          },
+          "preferredMfaMethod": {
+            "$ref": "#/components/schemas/MFADeviceMethod",
+            "description": "Optional preferred MFA method\n\nSets the user's preferred MFA method for authentication. Must be one of the MFA device methods the user has configured.\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters (matches typical method name length)"
+          },
+          "retainVerification": {
+            "type": "boolean",
+            "description": "Optional flag to retain verification status when updating email/phone\n\nWhen true:\n- Email verification status is preserved when email is updated\n- Phone verification status is preserved when phone is updated\n- Useful when verification was done externally or outside nauth-toolkit\n\nWhen false or undefined (default):\n- Email verification is reset to false when email is updated\n- Phone verification is reset to false when phone is updated\n- User must re-verify the new email/phone"
+          }
+        },
+        "description": "Request DTO for updating user attributes (self-service, no sub)"
+      },
+      "UpdateVerifiedStatusRequestDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "isEmailVerified": {
+            "type": "boolean",
+            "description": "Email verification status\n\nValidation:\n- If set to true, user must have an email address\n- If set to false, can be set even if email doesn't exist (default state)\n- Optional - only updates if provided",
+            "examples": [
+              true
+            ]
+          },
+          "isPhoneVerified": {
+            "type": "boolean",
+            "description": "Phone verification status\n\nValidation:\n- If set to true, user must have a phone number\n- If set to false, can be set even if phone doesn't exist (default state)\n- Optional - only updates if provided",
+            "examples": [
+              true
+            ]
+          }
+        },
+        "required": [
+          "sub"
+        ],
+        "additionalProperties": false,
+        "description": "Request DTO for updating verification status"
+      },
+      "UserUpdateDTO": {
+        "type": "object",
+        "properties": {
+          "username": {
+            "type": "string",
+            "description": "Optional username update\n\nValidation:\n- 3-50 characters\n- Alphanumeric, underscores, and hyphens only\n- Max 255 characters (DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Trimmed\n- Case preserved (username can be case-sensitive per config)"
+          },
+          "firstName": {
+            "type": "string",
+            "description": "Optional first name update\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "lastName": {
+            "type": "string",
+            "description": "Optional last name update\n\nValidation:\n- 1-100 characters\n- Max 100 characters (DB limit)\n\nSanitization:\n- Trimmed\n- Title case preserved"
+          },
+          "email": {
+            "type": "string",
+            "description": "Optional email address update\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Optional phone number update\n\nValidation:\n- E.164 format (international standard)\n- MUST start with + (required for security)\n- Max 20 characters (DB limit)\n- Uniqueness checked in service layer\n\nSanitization:\n- Whitespace removed\n- Only digits and leading + preserved\n\nSecurity:\n- Strict E.164 validation prevents SQL injection\n- Max length prevents oversized inputs"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional metadata update (custom fields)\n\nBehavior:\n- Existing metadata is merged with new values\n- To delete a metadata key, set it to null\n- To update a value, provide the new value\n- To add a new key, include it in the object\n\nSecurity:\n- Validated in service layer if used\n- Max depth/size limits should be enforced"
+          },
+          "preferredMfaMethod": {
+            "$ref": "#/components/schemas/MFADeviceMethod",
+            "description": "Optional preferred MFA method\n\nSets the user's preferred MFA method for authentication. Must be one of the MFA device methods the user has configured.\n\nValidation:\n- Must be one of: totp, sms, email, passkey\n- Max 50 characters (matches typical method name length)"
+          },
+          "retainVerification": {
+            "type": "boolean",
+            "description": "Optional flag to retain verification status when updating email/phone\n\nWhen true:\n- Email verification status is preserved when email is updated\n- Phone verification status is preserved when phone is updated\n- Useful when verification was done externally or outside nauth-toolkit\n\nWhen false or undefined (default):\n- Email verification is reset to false when email is updated\n- Phone verification is reset to false when phone is updated\n- User must re-verify the new email/phone"
+          }
+        },
+        "additionalProperties": false,
+        "description": "DTO for updating user attributes\n\nSecurity:\n- All fields validated against DB constraints\n- Input sanitization applied automatically\n- Email uniqueness checked in service layer\n- Phone uniqueness checked in service layer\n- Username uniqueness checked in service layer"
+      },
+      "ValidateAccessTokenDTO": {
+        "type": "object",
+        "properties": {
+          "accessToken": {
+            "type": "string",
+            "description": "JWT access token to validate\n\nValidation:\n- Must be a string\n- Min 10 characters (minimum valid JWT length)\n- Max 2048 characters (prevents DoS, typical JWT is 200-500 chars)\n\nNote: Token format, signature, and expiration validated in service layer",
+            "examples": [
+              "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
+            ]
+          }
+        },
+        "required": [
+          "accessToken"
+        ],
+        "additionalProperties": false,
+        "description": "Validate Access Token DTO\n\nUsed for validating JWT access tokens and decoding their payload.\n\nSecurity:\n- Token length validated (prevents DoS)\n- JWT tokens can be long, but we validate input length\n- Token is validated in service layer for format, signature, and expiration"
+      },
+      "ValidateAccessTokenResponseDTO": {
+        "type": "object",
+        "properties": {
+          "valid": {
+            "type": "boolean",
+            "description": "Whether the token is valid\n\nIf true, payload will be present. If false, error and errorType will be present."
+          },
+          "payload": {
+            "$ref": "#/components/schemas/JwtPayload",
+            "description": "Decoded JWT payload (only if valid is true)\n\nContains all token claims including user information and session details."
+          },
+          "error": {
+            "type": "string",
+            "description": "Error message (only if valid is false)\n\nHuman-readable description of why validation failed."
+          },
+          "errorType": {
+            "type": "string",
+            "enum": [
+              "expired",
+              "invalid",
+              "malformed",
+              "blacklisted"
+            ],
+            "description": "Error type for specific handling (only if valid is false)\n\nCategorizes the validation error for programmatic handling.\n\n- `expired`: Token has expired (exp claim < current time)\n- `invalid`: Token signature verification failed or invalid format\n- `malformed`: Token structure is invalid (not a proper JWT)\n- `blacklisted`: Token has been revoked or blacklisted"
+          }
+        },
+        "required": [
+          "valid"
+        ],
+        "additionalProperties": false,
+        "description": "Validate Access Token Response DTO\n\nResponse DTO for token validation operations."
+      },
+      "VerifyEmailResponseDTO": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Success message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for verifyEmailWithCode and verifyEmailWithToken"
+      },
+      "VerifyEmailWithCodeDTO": {
+        "type": "object",
+        "properties": {
+          "email": {
+            "type": "string",
+            "description": "User's email address Must match the email used during signup\n\nValidation:\n- Valid email format (RFC 5322)\n- Max 255 characters (matches DB column limit)\n- Automatically trimmed and lowercased\n\nSanitization:\n- Removes leading/trailing whitespace\n- Converts to lowercase for case-insensitive matching"
+          },
+          "code": {
+            "type": "string",
+            "description": "6-digit verification code from email\n\nValidation:\n- Must be numeric string (digits only)\n- Exactly 6 characters long\n- Fixed length prevents timing attacks\n\nSanitization:\n- Removes all whitespace (users might copy \"123 456\")\n- Removes non-digit characters"
+          },
+          "challengeSessionId": {
+            "type": "number",
+            "description": "Challenge session ID (internal use) Optional - used internally to link verification to specific challenge session. Provides security by ensuring codes are only valid for the session they were created for.\n\nValidation:\n- Must be a positive integer if provided\n- Optional (for backward compatibility and direct verification flows)"
+          }
+        },
+        "required": [
+          "email",
+          "code"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for verifying email with code (6-digit OTP)\n\nSecurity:\n- Email must be valid format and match DB limits\n- Code must be exactly 6 digits (no more, no less)\n- All fields are required (no optional fields to prevent attacks)\n- Input sanitization applied automatically"
+      },
+      "VerifyEmailWithTokenDTO": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "description": "Verification token from email link\n\nValidation:\n- Exactly 64 hexadecimal characters (SHA-256 hash output)\n- Only 0-9 and a-f characters allowed\n- Case-insensitive\n\nSanitization:\n- Removes whitespace\n- Converts to lowercase for consistent hashing"
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for verifying email with URL token\n\nSecurity:\n- Token must be valid hex format\n- Exact length enforced (64 chars = 32 bytes SHA-256 hash)\n- No SQL injection or XSS possible\n- Input sanitization prevents malformed tokens"
+      },
+      "VerifyMFACodeDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's unique identifier (UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed\n- Lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "methodName": {
+            "type": "string",
+            "description": "MFA method name\n\nValidation:\n- Must be one of: totp, sms, email, passkey, backup\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased",
+            "examples": [
+              "totp"
+            ]
+          },
+          "code": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E"
+              }
+            ],
+            "description": "Verification code or credential (provider-specific)\n\nValidation:\n- Must be a string or object depending on method\n- For TOTP/SMS/Email: string code\n- For Passkey: credential object\n- For Backup: string code"
+          },
+          "deviceId": {
+            "type": "number",
+            "description": "Optional device ID\n\nValidation:\n- Must be a positive integer if provided"
+          }
+        },
+        "required": [
+          "sub",
+          "methodName",
+          "code"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for verifying MFA code"
+      },
+      "VerifyMFACodeResponseDTO": {
+        "type": "object",
+        "properties": {
+          "valid": {
+            "type": "boolean",
+            "description": "Whether verification succeeded"
+          }
+        },
+        "required": [
+          "valid"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for MFA code verification"
+      },
+      "VerifyPhoneResponseDTO": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Success message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false,
+        "description": "Response DTO for verifyPhoneWithCode and verifyPhoneWithCodeBySub"
+      },
+      "VerifyPhoneWithCodeBySubDTO": {
+        "type": "object",
+        "properties": {
+          "sub": {
+            "type": "string",
+            "description": "User's external identifier (sub/UUID v4)\n\nValidation:\n- Must be a valid UUID v4 format\n- Matches DB constraint: char(36) or uuid\n\nSanitization:\n- Trimmed and lowercased for consistency",
+            "examples": [
+              "a21b654c-2746-4168-acee-c175083a65cd"
+            ]
+          },
+          "code": {
+            "type": "string",
+            "description": "6-digit verification code\n\nValidation:\n- Must be a numeric string\n- Exactly 6 digits",
+            "examples": [
+              "123456"
+            ]
+          },
+          "challengeSessionId": {
+            "type": "number",
+            "description": "Challenge session ID (internal use) Optional - used internally to link verification to specific challenge session. Provides security by ensuring codes are only valid for the session they were created for.\n\nValidation:\n- Must be a positive integer if provided\n- Optional (for backward compatibility and direct verification flows)"
+          }
+        },
+        "required": [
+          "sub",
+          "code"
+        ],
+        "additionalProperties": false,
+        "description": "Verify Phone with Code by User Sub DTO\n\nUsed for phone verification with 6-digit OTP code when allowing duplicate phones. Requires user sub to identify which user's phone to verify.\n\nSecurity:\n- UUID format validated (prevents injection)\n- Code format validated (6 digits)"
+      },
+      "VerifyPhoneWithCodeDTO": {
+        "type": "object",
+        "properties": {
+          "phone": {
+            "type": "string",
+            "description": "User's phone number in E.164 format\n\nValidation:\n- Must be a string\n- Must match E.164 format: +[country code][number]\n- Max 20 characters (matches DB constraint: varchar(20))\n\nSanitization:\n- Trimmed\n- Whitespace removed",
+            "examples": [
+              "+1234567890"
+            ]
+          },
+          "code": {
+            "type": "string",
+            "description": "6-digit verification code\n\nValidation:\n- Must be a string\n- Exactly 6 digits (numeric only)\n- No letters, spaces, or special characters\n- Fixed length prevents timing attacks\n\nSanitization:\n- Removes all whitespace (users might copy \"123 456\")\n- Ensures only numeric string",
+            "examples": [
+              "123456"
+            ]
+          },
+          "challengeSessionId": {
+            "type": "number",
+            "description": "Challenge session ID (internal use) Optional - used internally to link verification to specific challenge session. Provides security by ensuring codes are only valid for the session they were created for.\n\nValidation:\n- Must be a positive integer if provided\n- Optional (for backward compatibility and direct verification flows)"
+          }
+        },
+        "required": [
+          "phone",
+          "code"
+        ],
+        "additionalProperties": false,
+        "description": "Verify Phone with Code DTO\n\nUsed for phone verification with 6-digit OTP code.\n\nSecurity:\n- Phone validated against E.164 format (prevents SQL injection)\n- Code validated for exact 6 digits\n- All fields match DB constraints"
+      },
+      "VerifyTokenDTO": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "Social provider name\n\nValidation:\n- Must be one of: 'google', 'apple', 'facebook'\n- Max 50 characters\n\nSanitization:\n- Trimmed and lowercased"
+          },
+          "idToken": {
+            "type": "string",
+            "description": "ID token (JWT) from native SDK\n\nRequired for:\n- google (always)\n- apple (always)\n- facebook Limited Login (when accessToken is not provided)\n\nValidation:\n- Required for google/apple\n- Required for facebook only when accessToken is NOT provided\n- Must be non-empty string\n- Max 10000 characters (JWT tokens can be large)\n\nSanitization:\n- Trimmed"
+          },
+          "accessToken": {
+            "type": "string",
+            "description": "Access token (opaque) from native SDK\n\nRequired for:\n- facebook classic login (when idToken is not provided)\n\nOptional for:\n- google (provided alongside idToken)\n\nValidation:\n- Required for facebook only when idToken is NOT provided\n- Must be non-empty string if provided\n- Max 2000 characters\n\nSanitization:\n- Trimmed"
+          },
+          "profileData": {
+            "$ref": "#/components/schemas/Record%3Cstring%2Cunknown%3E",
+            "description": "Optional profile data from native SDK\n\nSome providers (e.g., Apple) only provide user profile data on first sign-in. Clients should capture and send this data for proper user creation.\n\nValidation:\n- Optional\n- Must be a valid object if provided"
+          }
+        },
+        "required": [
+          "provider"
+        ],
+        "additionalProperties": false,
+        "description": "DTO for verifying social authentication token from native mobile apps\n\nUsed when mobile apps (iOS, Android) use native SDKs (e.g., Google Sign-In SDK, Sign in with Apple, Facebook SDK) and need to verify tokens on the backend.\n\nSupports provider-aware validation:\n- **google**: requires `idToken`, `accessToken` optional\n- **apple**: requires `idToken`, `accessToken` optional, `profileData` optional\n- **facebook**:   - Classic login: requires `accessToken` (when `idToken` not provided)   - Limited Login (OIDC): requires `idToken` (JWT, when `accessToken` not provided)\n\nSecurity:\n- Provider allow-list enforced\n- Per-provider required fields validated\n- Token signature verification performed\n- Token must be fresh (not expired)"
+      }
+    }
+  }
+}