{
  "openapi": "3.0.3",
  "components": {
    "schemas": {
      "MfaTotpDisableMFADeviceDTO": {
        "type": "object",
        "properties": {
          "password": {
            "type": "string",
            "description": "User's password (for security confirmation)"
          }
        },
        "required": [
          "password"
        ],
        "additionalProperties": false,
        "description": "Disable MFA Device DTO\n\nDisable an MFA device (requires password confirmation)."
      },
      "MfaTotpGenerateBackupCodesResponseDTO": {
        "type": "object",
        "properties": {
          "codes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of backup codes Each code can only be used once"
          },
          "generated": {
            "type": "string",
            "description": "Generation timestamp"
          }
        },
        "required": [
          "codes",
          "generated"
        ],
        "additionalProperties": false,
        "description": "Generate Backup Codes Response DTO\n\nReturns newly generated backup codes. Codes are only shown once - user must save them securely."
      },
      "MfaTotpGetPasskeyChallengeResponseDTO": {
        "type": "object",
        "properties": {
          "options": {
            "type": "object",
            "properties": {
              "challenge": {
                "type": "string"
              },
              "timeout": {
                "type": "number"
              },
              "rpId": {
                "type": "string"
              },
              "allowCredentials": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "const": "public-key"
                    },
                    "transports": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "id",
                    "type"
                  ],
                  "additionalProperties": false
                }
              },
              "userVerification": {
                "type": "string",
                "enum": [
                  "required",
                  "preferred",
                  "discouraged"
                ]
              }
            },
            "required": [
              "challenge",
              "timeout",
              "rpId",
              "allowCredentials",
              "userVerification"
            ],
            "additionalProperties": false,
            "description": "WebAuthn authentication options Pass to navigator.credentials.get({ publicKey: options })"
          }
        },
        "required": [
          "options"
        ],
        "additionalProperties": false,
        "description": "Get Passkey Challenge Response DTO\n\nReturns WebAuthn authentication options for MFA challenge."
      },
      "MfaTotpListMFADevicesResponseDTO": {
        "type": "object",
        "properties": {
          "devices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MfaTotpMFADeviceDTO"
            },
            "description": "Array of MFA devices"
          },
          "hasBackupCodes": {
            "type": "boolean",
            "description": "Whether user has backup codes generated"
          }
        },
        "required": [
          "devices",
          "hasBackupCodes"
        ],
        "additionalProperties": false,
        "description": "List MFA Devices Response DTO\n\nReturns all MFA devices for a user."
      },
      "MfaTotpMFADeviceDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Device ID"
          },
          "type": {
            "type": "string",
            "enum": [
              "totp",
              "sms",
              "passkey"
            ],
            "description": "MFA method type"
          },
          "name": {
            "type": "string",
            "description": "User-friendly device name"
          },
          "isActive": {
            "type": "boolean",
            "description": "Whether device is active"
          },
          "isPreferred": {
            "type": "boolean",
            "description": "Whether this is the preferred device for this method"
          },
          "lastUsedAt": {
            "type": "string",
            "description": "Last usage timestamp"
          },
          "createdAt": {
            "type": "string",
            "description": "Registration timestamp"
          },
          "maskedPhone": {
            "type": "string",
            "description": "Masked phone number (SMS only)"
          }
        },
        "required": [
          "id",
          "type",
          "name",
          "isActive",
          "isPreferred",
          "createdAt"
        ],
        "additionalProperties": false,
        "description": "MFA Device DTO\n\nInformation about a registered MFA device."
      },
      "MfaTotpMFAChallengeResponseDTO": {
        "type": "object",
        "properties": {
          "challengeName": {
            "type": "string",
            "const": "MFA_REQUIRED",
            "description": "Challenge type (always 'MFA_REQUIRED')"
          },
          "session": {
            "type": "string",
            "description": "Temporary challenge session token Must be submitted with MFA verification"
          },
          "challengeParameters": {
            "type": "object",
            "properties": {
              "availableMethods": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "totp",
                    "sms",
                    "passkey",
                    "backup"
                  ]
                },
                "description": "MFA methods available for this user"
              },
              "preferredMethod": {
                "type": "string",
                "enum": [
                  "totp",
                  "sms",
                  "passkey"
                ],
                "description": "User's preferred MFA method"
              },
              "maskedPhone": {
                "type": "string",
                "description": "Masked phone number for SMS (if available)",
                "examples": [
                  "***-***-1234"
                ]
              }
            },
            "required": [
              "availableMethods"
            ],
            "additionalProperties": false,
            "description": "Challenge parameters with available MFA methods"
          }
        },
        "required": [
          "challengeName",
          "session",
          "challengeParameters"
        ],
        "additionalProperties": false,
        "description": "MFA Challenge Response DTO\n\nReturned when login requires MFA verification. Client must complete MFA challenge to receive access tokens."
      },
      "MfaTotpMFAStatusResponseDTO": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether MFA is enabled for this user"
          },
          "required": {
            "type": "boolean",
            "description": "Whether MFA is required (based on enforcement policy)"
          },
          "gracePeriodEnds": {
            "type": "string",
            "description": "Grace period expiration (if MFA is required) After this date, user must enable MFA to login"
          },
          "configuredMethods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "totp",
                "sms",
                "passkey"
              ]
            },
            "description": "MFA methods configured by user"
          },
          "preferredMethod": {
            "type": "string",
            "enum": [
              "totp",
              "sms",
              "passkey"
            ],
            "description": "User's preferred MFA method"
          },
          "hasBackupCodes": {
            "type": "boolean",
            "description": "Whether user has generated backup codes"
          }
        },
        "required": [
          "enabled",
          "required",
          "configuredMethods",
          "hasBackupCodes"
        ],
        "additionalProperties": false,
        "description": "MFA Status Response DTO\n\nReturns MFA configuration status for a user."
      },
      "MfaTotpSendSMSMFACodeDTO": {
        "type": "object",
        "properties": {
          "session": {
            "type": "string",
            "description": "Challenge session token"
          }
        },
        "required": [
          "session"
        ],
        "additionalProperties": false,
        "description": "Send SMS MFA Code DTO\n\nRequest SMS code during MFA challenge."
      },
      "MfaTotpSetupPasskeyResponseDTO": {
        "type": "object",
        "properties": {
          "options": {
            "type": "object",
            "properties": {
              "challenge": {
                "type": "string"
              },
              "rp": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "id"
                ],
                "additionalProperties": false
              },
              "user": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "displayName": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "displayName"
                ],
                "additionalProperties": false
              },
              "pubKeyCredParams": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "public-key"
                    },
                    "alg": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "type",
                    "alg"
                  ],
                  "additionalProperties": false
                }
              },
              "timeout": {
                "type": "number"
              },
              "attestation": {
                "type": "string",
                "enum": [
                  "none",
                  "indirect",
                  "direct"
                ]
              },
              "authenticatorSelection": {
                "type": "object",
                "properties": {
                  "authenticatorAttachment": {
                    "type": "string",
                    "enum": [
                      "platform",
                      "cross-platform"
                    ]
                  },
                  "requireResidentKey": {
                    "type": "boolean"
                  },
                  "userVerification": {
                    "type": "string",
                    "enum": [
                      "required",
                      "preferred",
                      "discouraged"
                    ]
                  }
                },
                "additionalProperties": false
              },
              "excludeCredentials": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "const": "public-key"
                    },
                    "transports": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "id",
                    "type"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "challenge",
              "rp",
              "user",
              "pubKeyCredParams",
              "timeout",
              "attestation"
            ],
            "additionalProperties": false,
            "description": "WebAuthn registration options Pass to navigator.credentials.create({ publicKey: options })"
          }
        },
        "required": [
          "options"
        ],
        "additionalProperties": false,
        "description": "Setup Passkey Response DTO\n\nReturns WebAuthn registration options. Client passes these to navigator.credentials.create()."
      },
      "MfaTotpSetupSMSMFADTO": {
        "type": "object",
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Phone number in E.164 format",
            "examples": [
              "+1234567890"
            ]
          },
          "deviceName": {
            "type": "string",
            "description": "User-friendly device name"
          }
        },
        "required": [
          "phoneNumber"
        ],
        "additionalProperties": false,
        "description": "Setup SMS MFA DTO\n\nConfigure SMS as MFA method. Sends verification code to phone number."
      },
      "MfaTotpSetupTOTPResponseDTO": {
        "type": "object",
        "properties": {
          "secret": {
            "type": "string",
            "description": "Base32-encoded TOTP secret Used to generate QR code and for manual entry"
          },
          "qrCode": {
            "type": "string",
            "description": "QR code as data URL User scans this with authenticator app"
          },
          "manualEntryKey": {
            "type": "string",
            "description": "Formatted secret for manual entry Displayed if QR scan fails",
            "examples": [
              "ABCD EFGH IJKL MNOP"
            ]
          },
          "issuer": {
            "type": "string",
            "description": "Issuer name (from config)"
          },
          "accountName": {
            "type": "string",
            "description": "Account name (typically user's email)"
          }
        },
        "required": [
          "secret",
          "qrCode",
          "manualEntryKey",
          "issuer",
          "accountName"
        ],
        "additionalProperties": false,
        "description": "Setup TOTP Response DTO\n\nReturns QR code and secret for TOTP setup. User must scan QR code with authenticator app and verify with a code."
      },
      "MfaTotpUpdateMFADeviceDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "New device name"
          },
          "isPreferred": {
            "type": "boolean",
            "description": "Set as preferred device"
          }
        },
        "additionalProperties": false,
        "description": "Update MFA Device DTO\n\nUpdate device name or preferred status."
      },
      "MfaTotpVerifyMFACodeDTO": {
        "type": "object",
        "properties": {
          "session": {
            "type": "string",
            "description": "Challenge session token from MFA challenge"
          },
          "method": {
            "type": "string",
            "enum": [
              "totp",
              "sms",
              "backup"
            ],
            "description": "MFA method being used"
          },
          "code": {
            "type": "string",
            "description": "MFA code to verify"
          },
          "trustDevice": {
            "type": "boolean",
            "description": "Trust this device (skip MFA for configured period) Only applicable if rememberDevice is enabled in config",
            "default": false
          },
          "deviceId": {
            "type": "string",
            "description": "Device identifier for trusted device tracking Should be persistent per device (e.g., UUID stored in localStorage)"
          }
        },
        "required": [
          "session",
          "method",
          "code"
        ],
        "additionalProperties": false,
        "description": "Verify MFA Code DTO\n\nSubmit MFA code to complete authentication challenge."
      },
      "MfaTotpVerifyPasskeyDTO": {
        "type": "object",
        "properties": {
          "session": {
            "type": "string",
            "description": "Challenge session token from MFA challenge"
          },
          "credential": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "rawId": {
                "type": "string"
              },
              "response": {
                "type": "object",
                "properties": {
                  "clientDataJSON": {
                    "type": "string"
                  },
                  "authenticatorData": {
                    "type": "string"
                  },
                  "signature": {
                    "type": "string"
                  },
                  "userHandle": {
                    "type": "string"
                  }
                },
                "required": [
                  "clientDataJSON",
                  "authenticatorData",
                  "signature"
                ],
                "additionalProperties": false
              },
              "type": {
                "type": "string",
                "const": "public-key"
              }
            },
            "required": [
              "id",
              "rawId",
              "response",
              "type"
            ],
            "additionalProperties": false,
            "description": "WebAuthn credential (PublicKeyCredential from navigator.credentials.get())"
          },
          "trustDevice": {
            "type": "boolean",
            "description": "Trust this device (skip MFA for configured period)",
            "default": false
          }
        },
        "required": [
          "session",
          "credential"
        ],
        "additionalProperties": false,
        "description": "Verify Passkey DTO\n\nSubmit WebAuthn assertion to complete authentication challenge."
      },
      "MfaTotpVerifyPasskeySetupDTO": {
        "type": "object",
        "properties": {
          "credential": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "rawId": {
                "type": "string"
              },
              "response": {
                "type": "object",
                "properties": {
                  "clientDataJSON": {
                    "type": "string"
                  },
                  "attestationObject": {
                    "type": "string"
                  }
                },
                "required": [
                  "clientDataJSON",
                  "attestationObject"
                ],
                "additionalProperties": false
              },
              "type": {
                "type": "string",
                "const": "public-key"
              }
            },
            "required": [
              "id",
              "rawId",
              "response",
              "type"
            ],
            "additionalProperties": false,
            "description": "WebAuthn credential from navigator.credentials.create()"
          },
          "deviceName": {
            "type": "string",
            "description": "User-friendly device name"
          }
        },
        "required": [
          "credential"
        ],
        "additionalProperties": false,
        "description": "Verify Passkey Setup DTO\n\nSubmit WebAuthn credential to complete passkey setup."
      },
      "MfaTotpVerifySMSMFASetupDTO": {
        "type": "object",
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Phone number receiving the code"
          },
          "code": {
            "type": "string",
            "description": "SMS verification code"
          }
        },
        "required": [
          "phoneNumber",
          "code"
        ],
        "additionalProperties": false,
        "description": "Verify SMS MFA Setup DTO\n\nSubmit code to complete SMS MFA setup."
      },
      "MfaTotpVerifyTOTPSetupDTO": {
        "type": "object",
        "properties": {
          "secret": {
            "type": "string",
            "description": "TOTP secret from setup response"
          },
          "code": {
            "type": "string",
            "description": "TOTP code from authenticator app"
          },
          "deviceName": {
            "type": "string",
            "description": "User-friendly device name"
          }
        },
        "required": [
          "secret",
          "code"
        ],
        "additionalProperties": false,
        "description": "Verify TOTP Setup DTO\n\nSubmit code to complete TOTP setup. Verifies the user can generate valid codes."
      }
    }
  }
}