macltok

public

Star0

Fork 0

Watch0

14 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `6f1d6591c10d`

tarball

atagen <boss@atagen.co>2026-09-27 01:42 UTC

8 files changed+177-47

account: remember the device across a soft logout

Deleting the record on Retain::Store left the device id only in memory, so a host restarting before the re-login saw no record and tried a fresh login on a store holding another device's keys. SessionStore::soft_log_out now keeps a tokenless record naming the homeserver, user, device and OAuth client, and Session::restore answers it as Restore::SoftLoggedOut instead of None.

Modified file: README.md+7 additions−5 deletions@@ -52,11 +52,13 @@ the next refresh, refresh tokens only work once
 `Termination::retain` says what to do about it. after `LoggedOut` or
 `AccessRevoked` the record and the store are dead, `discard` them once the
 client is dropped, since an open store won't go quietly. `SoftLoggedOut` wants
-the record forgotten, the store kept and a fresh login with
-`PasswordLogin::device_id` set to the device it carries, or the e2ee keys go
-with it. `ShutDown` and `HandlesDropped` keep everything. an `Err` is a real
-failure and kills nothing. one store directory per login, the sdk won't share a
-crypto store between devices
+the store kept and a fresh login as the same device, or the e2ee keys go with
+it. `soft_log_out` swaps the record for one naming that device, so a restart
+gets `Restore::SoftLoggedOut` and `SoftLogout::password_login` rather than
+nothing, and the login overwrites it with a live record. `ShutDown` and
+`HandlesDropped` keep everything. an `Err` is a real failure and kills nothing.
+one store directory per login, the sdk won't share a crypto store between
+devices
 
 ## wasm
 

Modified file: docs/design-decisions.md+6 additions−4 deletions@@ -173,10 +173,12 @@ so a crash mid save leaves the old one. it keeps the record out of the sdk's
 state store because sqlite writes custom values there in the clear, and a
 client can't open its store before it knows the homeserver the record holds.
 `discard` deletes the record, then the store, since a record without its store
-would restore into empty crypto. `forget` deletes only the record. the host
-follows `Termination::retain`, `Nothing` discards and `Store` forgets, keeping
-the store for a same-device login or the e2ee keys go with it. one store
-directory per login
+would restore into empty crypto. the host follows `Termination::retain`.
+`Nothing` discards. `Store` calls `soft_log_out`, which keeps the store and
+swaps the record for one holding the homeserver, user, device and oauth client
+id with no tokens. `restore` hands that back as `Restore::SoftLoggedOut`, so a
+restart still knows which device to log in again as, and the login overwrites
+it. one store directory per login
 
 ## room lists, spaces and profiles
 

Modified file: examples/headless.rs+8 additions−4 deletions@@ -1,6 +1,6 @@
 use macltok::{
-    EncryptedSessionStore, EngineConfig, Event, PasswordLogin, Retain, RoomMembership, Session,
-    SessionStore, StoreConfig, TimelineContent, TimelineDiff, TimelineId, TimelineItem,
+    EncryptedSessionStore, EngineConfig, Event, PasswordLogin, Restore, Retain, RoomMembership,
+    Session, SessionStore, StoreConfig, TimelineContent, TimelineDiff, TimelineId, TimelineItem,
     imbl::Vector,
 };
 
