diff --git a/crates/ruma-identity-service-api/src/association/bind_3pid.rs b/crates/ruma-identity-service-api/src/association/bind_3pid.rs index 8aadab0c..a769229c 100644 --- a/crates/ruma-identity-service-api/src/association/bind_3pid.rs +++ b/crates/ruma-identity-service-api/src/association/bind_3pid.rs @@ -1,3 +1,83 @@ +//! `POST /_matrix/identity/*/3pid/bind` +//! //! Endpoint to bind a session to a Matrix user ID. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv23pidbind + + use ruma_api::ruma_api; + use ruma_common::{thirdparty::Medium, MilliSecondsSinceUnixEpoch}; + use ruma_identifiers::{ClientSecret, ServerSignatures, SessionId, UserId}; + + ruma_api! { + metadata: { + description: "Publish an association between a session and a Matrix user ID.", + method: POST, + name: "bind_3pid", + stable_path: "/_matrix/identity/v2/3pid/bind", + rate_limited: false, + authentication: AccessToken, + added: 1.0, + } + + request: { + /// The session ID generated by the `requestToken` call. + pub sid: &'a SessionId, + + /// The client secret passed to the `requestToken` call. + pub client_secret: &'a ClientSecret, + + /// The Matrix user ID to associate with the 3PIDs. + pub mxid: &'a UserId, + } + + response: { + /// The 3PID address of the user being looked up. + pub address: String, + + /// The medium type of the 3PID. + pub medium: Medium, + + /// The Matrix user ID associated with the 3PID. + pub mxid: Box, + + /// A UNIX timestamp before which the association is not known to be valid. + pub not_before: MilliSecondsSinceUnixEpoch, + + /// A UNIX timestamp after which the association is not known to be valid. + pub not_after: MilliSecondsSinceUnixEpoch, + + /// The UNIX timestamp at which the association was verified. + pub ts: MilliSecondsSinceUnixEpoch, + + /// The signatures of the verifiying identity servers which show that the + /// association should be trusted, if you trust the verifying identity services. + pub signatures: ServerSignatures, + } + } + + impl<'a> Request<'a> { + /// Creates a `Request` with the given session ID, client secret and Matrix user ID. + pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, mxid: &'a UserId) -> Self { + Self { sid, client_secret, mxid } + } + } + + impl Response { + /// Creates a `Response` with the given 3PID address, medium, Matrix user ID, timestamps and + /// signatures. + pub fn new( + address: String, + medium: Medium, + mxid: Box, + not_before: MilliSecondsSinceUnixEpoch, + not_after: MilliSecondsSinceUnixEpoch, + ts: MilliSecondsSinceUnixEpoch, + signatures: ServerSignatures, + ) -> Self { + Self { address, medium, mxid, not_before, not_after, ts, signatures } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/bind_3pid/v2.rs b/crates/ruma-identity-service-api/src/association/bind_3pid/v2.rs deleted file mode 100644 index 79a65ff1..00000000 --- a/crates/ruma-identity-service-api/src/association/bind_3pid/v2.rs +++ /dev/null @@ -1,75 +0,0 @@ -//! [POST /_matrix/identity/v2/3pid/bind](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-bind) - -use ruma_api::ruma_api; -use ruma_common::{thirdparty::Medium, MilliSecondsSinceUnixEpoch}; -use ruma_identifiers::{ClientSecret, ServerSignatures, SessionId, UserId}; - -ruma_api! { - metadata: { - description: "Publish an association between a session and a Matrix user ID.", - method: POST, - name: "bind_3pid", - stable_path: "/_matrix/identity/v2/3pid/bind", - rate_limited: false, - authentication: AccessToken, - added: 1.0, - } - - request: { - /// The session ID generated by the `requestToken` call. - pub sid: &'a SessionId, - - /// The client secret passed to the `requestToken` call. - pub client_secret: &'a ClientSecret, - - /// The Matrix user ID to associate with the 3PIDs. - pub mxid: &'a UserId, - } - - response: { - /// The 3PID address of the user being looked up. - pub address: String, - - /// The medium type of the 3PID. - pub medium: Medium, - - /// The Matrix user ID associated with the 3PID. - pub mxid: Box, - - /// A UNIX timestamp before which the association is not known to be valid. - pub not_before: MilliSecondsSinceUnixEpoch, - - /// A UNIX timestamp after which the association is not known to be valid. - pub not_after: MilliSecondsSinceUnixEpoch, - - /// The UNIX timestamp at which the association was verified. - pub ts: MilliSecondsSinceUnixEpoch, - - /// The signatures of the verifiying identity servers which show that the - /// association should be trusted, if you trust the verifying identity services. - pub signatures: ServerSignatures, - } -} - -impl<'a> Request<'a> { - /// Creates a `Request` with the given session ID, client secret and Matrix user ID. - pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, mxid: &'a UserId) -> Self { - Self { sid, client_secret, mxid } - } -} - -impl Response { - /// Creates a `Response` with the given 3PID address, medium, Matrix user ID, timestamps and - /// signatures. - pub fn new( - address: String, - medium: Medium, - mxid: Box, - not_before: MilliSecondsSinceUnixEpoch, - not_after: MilliSecondsSinceUnixEpoch, - ts: MilliSecondsSinceUnixEpoch, - signatures: ServerSignatures, - ) -> Self { - Self { address, medium, mxid, not_before, not_after, ts, signatures } - } -} diff --git a/crates/ruma-identity-service-api/src/association/check_3pid_validity.rs b/crates/ruma-identity-service-api/src/association/check_3pid_validity.rs index b87c57a5..c5409d83 100644 --- a/crates/ruma-identity-service-api/src/association/check_3pid_validity.rs +++ b/crates/ruma-identity-service-api/src/association/check_3pid_validity.rs @@ -1,3 +1,61 @@ +//! `GET /_matrix/identity/*/3pid/getValidated3pid` +//! //! Endpoint to determine the validity of a 3PID. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv23pidgetvalidated3pid + + use js_int::UInt; + use ruma_api::ruma_api; + use ruma_common::thirdparty::Medium; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Determines if a given 3PID has been validated by a user.", + method: GET, + name: "check_3pid_validity", + stable_path: "/_matrix/identity/v2/3pid/getValidated3pid/", + rate_limited: false, + authentication: AccessToken, + added: 1.0, + } + + request: { + /// The Session ID generated by the `requestToken` call. + #[ruma_api(query)] + pub sid: &'a SessionId, + + /// The client secret passed to the `requestToken` call. + #[ruma_api(query)] + pub client_secret: &'a ClientSecret, + } + + response: { + /// The medium type of the 3PID. + pub medium: Medium, + + /// The address of the 3PID being looked up. + pub address: String, + + /// Timestamp, in milliseconds, indicating the time that the 3PID was validated. + pub validated_at: UInt, + } + } + + impl<'a> Request<'a> { + /// Creates a `Request` with the given Session ID and client secret. + pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret) -> Self { + Self { sid, client_secret } + } + } + + impl Response { + /// Creates a `Response` with the given medium, address and validation timestamp. + pub fn new(medium: Medium, address: String, validated_at: UInt) -> Self { + Self { medium, address, validated_at } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/check_3pid_validity/v2.rs b/crates/ruma-identity-service-api/src/association/check_3pid_validity/v2.rs deleted file mode 100644 index 2c858fc2..00000000 --- a/crates/ruma-identity-service-api/src/association/check_3pid_validity/v2.rs +++ /dev/null @@ -1,53 +0,0 @@ -//! [GET /_matrix/identity/v2/3pid/getValidated3pid](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-3pid-getvalidated3pid) - -use js_int::UInt; -use ruma_api::ruma_api; -use ruma_common::thirdparty::Medium; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Determines if a given 3PID has been validated by a user.", - method: GET, - name: "check_3pid_validity", - stable_path: "/_matrix/identity/v2/3pid/getValidated3pid/", - rate_limited: false, - authentication: AccessToken, - added: 1.0, - } - - request: { - /// The Session ID generated by the `requestToken` call. - #[ruma_api(query)] - pub sid: &'a SessionId, - - /// The client secret passed to the `requestToken` call. - #[ruma_api(query)] - pub client_secret: &'a ClientSecret, - } - - response: { - /// The medium type of the 3PID. - pub medium: Medium, - - /// The address of the 3PID being looked up. - pub address: String, - - /// Timestamp, in milliseconds, indicating the time that the 3PID was validated. - pub validated_at: UInt, - } -} - -impl<'a> Request<'a> { - /// Creates a `Request` with the given Session ID and client secret. - pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret) -> Self { - Self { sid, client_secret } - } -} - -impl Response { - /// Creates a `Response` with the given medium, address and validation timestamp. - pub fn new(medium: Medium, address: String, validated_at: UInt) -> Self { - Self { medium, address, validated_at } - } -} diff --git a/crates/ruma-identity-service-api/src/association/email/create_email_validation_session.rs b/crates/ruma-identity-service-api/src/association/email/create_email_validation_session.rs index 8aa4cd97..40519e8d 100644 --- a/crates/ruma-identity-service-api/src/association/email/create_email_validation_session.rs +++ b/crates/ruma-identity-service-api/src/association/email/create_email_validation_session.rs @@ -1,3 +1,69 @@ +//! `POST /_matrix/identity/*/validate/email/requestToken` +//! //! Create a session for verifying an email. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2validateemailrequesttoken + + use js_int::UInt; + use ruma_api::ruma_api; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Creates a session for validating an email address.", + method: POST, + name: "create_email_validation_session", + stable_path: "/_matrix/identity/v2/validate/email/requestToken", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// A unique string generated by the client, and used to identify the validation attempt. + pub client_secret: &'a ClientSecret, + + /// The email address to validate. + pub email: &'a str, + + /// 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. + pub send_attempt: UInt, + + /// When the validation is completed, the identity server will redirect the user to this + /// URL. + #[serde(skip_serializing_if = "Option::is_none")] + pub next_link: Option<&'a str>, + } + + response: { + /// The session ID. + /// + /// Session IDs are opaque strings generated by the identity server. + pub sid: Box, + } + } + + impl<'a> Request<'a> { + /// Create a new `Request` with the given client secret, email ID, `send_attempt` number, + /// and the link to redirect to after validation. + pub fn new( + client_secret: &'a ClientSecret, + email: &'a str, + send_attempt: UInt, + next_link: Option<&'a str>, + ) -> Self { + Self { client_secret, email, send_attempt, next_link } + } + } + + impl Response { + /// Create a new `Response` with the given session ID. + pub fn new(sid: Box) -> Self { + Self { sid } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/email/create_email_validation_session/v2.rs b/crates/ruma-identity-service-api/src/association/email/create_email_validation_session/v2.rs deleted file mode 100644 index 317191fc..00000000 --- a/crates/ruma-identity-service-api/src/association/email/create_email_validation_session/v2.rs +++ /dev/null @@ -1,61 +0,0 @@ -//! [POST /_matrix/identity/v2/validate/email/requestToken](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-email-requesttoken) - -use js_int::UInt; -use ruma_api::ruma_api; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Creates a session for validating an email address.", - method: POST, - name: "create_email_validation_session", - stable_path: "/_matrix/identity/v2/validate/email/requestToken", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// A unique string generated by the client, and used to identify the validation attempt. - pub client_secret: &'a ClientSecret, - - /// The email address to validate. - pub email: &'a str, - - /// 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. - pub send_attempt: UInt, - - /// When the validation is completed, the identity server will redirect the user to this - /// URL. - #[serde(skip_serializing_if = "Option::is_none")] - pub next_link: Option<&'a str>, - } - - response: { - /// The session ID. - /// - /// Session IDs are opaque strings generated by the identity server. - pub sid: Box, - } -} - -impl<'a> Request<'a> { - /// Create a new `Request` with the given client secret, email ID, `send_attempt` number, and - /// the link to redirect to after validation. - pub fn new( - client_secret: &'a ClientSecret, - email: &'a str, - send_attempt: UInt, - next_link: Option<&'a str>, - ) -> Self { - Self { client_secret, email, send_attempt, next_link } - } -} - -impl Response { - /// Create a new `Response` with the given session ID. - pub fn new(sid: Box) -> Self { - Self { sid } - } -} diff --git a/crates/ruma-identity-service-api/src/association/email/validate_email.rs b/crates/ruma-identity-service-api/src/association/email/validate_email.rs index b17fc825..ad62bd97 100644 --- a/crates/ruma-identity-service-api/src/association/email/validate_email.rs +++ b/crates/ruma-identity-service-api/src/association/email/validate_email.rs @@ -1,3 +1,54 @@ +//! `POST /_matrix/identity/*/validate/email/submitToken` +//! //! Validate an email ID after creation of a session. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2validateemailsubmittoken + + use ruma_api::ruma_api; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Validate ownership of an email address.", + method: POST, + name: "validate_email", + stable_path: "/_matrix/identity/v2/validate/email/submitToken", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The session ID, generated by the `requestToken` call. + pub sid: &'a SessionId, + + /// The client secret that was supplied to the `requestToken` call. + pub client_secret: &'a ClientSecret, + + /// The token generated by the `requestToken` call and emailed to the user. + pub token: &'a str, + } + + response: { + /// Whether the validation was successful or not. + pub success: bool, + } + } + + impl<'a> Request<'a> { + /// Create a new `Request` with the given session ID, client secret and token. + pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { + Self { sid, client_secret, token } + } + } + + impl Response { + /// Create a new `Response` with the success status. + pub fn new(success: bool) -> Self { + Self { success } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/email/validate_email/v2.rs b/crates/ruma-identity-service-api/src/association/email/validate_email/v2.rs deleted file mode 100644 index 8f17bf90..00000000 --- a/crates/ruma-identity-service-api/src/association/email/validate_email/v2.rs +++ /dev/null @@ -1,46 +0,0 @@ -//! [POST /_matrix/identity/v2/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-email-submittoken) - -use ruma_api::ruma_api; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Validate ownership of an email address.", - method: POST, - name: "validate_email", - stable_path: "/_matrix/identity/v2/validate/email/submitToken", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The session ID, generated by the `requestToken` call. - pub sid: &'a SessionId, - - /// The client secret that was supplied to the `requestToken` call. - pub client_secret: &'a ClientSecret, - - /// The token generated by the `requestToken` call and emailed to the user. - pub token: &'a str, - } - - response: { - /// Whether the validation was successful or not. - pub success: bool, - } -} - -impl<'a> Request<'a> { - /// Create a new `Request` with the given session ID, client secret and token. - pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { - Self { sid, client_secret, token } - } -} - -impl Response { - /// Create a new `Response` with the success status. - pub fn new(success: bool) -> Self { - Self { success } - } -} diff --git a/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user.rs b/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user.rs index 6bfc6723..90a1fbc7 100644 --- a/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user.rs +++ b/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user.rs @@ -1,3 +1,55 @@ +//! `GET /_matrix/identity/*/validate/email/submitToken` +//! //! Endpoint for validation of an email ID by the end-user, after creation of a session. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2validateemailsubmittoken + + use ruma_api::ruma_api; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Validate ownership of an email address.", + method: GET, + name: "validate_email_by_end_user", + stable_path: "/_matrix/identity/v2/validate/email/submitToken", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The session ID, generated by the `requestToken` call. + #[ruma_api(query)] + pub sid: &'a SessionId, + + /// The client secret that was supplied to the `requestToken` call. + #[ruma_api(query)] + pub client_secret: &'a ClientSecret, + + /// The token generated by the `requestToken` call and emailed to the user. + #[ruma_api(query)] + pub token: &'a str, + } + + #[derive(Default)] + response: {} + } + + impl<'a> Request<'a> { + /// Create a new `Request` with the given session ID, client secret and token. + pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { + Self { sid, client_secret, token } + } + } + + impl Response { + /// Create a new empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user/v2.rs b/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user/v2.rs deleted file mode 100644 index 346d099d..00000000 --- a/crates/ruma-identity-service-api/src/association/email/validate_email_by_end_user/v2.rs +++ /dev/null @@ -1,47 +0,0 @@ -//! [GET /_matrix/identity/v2/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-validate-email-submittoken) - -use ruma_api::ruma_api; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Validate ownership of an email address.", - method: GET, - name: "validate_email_by_end_user", - stable_path: "/_matrix/identity/v2/validate/email/submitToken", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The session ID, generated by the `requestToken` call. - #[ruma_api(query)] - pub sid: &'a SessionId, - - /// The client secret that was supplied to the `requestToken` call. - #[ruma_api(query)] - pub client_secret: &'a ClientSecret, - - /// The token generated by the `requestToken` call and emailed to the user. - #[ruma_api(query)] - pub token: &'a str, - } - - #[derive(Default)] - response: {} -} - -impl<'a> Request<'a> { - /// Create a new `Request` with the given session ID, client secret and token. - pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { - Self { sid, client_secret, token } - } -} - -impl Response { - /// Create a new empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session.rs b/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session.rs index c8d85a82..ce4c16fb 100644 --- a/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session.rs +++ b/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session.rs @@ -1,3 +1,75 @@ +//! `POST /_matrix/identity/*/validate/msisdn/requestToken` +//! //! Create a session for validation of a phone number. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2validatemsisdnrequesttoken + + use js_int::UInt; + use ruma_api::ruma_api; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Creates a session for validating a phone number.", + method: POST, + name: "create_msisdn_validation_session", + stable_path: "/_matrix/identity/v2/validate/msisdn/requestToken", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// A unique string generated by the client, and used to identify the validation attempt. + pub client_secret: &'a ClientSecret, + + /// The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in + /// `phone_number` should be parsed as if it were dialled from. + pub country: &'a str, + + /// The phone number to validate. + pub phone_number: &'a str, + + /// 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. + pub send_attempt: UInt, + + /// When the validation is completed, the identity server will redirect the user to this + /// URL. + #[serde(skip_serializing_if = "Option::is_none")] + pub next_link: Option<&'a str>, + } + + response: { + /// The session ID. + /// + /// Session IDs are opaque strings generated by the identity server. + pub sid: Box, + } + } + + impl<'a> Request<'a> { + /// Create a new `Request` with the given client secret, country code, phone number, the + /// `send_attempt` number and the next link to go to after validation. + pub fn new( + client_secret: &'a ClientSecret, + country: &'a str, + phone_number: &'a str, + send_attempt: UInt, + next_link: Option<&'a str>, + ) -> Self { + Self { client_secret, country, phone_number, send_attempt, next_link } + } + } + + impl Response { + /// Create a new `Response` with the given session ID. + pub fn new(sid: Box) -> Self { + Self { sid } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session/v2.rs b/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session/v2.rs deleted file mode 100644 index 80b28a4d..00000000 --- a/crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session/v2.rs +++ /dev/null @@ -1,67 +0,0 @@ -//! [POST /_matrix/identity/v2/validate/msisdn/requestToken](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-msisdn-requesttoken) - -use js_int::UInt; -use ruma_api::ruma_api; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Creates a session for validating a phone number.", - method: POST, - name: "create_msisdn_validation_session", - stable_path: "/_matrix/identity/v2/validate/msisdn/requestToken", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// A unique string generated by the client, and used to identify the validation attempt. - pub client_secret: &'a ClientSecret, - - /// The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in - /// `phone_number` should be parsed as if it were dialled from. - pub country: &'a str, - - /// The phone number to validate. - pub phone_number: &'a str, - - /// 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. - pub send_attempt: UInt, - - /// When the validation is completed, the identity server will redirect the user to this - /// URL. - #[serde(skip_serializing_if = "Option::is_none")] - pub next_link: Option<&'a str>, - } - - response: { - /// The session ID. - /// - /// Session IDs are opaque strings generated by the identity server. - pub sid: Box, - } -} - -impl<'a> Request<'a> { - /// Create a new `Request` with the given client secret, country code, phone number, the - /// `send_attempt` number and the next link to go to after validation. - pub fn new( - client_secret: &'a ClientSecret, - country: &'a str, - phone_number: &'a str, - send_attempt: UInt, - next_link: Option<&'a str>, - ) -> Self { - Self { client_secret, country, phone_number, send_attempt, next_link } - } -} - -impl Response { - /// Create a new `Response` with the given session ID. - pub fn new(sid: Box) -> Self { - Self { sid } - } -} diff --git a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn.rs b/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn.rs index 2fde4af1..027204c1 100644 --- a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn.rs +++ b/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn.rs @@ -1,3 +1,54 @@ +//! `POST /_matrix/identity/*/validate/msisdn/submitToken` +//! //! Validate the ownership of a phone number. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken + + use ruma_api::ruma_api; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Validate ownership of an phone number.", + method: POST, + name: "validate_msisdn", + stable_path: "/_matrix/identity/v2/validate/msisdn/submitToken", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The session ID, generated by the `requestToken` call. + pub sid: &'a SessionId, + + /// The client secret that was supplied to the `requestToken` call. + pub client_secret: &'a ClientSecret, + + /// The token generated by the `requestToken` call and sent to the user. + pub token: &'a str, + } + + response: { + /// Whether the validation was successful or not. + pub success: bool, + } + } + + impl<'a> Request<'a> { + /// Create a new `Request` with the given session ID, client secret and token. + pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { + Self { sid, client_secret, token } + } + } + + impl Response { + /// Create a new `Response` with the success status. + pub fn new(success: bool) -> Self { + Self { success } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn/v2.rs b/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn/v2.rs deleted file mode 100644 index 806e4fc8..00000000 --- a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn/v2.rs +++ /dev/null @@ -1,46 +0,0 @@ -//! [POST /_matrix/identity/v2/validate/msisdn/submitToken](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-msisdn-submittoken) - -use ruma_api::ruma_api; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Validate ownership of an phone number.", - method: POST, - name: "validate_msisdn", - stable_path: "/_matrix/identity/v2/validate/msisdn/submitToken", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The session ID, generated by the `requestToken` call. - pub sid: &'a SessionId, - - /// The client secret that was supplied to the `requestToken` call. - pub client_secret: &'a ClientSecret, - - /// The token generated by the `requestToken` call and sent to the user. - pub token: &'a str, - } - - response: { - /// Whether the validation was successful or not. - pub success: bool, - } -} - -impl<'a> Request<'a> { - /// Create a new `Request` with the given session ID, client secret and token. - pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { - Self { sid, client_secret, token } - } -} - -impl Response { - /// Create a new `Response` with the success status. - pub fn new(success: bool) -> Self { - Self { success } - } -} diff --git a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number.rs b/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number.rs index c4dfa542..b75ae175 100644 --- a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number.rs +++ b/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number.rs @@ -1,3 +1,55 @@ +//! `GET /_matrix/identity/*/validate/msisdn/submitToken` +//! //! Endpoint to validate the ownership of a phone number by the end user. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2validatemsisdnsubmittoken + + use ruma_api::ruma_api; + use ruma_identifiers::{ClientSecret, SessionId}; + + ruma_api! { + metadata: { + description: "Validate ownership of an email address.", + method: GET, + name: "validate_email_by_end_user", + stable_path: "/_matrix/identity/v2/validate/msisdn/submitToken", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The session ID, generated by the `requestToken` call. + #[ruma_api(query)] + pub sid: &'a SessionId, + + /// The client secret that was supplied to the `requestToken` call. + #[ruma_api(query)] + pub client_secret: &'a ClientSecret, + + /// The token generated by the `requestToken` call and sent to the user. + #[ruma_api(query)] + pub token: &'a str, + } + + #[derive(Default)] + response: {} + } + + impl<'a> Request<'a> { + /// Create a new `Request` with the given session ID, client secret and token. + pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { + Self { sid, client_secret, token } + } + } + + impl Response { + /// Create a new empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number/v2.rs b/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number/v2.rs deleted file mode 100644 index 3312ad01..00000000 --- a/crates/ruma-identity-service-api/src/association/msisdn/validate_msisdn_by_phone_number/v2.rs +++ /dev/null @@ -1,47 +0,0 @@ -//! [GET /_matrix/identity/v2/validate/msisdn/submitToken](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-validate-msisdn-submittoken) - -use ruma_api::ruma_api; -use ruma_identifiers::{ClientSecret, SessionId}; - -ruma_api! { - metadata: { - description: "Validate ownership of an email address.", - method: GET, - name: "validate_email_by_end_user", - stable_path: "/_matrix/identity/v2/validate/msisdn/submitToken", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The session ID, generated by the `requestToken` call. - #[ruma_api(query)] - pub sid: &'a SessionId, - - /// The client secret that was supplied to the `requestToken` call. - #[ruma_api(query)] - pub client_secret: &'a ClientSecret, - - /// The token generated by the `requestToken` call and sent to the user. - #[ruma_api(query)] - pub token: &'a str, - } - - #[derive(Default)] - response: {} -} - -impl<'a> Request<'a> { - /// Create a new `Request` with the given session ID, client secret and token. - pub fn new(sid: &'a SessionId, client_secret: &'a ClientSecret, token: &'a str) -> Self { - Self { sid, client_secret, token } - } -} - -impl Response { - /// Create a new empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-identity-service-api/src/association/unbind_3pid.rs b/crates/ruma-identity-service-api/src/association/unbind_3pid.rs index 7e744e15..55ac702e 100644 --- a/crates/ruma-identity-service-api/src/association/unbind_3pid.rs +++ b/crates/ruma-identity-service-api/src/association/unbind_3pid.rs @@ -1,3 +1,104 @@ +//! `POST /_matrix/identity/*/3pid/unbind` +//! //! Endpoint to remove an association between a session and a Matrix user ID. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv23pidunbind + + use ruma_api::ruma_api; + use ruma_common::thirdparty::Medium; + use ruma_identifiers::{user_id::UserId, ClientSecret, SessionId}; + use serde::{Deserialize, Serialize}; + + ruma_api! { + metadata: { + description: "Remove an association between a session and a Matrix user ID.", + method: POST, + name: "unbind_3pid", + stable_path: "/_matrix/identity/v2/3pid/unbind", + rate_limited: false, + authentication: AccessToken, + added: 1.0, + } + + request: { + /// The proof that the client owns the 3PID. + /// + /// If this is not provided, the request must be signed by the homeserver which controls + /// the `mxid`. + #[serde(flatten, skip_serializing_if = "Option::is_none")] + pub threepid_ownership_proof: Option<&'a ThreePidOwnershipProof>, + + /// The Matrix user ID to remove from the 3PIDs. + pub mxid: &'a UserId, + + /// The 3PID to remove. + /// + /// Must match the 3PID used to generate the session if using `sid` and `client_secret` to + /// authenticate this request. + pub threepid: &'a ThirdPartyId, + } + + #[derive(Default)] + response: {} + } + + impl<'a> Request<'a> { + /// Creates a `Request` with the given Session ID, client secret, Matrix user ID and 3PID. + pub fn new( + threepid_ownership_proof: Option<&'a ThreePidOwnershipProof>, + mxid: &'a UserId, + threepid: &'a ThirdPartyId, + ) -> Self { + Self { threepid_ownership_proof, mxid, threepid } + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new() -> Self { + Self {} + } + } + + /// A 3PID to unbind. + #[derive(Clone, Debug, Serialize, Deserialize)] + #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] + pub struct ThirdPartyId { + /// A medium matching the medium of identifier to unbind. + pub medium: Medium, + + /// The 3PID address to remove. + pub address: String, + } + + impl ThirdPartyId { + /// Creates a new `ThirdPartyId` with the given medium and address. + pub fn new(medium: Medium, address: String) -> Self { + Self { medium, address } + } + } + + /// A proof that the client owns the 3PID. + /// + /// Must be constructed using the same session ID and client secret generated and passed by the + /// `requestToken` call for the given 3PID. + #[derive(Clone, Debug, Serialize, Deserialize)] + #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] + pub struct ThreePidOwnershipProof { + /// The Session ID generated by the `requestToken` call. + pub sid: Box, + + /// The client secret passed to the `requestToken` call. + pub client_secret: Box, + } + + impl ThreePidOwnershipProof { + /// Creates a new `ThreePidOwnershipProof` with the given session ID and client secret. + pub fn new(sid: Box, client_secret: Box) -> Self { + Self { sid, client_secret } + } + } +} diff --git a/crates/ruma-identity-service-api/src/association/unbind_3pid/v2.rs b/crates/ruma-identity-service-api/src/association/unbind_3pid/v2.rs deleted file mode 100644 index 092d7014..00000000 --- a/crates/ruma-identity-service-api/src/association/unbind_3pid/v2.rs +++ /dev/null @@ -1,96 +0,0 @@ -//! [POST /_matrix/identity/v2/3pid/unbind](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-unbind) - -use ruma_api::ruma_api; -use ruma_common::thirdparty::Medium; -use ruma_identifiers::{user_id::UserId, ClientSecret, SessionId}; -use serde::{Deserialize, Serialize}; - -ruma_api! { - metadata: { - description: "Remove an association between a session and a Matrix user ID.", - method: POST, - name: "unbind_3pid", - stable_path: "/_matrix/identity/v2/3pid/unbind", - rate_limited: false, - authentication: AccessToken, - added: 1.0, - } - - request: { - /// The proof that the client owns the 3PID. - /// - /// If this is not provided, the request must be signed by the homeserver which controls - /// the `mxid`. - #[serde(flatten, skip_serializing_if = "Option::is_none")] - pub threepid_ownership_proof: Option<&'a ThreePidOwnershipProof>, - - /// The Matrix user ID to remove from the 3PIDs. - pub mxid: &'a UserId, - - /// The 3PID to remove. - /// - /// Must match the 3PID used to generate the session if using `sid` and `client_secret` to - /// authenticate this request. - pub threepid: &'a ThirdPartyId, - } - - #[derive(Default)] - response: {} -} - -impl<'a> Request<'a> { - /// Creates a `Request` with the given Session ID, client secret, Matrix user ID and 3PID. - pub fn new( - threepid_ownership_proof: Option<&'a ThreePidOwnershipProof>, - mxid: &'a UserId, - threepid: &'a ThirdPartyId, - ) -> Self { - Self { threepid_ownership_proof, mxid, threepid } - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new() -> Self { - Self {} - } -} - -/// A 3PID to unbind. -#[derive(Clone, Debug, Serialize, Deserialize)] -#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] -pub struct ThirdPartyId { - /// A medium matching the medium of identifier to unbind. - pub medium: Medium, - - /// The 3PID address to remove. - pub address: String, -} - -impl ThirdPartyId { - /// Creates a new `ThirdPartyId` with the given medium and address. - pub fn new(medium: Medium, address: String) -> Self { - Self { medium, address } - } -} - -/// A proof that the client owns the 3PID. -/// -/// Must be constructed using the same session ID and client secret generated and passed by the -/// `requestToken` call for the given 3PID. -#[derive(Clone, Debug, Serialize, Deserialize)] -#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] -pub struct ThreePidOwnershipProof { - /// The Session ID generated by the `requestToken` call. - pub sid: Box, - - /// The client secret passed to the `requestToken` call. - pub client_secret: Box, -} - -impl ThreePidOwnershipProof { - /// Creates a new `ThreePidOwnershipProof` with the given session ID and client secret. - pub fn new(sid: Box, client_secret: Box) -> Self { - Self { sid, client_secret } - } -} diff --git a/crates/ruma-identity-service-api/src/authentication/get_account_information.rs b/crates/ruma-identity-service-api/src/authentication/get_account_information.rs index 885f4353..3a6a7bfd 100644 --- a/crates/ruma-identity-service-api/src/authentication/get_account_information.rs +++ b/crates/ruma-identity-service-api/src/authentication/get_account_information.rs @@ -1,3 +1,46 @@ +//! `GET /_matrix/identity/*/account` +//! //! Gets information about what user owns the access token used in the request. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2account + + use ruma_api::ruma_api; + use ruma_identifiers::UserId; + + ruma_api! { + metadata: { + description: "Gets information about what user owns the access token used in the request.", + method: POST, + name: "get_account_information", + stable_path: "/_matrix/identity/v2/account", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + #[derive(Default)] + request: {} + + response: { + /// The user ID which registered the token. + pub user_id: Box, + } + } + + impl Request { + /// Creates an empty `Request`. + pub fn new() -> Self { + Self {} + } + } + + impl Response { + /// Creates a new `Response` with the given `UserId`. + pub fn new(user_id: Box) -> Self { + Self { user_id } + } + } +} diff --git a/crates/ruma-identity-service-api/src/authentication/get_account_information/v2.rs b/crates/ruma-identity-service-api/src/authentication/get_account_information/v2.rs deleted file mode 100644 index 2c0b38c9..00000000 --- a/crates/ruma-identity-service-api/src/authentication/get_account_information/v2.rs +++ /dev/null @@ -1,38 +0,0 @@ -//! [GET /_matrix/identity/v2/account](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-account) - -use ruma_api::ruma_api; -use ruma_identifiers::UserId; - -ruma_api! { - metadata: { - description: "Gets information about what user owns the access token used in the request.", - method: POST, - name: "get_account_information", - stable_path: "/_matrix/identity/v2/account", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - #[derive(Default)] - request: {} - - response: { - /// The user ID which registered the token. - pub user_id: Box, - } -} - -impl Request { - /// Creates an empty `Request`. - pub fn new() -> Self { - Self {} - } -} - -impl Response { - /// Creates a new `Response` with the given `UserId`. - pub fn new(user_id: Box) -> Self { - Self { user_id } - } -} diff --git a/crates/ruma-identity-service-api/src/authentication/logout.rs b/crates/ruma-identity-service-api/src/authentication/logout.rs index d7b6f790..5943b2d4 100644 --- a/crates/ruma-identity-service-api/src/authentication/logout.rs +++ b/crates/ruma-identity-service-api/src/authentication/logout.rs @@ -1,4 +1,44 @@ +//! `POST /_matrix/identity/*/account/logout` +//! //! Logs out the access token, preventing it from being used to authenticate future requests to the //! server. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2accountlogout + + use ruma_api::ruma_api; + + ruma_api! { + metadata: { + description: "Logs out the access token, preventing it from being used to authenticate future requests to the server.", + method: POST, + name: "logout", + stable_path: "/_matrix/identity/v2/account/logout", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + #[derive(Default)] + request: {} + + #[derive(Default)] + response: {} + } + + impl Request { + /// Creates an empty `Request`. + pub fn new() -> Self { + Self {} + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-identity-service-api/src/authentication/logout/v2.rs b/crates/ruma-identity-service-api/src/authentication/logout/v2.rs deleted file mode 100644 index cddd9425..00000000 --- a/crates/ruma-identity-service-api/src/authentication/logout/v2.rs +++ /dev/null @@ -1,35 +0,0 @@ -//! [POST /_matrix/identity/v2/account/logout](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-account-logout) - -use ruma_api::ruma_api; - -ruma_api! { - metadata: { - description: "Logs out the access token, preventing it from being used to authenticate future requests to the server.", - method: POST, - name: "logout", - stable_path: "/_matrix/identity/v2/account/logout", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - #[derive(Default)] - request: {} - - #[derive(Default)] - response: {} -} - -impl Request { - /// Creates an empty `Request`. - pub fn new() -> Self { - Self {} - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-identity-service-api/src/authentication/register.rs b/crates/ruma-identity-service-api/src/authentication/register.rs index 2471b10f..7b3f0912 100644 --- a/crates/ruma-identity-service-api/src/authentication/register.rs +++ b/crates/ruma-identity-service-api/src/authentication/register.rs @@ -1,3 +1,72 @@ +//! `POST /_matrix/identity/*/account/register` +//! //! Exchanges an OpenID token from the homeserver for an access token to access the identity server. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2accountregister + + use std::time::Duration; + + use ruma_api::ruma_api; + use ruma_common::authentication::TokenType; + use ruma_identifiers::ServerName; + + ruma_api! { + metadata: { + description: "Exchanges an OpenID token from the homeserver for an access token to access the identity server.", + method: POST, + name: "register_account", + stable_path: "/_matrix/identity/v2/account/register", + authentication: None, + rate_limited: false, + added: 1.0, + } + + request: { + /// An access token the consumer may use to verify the identity of the person who generated + /// the token. + /// + /// This is given to the federation API `GET /openid/userinfo` to verify the user's + /// identity. + pub access_token: &'a str, + + /// The string `Bearer`. + pub token_type: TokenType, + + /// The homeserver domain the consumer should use when attempting to verify the user's + /// identity. + pub matrix_server_name: &'a ServerName, + + /// The number of seconds before this token expires and a new one must be generated. + #[serde(with = "ruma_serde::duration::secs")] + pub expires_in: Duration, + } + + response: { + /// An opaque string representing the token to authenticate future requests to the identity + /// server with. + pub token: String, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given parameters. + pub fn new( + access_token: &'a str, + token_type: TokenType, + matrix_server_name: &'a ServerName, + expires_in: Duration, + ) -> Self { + Self { access_token, token_type, matrix_server_name, expires_in } + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new(token: String) -> Self { + Self { token } + } + } +} diff --git a/crates/ruma-identity-service-api/src/authentication/register/v2.rs b/crates/ruma-identity-service-api/src/authentication/register/v2.rs deleted file mode 100644 index 29f80e60..00000000 --- a/crates/ruma-identity-service-api/src/authentication/register/v2.rs +++ /dev/null @@ -1,64 +0,0 @@ -//! [POST /_matrix/identity/v2/account/register](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-account-register) - -use std::time::Duration; - -use ruma_api::ruma_api; -use ruma_common::authentication::TokenType; -use ruma_identifiers::ServerName; - -ruma_api! { - metadata: { - description: "Exchanges an OpenID token from the homeserver for an access token to access the identity server.", - method: POST, - name: "register_account", - stable_path: "/_matrix/identity/v2/account/register", - authentication: None, - rate_limited: false, - added: 1.0, - } - - request: { - /// An access token the consumer may use to verify the identity of the person who generated - /// the token. - /// - /// This is given to the federation API `GET /openid/userinfo` to verify the user's - /// identity. - pub access_token: &'a str, - - /// The string `Bearer`. - pub token_type: TokenType, - - /// The homeserver domain the consumer should use when attempting to verify the user's - /// identity. - pub matrix_server_name: &'a ServerName, - - /// The number of seconds before this token expires and a new one must be generated. - #[serde(with = "ruma_serde::duration::secs")] - pub expires_in: Duration, - } - - response: { - /// An opaque string representing the token to authenticate future requests to the identity - /// server with. - pub token: String, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given parameters. - pub fn new( - access_token: &'a str, - token_type: TokenType, - matrix_server_name: &'a ServerName, - expires_in: Duration, - ) -> Self { - Self { access_token, token_type, matrix_server_name, expires_in } - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new(token: String) -> Self { - Self { token } - } -} diff --git a/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519.rs b/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519.rs index 53a64ac1..df370060 100644 --- a/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519.rs +++ b/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519.rs @@ -1,2 +1,70 @@ +//! `POST /_matrix/identity/*/sign-ed25519` +//! //! Endpoint to sign invitation details. -pub mod v2; + +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2sign-ed25519 + + use ruma_api::ruma_api; + use ruma_identifiers::{ServerSignatures, UserId}; + use ruma_serde::Base64; + + ruma_api! { + metadata: { + description: "Sign invitation details.", + method: POST, + name: "sign_invitation_ed25519", + stable_path: "/_matrix/identity/v2/sign-ed25519", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The Matrix user ID of the user accepting the invitation. + pub mxid: &'a UserId, + + /// The token from the call to store-invite. + pub token: &'a str, + + /// The private key, encoded as unpadded base64. + pub private_key: &'a Base64, + } + + response: { + /// The Matrix user ID of the user accepting the invitation. + pub mxid: Box, + + /// The Matrix user ID of the user who sent the invitation. + pub sender: Box, + + /// The signature of the mxid, sender and token. + pub signatures: ServerSignatures, + + /// The token for the invitation. + pub token: String, + } + } + + impl<'a> Request<'a> { + /// Creates a `Request` with the given Matrix user ID, token and private_key. + pub fn new(mxid: &'a UserId, token: &'a str, private_key: &'a Base64) -> Self { + Self { mxid, token, private_key } + } + } + + impl Response { + /// Creates a `Response` with the given Matrix user ID, sender user ID, signatures and + /// token. + pub fn new( + mxid: Box, + sender: Box, + signatures: ServerSignatures, + token: String, + ) -> Self { + Self { mxid, sender, signatures, token } + } + } +} diff --git a/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519/v2.rs b/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519/v2.rs deleted file mode 100644 index 60f87577..00000000 --- a/crates/ruma-identity-service-api/src/invitation/sign_invitation_ed25519/v2.rs +++ /dev/null @@ -1,61 +0,0 @@ -//![POST /_matrix/identity/v2/sign-ed25519](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-sign-ed25519) - -use ruma_api::ruma_api; -use ruma_identifiers::{ServerSignatures, UserId}; -use ruma_serde::Base64; - -ruma_api! { - metadata: { - description: "Sign invitation details.", - method: POST, - name: "sign_invitation_ed25519", - stable_path: "/_matrix/identity/v2/sign-ed25519", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The Matrix user ID of the user accepting the invitation. - pub mxid: &'a UserId, - - /// The token from the call to store-invite. - pub token: &'a str, - - /// The private key, encoded as unpadded base64. - pub private_key: &'a Base64, - } - - response: { - /// The Matrix user ID of the user accepting the invitation. - pub mxid: Box, - - /// The Matrix user ID of the user who sent the invitation. - pub sender: Box, - - /// The signature of the mxid, sender and token. - pub signatures: ServerSignatures, - - /// The token for the invitation. - pub token: String, - } -} - -impl<'a> Request<'a> { - /// Creates a `Request` with the given Matrix user ID, token and private_key. - pub fn new(mxid: &'a UserId, token: &'a str, private_key: &'a Base64) -> Self { - Self { mxid, token, private_key } - } -} - -impl Response { - /// Creates a `Response` with the given Matrix user ID, sender user ID, signatures and token. - pub fn new( - mxid: Box, - sender: Box, - signatures: ServerSignatures, - token: String, - ) -> Self { - Self { mxid, sender, signatures, token } - } -} diff --git a/crates/ruma-identity-service-api/src/invitation/store_invitation.rs b/crates/ruma-identity-service-api/src/invitation/store_invitation.rs index 56b71da3..1c469237 100644 --- a/crates/ruma-identity-service-api/src/invitation/store_invitation.rs +++ b/crates/ruma-identity-service-api/src/invitation/store_invitation.rs @@ -1,3 +1,161 @@ +//! `POST /_matrix/identity/*/store-invite` +//! //! Endpoint to store pending invitations to a user's 3PID. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2store-invite + + use ruma_api::ruma_api; + use ruma_common::thirdparty::Medium; + use ruma_identifiers::{MxcUri, RoomAliasId, RoomId, RoomName, UserId}; + use serde::{ser::SerializeSeq, Deserialize, Serialize}; + + ruma_api! { + metadata: { + description: "Store pending invitations to a user's 3PID.", + method: POST, + name: "store_invitation", + stable_path: "/_matrix/identity/v2/store-invite", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The type of the third party identifier for the invited user. + /// + /// Currently, only `Medium::Email` is supported. + pub medium: &'a Medium, + + /// The email address of the invited user. + pub address: &'a str, + + /// The Matrix room ID to which the user is invited. + pub room_id: &'a RoomId, + + /// The Matrix user ID of the inviting user. + pub sender: &'a UserId, + + /// The Matrix room alias for the room to which the user is invited. + /// + /// This should be retrieved from the `m.room.canonical` state event. + #[serde(skip_serializing_if = "Option::is_none")] + pub room_alias: Option<&'a RoomAliasId>, + + /// The Content URI for the room to which the user is invited. + /// + /// This should be retrieved from the `m.room.avatar` state event. + #[serde(skip_serializing_if = "Option::is_none")] + pub room_avatar_url: Option<&'a MxcUri>, + + /// The `join_rule` for the room to which the user is invited. + /// + /// This should be retrieved from the `m.room.join_rules` state event. + #[serde(skip_serializing_if = "Option::is_none")] + pub room_join_rules: Option<&'a str>, + + /// The name of the room to which the user is invited. + /// + /// This should be retrieved from the `m.room.name` state event. + #[serde(skip_serializing_if = "Option::is_none")] + pub room_name: Option<&'a RoomName>, + + /// The display name of the user ID initiating the invite. + #[serde(skip_serializing_if = "Option::is_none")] + pub sender_display_name: Option<&'a str>, + + /// The Content URI for the avater of the user ID initiating the invite. + #[serde(skip_serializing_if = "Option::is_none")] + pub sender_avatar_url: Option<&'a MxcUri>, + } + + response: { + /// The generated token. + /// + /// 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. + pub token: String, + + /// A list of [server's long-term public key, generated ephemeral public key]. + pub public_keys: PublicKeys, + + /// The generated (redacted) display_name. + /// + /// An example is `f...@b...`. + pub display_name: String, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request with the given medium, email address, room ID and sender. + pub fn new( + medium: &'a Medium, + address: &'a str, + room_id: &'a RoomId, + sender: &'a UserId, + ) -> Self { + Self { + medium, + address, + room_id, + sender, + room_alias: None, + room_avatar_url: None, + room_join_rules: None, + room_name: None, + sender_display_name: None, + sender_avatar_url: None, + } + } + + /// Creates a new `Request` with the given email address, room ID and sender. + pub fn email(address: &'a str, room_id: &'a RoomId, sender: &'a UserId) -> Self { + Self::new(&Medium::Email, address, room_id, sender) + } + } + + impl Response { + /// Creates a new `Response` with the given token, public keys and display name. + pub fn new(token: String, public_keys: PublicKeys, display_name: String) -> Self { + Self { token, public_keys, display_name } + } + } + + /// The server's long-term public key and generated ephemeral public key. + #[derive(Debug, Clone)] + #[allow(clippy::exhaustive_structs)] + pub struct PublicKeys { + /// The server's long-term public key. + pub server_key: String, + + /// The generated ephemeral public key. + pub ephemeral_key: String, + } + + impl<'de> Deserialize<'de> for PublicKeys { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + let [server_key, ephemeral_key] = <[String; 2]>::deserialize(deserializer)?; + + Ok(Self { server_key, ephemeral_key }) + } + } + + impl Serialize for PublicKeys { + fn serialize(&self, serializer: S) -> Result + where + S: serde::Serializer, + { + let mut seq = serializer.serialize_seq(Some(2))?; + + seq.serialize_element(&self.server_key)?; + seq.serialize_element(&self.ephemeral_key)?; + + seq.end() + } + } +} diff --git a/crates/ruma-identity-service-api/src/invitation/store_invitation/v2.rs b/crates/ruma-identity-service-api/src/invitation/store_invitation/v2.rs deleted file mode 100644 index 9d986987..00000000 --- a/crates/ruma-identity-service-api/src/invitation/store_invitation/v2.rs +++ /dev/null @@ -1,153 +0,0 @@ -//! [POST /_matrix/identity/v2/store-invite](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-store-invite) - -use ruma_api::ruma_api; -use ruma_common::thirdparty::Medium; -use ruma_identifiers::{MxcUri, RoomAliasId, RoomId, RoomName, UserId}; -use serde::{ser::SerializeSeq, Deserialize, Serialize}; - -ruma_api! { - metadata: { - description: "Store pending invitations to a user's 3PID.", - method: POST, - name: "store_invitation", - stable_path: "/_matrix/identity/v2/store-invite", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The type of the third party identifier for the invited user. - /// - /// Currently, only `Medium::Email` is supported. - pub medium: &'a Medium, - - /// The email address of the invited user. - pub address: &'a str, - - /// The Matrix room ID to which the user is invited. - pub room_id: &'a RoomId, - - /// The Matrix user ID of the inviting user. - pub sender: &'a UserId, - - /// The Matrix room alias for the room to which the user is invited. - /// - /// This should be retrieved from the `m.room.canonical` state event. - #[serde(skip_serializing_if = "Option::is_none")] - pub room_alias: Option<&'a RoomAliasId>, - - /// The Content URI for the room to which the user is invited. - /// - /// This should be retrieved from the `m.room.avatar` state event. - #[serde(skip_serializing_if = "Option::is_none")] - pub room_avatar_url: Option<&'a MxcUri>, - - /// The `join_rule` for the room to which the user is invited. - /// - /// This should be retrieved from the `m.room.join_rules` state event. - #[serde(skip_serializing_if = "Option::is_none")] - pub room_join_rules: Option<&'a str>, - - /// The name of the room to which the user is invited. - /// - /// This should be retrieved from the `m.room.name` state event. - #[serde(skip_serializing_if = "Option::is_none")] - pub room_name: Option<&'a RoomName>, - - /// The display name of the user ID initiating the invite. - #[serde(skip_serializing_if = "Option::is_none")] - pub sender_display_name: Option<&'a str>, - - /// The Content URI for the avater of the user ID initiating the invite. - #[serde(skip_serializing_if = "Option::is_none")] - pub sender_avatar_url: Option<&'a MxcUri>, - } - - response: { - /// The generated token. - /// - /// 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. - pub token: String, - - /// A list of [server's long-term public key, generated ephemeral public key]. - pub public_keys: PublicKeys, - - /// The generated (redacted) display_name. - /// - /// An example is `f...@b...`. - pub display_name: String, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request with the given medium, email address, room ID and sender. - pub fn new( - medium: &'a Medium, - address: &'a str, - room_id: &'a RoomId, - sender: &'a UserId, - ) -> Self { - Self { - medium, - address, - room_id, - sender, - room_alias: None, - room_avatar_url: None, - room_join_rules: None, - room_name: None, - sender_display_name: None, - sender_avatar_url: None, - } - } - - /// Creates a new `Request` with the given email address, room ID and sender. - pub fn email(address: &'a str, room_id: &'a RoomId, sender: &'a UserId) -> Self { - Self::new(&Medium::Email, address, room_id, sender) - } -} - -impl Response { - /// Creates a new `Response` with the given token, public keys and display name. - pub fn new(token: String, public_keys: PublicKeys, display_name: String) -> Self { - Self { token, public_keys, display_name } - } -} - -/// The server's long-term public key and generated ephemeral public key. -#[derive(Debug, Clone)] -#[allow(clippy::exhaustive_structs)] -pub struct PublicKeys { - /// The server's long-term public key. - pub server_key: String, - - /// The generated ephemeral public key. - pub ephemeral_key: String, -} - -impl<'de> Deserialize<'de> for PublicKeys { - fn deserialize(deserializer: D) -> Result - where - D: serde::Deserializer<'de>, - { - let [server_key, ephemeral_key] = <[String; 2]>::deserialize(deserializer)?; - - Ok(Self { server_key, ephemeral_key }) - } -} - -impl Serialize for PublicKeys { - fn serialize(&self, serializer: S) -> Result - where - S: serde::Serializer, - { - let mut seq = serializer.serialize_seq(Some(2))?; - - seq.serialize_element(&self.server_key)?; - seq.serialize_element(&self.ephemeral_key)?; - - seq.end() - } -} diff --git a/crates/ruma-identity-service-api/src/keys/check_public_key_validity.rs b/crates/ruma-identity-service-api/src/keys/check_public_key_validity.rs index b4d737c5..c41b1b79 100644 --- a/crates/ruma-identity-service-api/src/keys/check_public_key_validity.rs +++ b/crates/ruma-identity-service-api/src/keys/check_public_key_validity.rs @@ -1,3 +1,49 @@ +//! `GET /_matrix/identity/*/pubkey/isvalid` +//! //! Endpoint to check for valid public key with an identity server. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2pubkeyisvalid + + use ruma_api::ruma_api; + use ruma_serde::Base64; + + ruma_api! { + metadata: { + description: "Check whether a long-term public key is valid. The response should always be the same, provided the key exists.", + method: GET, + name: "check_public_key_validity", + stable_path: "/_matrix/identity/v2/pubkey/isvalid", + authentication: None, + rate_limited: false, + added: 1.0, + } + + request: { + /// Base64-encoded (no padding) public key to check for validity. + #[ruma_api(query)] + pub public_key: &'a Base64, + } + + response: { + /// Whether the public key is recognised and is currently valid. + pub valid: bool, + } + } + + impl<'a> Request<'a> { + /// Create a `Request` with the given base64-encoded (unpadded) public key. + pub fn new(public_key: &'a Base64) -> Self { + Self { public_key } + } + } + + impl Response { + /// Create a `Response` with the given bool indicating the validity of the public key. + pub fn new(valid: bool) -> Self { + Self { valid } + } + } +} diff --git a/crates/ruma-identity-service-api/src/keys/check_public_key_validity/v2.rs b/crates/ruma-identity-service-api/src/keys/check_public_key_validity/v2.rs deleted file mode 100644 index 1ad3d9ce..00000000 --- a/crates/ruma-identity-service-api/src/keys/check_public_key_validity/v2.rs +++ /dev/null @@ -1,41 +0,0 @@ -//! [GET /_matrix/identity/v2/pubkey/isvalid](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-pubkey-isvalid) - -use ruma_api::ruma_api; -use ruma_serde::Base64; - -ruma_api! { - metadata: { - description: "Check whether a long-term public key is valid. The response should always be the same, provided the key exists.", - method: GET, - name: "check_public_key_validity", - stable_path: "/_matrix/identity/v2/pubkey/isvalid", - authentication: None, - rate_limited: false, - added: 1.0, - } - - request: { - /// Base64-encoded (no padding) public key to check for validity. - #[ruma_api(query)] - pub public_key: &'a Base64, - } - - response: { - /// Whether the public key is recognised and is currently valid. - pub valid: bool, - } -} - -impl<'a> Request<'a> { - /// Create a `Request` with the given base64-encoded (unpadded) public key. - pub fn new(public_key: &'a Base64) -> Self { - Self { public_key } - } -} - -impl Response { - /// Create a `Response` with the given bool indicating the validity of the public key. - pub fn new(valid: bool) -> Self { - Self { valid } - } -} diff --git a/crates/ruma-identity-service-api/src/keys/get_public_key.rs b/crates/ruma-identity-service-api/src/keys/get_public_key.rs index ac4b08a8..3190869d 100644 --- a/crates/ruma-identity-service-api/src/keys/get_public_key.rs +++ b/crates/ruma-identity-service-api/src/keys/get_public_key.rs @@ -1,3 +1,50 @@ +//! `GET /_matrix/identity/*/pubkey/{keyId}` +//! //! Endpoint to retrieve the public key for a key ID. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2pubkeykeyid + + use ruma_api::ruma_api; + use ruma_identifiers::ServerSigningKeyId; + use ruma_serde::Base64; + + ruma_api! { + metadata: { + description: "Get the public key for the given key ID.", + method: GET, + name: "get_public_key", + stable_path: "/_matrix/identity/v2/pubkey/:key_id", + rate_limited: false, + authentication: None, + added: 1.0, + } + + request: { + /// The ID of the key. + #[ruma_api(path)] + pub key_id: &'a ServerSigningKeyId, + } + + response: { + /// Unpadded base64-encoded public key. + pub public_key: Base64, + } + } + + impl<'a> Request<'a> { + /// Create a `Request` with the given key_id. + pub fn new(key_id: &'a ServerSigningKeyId) -> Self { + Self { key_id } + } + } + + impl Response { + /// Create a `Response` with the given base64-encoded (unpadded) public key. + pub fn new(public_key: Base64) -> Self { + Self { public_key } + } + } +} diff --git a/crates/ruma-identity-service-api/src/keys/get_public_key/v2.rs b/crates/ruma-identity-service-api/src/keys/get_public_key/v2.rs deleted file mode 100644 index 70dec558..00000000 --- a/crates/ruma-identity-service-api/src/keys/get_public_key/v2.rs +++ /dev/null @@ -1,42 +0,0 @@ -//! [GET /_matrix/identity/v2/pubkey/{keyId}](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-pubkey-keyid) - -use ruma_api::ruma_api; -use ruma_identifiers::ServerSigningKeyId; -use ruma_serde::Base64; - -ruma_api! { - metadata: { - description: "Get the public key for the given key ID.", - method: GET, - name: "get_public_key", - stable_path: "/_matrix/identity/v2/pubkey/:key_id", - rate_limited: false, - authentication: None, - added: 1.0, - } - - request: { - /// The ID of the key. - #[ruma_api(path)] - pub key_id: &'a ServerSigningKeyId, - } - - response: { - /// Unpadded base64-encoded public key. - pub public_key: Base64, - } -} - -impl<'a> Request<'a> { - /// Create a `Request` with the given key_id. - pub fn new(key_id: &'a ServerSigningKeyId) -> Self { - Self { key_id } - } -} - -impl Response { - /// Create a `Response` with the given base64-encoded (unpadded) public key. - pub fn new(public_key: Base64) -> Self { - Self { public_key } - } -} diff --git a/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key.rs b/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key.rs index 37809201..c5bbcfeb 100644 --- a/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key.rs +++ b/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key.rs @@ -1,3 +1,50 @@ +//! `GET /_matrix/identity/*/pubkey/ephemeral/isvalid` +//! //! Endpoint to check for validity of short-term public key. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid + + use ruma_api::ruma_api; + use ruma_serde::Base64; + + ruma_api! { + metadata: { + description: "Check whether a short-term public key is valid.", + method: GET, + name: "validate_ephemeral_key", + stable_path: "/_matrix/identity/v2/pubkey/ephemeral/isvalid", + authentication: None, + rate_limited: false, + added: 1.0, + } + + request: { + /// The unpadded base64-encoded short-term public key to check. + #[ruma_api(query)] + pub public_key: &'a Base64, + } + + response: { + /// Whether the short-term public key is recognised and is currently valid. + pub valid: bool, + } + } + + impl<'a> Request<'a> { + /// Create a `Request` with the given base64-encoded (unpadded) short-term public key. + pub fn new(public_key: &'a Base64) -> Self { + Self { public_key } + } + } + + impl Response { + /// Create a `Response` with the given bool indicating the validity of the short-term public + /// key. + pub fn new(valid: bool) -> Self { + Self { valid } + } + } +} diff --git a/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key/v2.rs b/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key/v2.rs deleted file mode 100644 index 1f802a3b..00000000 --- a/crates/ruma-identity-service-api/src/keys/validate_ephemeral_key/v2.rs +++ /dev/null @@ -1,42 +0,0 @@ -//! [GET /_matrix/identity/v2/pubkey/ephemeral/isvalid](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-pubkey-ephemeral-isvalid) - -use ruma_api::ruma_api; -use ruma_serde::Base64; - -ruma_api! { - metadata: { - description: "Check whether a short-term public key is valid.", - method: GET, - name: "validate_ephemeral_key", - stable_path: "/_matrix/identity/v2/pubkey/ephemeral/isvalid", - authentication: None, - rate_limited: false, - added: 1.0, - } - - request: { - /// The unpadded base64-encoded short-term public key to check. - #[ruma_api(query)] - pub public_key: &'a Base64, - } - - response: { - /// Whether the short-term public key is recognised and is currently valid. - pub valid: bool, - } -} - -impl<'a> Request<'a> { - /// Create a `Request` with the given base64-encoded (unpadded) short-term public key. - pub fn new(public_key: &'a Base64) -> Self { - Self { public_key } - } -} - -impl Response { - /// Create a `Response` with the given bool indicating the validity of the short-term public - /// key. - pub fn new(valid: bool) -> Self { - Self { valid } - } -} diff --git a/crates/ruma-identity-service-api/src/lib.rs b/crates/ruma-identity-service-api/src/lib.rs index 5c458d96..c3f1bfb0 100644 --- a/crates/ruma-identity-service-api/src/lib.rs +++ b/crates/ruma-identity-service-api/src/lib.rs @@ -3,7 +3,7 @@ //! (De)serializable types for the [Matrix Identity Service API][identity-api]. //! These types can be shared by client and identity service code. //! -//! [identity-api]: https://matrix.org/docs/spec/identity_service/r0.3.0.html +//! [identity-api]: https://spec.matrix.org/v1.2/identity-service-api/ #![warn(missing_docs)] diff --git a/crates/ruma-identity-service-api/src/lookup/get_hash_parameters.rs b/crates/ruma-identity-service-api/src/lookup/get_hash_parameters.rs index 7d701e53..0af7dbde 100644 --- a/crates/ruma-identity-service-api/src/lookup/get_hash_parameters.rs +++ b/crates/ruma-identity-service-api/src/lookup/get_hash_parameters.rs @@ -1,3 +1,54 @@ +//! `GET /_matrix/identity/*/hash_details` +//! //! Endpoint to get details about Hashing identifiers. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2hash_details + + use ruma_api::ruma_api; + + use crate::lookup::IdentifierHashingAlgorithm; + + ruma_api! { + metadata: { + description: "Gets parameters for hashing identifiers from the server. This can include any of the algorithms defined in the spec.", + method: GET, + name: "get_hash_parameters", + stable_path: "/_matrix/identity/v2/hash_details", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + #[derive(Default)] + request: {} + + response: { + /// The pepper the client MUST use in hashing identifiers, and MUST supply to the /lookup endpoint when performing lookups. + /// + /// Servers SHOULD rotate this string often. + pub lookup_pepper: String, + + /// The algorithms the server supports. + /// + /// Must contain at least `sha256`. + pub algorithms: Vec, + } + } + + impl Request { + /// Creates an empty `Request`. + pub fn new() -> Self { + Self {} + } + } + + impl Response { + /// Create a new `Response` using the given pepper and `Vec` of algorithms. + pub fn new(lookup_pepper: String, algorithms: Vec) -> Self { + Self { lookup_pepper, algorithms } + } + } +} diff --git a/crates/ruma-identity-service-api/src/lookup/get_hash_parameters/v2.rs b/crates/ruma-identity-service-api/src/lookup/get_hash_parameters/v2.rs deleted file mode 100644 index 37b82f9a..00000000 --- a/crates/ruma-identity-service-api/src/lookup/get_hash_parameters/v2.rs +++ /dev/null @@ -1,46 +0,0 @@ -//! [GET /_matrix/identity/v2/hash_details](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-hash-details) - -use ruma_api::ruma_api; - -use crate::lookup::IdentifierHashingAlgorithm; - -ruma_api! { - metadata: { - description: "Gets parameters for hashing identifiers from the server. This can include any of the algorithms defined in the spec.", - method: GET, - name: "get_hash_parameters", - stable_path: "/_matrix/identity/v2/hash_details", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - #[derive(Default)] - request: {} - - response: { - /// The pepper the client MUST use in hashing identifiers, and MUST supply to the /lookup endpoint when performing lookups. - /// - /// Servers SHOULD rotate this string often. - pub lookup_pepper: String, - - /// The algorithms the server supports. - /// - /// Must contain at least `sha256`. - pub algorithms: Vec, - } -} - -impl Request { - /// Creates an empty `Request`. - pub fn new() -> Self { - Self {} - } -} - -impl Response { - /// Create a new `Response` using the given pepper and `Vec` of algorithms. - pub fn new(lookup_pepper: String, algorithms: Vec) -> Self { - Self { lookup_pepper, algorithms } - } -} diff --git a/crates/ruma-identity-service-api/src/lookup/lookup_3pid.rs b/crates/ruma-identity-service-api/src/lookup/lookup_3pid.rs index 619c3fd7..db3eeba3 100644 --- a/crates/ruma-identity-service-api/src/lookup/lookup_3pid.rs +++ b/crates/ruma-identity-service-api/src/lookup/lookup_3pid.rs @@ -1,3 +1,71 @@ +//! `POST /_matrix/identity/*/lookup` +//! //! Endpoint to look up set of Matrix IDs which are bound to 3PIDs. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2lookup + + use std::collections::BTreeMap; + + use ruma_api::ruma_api; + use ruma_identifiers::UserId; + + use crate::lookup::IdentifierHashingAlgorithm; + + ruma_api! { + metadata: { + description: "Looks up the set of Matrix User IDs which have bound the 3PIDs given, if bindings are available.", + method: POST, + name: "lookup_3pid", + stable_path: "/_matrix/identity/v2/lookup", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The algorithm the client is using to encode the `addresses`. This should be one of the + /// available options from `/hash_details`. + pub algorithm: &'a IdentifierHashingAlgorithm, + + /// The pepper from `/hash_details`. This is required even when the `algorithm` does not + /// make use of it. + pub pepper: &'a str, + + /// The addresses to look up. + /// + /// The format of the entries here depend on the `algorithm` used. Note that queries which + /// have been incorrectly hashed or formatted will lead to no matches. + pub addresses: &'a [String], + } + + response: { + /// Any applicable mappings of `addresses` to Matrix User IDs. + /// + /// Addresses which do not have associations will not be included, which can make this + /// property be an empty object. + pub mappings: BTreeMap>, + } + } + + impl<'a> Request<'a> { + /// Create a `Request` with algorithm, pepper and addresses to loop up. + pub fn new( + algorithm: &'a IdentifierHashingAlgorithm, + pepper: &'a str, + addresses: &'a [String], + ) -> Self { + Self { algorithm, pepper, addresses } + } + } + + impl Response { + /// Create a `Response` with the BTreeMap which map addresses from the request which were + /// found to their corresponding User IDs. + pub fn new(mappings: BTreeMap>) -> Self { + Self { mappings } + } + } +} diff --git a/crates/ruma-identity-service-api/src/lookup/lookup_3pid/v2.rs b/crates/ruma-identity-service-api/src/lookup/lookup_3pid/v2.rs deleted file mode 100644 index 098f0636..00000000 --- a/crates/ruma-identity-service-api/src/lookup/lookup_3pid/v2.rs +++ /dev/null @@ -1,63 +0,0 @@ -//! [POST /_matrix/identity/v2/lookup](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-lookup) - -use std::collections::BTreeMap; - -use ruma_api::ruma_api; -use ruma_identifiers::UserId; - -use crate::lookup::IdentifierHashingAlgorithm; - -ruma_api! { - metadata: { - description: "Looks up the set of Matrix User IDs which have bound the 3PIDs given, if bindings are available.", - method: POST, - name: "lookup_3pid", - stable_path: "/_matrix/identity/v2/lookup", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The algorithm the client is using to encode the `addresses`. This should be one of the - /// available options from `/hash_details`. - pub algorithm: &'a IdentifierHashingAlgorithm, - - /// The pepper from `/hash_details`. This is required even when the `algorithm` does not - /// make use of it. - pub pepper: &'a str, - - /// The addresses to look up. - /// - /// The format of the entries here depend on the `algorithm` used. Note that queries which - /// have been incorrectly hashed or formatted will lead to no matches. - pub addresses: &'a [String], - } - - response: { - /// Any applicable mappings of `addresses` to Matrix User IDs. - /// - /// Addresses which do not have associations will not be included, which can make this - /// property be an empty object. - pub mappings: BTreeMap>, - } -} - -impl<'a> Request<'a> { - /// Create a `Request` with algorithm, pepper and addresses to loop up. - pub fn new( - algorithm: &'a IdentifierHashingAlgorithm, - pepper: &'a str, - addresses: &'a [String], - ) -> Self { - Self { algorithm, pepper, addresses } - } -} - -impl Response { - /// Create a `Response` with the BTreeMap which map addresses from the request which were - /// found to their corresponding User IDs. - pub fn new(mappings: BTreeMap>) -> Self { - Self { mappings } - } -} diff --git a/crates/ruma-identity-service-api/src/status.rs b/crates/ruma-identity-service-api/src/status.rs index d5238e30..6effd46b 100644 --- a/crates/ruma-identity-service-api/src/status.rs +++ b/crates/ruma-identity-service-api/src/status.rs @@ -1,3 +1,43 @@ +//! `GET /_matrix/identity/*` +//! //! Endpoint to check the status of an identity server. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2 + + use ruma_api::ruma_api; + + ruma_api! { + metadata: { + description: "Checks that an identity server is available at this API endpoint.", + method: GET, + name: "status", + stable_path: "/_matrix/identity/v2", + authentication: None, + rate_limited: false, + added: 1.0, + } + + #[derive(Default)] + request: {} + + #[derive(Default)] + response: {} + } + + impl Request { + /// Creates an empty `Request`. + pub fn new() -> Self { + Self {} + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-identity-service-api/src/status/v2.rs b/crates/ruma-identity-service-api/src/status/v2.rs deleted file mode 100644 index 07c3bc7a..00000000 --- a/crates/ruma-identity-service-api/src/status/v2.rs +++ /dev/null @@ -1,35 +0,0 @@ -//! [GET /_matrix/identity/v2](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2) - -use ruma_api::ruma_api; - -ruma_api! { - metadata: { - description: "Checks that an identity server is available at this API endpoint.", - method: GET, - name: "status", - stable_path: "/_matrix/identity/v2", - authentication: None, - rate_limited: false, - added: 1.0, - } - - #[derive(Default)] - request: {} - - #[derive(Default)] - response: {} -} - -impl Request { - /// Creates an empty `Request`. - pub fn new() -> Self { - Self {} - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-identity-service-api/src/tos/accept_terms_of_service.rs b/crates/ruma-identity-service-api/src/tos/accept_terms_of_service.rs index 999a1632..8f700ed9 100644 --- a/crates/ruma-identity-service-api/src/tos/accept_terms_of_service.rs +++ b/crates/ruma-identity-service-api/src/tos/accept_terms_of_service.rs @@ -1,3 +1,47 @@ +//! `POST /_matrix/identity/*/terms` +//! //! Endpoint to send acceptance of the terms of service of an identity server. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#post_matrixidentityv2terms + + use ruma_api::ruma_api; + + ruma_api! { + metadata: { + description: "Called by a client to indicate that the user has accepted/agreed to the included set of URLs.", + method: POST, + name: "accept_terms_of_service", + stable_path: "/_matrix/identity/v2/terms", + authentication: AccessToken, + rate_limited: false, + added: 1.0, + } + + request: { + /// The URLs the user is accepting in this request. + /// + /// An example is `https://example.org/somewhere/terms-2.0-en.html`. + pub user_accepts: Vec, + } + + #[derive(Default)] + response: {} + } + + impl Request { + /// Creates a new `Request` with the given URLs which the user accepts. + pub fn new(user_accepts: Vec) -> Self { + Self { user_accepts } + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-identity-service-api/src/tos/accept_terms_of_service/v2.rs b/crates/ruma-identity-service-api/src/tos/accept_terms_of_service/v2.rs deleted file mode 100644 index ea8de549..00000000 --- a/crates/ruma-identity-service-api/src/tos/accept_terms_of_service/v2.rs +++ /dev/null @@ -1,39 +0,0 @@ -//! [POST /_matrix/identity/v2/terms](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-terms) - -use ruma_api::ruma_api; - -ruma_api! { - metadata: { - description: "Called by a client to indicate that the user has accepted/agreed to the included set of URLs.", - method: POST, - name: "accept_terms_of_service", - stable_path: "/_matrix/identity/v2/terms", - authentication: AccessToken, - rate_limited: false, - added: 1.0, - } - - request: { - /// The URLs the user is accepting in this request. - /// - /// An example is `https://example.org/somewhere/terms-2.0-en.html`. - pub user_accepts: Vec, - } - - #[derive(Default)] - response: {} -} - -impl Request { - /// Creates a new `Request` with the given URLs which the user accepts. - pub fn new(user_accepts: Vec) -> Self { - Self { user_accepts } - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-identity-service-api/src/tos/get_terms_of_service.rs b/crates/ruma-identity-service-api/src/tos/get_terms_of_service.rs index 62895710..c2ba605d 100644 --- a/crates/ruma-identity-service-api/src/tos/get_terms_of_service.rs +++ b/crates/ruma-identity-service-api/src/tos/get_terms_of_service.rs @@ -1,3 +1,98 @@ +//! `GET /_matrix/identity/*/terms` +//! //! Endpoint to retrieve the terms of service of an identity server. -pub mod v2; +pub mod v2 { + //! `/v2/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/identity-service-api/#get_matrixidentityv2terms + + use std::collections::BTreeMap; + + use ruma_api::ruma_api; + use serde::{Deserialize, Serialize}; + + ruma_api! { + metadata: { + description: "Gets all the terms of service offered by the server.", + method: GET, + name: "get_terms_of_service", + stable_path: "/_matrix/identity/v2/terms", + authentication: None, + rate_limited: false, + added: 1.0, + } + + #[derive(Default)] + request: {} + + response: { + /// The policies the server offers. + /// + /// Mapped from arbitrary ID (unused in this version of the specification) to a Policy Object. + pub policies: BTreeMap, + } + } + + impl Request { + /// Creates an empty `Request`. + pub fn new() -> Self { + Self {} + } + } + + impl Response { + /// Creates a new `Response` with the given `Policies`. + pub fn new(policies: BTreeMap) -> Self { + Self { policies } + } + } + + /// Collection of localized policies. + #[derive(Clone, Debug, Serialize, Deserialize)] + #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] + pub struct Policies { + /// The version for the policy. + /// + /// There are no requirements on what this might be and could be + /// "alpha", semantically versioned, or arbitrary. + pub version: String, + + /// Available languages for the policy. + /// + /// The keys could be the language code corresponding to + /// the given `LocalizedPolicy`, for example "en" or "fr". + #[serde(flatten)] + pub localized: BTreeMap, + } + + impl Policies { + /// Create a new `Policies` with the given version and localized map. + pub fn new(version: String, localized: BTreeMap) -> Self { + Self { version, localized } + } + } + + /// A localized policy offered by a server. + #[derive(Clone, Debug, Serialize, Deserialize)] + #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] + pub struct LocalizedPolicy { + /// The localized name of the policy. + /// + /// Examples are "Terms of Service", "Conditions d'utilisation". + pub name: String, + + /// The URL at which the policy is available. + /// + /// Examples are `https://example.org/somewhere/terms-2.0-en.html` + /// and `https://example.org/somewhere/terms-2.0-fr.html`. + pub url: String, + } + + impl LocalizedPolicy { + /// Create a new `LocalizedPolicy` with the given name and url. + pub fn new(name: String, url: String) -> Self { + Self { name, url } + } + } +} diff --git a/crates/ruma-identity-service-api/src/tos/get_terms_of_service/v2.rs b/crates/ruma-identity-service-api/src/tos/get_terms_of_service/v2.rs deleted file mode 100644 index 2b897174..00000000 --- a/crates/ruma-identity-service-api/src/tos/get_terms_of_service/v2.rs +++ /dev/null @@ -1,90 +0,0 @@ -//! [GET /_matrix/identity/v2/terms](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-terms) - -use std::collections::BTreeMap; - -use ruma_api::ruma_api; -use serde::{Deserialize, Serialize}; - -ruma_api! { - metadata: { - description: "Gets all the terms of service offered by the server.", - method: GET, - name: "get_terms_of_service", - stable_path: "/_matrix/identity/v2/terms", - authentication: None, - rate_limited: false, - added: 1.0, - } - - #[derive(Default)] - request: {} - - response: { - /// The policies the server offers. - /// - /// Mapped from arbitrary ID (unused in this version of the specification) to a Policy Object. - pub policies: BTreeMap, - } -} - -impl Request { - /// Creates an empty `Request`. - pub fn new() -> Self { - Self {} - } -} - -impl Response { - /// Creates a new `Response` with the given `Policies`. - pub fn new(policies: BTreeMap) -> Self { - Self { policies } - } -} - -/// Collection of localized policies. -#[derive(Clone, Debug, Serialize, Deserialize)] -#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] -pub struct Policies { - /// The version for the policy. - /// - /// There are no requirements on what this might be and could be - /// "alpha", semantically versioned, or arbitrary. - pub version: String, - - /// Available languages for the policy. - /// - /// The keys could be the language code corresponding to - /// the given `LocalizedPolicy`, for example "en" or "fr". - #[serde(flatten)] - pub localized: BTreeMap, -} - -impl Policies { - /// Create a new `Policies` with the given version and localized map. - pub fn new(version: String, localized: BTreeMap) -> Self { - Self { version, localized } - } -} - -/// A localized policy offered by a server. -#[derive(Clone, Debug, Serialize, Deserialize)] -#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] -pub struct LocalizedPolicy { - /// The localized name of the policy. - /// - /// Examples are "Terms of Service", "Conditions d'utilisation". - pub name: String, - - /// The URL at which the policy is available. - /// - /// Examples are `https://example.org/somewhere/terms-2.0-en.html` - /// and `https://example.org/somewhere/terms-2.0-fr.html`. - pub url: String, -} - -impl LocalizedPolicy { - /// Create a new `LocalizedPolicy` with the given name and url. - pub fn new(name: String, url: String) -> Self { - Self { name, url } - } -}