ruma_federation_api/thirdparty/
bind_callback.rs

1//! `PUT /_matrix/federation/*/3pid/onbind`
2//!
3//! Used by identity servers to notify the homeserver that one of its users has bound a third party
4//! identifier successfully, including any pending room invites the identity server has been made
5//! aware of.
6
7pub mod v1 {
8    //! `/v1/` ([spec])
9    //!
10    //! [spec]: https://spec.matrix.org/latest/server-server-api/#put_matrixfederationv13pidonbind
11
12    use ruma_common::{
13        api::{request, response, Metadata},
14        metadata,
15        serde::Raw,
16        thirdparty::Medium,
17        OwnedRoomId, OwnedUserId,
18    };
19    use ruma_events::room::member::SignedContent;
20    use serde::{Deserialize, Serialize};
21
22    const METADATA: Metadata = metadata! {
23        method: PUT,
24        rate_limited: false,
25        authentication: None,
26        history: {
27            1.0 => "/_matrix/federation/v1/3pid/onbind",
28        }
29    };
30
31    /// Request type for the `bind_callback` endpoint.
32    #[request]
33    pub struct Request {
34        /// The type of third party identifier.
35        ///
36        /// Currently only `Medium::Email` is supported.
37        pub medium: Medium,
38
39        /// The third party identifier itself.
40        ///
41        /// For example: an email address.
42        pub address: String,
43
44        /// The user that is now bound to the third party identifier.
45        pub mxid: OwnedUserId,
46
47        /// A list of pending invites that the third party identifier has received.
48        pub invites: Vec<ThirdPartyInvite>,
49    }
50
51    /// Response type for the `bind_callback` endpoint.
52    #[response]
53    #[derive(Default)]
54    pub struct Response {}
55
56    impl Request {
57        /// Creates a new `Request` with the given medium, address, user ID and third party invites.
58        pub fn new(
59            medium: Medium,
60            address: String,
61            mxid: OwnedUserId,
62            invites: Vec<ThirdPartyInvite>,
63        ) -> Self {
64            Self { medium, address, mxid, invites }
65        }
66
67        /// Creates a new `Request` with the given email address, user ID and third party invites.
68        pub fn email(address: String, mxid: OwnedUserId, invites: Vec<ThirdPartyInvite>) -> Self {
69            Self::new(Medium::Email, address, mxid, invites)
70        }
71    }
72
73    /// A pending invite the third party identifier has received.
74    #[derive(Debug, Clone, Deserialize, Serialize)]
75    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
76    pub struct ThirdPartyInvite {
77        /// The type of third party invite issues.
78        ///
79        /// Currently only `Medium::Email` is used.
80        pub medium: Medium,
81
82        /// The third party identifier that received the invite.
83        pub address: String,
84
85        /// The now-bound user ID that received the invite.
86        pub mxid: OwnedUserId,
87
88        /// The room ID the invite is valid for.
89        pub room_id: OwnedRoomId,
90
91        /// The user ID that sent the invite.
92        pub sender: OwnedUserId,
93
94        /// A block of content which has been signed, which servers can use to verify the
95        /// third-party invite.
96        pub signed: Raw<SignedContent>,
97    }
98
99    impl ThirdPartyInvite {
100        /// Creates a new third party invite with the given parameters.
101        pub fn new(
102            address: String,
103            mxid: OwnedUserId,
104            room_id: OwnedRoomId,
105            sender: OwnedUserId,
106            signed: Raw<SignedContent>,
107        ) -> Self {
108            Self { medium: Medium::Email, address, mxid, room_id, sender, signed }
109        }
110    }
111
112    impl Response {
113        /// Construct an empty response.
114        pub fn new() -> Self {
115            Self {}
116        }
117    }
118}
ruma_federation_api/thirdparty/bind_callback.rs

ruma_federation_api/thirdparty/
bind_callback.rs
