identity-service-api: Add endpoints for email validation

ruma-identity-service-api/CHANGELOG.md

@@ -3,4 +3,16 @@
 # 0.0.1
 
 * Add authentication endpoints:
-  `authentication::{get_account_information::v2, logout::v2, register::v2}`
+  ```rust
+  authentication::{get_account_information::v2, logout::v2, register::v2}
+  ```
+* Add email association endpoints:
+  ```rust
+  association::{
+      email::{
+          create_email_validation_session::v2,
+          validate_email::v2,
+          validate_email_by_end_user::v2,
+      }
+  }
+  ```

ruma-identity-service-api/Cargo.toml

@@ -11,6 +11,7 @@ repository = "https://github.com/ruma/ruma"
 edition = "2018"
 
 [dependencies]
+js_int = { version = "0.2.0", features = ["serde"] }
 ruma-api = { version = "=0.17.0-alpha.4", path = "../ruma-api" }
 ruma-common = { version = "0.5.0", path = "../ruma-common" }
 ruma-identifiers = { version = "0.19.0", path = "../ruma-identifiers" }

ruma-identity-service-api/src/association.rs

@@ -0,0 +1,3 @@
+//! Endpoints to create associations with a Matrix ID on the identity server.
+
+pub mod email;

ruma-identity-service-api/src/association/email.rs

@@ -0,0 +1,5 @@
+//! Endpoints to create an association betwen a Matrix ID and an email ID on the identity server.
+
+pub mod create_email_validation_session;
+pub mod validate_email;
+pub mod validate_email_by_end_user;

ruma-identity-service-api/src/association/email/create_email_validation_session.rs

@@ -0,0 +1,3 @@
+//! Create a session for verifying an email.
+
+pub mod v2;

ruma-identity-service-api/src/association/email/create_email_validation_session/v2.rs

@@ -0,0 +1,57 @@
+//! [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;
+
+ruma_api! {
+    metadata: {
+        description: "Creates a session for validating an email address.",
+        method: POST,
+        name: "create_email_validation_session",
+        path: "/_matrix/identity/v2/validate/email/requestToken",
+        authentication: AccessToken,
+        rate_limited: false,
+    }
+
+    request: {
+        /// A unique string generated by the client, and used to identify the validation attempt.
+        pub client_secret: &'a str,
+
+        /// 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: String,
+    }
+}
+
+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 str,
+        email: &'a str,
+        send_attempt: js_int::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: String) -> Self {
+        Self { sid }
+    }
+}

ruma-identity-service-api/src/association/email/validate_email.rs

@@ -0,0 +1,3 @@
+//! Validate an email ID after creation of a session.
+
+pub mod v2;

ruma-identity-service-api/src/association/email/validate_email/v2.rs

@@ -0,0 +1,44 @@
+//! [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;
+
+ruma_api! {
+    metadata: {
+        description: "Validate ownership of an email address.",
+        method: POST,
+        name: "validate_email",
+        path: "/_matrix/identity/v2/validate/email/submitToken",
+        authentication: AccessToken,
+        rate_limited: false,
+    }
+
+    request: {
+        /// The session ID, generated by the `requestToken` call.
+        pub sid: &'a str,
+
+        /// The client secret that was supplied to the `requestToken` call.
+        pub client_secret: &'a str,
+
+        /// 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 str, client_secret: &'a str, 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 }
+    }
+}

ruma-identity-service-api/src/association/email/validate_email_by_end_user.rs

@@ -0,0 +1,3 @@
+//! Endpoint for validation of an email ID by the end-user, after creation of a session.
+
+pub mod v2;

ruma-identity-service-api/src/association/email/validate_email_by_end_user/v2.rs

@@ -0,0 +1,45 @@
+//! [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;
+
+ruma_api! {
+    metadata: {
+        description: "Validate ownership of an email address.",
+        method: GET,
+        name: "validate_email_by_end_user",
+        path: "/_matrix/identity/v2/validate/email/submitToken",
+        authentication: AccessToken,
+        rate_limited: false,
+    }
+
+    request: {
+        /// The session ID, generated by the `requestToken` call.
+        #[ruma_api(query)]
+        pub sid: &'a str,
+
+        /// The client secret that was supplied to the `requestToken` call.
+        #[ruma_api(query)]
+        pub client_secret: &'a str,
+
+        /// 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 str, client_secret: &'a str, token: &'a str) -> Self {
+        Self { sid, client_secret, token }
+    }
+}
+
+impl Response {
+    /// Create a new empty `Response`.
+    pub fn new() -> Self {
+        Self {}
+    }
+}

ruma-identity-service-api/src/lib.rs

@@ -7,6 +7,7 @@
 
 #![warn(missing_docs)]
 
+pub mod association;
 pub mod authentication;
 pub mod keys;
 pub mod lookup;