ruma_identity_service_api/association/
unbind_3pid.rs

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

ruma_identity_service_api/association/
unbind_3pid.rs
