ruma_events/
room.rs

Help
1//! Modules for events in the `m.room` namespace.
2//!
3//! This module also contains types shared by events in its child namespaces.
4
5use std::collections::BTreeMap;
6
7use js_int::UInt;
8use ruma_common::{
9    serde::{base64::UrlSafe, Base64},
10    OwnedMxcUri,
11};
12use serde::{de, Deserialize, Serialize};
13
14pub mod aliases;
15pub mod avatar;
16pub mod canonical_alias;
17pub mod create;
18pub mod encrypted;
19pub mod encryption;
20pub mod guest_access;
21pub mod history_visibility;
22pub mod join_rules;
23pub mod member;
24pub mod message;
25pub mod name;
26pub mod pinned_events;
27pub mod power_levels;
28pub mod redaction;
29pub mod server_acl;
30pub mod third_party_invite;
31mod thumbnail_source_serde;
32pub mod tombstone;
33pub mod topic;
34
35/// The source of a media file.
36#[derive(Clone, Debug, Serialize)]
37#[allow(clippy::exhaustive_enums)]
38pub enum MediaSource {
39    /// The MXC URI to the unencrypted media file.
40    #[serde(rename = "url")]
41    Plain(OwnedMxcUri),
42
43    /// The encryption info of the encrypted media file.
44    #[serde(rename = "file")]
45    Encrypted(Box<EncryptedFile>),
46}
47
48// Custom implementation of `Deserialize`, because serde doesn't guarantee what variant will be
49// deserialized for "externally tagged"¹ enums where multiple "tag" fields exist.
50//
51// ¹ https://serde.rs/enum-representations.html
52impl<'de> Deserialize<'de> for MediaSource {
53    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
54    where
55        D: serde::Deserializer<'de>,
56    {
57        #[derive(Deserialize)]
58        struct MediaSourceJsonRepr {
59            url: Option<OwnedMxcUri>,
60            file: Option<Box<EncryptedFile>>,
61        }
62
63        match MediaSourceJsonRepr::deserialize(deserializer)? {
64            MediaSourceJsonRepr { url: None, file: None } => Err(de::Error::missing_field("url")),
65            // Prefer file if it is set
66            MediaSourceJsonRepr { file: Some(file), .. } => Ok(MediaSource::Encrypted(file)),
67            MediaSourceJsonRepr { url: Some(url), .. } => Ok(MediaSource::Plain(url)),
68        }
69    }
70}
71
72/// Metadata about an image.
73#[derive(Clone, Debug, Default, Deserialize, Serialize)]
74#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
75pub struct ImageInfo {
76    /// The height of the image in pixels.
77    #[serde(rename = "h", skip_serializing_if = "Option::is_none")]
78    pub height: Option<UInt>,
79
80    /// The width of the image in pixels.
81    #[serde(rename = "w", skip_serializing_if = "Option::is_none")]
82    pub width: Option<UInt>,
83
84    /// The MIME type of the image, e.g. "image/png."
85    #[serde(skip_serializing_if = "Option::is_none")]
86    pub mimetype: Option<String>,
87
88    /// The file size of the image in bytes.
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub size: Option<UInt>,
91
92    /// Metadata about the image referred to in `thumbnail_source`.
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub thumbnail_info: Option<Box<ThumbnailInfo>>,
95
96    /// The source of the thumbnail of the image.
97    #[serde(flatten, with = "thumbnail_source_serde", skip_serializing_if = "Option::is_none")]
98    pub thumbnail_source: Option<MediaSource>,
99
100    /// The [BlurHash](https://blurha.sh) for this image.
101    ///
102    /// This uses the unstable prefix in
103    /// [MSC2448](https://github.com/matrix-org/matrix-spec-proposals/pull/2448).
104    #[cfg(feature = "unstable-msc2448")]
105    #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
106    pub blurhash: Option<String>,
107
108    /// Whether the image is animated.
109    ///
110    /// This uses the unstable prefix in [MSC4230].
111    ///
112    /// [MSC4230]: https://github.com/matrix-org/matrix-spec-proposals/pull/4230
113    #[cfg(feature = "unstable-msc4230")]
114    #[serde(rename = "org.matrix.msc4230.is_animated", skip_serializing_if = "Option::is_none")]
115    pub is_animated: Option<bool>,
116}
117
118impl ImageInfo {
119    /// Creates an empty `ImageInfo`.
120    pub fn new() -> Self {
121        Self::default()
122    }
123}
124
125/// Metadata about a thumbnail.
126#[derive(Clone, Debug, Default, Deserialize, Serialize)]
127#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
128pub struct ThumbnailInfo {
129    /// The height of the thumbnail in pixels.
130    #[serde(rename = "h", skip_serializing_if = "Option::is_none")]
131    pub height: Option<UInt>,
132
133    /// The width of the thumbnail in pixels.
134    #[serde(rename = "w", skip_serializing_if = "Option::is_none")]
135    pub width: Option<UInt>,
136
137    /// The MIME type of the thumbnail, e.g. "image/png."
138    #[serde(skip_serializing_if = "Option::is_none")]
139    pub mimetype: Option<String>,
140
141    /// The file size of the thumbnail in bytes.
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub size: Option<UInt>,
144}
145
146impl ThumbnailInfo {
147    /// Creates an empty `ThumbnailInfo`.
148    pub fn new() -> Self {
149        Self::default()
150    }
151}
152
153/// A file sent to a room with end-to-end encryption enabled.
154///
155/// To create an instance of this type, first create a `EncryptedFileInit` and convert it via
156/// `EncryptedFile::from` / `.into()`.
157#[derive(Clone, Debug, Deserialize, Serialize)]
158#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
159pub struct EncryptedFile {
160    /// The URL to the file.
161    pub url: OwnedMxcUri,
162
163    /// A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
164    pub key: JsonWebKey,
165
166    /// The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.
167    pub iv: Base64,
168
169    /// A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64.
170    ///
171    /// Clients should support the SHA-256 hash, which uses the key sha256.
172    pub hashes: BTreeMap<String, Base64>,
173
174    /// Version of the encrypted attachments protocol.
175    ///
176    /// Must be `v2`.
177    pub v: String,
178}
179
180/// Initial set of fields of `EncryptedFile`.
181///
182/// This struct will not be updated even if additional fields are added to `EncryptedFile` in a new
183/// (non-breaking) release of the Matrix specification.
184#[derive(Debug)]
185#[allow(clippy::exhaustive_structs)]
186pub struct EncryptedFileInit {
187    /// The URL to the file.
188    pub url: OwnedMxcUri,
189
190    /// A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
191    pub key: JsonWebKey,
192
193    /// The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.
194    pub iv: Base64,
195
196    /// A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64.
197    ///
198    /// Clients should support the SHA-256 hash, which uses the key sha256.
199    pub hashes: BTreeMap<String, Base64>,
200
201    /// Version of the encrypted attachments protocol.
202    ///
203    /// Must be `v2`.
204    pub v: String,
205}
206
207impl From<EncryptedFileInit> for EncryptedFile {
208    fn from(init: EncryptedFileInit) -> Self {
209        let EncryptedFileInit { url, key, iv, hashes, v } = init;
210        Self { url, key, iv, hashes, v }
211    }
212}
213
214/// A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
215///
216/// To create an instance of this type, first create a `JsonWebKeyInit` and convert it via
217/// `JsonWebKey::from` / `.into()`.
218#[derive(Clone, Debug, Deserialize, Serialize)]
219#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
220pub struct JsonWebKey {
221    /// Key type.
222    ///
223    /// Must be `oct`.
224    pub kty: String,
225
226    /// Key operations.
227    ///
228    /// Must at least contain `encrypt` and `decrypt`.
229    pub key_ops: Vec<String>,
230
231    /// Algorithm.
232    ///
233    /// Must be `A256CTR`.
234    pub alg: String,
235
236    /// The key, encoded as url-safe unpadded base64.
237    pub k: Base64<UrlSafe>,
238
239    /// Extractable.
240    ///
241    /// Must be `true`. This is a
242    /// [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk).
243    pub ext: bool,
244}
245
246/// Initial set of fields of `JsonWebKey`.
247///
248/// This struct will not be updated even if additional fields are added to `JsonWebKey` in a new
249/// (non-breaking) release of the Matrix specification.
250#[derive(Debug)]
251#[allow(clippy::exhaustive_structs)]
252pub struct JsonWebKeyInit {
253    /// Key type.
254    ///
255    /// Must be `oct`.
256    pub kty: String,
257
258    /// Key operations.
259    ///
260    /// Must at least contain `encrypt` and `decrypt`.
261    pub key_ops: Vec<String>,
262
263    /// Algorithm.
264    ///
265    /// Must be `A256CTR`.
266    pub alg: String,
267
268    /// The key, encoded as url-safe unpadded base64.
269    pub k: Base64<UrlSafe>,
270
271    /// Extractable.
272    ///
273    /// Must be `true`. This is a
274    /// [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk).
275    pub ext: bool,
276}
277
278impl From<JsonWebKeyInit> for JsonWebKey {
279    fn from(init: JsonWebKeyInit) -> Self {
280        let JsonWebKeyInit { kty, key_ops, alg, k, ext } = init;
281        Self { kty, key_ops, alg, k, ext }
282    }
283}
284
285#[cfg(test)]
286mod tests {
287    use std::collections::BTreeMap;
288
289    use assert_matches2::assert_matches;
290    use ruma_common::{mxc_uri, serde::Base64};
291    use serde::Deserialize;
292    use serde_json::{from_value as from_json_value, json};
293
294    use super::{EncryptedFile, JsonWebKey, MediaSource};
295
296    #[derive(Deserialize)]
297    struct MsgWithAttachment {
298        #[allow(dead_code)]
299        body: String,
300        #[serde(flatten)]
301        source: MediaSource,
302    }
303
304    fn dummy_jwt() -> JsonWebKey {
305        JsonWebKey {
306            kty: "oct".to_owned(),
307            key_ops: vec!["encrypt".to_owned(), "decrypt".to_owned()],
308            alg: "A256CTR".to_owned(),
309            k: Base64::new(vec![0; 64]),
310            ext: true,
311        }
312    }
313
314    fn encrypted_file() -> EncryptedFile {
315        EncryptedFile {
316            url: mxc_uri!("mxc://localhost/encryptedfile").to_owned(),
317            key: dummy_jwt(),
318            iv: Base64::new(vec![0; 64]),
319            hashes: BTreeMap::new(),
320            v: "v2".to_owned(),
321        }
322    }
323
324    #[test]
325    fn prefer_encrypted_attachment_over_plain() {
326        let msg: MsgWithAttachment = from_json_value(json!({
327            "body": "",
328            "url": "mxc://localhost/file",
329            "file": encrypted_file(),
330        }))
331        .unwrap();
332
333        assert_matches!(msg.source, MediaSource::Encrypted(_));
334
335        // As above, but with the file field before the url field
336        let msg: MsgWithAttachment = from_json_value(json!({
337            "body": "",
338            "file": encrypted_file(),
339            "url": "mxc://localhost/file",
340        }))
341        .unwrap();
342
343        assert_matches!(msg.source, MediaSource::Encrypted(_));
344    }
345}
ruma_events/room.rs

ruma_events/
room.rs
