From 32f3670aeb7dc2859a45fdff7ca0350977754083 Mon Sep 17 00:00:00 2001
From: Andy Balaam <andy.balaam@matrix.org>
Date: Wed, 1 Oct 2025 15:02:03 +0100
Subject: [PATCH] task(crypto): Warn API users to fetch device info before
 processing verification requests

---
 bindings/matrix-sdk-crypto-ffi/src/machine.rs   | 17 +++++++++++++++++
 .../src/response_processors/verification.rs     |  9 +++++++++
 crates/matrix-sdk-crypto/src/machine/mod.rs     |  9 +++++++++
 3 files changed, 35 insertions(+)

diff --git a/bindings/matrix-sdk-crypto-ffi/src/machine.rs b/bindings/matrix-sdk-crypto-ffi/src/machine.rs
index 552389fd6..fb029eb7f 100644
--- a/bindings/matrix-sdk-crypto-ffi/src/machine.rs
+++ b/bindings/matrix-sdk-crypto-ffi/src/machine.rs
@@ -869,9 +869,18 @@ impl OlmMachine {
     ///
     /// * `room_id` - The unique id of the room where the event was sent to.
     ///
+    /// * `handle_verification_events` - if the supplied event is a verification
+    ///   event, use it to update the verification state. **Note**: it is
+    ///   recommended to avoid setting this flag to true and use the explicit
+    ///   [`OlmMachine::receive_verification_event`] method instead:
+    ///   verification events sometimes need preparation before we can handle
+    ///   them: see the documentation for
+    ///   [`OlmMachine::receive_verification_event`].
+    ///
     /// * `strict_shields` - If `true`, messages will be decorated with strict
     ///   warnings (use `false` to match legacy behaviour where unsafe keys have
     ///   lower severity warnings and unverified identities are not decorated).
+    ///
     /// * `decryption_settings` - The setting for decrypting messages.
     pub fn decrypt_room_event(
         &self,
@@ -1100,6 +1109,14 @@ impl OlmMachine {
     ///
     /// This method can be used to pass verification events that are happening
     /// in rooms to the `OlmMachine`. The event should be in the decrypted form.
+    ///
+    /// **Note**: If the supplied event is an `m.room.message` event with
+    /// `msgtype: m.key.verification.request`, then the device information for
+    /// the sending user must be up-to-date before calling this method
+    /// (otherwise, the request will be ignored). It is hard to guarantee this
+    /// is the case, but you can maximize your chances by explicitly making a
+    /// request to /keys/query for the user's device info, and processing the
+    /// response with [`OlmMachine::mark_request_as_sent`].
     pub fn receive_verification_event(
         &self,
         event: String,
diff --git a/crates/matrix-sdk-base/src/response_processors/verification.rs b/crates/matrix-sdk-base/src/response_processors/verification.rs
index 83e7b3ba1..614c54fb0 100644
--- a/crates/matrix-sdk-base/src/response_processors/verification.rs
+++ b/crates/matrix-sdk-base/src/response_processors/verification.rs
@@ -25,6 +25,15 @@ use crate::Result;
 
 /// Process the given event as a verification event if it is a candidate. The
 /// event must be decrypted.
+///
+/// **Note**: If the supplied event is an `m.room.message` event with
+/// `msgtype: m.key.verification.request`, then the device information for
+/// the sending user must be up-to-date before calling this method
+/// (otherwise, the request will be ignored). It is hard to guarantee this
+/// is the case, but you can maximize your chances by explicitly making a
+/// request for this user's device info by calling
+/// [`OlmMachine::query_keys_for_users`], sending the request, and
+/// processing the response with [`OlmMachine::mark_request_as_sent`].
 pub async fn process_if_relevant(
     event: &AnySyncTimelineEvent,
     e2ee: E2EE<'_>,
diff --git a/crates/matrix-sdk-crypto/src/machine/mod.rs b/crates/matrix-sdk-crypto/src/machine/mod.rs
index f8ecb766f..0b5f60818 100644
--- a/crates/matrix-sdk-crypto/src/machine/mod.rs
+++ b/crates/matrix-sdk-crypto/src/machine/mod.rs
@@ -1292,6 +1292,15 @@ impl OlmMachine {
     /// Receive a verification event.
     ///
     /// The event should be in the decrypted form.
+    ///
+    /// **Note**: If the supplied event is an `m.room.message` event with
+    /// `msgtype: m.key.verification.request`, then the device information for
+    /// the sending user must be up-to-date before calling this method
+    /// (otherwise, the request will be ignored). It is hard to guarantee this
+    /// is the case, but you can maximize your chances by explicitly making a
+    /// request for this user's device info by calling
+    /// [`OlmMachine::query_keys_for_users`], sending the request, and
+    /// processing the response with [`OlmMachine::mark_request_as_sent`].
     pub async fn receive_verification_event(&self, event: &AnyMessageLikeEvent) -> StoreResult<()> {
         self.inner.verification_machine.receive_any_event(event).await
     }