feat(oauth): add flow for granting login by scanning a QR code

Signed-off-by: Johannes Marbach <[email protected]>

Author: Johennes

crates/matrix-sdk/CHANGELOG.md

@@ -8,6 +8,9 @@ All notable changes to this project will be documented in this file.
 
 ### Features
 
+- Extend `authentication::oauth::OAuth::grant_login_with_qr_code` to support granting
+  login by scanning a QR code on the existing device.
+  ([#5818](https://github.com/matrix-org/matrix-rust-sdk/pull/5818))
 - Add a new `RequestConfig::skip_auth()` option. This is useful to ensure that
   certain request won't ever include an authorization header.
   ([#5822](https://github.com/matrix-org/matrix-rust-sdk/pull/5822))

crates/matrix-sdk/src/authentication/oauth/mod.rs

@@ -216,7 +216,10 @@ mod tests;
 #[cfg(feature = "e2e-encryption")]
 use self::cross_process::{CrossProcessRefreshLockGuard, CrossProcessRefreshManager};
 #[cfg(feature = "e2e-encryption")]
-use self::qrcode::{GrantLoginWithGeneratedQrCode, LoginWithGeneratedQrCode, LoginWithQrCode};
+use self::qrcode::{
+    GrantLoginWithGeneratedQrCode, GrantLoginWithScannedQrCode, LoginWithGeneratedQrCode,
+    LoginWithQrCode,
+};
 pub use self::{
     account_management_url::{AccountManagementActionFull, AccountManagementUrlBuilder},
     auth_code_builder::{OAuthAuthCodeUrlBuilder, OAuthAuthorizationData},
@@ -1537,7 +1540,7 @@ pub struct GrantLoginWithQrCodeBuilder<'a> {
 #[cfg(feature = "e2e-encryption")]
 impl<'a> GrantLoginWithQrCodeBuilder<'a> {
     /// Create a new builder with the default device creation timeout.
-    pub fn new(client: &'a Client) -> Self {
+    fn new(client: &'a Client) -> Self {
         Self { client, device_creation_timeout: Duration::from_secs(10) }
     }
 
@@ -1552,6 +1555,86 @@ impl<'a> GrantLoginWithQrCodeBuilder<'a> {
         self
     }
 
+    /// This method allows you to grant login to a new device by scanning a
+    /// QR code generated by the new device.
+    ///
+    /// The new device needs to display the QR code which this device can
+    /// scan and call this method to grant the login.
+    ///
+    /// A successful login grant using this method will automatically mark the
+    /// new device as verified and transfer all end-to-end encryption
+    /// related secrets, like the private cross-signing keys and the backup
+    /// key from this device device to the new device.
+    ///
+    /// For the reverse flow where this device generates the QR code
+    /// for the new device to scan, use
+    /// [`GrantLoginWithQrCodeBuilder::generate`].
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - The data scanned from a QR code.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use anyhow::bail;
+    /// use futures_util::StreamExt;
+    /// use matrix_sdk::{
+    ///     Client, authentication::oauth::{
+    ///         qrcode::{GrantLoginProgress, QrCodeData, QrCodeModeData, QrProgress},
+    ///     }
+    /// };
+    /// use std::{error::Error, io::stdin};
+    /// # _ = async {
+    /// # let bytes = unimplemented!();
+    /// // You'll need to use a different library to scan and extract the raw bytes from the QR
+    /// // code.
+    /// let qr_code_data = QrCodeData::from_bytes(bytes)?;
+    ///
+    /// // Build the client as usual.
+    /// let client = Client::builder()
+    ///     .server_name_or_homeserver_url("matrix.org")
+    ///     .handle_refresh_tokens()
+    ///     .build()
+    ///     .await?;
+    ///
+    /// let oauth = client.oauth();
+    ///
+    /// // Subscribing to the progress is necessary to capture
+    /// // the checkcode in order to display it to the other device and to obtain the verification URL to
+    /// // open it in a browser so the user can consent to the new login.
+    /// let mut grant = oauth.grant_login_with_qr_code().scan(&qr_code_data);
+    /// let mut progress = grant.subscribe_to_progress();
+    ///
+    /// // Create a task which will show us the progress and allows us to receive
+    /// // and feed back data.
+    /// let task = tokio::spawn(async move {
+    ///     while let Some(state) = progress.next().await {
+    ///         match state {
+    ///             GrantLoginProgress::Starting | GrantLoginProgress::SyncingSecrets => (),
+    ///             GrantLoginProgress::EstablishingSecureChannel(QrProgress { check_code }) => {
+    ///                 println!("Please enter the checkcode on your other device: {:?}", check_code);
+    ///             }
+    ///             GrantLoginProgress::WaitingForAuth { verification_uri } => {
+    ///                 println!("Please open {verification_uri} to confirm the new login")
+    ///             },
+    ///             GrantLoginProgress::Done => break,
+    ///         }
+    ///     }
+    ///     Ok::<(), Box<dyn Error + Send + Sync>>(())
+    /// });
+    ///
+    /// // Now run the future to grant the login.
+    /// grant.await?;
+    /// task.abort();
+    ///
+    /// println!("Successfully granted login");
+    /// # anyhow::Ok(()) };
+    /// ```
+    pub fn scan(self, data: &'a QrCodeData) -> GrantLoginWithScannedQrCode<'a> {
+        GrantLoginWithScannedQrCode::new(self.client, data, self.device_creation_timeout)
+    }
+
     /// This method allows you to grant login to a new device by generating a QR
     /// code on this device to be scanned by the new device.
     ///