diff options
Diffstat (limited to 'lib/csapi/administrative_contact.h')
| -rw-r--r-- | lib/csapi/administrative_contact.h | 332 |
1 files changed, 222 insertions, 110 deletions
diff --git a/lib/csapi/administrative_contact.h b/lib/csapi/administrative_contact.h index af98fe9c..53c89272 100644 --- a/lib/csapi/administrative_contact.h +++ b/lib/csapi/administrative_contact.h @@ -4,18 +4,15 @@ #pragma once -#include "converters.h" - -#include "csapi/../identity/definitions/sid.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" -#include <QtCore/QVector> - namespace Quotient { -// Operations - /*! \brief Gets a list of a user's third party identifiers. * * Gets a list of the third party identifiers that the homeserver has @@ -63,7 +60,6 @@ public: * is necessary but the job itself isn't. */ static QUrl makeRequestUrl(QUrl baseUrl); - ~GetAccount3PIDsJob() override; // Result properties @@ -75,19 +71,36 @@ public: /// /// Identifiers in this list may be used by the homeserver as, for example, /// identifiers that it will accept to reset the user's account password. - const QVector<ThirdPartyIdentifier>& threepids() const; - -protected: - Status parseJson(const QJsonDocument& data) override; + QVector<ThirdPartyIdentifier> threepids() const + { + return loadFromJson<QVector<ThirdPartyIdentifier>>("threepids"_ls); + } +}; -private: - class Private; - QScopedPointer<Private> d; +template <> +struct JsonObjectConverter<GetAccount3PIDsJob::ThirdPartyIdentifier> { + static void fillFrom(const QJsonObject& jo, + GetAccount3PIDsJob::ThirdPartyIdentifier& result) + { + fromJson(jo.value("medium"_ls), result.medium); + fromJson(jo.value("address"_ls), result.address); + fromJson(jo.value("validated_at"_ls), result.validatedAt); + fromJson(jo.value("added_at"_ls), result.addedAt); + } }; /*! \brief Adds contact information to the user's account. * * Adds contact information to the user's account. + * + * This endpoint is deprecated in favour of the more specific ``/3pid/add`` + * and ``/3pid/bind`` endpoints. + * + * .. Note:: + * Previously this endpoint supported a ``bind`` parameter. This parameter + * has been removed, making this endpoint behave as though it was ``false``. + * This results in this endpoint being an equivalent to ``/3pid/bind`` rather + * than dual-purpose. */ class Post3PIDsJob : public BaseJob { public: @@ -99,6 +112,10 @@ public: QString clientSecret; /// The identity server to use. QString idServer; + /// An access token previously registered with the identity server. + /// Servers can treat this as optional to distinguish between + /// r0.5-compatible clients and this specification version. + QString idAccessToken; /// The session identifier given by the identity server. QString sid; }; @@ -107,152 +124,247 @@ public: /*! \brief Adds contact information to the user's account. * + * * \param threePidCreds * The third party credentials to associate with the account. - * \param bind - * Whether the homeserver should also bind this third party - * identifier to the account's Matrix ID with the passed identity - * server. Default: ``false``. */ - explicit Post3PIDsJob(const ThreePidCredentials& threePidCreds, - Omittable<bool> bind = none); + explicit Post3PIDsJob(const ThreePidCredentials& threePidCreds); +}; + +template <> +struct JsonObjectConverter<Post3PIDsJob::ThreePidCredentials> { + static void dumpTo(QJsonObject& jo, + const Post3PIDsJob::ThreePidCredentials& pod) + { + addParam<>(jo, QStringLiteral("client_secret"), pod.clientSecret); + addParam<>(jo, QStringLiteral("id_server"), pod.idServer); + addParam<>(jo, QStringLiteral("id_access_token"), pod.idAccessToken); + addParam<>(jo, QStringLiteral("sid"), pod.sid); + } +}; + +/*! \brief Adds contact information to the user's account. + * + * This API endpoint uses the `User-Interactive Authentication API`_. + * + * Adds contact information to the user's account. Homeservers should use 3PIDs + * added through this endpoint for password resets instead of relying on the + * identity server. + * + * Homeservers should prevent the caller from adding a 3PID to their account if + * it has already been added to another user's account on the homeserver. + */ +class Add3PIDJob : public BaseJob { +public: + /*! \brief Adds contact information to the user's account. + * + * + * \param clientSecret + * The client secret used in the session with the homeserver. + * + * \param sid + * The session identifier given by the homeserver. + * + * \param auth + * Additional authentication information for the + * user-interactive authentication API. + */ + explicit Add3PIDJob(const QString& clientSecret, const QString& sid, + const Omittable<AuthenticationData>& auth = none); +}; + +/*! \brief Binds a 3PID to the user's account through an Identity Service. + * + * Binds a 3PID to the user's account through the specified identity server. + * + * Homeservers should not prevent this request from succeeding if another user + * has bound the 3PID. Homeservers should simply proxy any errors received by + * the identity server to the caller. + * + * Homeservers should track successful binds so they can be unbound later. + */ +class Bind3PIDJob : public BaseJob { +public: + /*! \brief Binds a 3PID to the user's account through an Identity Service. + * + * + * \param clientSecret + * The client secret used in the session with the identity server. + * + * \param idServer + * The identity server to use. + * + * \param idAccessToken + * An access token previously registered with the identity server. + * + * \param sid + * The session identifier given by the identity server. + */ + explicit Bind3PIDJob(const QString& clientSecret, const QString& idServer, + const QString& idAccessToken, const QString& sid); }; /*! \brief Deletes a third party identifier from the user's account * * Removes a third party identifier from the user's account. This might not * cause an unbind of the identifier from the identity server. + * + * 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 Delete3pidFromAccountJob : public BaseJob { public: /*! \brief Deletes a third party identifier from the user's account * + * * \param medium * The medium of the third party identifier being removed. + * * \param address * The third party address being removed. + * + * \param idServer + * The identity server to unbind from. If not provided, the homeserver + * MUST use the ``id_server`` the identifier was added through. If the + * homeserver does not know the original ``id_server``, it MUST return + * a ``id_server_unbind_result`` of ``no-support``. */ explicit Delete3pidFromAccountJob(const QString& medium, - const QString& address); + const QString& address, + const QString& idServer = {}); + + // Result properties + + /// An indicator as to whether or not the homeserver was able to unbind + /// the 3PID from the identity server. ``success`` indicates that the + /// indentity server has unbound the identifier whereas ``no-support`` + /// indicates that the identity server refuses to support the request + /// or the homeserver was not able to determine an identity server to + /// unbind from. + QString idServerUnbindResult() const + { + return loadFromJson<QString>("id_server_unbind_result"_ls); + } +}; + +/*! \brief Removes a user's third party identifier from an identity server. + * + * Removes a user's third party identifier from the provided identity server + * without removing it from the homeserver. + * + * 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 Unbind3pidFromAccountJob : public BaseJob { +public: + /*! \brief Removes a user's third party identifier from an identity server. + * + * + * \param medium + * The medium of the third party identifier being removed. + * + * \param address + * The third party address being removed. + * + * \param idServer + * The identity server to unbind from. If not provided, the homeserver + * MUST use the ``id_server`` the identifier was added through. If the + * homeserver does not know the original ``id_server``, it MUST return + * a ``id_server_unbind_result`` of ``no-support``. + */ + explicit Unbind3pidFromAccountJob(const QString& medium, + const QString& address, + const QString& idServer = {}); + + // Result properties + + /// An indicator as to whether or not the identity server was able to unbind + /// the 3PID. ``success`` indicates that the identity server has unbound the + /// identifier whereas ``no-support`` indicates that the identity server + /// refuses to support the request or the homeserver was not able to + /// determine an identity server to unbind from. + QString idServerUnbindResult() const + { + return loadFromJson<QString>("id_server_unbind_result"_ls); + } }; /*! \brief Begins the validation process for an email address for association * with the user's account. * - * 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. This API should be used to request - * validation tokens when adding an email address to an account. This API's - * parameters and response are identical to that of the - * |/register/email/requestToken|_ endpoint. + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. This API should + * be used to request validation tokens when adding an email address to an + * account. This API's parameters and response are identical to that of + * the |/register/email/requestToken|_ endpoint. The homeserver should validate + * the email itself, either by sending a validation email itself or by using + * a service it has control over. */ class RequestTokenTo3PIDEmailJob : public BaseJob { public: /*! \brief Begins the validation process for an email address for * association with the user's 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 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. This API should + * be used to request validation tokens when adding an email address to an + * account. This API's parameters and response are identical to that of + * the |/register/email/requestToken|_ endpoint. The homeserver should + * validate the email itself, either by sending a validation email itself or + * by using a service it has control over. */ - explicit RequestTokenTo3PIDEmailJob(const QString& clientSecret, - const QString& email, int sendAttempt, - const QString& idServer, - const QString& nextLink = {}); - - ~RequestTokenTo3PIDEmailJob() override; + explicit RequestTokenTo3PIDEmailJob(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; + /// An email was sent to the given 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 Begins the validation process for a phone number for association with * the user's 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. This API should be used to request - * validation tokens when adding a phone number to an account. This API's - * parameters and response are identical to that of the - * |/register/msisdn/requestToken|_ endpoint. + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. This API should + * be used to request validation tokens when adding a phone number to an + * account. This API's parameters and response are identical to that of + * the |/register/msisdn/requestToken|_ endpoint. 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 RequestTokenTo3PIDMSISDNJob : public BaseJob { public: /*! \brief Begins the validation process for a phone number for association * with the user's 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. This API should + * be used to request validation tokens when adding a phone number to an + * account. This API's parameters and response are identical to that of + * the |/register/msisdn/requestToken|_ endpoint. 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 RequestTokenTo3PIDMSISDNJob(const QString& clientSecret, - const QString& country, - const QString& phoneNumber, - int sendAttempt, - const QString& idServer, - const QString& nextLink = {}); - - ~RequestTokenTo3PIDMSISDNJob() override; + explicit RequestTokenTo3PIDMSISDNJob(const MsisdnValidationData& 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()); + } }; } // namespace Quotient |