ruma_federation_api/thirdparty/
bind_callback.rs

Help
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 std::collections::BTreeMap;
13
14    use ruma_common::{
15        api::{request, response, Metadata},
16        metadata,
17        thirdparty::Medium,
18        OwnedRoomId, OwnedServerName, OwnedServerSigningKeyId, OwnedUserId,
19    };
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    pub struct Response {}
54
55    impl Request {
56        /// Creates a new `Request` with the given medium, address, user ID and third party invites.
57        pub fn new(
58            medium: Medium,
59            address: String,
60            mxid: OwnedUserId,
61            invites: Vec<ThirdPartyInvite>,
62        ) -> Self {
63            Self { medium, address, mxid, invites }
64        }
65
66        /// Creates a new `Request` with the given email address, user ID and third party invites.
67        pub fn email(address: String, mxid: OwnedUserId, invites: Vec<ThirdPartyInvite>) -> Self {
68            Self::new(Medium::Email, address, mxid, invites)
69        }
70    }
71
72    /// A pending invite the third party identifier has received.
73    #[derive(Debug, Clone, Deserialize, Serialize)]
74    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
75    pub struct ThirdPartyInvite {
76        /// The type of third party invite issues.
77        ///
78        /// Currently only `Medium::Email` is used.
79        pub medium: Medium,
80
81        /// The third party identifier that received the invite.
82        pub address: String,
83
84        /// The now-bound user ID that received the invite.
85        pub mxid: OwnedUserId,
86
87        /// The room ID the invite is valid for.
88        pub room_id: OwnedRoomId,
89
90        /// The user ID that sent the invite.
91        pub sender: OwnedUserId,
92
93        /// Signature from the identity server using a long-term private key.
94        pub signed: BTreeMap<OwnedServerName, BTreeMap<OwnedServerSigningKeyId, String>>,
95    }
96
97    impl ThirdPartyInvite {
98        /// Creates a new third party invite with the given parameters.
99        pub fn new(
100            address: String,
101            mxid: OwnedUserId,
102            room_id: OwnedRoomId,
103            sender: OwnedUserId,
104            signed: BTreeMap<OwnedServerName, BTreeMap<OwnedServerSigningKeyId, String>>,
105        ) -> Self {
106            Self { medium: Medium::Email, address, mxid, room_id, sender, signed }
107        }
108    }
109}
ruma_federation_api/thirdparty/bind_callback.rs

ruma_federation_api/thirdparty/
bind_callback.rs