@@ -13,7 +13,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         StoreConfig::sqlite(&store_path, &passphrase),
     );
     let session = match Session::restore(&sessions).await? {
-        Some(session) => session,
+        Some(Restore::Resumed(session)) => session,
+        Some(Restore::SoftLoggedOut(soft)) => {
+            Session::login_password(soft.password_login(required("MATRIX_PASSWORD")?), &sessions)
+                .await?
+        }
         None => {
             Session::login_password(
                 PasswordLogin::new(
@@ -92,7 +96,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     drop((handle, events));
     match termination.retain() {
         Retain::RecordAndStore => {}
-        Retain::Store => sessions.forget().await?,
+        Retain::Store => sessions.soft_log_out().await?,
         Retain::Nothing => sessions.discard().await?,
     }
     Ok(())

Modified file: src/account.rs+66 additions−9 deletions@@ -3,7 +3,7 @@ use std::path::PathBuf;
 use std::{collections::HashMap, sync::Arc};
 
 use matrix_sdk::{
-    Client, ClientBuilder, SendOutsideWasm, SyncOutsideWasm, ThreadingSupport,
+    Client, ClientBuilder, SendOutsideWasm, SessionMeta, SyncOutsideWasm, ThreadingSupport,
     authentication::{
         AuthSession,
         matrix::MatrixSession,
@@ -14,7 +14,7 @@ use matrix_sdk::{
     },
     cross_process_lock::CrossProcessLockConfig,
     encryption::{BackupDownloadStrategy, EncryptionSettings},
-    ruma::{OwnedDeviceId, serde::Raw},
+    ruma::{OwnedDeviceId, OwnedUserId, serde::Raw},
 };
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
@@ -255,6 +255,10 @@ enum AuthenticationRecord {
         client_id: ClientId,
         user: UserSession,
     },
+    SoftLoggedOut {
+        meta: SessionMeta,
+        client_id: Option<ClientId>,
+    },
 }
 
 impl SessionRecord {
@@ -262,6 +266,51 @@ impl SessionRecord {
     pub fn homeserver(&self) -> &str {
         &self.homeserver
     }
+
+    pub(crate) fn soft_logged_out(self) -> Self {
+        let authentication = match self.authentication {
+            AuthenticationRecord::Matrix(session) => AuthenticationRecord::SoftLoggedOut {
+                meta: session.meta,
+                client_id: None,
+            },
+            AuthenticationRecord::OAuth { client_id, user } => {
+                AuthenticationRecord::SoftLoggedOut {
+                    meta: user.meta,
+                    client_id: Some(client_id),
+                }
+            }
+            soft @ AuthenticationRecord::SoftLoggedOut { .. } => soft,
+        };
+        Self {
+            homeserver: self.homeserver,
+            authentication,
+        }
+    }
+}
+
+pub enum Restore {
+    Resumed(Session),
+    SoftLoggedOut(SoftLogout),
+}
+
+/// who to log in again as. the store keeps this device's e2ee keys, so a login
+/// as any other device would orphan them
+#[derive(Clone, Debug)]
+#[non_exhaustive]
+pub struct SoftLogout {
+    pub homeserver: String,
+    pub user_id: OwnedUserId,
+    pub device_id: OwnedDeviceId,
+    /// set when the login was OAuth, for `OAuthLogin::with_client_id`
+    pub client_id: Option<String>,
+}
+
+impl SoftLogout {
+    #[must_use]
+    pub fn password_login(&self, password: impl Into<String>) -> PasswordLogin {
+        PasswordLogin::new(self.homeserver.clone(), self.user_id.as_str(), password)
+            .with_device_id(self.device_id.clone())
+    }
 }
 
 #[derive(Debug, Error)]
@@ -359,26 +408,34 @@ impl Session {
 
     /// Restore the record `sessions` holds, or `None` when it holds none.
     /// The caller must also handle refresh, rejection, and explicit logout.
-    pub async fn restore(sessions: &dyn SessionStore) -> Result<Option<Self>, AccountError> {
+    pub async fn restore(sessions: &dyn SessionStore) -> Result<Option<Restore>, AccountError> {
         let Some(record) = sessions.load().await? else {
             return Ok(None);
         };
-        let client = matrix_client_builder(sessions.store())
-            .homeserver_url(&record.homeserver)
-            .build()
-            .await
-            .map_err(|error| account_error("reopening the Matrix store", error))?;
         let authentication = match record.authentication {
             AuthenticationRecord::Matrix(session) => AuthSession::Matrix(session),
             AuthenticationRecord::OAuth { client_id, user } => {
                 OAuthSession { client_id, user }.into()
             }
+            AuthenticationRecord::SoftLoggedOut { meta, client_id } => {
+                return Ok(Some(Restore::SoftLoggedOut(SoftLogout {
+                    homeserver: record.homeserver,
+                    user_id: meta.user_id,
+                    device_id: meta.device_id,
+                    client_id: client_id.map(|client_id| client_id.as_str().to_owned()),
+                })));
+            }
         };
+        let client = matrix_client_builder(sessions.store())
+            .homeserver_url(&record.homeserver)
+            .build()
+            .await
+            .map_err(|error| account_error("reopening the Matrix store", error))?;
         client
             .restore_session(authentication)
             .await
             .map_err(|error| account_error("restoring the authenticated session", error))?;
-        Ok(Some(Self { client }))
+        Ok(Some(Restore::Resumed(Self { client })))
     }
 
     pub async fn build(

Modified file: src/lib.rs+2 additions−2 deletions@@ -21,8 +21,8 @@ mod session_store;
 
 #[cfg(any(feature = "sqlite", feature = "indexeddb"))]
 pub use account::{
-    AccountError, OAuthApplicationType, OAuthLogin, PasswordLogin, PendingOAuthLogin, Session,
-    SessionRecord, StoreConfig,
+    AccountError, OAuthApplicationType, OAuthLogin, PasswordLogin, PendingOAuthLogin, Restore,
+    Session, SessionRecord, SoftLogout, StoreConfig,
 };
 #[cfg(any(feature = "sqlite", feature = "indexeddb"))]
 pub use session_store::{EncryptedSessionStore, SessionStore};

Modified file: src/model.rs+1

@@ -744,6 +744,7 @@ impl Termination {

744744 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]

745745 pub enum Retain {

746746 RecordAndStore,

747+ /// keep the store and a record naming the device to log in again as

747748 Store,

748749 Nothing,

749750 }

Modified file: src/session_store.rs+40 additions−21 deletions@@ -22,8 +22,9 @@ pub trait SessionStore: SendOutsideWasm + SyncOutsideWasm {
     /// replace the saved record, all or nothing
     fn save<'a>(&'a self, record: &'a SessionRecord) -> BoxFuture<'a, Result<(), AccountError>>;
 
-    /// drop the record and keep the store, for `Retain::Store`
-    fn forget(&self) -> BoxFuture<'_, Result<(), AccountError>>;
+    /// swap the record for one that only says who to log in again as, keeping the store.
+    /// `Session::restore` then answers `Restore::SoftLoggedOut`, even after a restart
+    fn soft_log_out(&self) -> BoxFuture<'_, Result<(), AccountError>>;
 
     /// drop the record and delete the store, once nothing has the store open
     fn discard(&self) -> BoxFuture<'_, Result<(), AccountError>>;
@@ -67,6 +68,35 @@ impl EncryptedSessionStore {
 
     async fn load_record(&self) -> Result<Option<SessionRecord>, AccountError> {
         let mut sealer = self.sealer.lock().await;
+        self.read(&mut sealer).await
+    }
+
+    async fn save_record(&self, record: &SessionRecord) -> Result<(), AccountError> {
+        let mut sealer = self.sealer.lock().await;
+        self.write(&mut sealer, record).await
+    }
+
+    async fn soft_log_out_record(&self) -> Result<(), AccountError> {
+        let mut sealer = self.sealer.lock().await;
+        match self.read(&mut sealer).await? {
+            Some(record) => self.write(&mut sealer, &record.soft_logged_out()).await,
+            None => Ok(()),
+        }
+    }
+
+    async fn discard_all(&self) -> Result<(), AccountError> {
+        let mut sealer = self.sealer.lock().await;
+        backend::remove(&self.record)
+            .await
+            .map_err(|error| account_error("removing the session record", error))?;
+        *sealer = None;
+        self.store.delete().await
+    }
+
+    async fn read(
+        &self,
+        sealer: &mut Option<Sealer>,
+    ) -> Result<Option<SessionRecord>, AccountError> {
         let Some(sealed) = backend::read(&self.record)
             .await
             .map_err(|error| account_error("reading the session record", error))?
@@ -78,9 +108,12 @@ impl EncryptedSessionStore {
         Ok(Some(record))
     }
 
-    async fn save_record(&self, record: &SessionRecord) -> Result<(), AccountError> {
-        let mut sealer = self.sealer.lock().await;
-        let sealer = match &mut *sealer {
+    async fn write(
+        &self,
+        sealer: &mut Option<Sealer>,
+        record: &SessionRecord,
+    ) -> Result<(), AccountError> {
+        let sealer = match sealer {
             Some(sealer) => sealer,
             empty => empty.insert(Sealer::new(self.store.passphrase())?),
         };
@@ -89,20 +122,6 @@ impl EncryptedSessionStore {
             .await
             .map_err(|error| account_error("writing the session record", error))
     }
-
-    async fn forget_record(&self) -> Result<(), AccountError> {
-        let mut sealer = self.sealer.lock().await;
-        backend::remove(&self.record)
-            .await
-            .map_err(|error| account_error("removing the session record", error))?;
-        *sealer = None;
-        Ok(())
-    }
-
-    async fn discard_all(&self) -> Result<(), AccountError> {
-        self.forget_record().await?;
-        self.store.delete().await
-    }
 }
 
 impl SessionStore for EncryptedSessionStore {
@@ -118,8 +137,8 @@ impl SessionStore for EncryptedSessionStore {
         Box::pin(self.save_record(record))
     }
 
-    fn forget(&self) -> BoxFuture<'_, Result<(), AccountError>> {
-        Box::pin(self.forget_record())
+    fn soft_log_out(&self) -> BoxFuture<'_, Result<(), AccountError>> {
+        Box::pin(self.soft_log_out_record())
     }
 
     fn discard(&self) -> BoxFuture<'_, Result<(), AccountError>> {

Modified file: tests/account.rs+47 additions−2 deletions@@ -4,7 +4,7 @@ mod support;
 use std::{path::PathBuf, time::SystemTime};
 
 use macltok::{
-    EncryptedSessionStore, EngineConfig, Event, PasswordLogin, Session, SessionRecord,
+    EncryptedSessionStore, EngineConfig, Event, PasswordLogin, Restore, Session, SessionRecord,
     SessionStore, StoreConfig,
 };
 use matrix_sdk::{ruma::api::client::sync::sync_events::v5, test_utils::mocks::MatrixMockServer};
@@ -57,7 +57,9 @@ async fn password_session_round_trips_and_discards_with_its_store() {
     assert!(wrong.load().await.is_err());
 
     let sessions = sessions();
-    let session = Session::restore(&sessions).await.unwrap().unwrap();
+    let Some(Restore::Resumed(session)) = Session::restore(&sessions).await.unwrap() else {
+        panic!("the saved login didn't resume");
+    };
     let (engine, handle, mut events) = session.build(config).await.unwrap();
     let running = tokio::spawn(engine.run());
     support::receive_until(&mut events, |event| {
@@ -75,6 +77,49 @@ async fn password_session_round_trips_and_discards_with_its_store() {
 }
 
 #[tokio::test]
+async fn a_restart_after_a_soft_logout_still_knows_the_device() {
+    let server = MatrixMockServer::new().await;
+    server.mock_versions().ok().mount().await;
+    server.mock_login().ok().mount().await;
+    let root = temporary_path();
+    let sessions = || {
+        EncryptedSessionStore::file(
+            root.join("session"),
+            StoreConfig::sqlite(root.join("store"), "test store passphrase"),
+        )
+    };
+    Session::login_password(
+        PasswordLogin::new(server.uri(), "example", "wordpass"),
+        &sessions(),
+    )
+    .await
+    .unwrap();
+    sessions().soft_log_out().await.unwrap();
+
+    let Some(Restore::SoftLoggedOut(soft)) = Session::restore(&sessions()).await.unwrap() else {
+        panic!("a soft logged out record came back as something else");
+    };
+    // the device matrix-sdk-test's canned login response hands out
+    assert_eq!(soft.device_id, "GHTYAJCE");
+    Session::login_password(soft.password_login("wordpass"), &sessions())
+        .await
+        .unwrap();
+    let requests = server.server().received_requests().await.unwrap();
+    let relogin: serde_json::Value = requests
+        .iter()
+        .rfind(|request| request.url.path().ends_with("/login"))
+        .unwrap()
+        .body_json()
+        .unwrap();
+    assert_eq!(relogin["device_id"], "GHTYAJCE");
+    assert!(matches!(
+        Session::restore(&sessions()).await.unwrap(),
+        Some(Restore::Resumed(_))
+    ));
+    std::fs::remove_dir_all(root).unwrap();
+}
+
+#[tokio::test]
 async fn a_torn_or_failed_save_leaves_the_old_record() {
     let root = temporary_path();
     let record_path = root.join("session");

macltok

Commit 6f1d6591c10d

Commit `6f1d6591c10d`