1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

//! Endpoints for account registration and management.

/// [POST /_matrix/client/r0/register](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-register)
pub mod register {
    use ruma_api_macros::ruma_api;
    use ruma_identifiers::UserId;

    ruma_api! {
        metadata {
            description: "Register an account on this homeserver.",
            method: POST,
            name: "register",
            path: "/_matrix/client/r0/register",
            rate_limited: true,
            requires_authentication: false,
        }

        request {
            /// If true, the server binds the email used for authentication
            /// to the Matrix ID with the ID Server.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub bind_email: Option<bool>,
            /// The desired password for the account.
            ///
            /// Should only be empty for guest accounts.
            // TODO: the spec says nothing about when it is actually required.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub password: Option<String>,
            /// local part of the desired Matrix ID.
            ///
            /// If omitted, the homeserver MUST generate a Matrix ID local part.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub username: Option<String>,
            /// ID of the client device.
            ///
            /// If this does not correspond to a known client device, a new device will be created.
            /// The server will auto-generate a device_id if this is not specified.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub device_id: Option<String>,
            /// A display name to assign to the newly-created device.
            ///
            /// Ignored if `device_id` corresponds to a known device.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub initial_device_display_name: Option<String>,
            /// Additional authentication information for the user-interactive authentication API.
            ///
            /// Note that this information is not used to define how the registered user should be
            /// authenticated, but is instead used to authenticate the register call itself.
            /// It should be left empty, or omitted, unless an earlier call returned an response
            /// with status code 401.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub auth: Option<AuthenticationData>,
            /// Kind of account to register
            ///
            /// Defaults to `User` if ommited.
            #[ruma_api(query)]
            #[serde(skip_serializing_if = "Option::is_none")]
            pub kind: Option<RegistrationKind>,
        }

        response {
            /// An access token for the account.
            ///
            /// This access token can then be used to authorize other requests.
            pub access_token: String,
            /// The hostname of the homeserver on which the account has been registered.
            pub home_server: String,
            /// The fully-qualified Matrix ID that has been registered.
            pub user_id: UserId,
            /// ID of the registered device.
            ///
            /// Will be the same as the corresponding parameter in the request, if one was specified.
            pub device_id: String,
        }
    }

    /// Additional authentication information for the user-interactive authentication API.
    #[derive(Clone, Debug, Deserialize, Serialize)]
    pub struct AuthenticationData {
        /// The login type that the client is attempting to complete.
        #[serde(rename = "type")]
        kind: String,
        /// The value of the session key given by the homeserver.
        session: Option<String>
    }

    /// The kind of account being registered.
    #[derive(Copy, Clone, Debug, Deserialize, Serialize)]
    pub enum RegistrationKind {
        /// A guest account
        ///
        /// These accounts may have limited permissions and may not be supported by all servers.
        #[serde(rename="guest")]
        Guest,
        /// A regular user account
        #[serde(rename="user")]
        User,
    }
}

/// [POST /_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-account-password-email-requesttoken)
pub mod request_password_change_token {
    use ruma_api_macros::ruma_api;

    ruma_api! {
        metadata {
            description: "Request that a password change token is sent to the given email address.",
            method: POST,
            name: "request_password_change_token",
            path: "/_matrix/client/r0/account/password/email/requestToken",
            rate_limited: false,
            requires_authentication: false,
        }

        request {
            /// TODO: This parameter is not documented in the spec.
            pub client_secret: String,
            /// TODO: This parameter is not documented in the spec.
            pub email: String,
            /// TODO: This parameter is not documented in the spec.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub id_server: Option<String>,
            /// TODO: This parameter is not documented in the spec.
            pub send_attempt: u64,
        }

        response {}
    }
}

/// [POST /_matrix/client/r0/account/deactivate](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-account-deactivate)
pub mod deactivate {
    // TODO: missing request parameters

    use ruma_api_macros::ruma_api;

    ruma_api! {
        metadata {
            description: "Deactivate the current user's account.",
            method: POST,
            name: "deactivate",
            path: "/_matrix/client/r0/account/deactivate",
            rate_limited: true,
            requires_authentication: true,
        }

        request {}

        response {}
    }
}

/// [POST /_matrix/client/r0/account/password](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-account-password)
pub mod change_password {
    use ruma_api_macros::ruma_api;

    ruma_api! {
        metadata {
            description: "Change the password of the current user's account.",
            method: POST,
            name: "change_password",
            path: "/_matrix/client/r0/account/password",
            rate_limited: true,
            requires_authentication: true,
        }

        request {
            /// The new password for the account.
            pub new_password: String,
            // TODO: missing `auth` field
        }

        response {}
    }
}

/// [POST /_matrix/client/r0/register/email/requestToken](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-register-email-requesttoken)
pub mod request_register_token {
    use ruma_api_macros::ruma_api;

    ruma_api! {
        metadata {
            description: "Request a register token with a 3rd party email.",
            method: POST,
            name: "request_register_token",
            path: "/_matrix/client/r0/register/email/requestToken",
            rate_limited: true,
            requires_authentication: true,
        }

        request {
            /// Client-generated secret string used to protect this session.
            pub client_secret: String,
            /// The email address.
            pub email: String,
            /// The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
            #[serde(skip_serializing_if = "Option::is_none")]
            pub id_server: Option<String>,
            /// Used to distinguish protocol level retries from requests to re-send the email.
            pub send_attempt: u64,
        }

        response {}
    }
}