diff options
Diffstat (limited to 'lib/csapi/registration.h')
| -rw-r--r-- | lib/csapi/registration.h | 428 |
1 files changed, 203 insertions, 225 deletions
diff --git a/lib/csapi/registration.h b/lib/csapi/registration.h index 2619dd87..9d96db32 100644 --- a/lib/csapi/registration.h +++ b/lib/csapi/registration.h @@ -4,20 +4,20 @@ #pragma once -#include "converters.h" - -#include "csapi/../identity/definitions/sid.h" +#include "csapi/../identity/definitions/request_msisdn_validation.h" +#include "csapi/./definitions/request_email_validation.h" +#include "csapi/./definitions/request_msisdn_validation.h" #include "csapi/definitions/auth_data.h" +#include "csapi/definitions/request_token_response.h" #include "jobs/basejob.h" namespace Quotient { -// Operations - /*! \brief Register for an account on this homeserver. * - * This API endpoint uses the `User-Interactive Authentication API`_. + * This API endpoint uses the `User-Interactive Authentication API`_, except in + * the cases where a guest account is being registered. * * Register for an account on this homeserver. * @@ -49,36 +49,46 @@ namespace Quotient { * supplied by the client or generated by the server. The server may * invalidate any access token previously associated with that device. See * `Relationship between access tokens and devices`_. + * + * When registering a guest account, all parameters in the request body + * with the exception of ``initial_device_display_name`` MUST BE ignored + * by the server. The server MUST pick a ``device_id`` for the account + * regardless of input. + * + * Any user ID returned by this API must conform to the grammar given in the + * `Matrix specification <../appendices.html#user-identifiers>`_. */ class RegisterJob : public BaseJob { public: /*! \brief Register for an account on this homeserver. * + * * \param kind - * The kind of account to register. Defaults to `user`. + * The kind of account to register. Defaults to ``user``. + * * \param auth * Additional authentication information for the * user-interactive authentication API. Note that this * information is *not* used to define how the registered user * should be authenticated, but is instead used to - * authenticate the ``register`` call itself. It should be - * left empty, or omitted, unless an earlier call returned an - * response with status code 401. - * \param bindEmail - * If true, the server binds the email used for authentication to - * the Matrix ID with the identity server. + * authenticate the ``register`` call itself. + * * \param username * The basis for the localpart of the desired Matrix ID. If omitted, * the homeserver MUST generate a Matrix ID local part. + * * \param password * The desired password for the account. + * * \param deviceId * ID of the client device. If this does not correspond to a * known client device, a new device will be created. The server * will auto-generate a device_id if this is not specified. + * * \param initialDeviceDisplayName * A display name to assign to the newly-created device. Ignored * if ``device_id`` corresponds to a known device. + * * \param inhibitLogin * If true, an ``access_token`` and ``device_id`` should not be * returned from this call, therefore preventing an automatic @@ -86,28 +96,27 @@ public: */ explicit RegisterJob(const QString& kind = QStringLiteral("user"), const Omittable<AuthenticationData>& auth = none, - Omittable<bool> bindEmail = none, const QString& username = {}, const QString& password = {}, const QString& deviceId = {}, const QString& initialDeviceDisplayName = {}, Omittable<bool> inhibitLogin = none); - ~RegisterJob() override; - // Result properties /// The fully-qualified Matrix user ID (MXID) that has been registered. /// /// Any user ID returned by this API must conform to the grammar given in - /// the `Matrix specification - /// <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_. - const QString& userId() const; + /// the `Matrix specification <../appendices.html#user-identifiers>`_. + QString userId() const { return loadFromJson<QString>("user_id"_ls); } /// An access token for the account. /// This access token can then be used to authorize other requests. /// Required if the ``inhibit_login`` option is false. - const QString& accessToken() const; + QString accessToken() const + { + return loadFromJson<QString>("access_token"_ls); + } /// The server_name of the homeserver on which the account has /// been registered. @@ -115,180 +124,141 @@ public: /// **Deprecated**. Clients should extract the server_name from /// ``user_id`` (by splitting at the first colon) if they require /// it. Note also that ``homeserver`` is not spelt this way. - const QString& homeServer() const; + QString homeServer() const + { + return loadFromJson<QString>("home_server"_ls); + } /// ID of the registered device. Will be the same as the /// corresponding parameter in the request, if one was specified. /// Required if the ``inhibit_login`` option is false. - const QString& deviceId() const; - -protected: - Status parseJson(const QJsonDocument& data) override; - -private: - class Private; - QScopedPointer<Private> d; + QString deviceId() const { return loadFromJson<QString>("device_id"_ls); } }; /*! \brief Begins the validation process for an email to be used during * registration. * - * Proxies the Identity Service API ``validate/email/requestToken``, but - * first checks that the given email address is not already associated - * with an account on this homeserver. See the Identity Service API for - * further information. + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the email itself, either by sending a validation email + * itself or by using a service it has control over. */ class RequestTokenToRegisterEmailJob : public BaseJob { public: /*! \brief Begins the validation process for an email to be used during * registration. * - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param email - * The email address to validate. - * \param sendAttempt - * The server will only send an email if the ``send_attempt`` - * is a number greater than the most recent one which it has seen, - * scoped to that ``email`` + ``client_secret`` pair. This is to - * avoid repeatedly sending the same email in the case of request - * retries between the POSTing user and the identity server. - * The client should increment this value if they desire a new - * email (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. + * + * \param body + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the email itself, either by sending a validation email + * itself or by using a service it has control over. */ - explicit RequestTokenToRegisterEmailJob(const QString& clientSecret, - const QString& email, - int sendAttempt, - const QString& idServer, - const QString& nextLink = {}); - - ~RequestTokenToRegisterEmailJob() override; + explicit RequestTokenToRegisterEmailJob(const EmailValidationData& body); // Result properties - /// An email has been sent to the specified address. - /// Note that this may be an email containing the validation token or it may - /// be informing the user of an error. - const Sid& data() const; - -protected: - Status parseJson(const QJsonDocument& data) override; - -private: - class Private; - QScopedPointer<Private> d; + /// An email has been sent to the specified address. Note that this + /// may be an email containing the validation token or it may be + /// informing the user of an error. + RequestTokenResponse data() const + { + return fromJson<RequestTokenResponse>(jsonData()); + } }; /*! \brief Requests a validation token be sent to the given phone number for the * purpose of registering an account * - * Proxies the Identity Service API ``validate/msisdn/requestToken``, but - * first checks that the given phone number is not already associated - * with an account on this homeserver. See the Identity Service API for - * further information. + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the phone number itself, either by sending a validation + * message itself or by using a service it has control over. */ class RequestTokenToRegisterMSISDNJob : public BaseJob { public: /*! \brief Requests a validation token be sent to the given phone number for * the purpose of registering an account * - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param country - * The two-letter uppercase ISO country code that the number in - * ``phone_number`` should be parsed as if it were dialled from. - * \param phoneNumber - * The phone number to validate. - * \param sendAttempt - * The server will only send an SMS if the ``send_attempt`` is a - * number greater than the most recent one which it has seen, - * scoped to that ``country`` + ``phone_number`` + ``client_secret`` - * triple. This is to avoid repeatedly sending the same SMS in - * the case of request retries between the POSTing user and the - * identity server. The client should increment this value if - * they desire a new SMS (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. + * + * \param body + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the phone number itself, either by sending a validation + * message itself or by using a service it has control over. */ - explicit RequestTokenToRegisterMSISDNJob(const QString& clientSecret, - const QString& country, - const QString& phoneNumber, - int sendAttempt, - const QString& idServer, - const QString& nextLink = {}); - - ~RequestTokenToRegisterMSISDNJob() override; + explicit RequestTokenToRegisterMSISDNJob(const MsisdnValidationData& body); // Result properties - /// An SMS message has been sent to the specified phone number. - /// Note that this may be an SMS message containing the validation token or + /// An SMS message has been sent to the specified phone number. Note + /// that this may be an SMS message containing the validation token or /// it may be informing the user of an error. - const Sid& data() const; - -protected: - Status parseJson(const QJsonDocument& data) override; - -private: - class Private; - QScopedPointer<Private> d; + RequestTokenResponse data() const + { + return fromJson<RequestTokenResponse>(jsonData()); + } }; /*! \brief Changes a user's password. * * Changes the password for an account on this homeserver. * - * This API endpoint uses the `User-Interactive Authentication API`_. + * This API endpoint uses the `User-Interactive Authentication API`_ to + * ensure the user changing the password is actually the owner of the + * account. * * An access token should be submitted to this endpoint if the client has * an active session. * * The homeserver may change the flows available depending on whether a - * valid access token is provided. + * valid access token is provided. The homeserver SHOULD NOT revoke the + * access token provided in the request. Whether other access tokens for + * the user are revoked depends on the request parameters. */ class ChangePasswordJob : public BaseJob { public: /*! \brief Changes a user's password. * + * * \param newPassword * The new password for the account. + * + * \param logoutDevices + * Whether the user's other access tokens, and their associated devices, + * should be revoked if the request succeeds. Defaults to true. + * + * When ``false``, the server can still take advantage of `the soft logout + * method <#soft-logout>`_ for the user's remaining devices. + * * \param auth * Additional authentication information for the user-interactive * authentication API. */ explicit ChangePasswordJob(const QString& newPassword, + Omittable<bool> logoutDevices = none, const Omittable<AuthenticationData>& auth = none); }; /*! \brief Requests a validation token be sent to the given email address for * the purpose of resetting a user's password * - * Proxies the Identity Service API ``validate/email/requestToken``, but - * first checks that the given email address **is** associated with an account - * on this homeserver. This API should be used to request - * validation tokens when authenticating for the - * `account/password` endpoint. This API's parameters and response are - * identical to that of the HS API |/register/email/requestToken|_ except that - * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * The homeserver must check that the given email address **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * ``/account/password`` endpoint. + * + * This API's parameters and response are identical to that of the + * |/register/email/requestToken|_ endpoint, except that + * ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the * given email address could be found. The server may instead send an * email to the given address prompting the user to create an account. - * `M_THREEPID_IN_USE` may not be returned. + * ``M_THREEPID_IN_USE`` may not be returned. + * + * The homeserver should validate the email itself, either by sending a + * validation email itself or by using a service it has control over. + * * * .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` * @@ -300,62 +270,58 @@ public: /*! \brief Requests a validation token be sent to the given email address * for the purpose of resetting a user's password * - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param email - * The email address to validate. - * \param sendAttempt - * The server will only send an email if the ``send_attempt`` - * is a number greater than the most recent one which it has seen, - * scoped to that ``email`` + ``client_secret`` pair. This is to - * avoid repeatedly sending the same email in the case of request - * retries between the POSTing user and the identity server. - * The client should increment this value if they desire a new - * email (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. + * + * \param body + * The homeserver must check that the given email address **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * ``/account/password`` endpoint. + * + * This API's parameters and response are identical to that of the + * |/register/email/requestToken|_ endpoint, except that + * ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + * given email address could be found. The server may instead send an + * email to the given address prompting the user to create an account. + * ``M_THREEPID_IN_USE`` may not be returned. + * + * The homeserver should validate the email itself, either by sending a + * validation email itself or by using a service it has control over. + * + * + * .. |/register/email/requestToken| replace:: + * ``/register/email/requestToken`` + * + * .. _/register/email/requestToken: + * #post-matrix-client-r0-register-email-requesttoken */ - explicit RequestTokenToResetPasswordEmailJob(const QString& clientSecret, - const QString& email, - int sendAttempt, - const QString& idServer, - const QString& nextLink = {}); - - ~RequestTokenToResetPasswordEmailJob() override; + explicit RequestTokenToResetPasswordEmailJob(const EmailValidationData& body); // Result properties /// An email was sent to the given address. - const Sid& data() const; - -protected: - Status parseJson(const QJsonDocument& data) override; - -private: - class Private; - QScopedPointer<Private> d; + RequestTokenResponse data() const + { + return fromJson<RequestTokenResponse>(jsonData()); + } }; /*! \brief Requests a validation token be sent to the given phone number for the * purpose of resetting a user's password. * - * Proxies the Identity Service API ``validate/msisdn/requestToken``, but - * first checks that the given phone number **is** associated with an account - * on this homeserver. This API should be used to request - * validation tokens when authenticating for the - * `account/password` endpoint. This API's parameters and response are - * identical to that of the HS API |/register/msisdn/requestToken|_ except that - * `M_THREEPID_NOT_FOUND` may be returned if no account matching the - * given phone number could be found. The server may instead send an - * SMS message to the given address prompting the user to create an account. - * `M_THREEPID_IN_USE` may not be returned. + * The homeserver must check that the given phone number **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * ``/account/password`` endpoint. + * + * This API's parameters and response are identical to that of the + * |/register/msisdn/requestToken|_ endpoint, except that + * ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + * given phone number could be found. The server may instead send the SMS + * to the given phone number prompting the user to create an account. + * ``M_THREEPID_IN_USE`` may not be returned. + * + * The homeserver should validate the phone number itself, either by sending a + * validation message itself or by using a service it has control over. * * .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` * @@ -367,51 +333,39 @@ public: /*! \brief Requests a validation token be sent to the given phone number for * the purpose of resetting a user's password. * - * \param clientSecret - * A unique string generated by the client, and used to identify the - * validation attempt. It must be a string consisting of the characters - * ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it - * must not be empty. - * \param country - * The two-letter uppercase ISO country code that the number in - * ``phone_number`` should be parsed as if it were dialled from. - * \param phoneNumber - * The phone number to validate. - * \param sendAttempt - * The server will only send an SMS if the ``send_attempt`` is a - * number greater than the most recent one which it has seen, - * scoped to that ``country`` + ``phone_number`` + ``client_secret`` - * triple. This is to avoid repeatedly sending the same SMS in - * the case of request retries between the POSTing user and the - * identity server. The client should increment this value if - * they desire a new SMS (e.g. a reminder) to be sent. - * \param idServer - * The hostname of the identity server to communicate with. May - * optionally include a port. - * \param nextLink - * Optional. When the validation is completed, the identity - * server will redirect the user to this URL. + * + * \param body + * The homeserver must check that the given phone number **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * ``/account/password`` endpoint. + * + * This API's parameters and response are identical to that of the + * |/register/msisdn/requestToken|_ endpoint, except that + * ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + * given phone number could be found. The server may instead send the SMS + * to the given phone number prompting the user to create an account. + * ``M_THREEPID_IN_USE`` may not be returned. + * + * The homeserver should validate the phone number itself, either by sending + * a validation message itself or by using a service it has control over. + * + * .. |/register/msisdn/requestToken| replace:: + * ``/register/msisdn/requestToken`` + * + * .. _/register/msisdn/requestToken: + * #post-matrix-client-r0-register-email-requesttoken */ - explicit RequestTokenToResetPasswordMSISDNJob(const QString& clientSecret, - const QString& country, - const QString& phoneNumber, - int sendAttempt, - const QString& idServer, - const QString& nextLink = {}); - - ~RequestTokenToResetPasswordMSISDNJob() override; + explicit RequestTokenToResetPasswordMSISDNJob( + const RequestMsisdnValidation& body); // Result properties /// An SMS message was sent to the given phone number. - const Sid& data() const; - -protected: - Status parseJson(const QJsonDocument& data) override; - -private: - class Private; - QScopedPointer<Private> d; + RequestTokenResponse data() const + { + return fromJson<RequestTokenResponse>(jsonData()); + } }; /*! \brief Deactivate a user's account. @@ -426,17 +380,45 @@ private: * * The homeserver may change the flows available depending on whether a * valid access token is provided. + * + * Unlike other endpoints, this endpoint does not take an ``id_access_token`` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. */ class DeactivateAccountJob : public BaseJob { public: /*! \brief Deactivate a user's account. * + * * \param auth * Additional authentication information for the user-interactive * authentication API. + * + * \param idServer + * The identity server to unbind all of the user's 3PIDs from. + * If not provided, the homeserver MUST use the ``id_server`` + * that was originally use to bind each identifier. If the + * homeserver does not know which ``id_server`` that was, + * it must return an ``id_server_unbind_result`` of + * ``no-support``. */ - explicit DeactivateAccountJob( - const Omittable<AuthenticationData>& auth = none); + explicit DeactivateAccountJob(const Omittable<AuthenticationData>& auth = none, + const QString& idServer = {}); + + // Result properties + + /// An indicator as to whether or not the homeserver was able to unbind + /// the user's 3PIDs from the identity server(s). ``success`` indicates + /// that all identifiers have been unbound from the identity server while + /// ``no-support`` indicates that one or more identifiers failed to unbind + /// due to the identity server refusing the request or the homeserver + /// being unable to determine an identity server to unbind from. This + /// must be ``success`` if the homeserver has no identifiers to unbind + /// for the user. + QString idServerUnbindResult() const + { + return loadFromJson<QString>("id_server_unbind_result"_ls); + } }; /*! \brief Checks to see if a username is available on the server. @@ -458,6 +440,7 @@ class CheckUsernameAvailabilityJob : public BaseJob { public: /*! \brief Checks to see if a username is available on the server. * + * * \param username * The username to check the availability of. */ @@ -469,20 +452,15 @@ public: * is necessary but the job itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl, const QString& username); - ~CheckUsernameAvailabilityJob() override; // Result properties /// A flag to indicate that the username is available. This should always /// be ``true`` when the server replies with 200 OK. - Omittable<bool> available() const; - -protected: - Status parseJson(const QJsonDocument& data) override; - -private: - class Private; - QScopedPointer<Private> d; + Omittable<bool> available() const + { + return loadFromJson<Omittable<bool>>("available"_ls); + } }; } // namespace Quotient |