ruma_identity_service_api/association/
unbind_3pid.rs

Help
1//! `POST /_matrix/identity/*/3pid/unbind`
2//!
3//! Remove an association between a session and a Matrix user ID.
4
5pub mod v2 {
6    //! `/v2/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/identity-service-api/#post_matrixidentityv23pidunbind
9
10    use ruma_common::{
11        api::{request, response, Metadata},
12        metadata,
13        thirdparty::Medium,
14        OwnedClientSecret, OwnedSessionId, OwnedUserId,
15    };
16    use serde::{Deserialize, Serialize};
17
18    const METADATA: Metadata = metadata! {
19        method: POST,
20        rate_limited: false,
21        authentication: AccessToken,
22        history: {
23            1.0 => "/_matrix/identity/v2/3pid/unbind",
24        }
25    };
26
27    /// Request type for the `unbind_3pid` endpoint.
28    #[request]
29    pub struct Request {
30        /// The proof that the client owns the 3PID.
31        ///
32        /// If this is not provided, the request must be signed by the homeserver which controls
33        /// the `mxid`.
34        #[serde(flatten, skip_serializing_if = "Option::is_none")]
35        pub threepid_ownership_proof: Option<ThreePidOwnershipProof>,
36
37        /// The Matrix user ID to remove from the 3PIDs.
38        pub mxid: OwnedUserId,
39
40        /// The 3PID to remove.
41        ///
42        /// Must match the 3PID used to generate the session if using `sid` and `client_secret` to
43        /// authenticate this request.
44        pub threepid: ThirdPartyId,
45    }
46
47    /// Response type for the `unbind_3pid` endpoint.
48    #[response]
49    #[derive(Default)]
50    pub struct Response {}
51
52    impl Request {
53        /// Creates a `Request` with the given Session ID, client secret, Matrix user ID and 3PID.
54        pub fn new(
55            threepid_ownership_proof: Option<ThreePidOwnershipProof>,
56            mxid: OwnedUserId,
57            threepid: ThirdPartyId,
58        ) -> Self {
59            Self { threepid_ownership_proof, mxid, threepid }
60        }
61    }
62
63    impl Response {
64        /// Creates an empty `Response`.
65        pub fn new() -> Self {
66            Self {}
67        }
68    }
69
70    /// A 3PID to unbind.
71    #[derive(Clone, Debug, Serialize, Deserialize)]
72    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
73    pub struct ThirdPartyId {
74        /// A medium matching the medium of identifier to unbind.
75        pub medium: Medium,
76
77        /// The 3PID address to remove.
78        pub address: String,
79    }
80
81    impl ThirdPartyId {
82        /// Creates a new `ThirdPartyId` with the given medium and address.
83        pub fn new(medium: Medium, address: String) -> Self {
84            Self { medium, address }
85        }
86    }
87
88    /// A proof that the client owns the 3PID.
89    ///
90    /// Must be constructed using the same session ID and client secret generated and passed by the
91    /// `requestToken` call for the given 3PID.
92    #[derive(Clone, Debug, Serialize, Deserialize)]
93    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
94    pub struct ThreePidOwnershipProof {
95        /// The Session ID generated by the `requestToken` call.
96        pub sid: OwnedSessionId,
97
98        /// The client secret passed to the `requestToken` call.
99        pub client_secret: OwnedClientSecret,
100    }
101
102    impl ThreePidOwnershipProof {
103        /// Creates a new `ThreePidOwnershipProof` with the given session ID and client secret.
104        pub fn new(sid: OwnedSessionId, client_secret: OwnedClientSecret) -> Self {
105            Self { sid, client_secret }
106        }
107    }
108}
ruma_identity_service_api/association/unbind_3pid.rs

ruma_identity_service_api/association/
unbind_3pid.rs
