macltok

public
Star0
Watch0
43 commits 3 branches 0 tags 0 releases3.0 MiB
#[cfg(feature = "sqlite")]
use std::path::PathBuf;
#[cfg(not(target_family = "wasm"))]
use std::sync::atomic::{AtomicBool, Ordering};
use std::{collections::HashMap, sync::Arc};

use matrix_sdk::{
    Client, ClientBuilder, SendOutsideWasm, SessionChange, SessionMeta, SyncOutsideWasm,
    ThreadingSupport,
    authentication::{
        AuthSession,
        matrix::MatrixSession,
        oauth::{
            ClientId, ClientRegistrationData, CsrfToken, OAuthSession, PendingAuthorization,
            UserSession,
            registration::{ApplicationType, ClientMetadata, Localized, OAuthGrantType},
        },
    },
    cross_process_lock::CrossProcessLockConfig,
    encryption::{BackupDownloadStrategy, EncryptionSettings},
    ruma::{MilliSecondsSinceUnixEpoch, OwnedDeviceId, OwnedUserId, serde::Raw},
};
use serde::{Deserialize, Serialize};
use thiserror::Error;
use tokio::sync::{broadcast, mpsc};
use url::Url;

use crate::{
    ClientHandle, Engine, EngineConfig, EngineError, ErrorKind, EventStream, ServerError,
    SessionStore,
    engine::{Persistence, StoreLock},
    error::SourceError,
};

/// a logged in client and the `SessionStore` its record lives in. the engine it builds
/// saves every token rotation there, unless told `without_persistence`
pub struct Session {
    client: Client,
    tracking: Tracking,
    store_lock: StoreLock,
}

/// taken as soon as the client exists, since the sdk can refresh before there's an engine
struct Tracking {
    session_changes: broadcast::Receiver<SessionChange>,
    persistence: Option<Persistence>,
    #[cfg(not(target_family = "wasm"))]
    inline: Arc<AtomicBool>,
}

#[non_exhaustive]
pub struct PasswordLogin {
    pub homeserver: String,
    pub username: String,
    pub password: String,
    pub device_display_name: Option<String>,
    /// set after a soft logout so the store's keys still belong to us
    pub device_id: Option<OwnedDeviceId>,
    /// let plain http through, for loopback hosts only
    pub allow_insecure_loopback: bool,
}

impl PasswordLogin {
    #[must_use]
    pub fn new(
        homeserver: impl Into<String>,
        username: impl Into<String>,
        password: impl Into<String>,
    ) -> Self {
        Self {
            homeserver: homeserver.into(),
            username: username.into(),
            password: password.into(),
            device_display_name: None,
            device_id: None,
            allow_insecure_loopback: false,
        }
    }

    #[must_use]
    pub fn with_device_display_name(mut self, name: impl Into<String>) -> Self {
        self.device_display_name = Some(name.into());
        self
    }

    #[must_use]
    pub fn with_device_id(mut self, device_id: OwnedDeviceId) -> Self {
        self.device_id = Some(device_id);
        self
    }

    #[must_use]
    pub fn allow_insecure_loopback(mut self, allow: bool) -> Self {
        self.allow_insecure_loopback = allow;
        self
    }
}

#[non_exhaustive]
pub struct OAuthLogin {
    pub homeserver: String,
    pub redirect_uri: String,
    pub client_uri: String,
    pub client_name: Option<String>,
    pub client_id: Option<String>,
    pub device_id: Option<OwnedDeviceId>,
    pub application_type: OAuthApplicationType,
    /// let plain http through, for loopback hosts only
    pub allow_insecure_loopback: bool,
}

impl OAuthLogin {
    #[must_use]
    pub fn new(
        homeserver: impl Into<String>,
        redirect_uri: impl Into<String>,
        client_uri: impl Into<String>,
        application_type: OAuthApplicationType,
    ) -> Self {
        Self {
            homeserver: homeserver.into(),
            redirect_uri: redirect_uri.into(),
            client_uri: client_uri.into(),
            client_name: None,
            client_id: None,
            device_id: None,
            application_type,
            allow_insecure_loopback: false,
        }
    }

    #[must_use]
    pub fn with_client_name(mut self, name: impl Into<String>) -> Self {
        self.client_name = Some(name.into());
        self
    }

    /// a statically registered client id, skipping dynamic registration
    #[must_use]
    pub fn with_client_id(mut self, client_id: impl Into<String>) -> Self {
        self.client_id = Some(client_id.into());
        self
    }

    #[must_use]
    pub fn with_device_id(mut self, device_id: OwnedDeviceId) -> Self {
        self.device_id = Some(device_id);
        self
    }

    #[must_use]
    pub fn allow_insecure_loopback(mut self, allow: bool) -> Self {
        self.allow_insecure_loopback = allow;
        self
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum OAuthApplicationType {
    Native,
    Web,
}

pub struct PendingOAuthLogin {
    client: Client,
    sessions: Arc<dyn SessionStore>,
    tracking: Option<(Tracking, StoreLock)>,
    authorization_url: String,
    state: Option<CsrfToken>,
    previous: Option<SessionRecord>,
}

impl PendingOAuthLogin {
    #[must_use]
    pub fn authorization_url(&self) -> &str {
        &self.authorization_url
    }

    #[must_use]
    pub fn registered_client_id(&self) -> String {
        self.client
            .oauth()
            .client_id()
            .expect("OAuth client was registered before authorization")
            .as_str()
            .to_owned()
    }

    #[must_use]
    pub const fn is_pending(&self) -> bool {
        self.state.is_some()
    }

    pub async fn finish(&mut self, callback_url: &str) -> Result<Session, AccountError> {
        let callback_url = Url::parse(callback_url)
            .map_err(|error| account_error("parsing the OAuth callback URL", error))?;
        let state = self
            .state
            .take()
            .ok_or(AccountError::OAuthCallbackAlreadySubmitted)?;
        let oauth = self.client.oauth();
        if let Err(error) = oauth.finish_login(callback_url.into()).await {
            oauth.abort_login(&state).await;
            if let Some(previous) = self.previous.take() {
                put_back(self.sessions.as_ref(), previous).await;
            }
            return Err(account_error("OAuth login", error));
        }
        let (tracking, store_lock) = self
            .tracking
            .take()
            .ok_or(AccountError::OAuthCallbackAlreadySubmitted)?;
        Session::saved(
            self.client.clone(),
            self.sessions.clone(),
            tracking,
            store_lock,
        )
        .await
    }

    /// puts back what the store held before, or deletes the store if it held nothing
    pub async fn abort(self) {
        let Self {
            client,
            sessions,
            tracking,
            state,
            previous,
            ..
        } = self;
        let Some(state) = state else {
            return;
        };
        client.oauth().abort_login(&state).await;
        drop(client);
        match previous {
            Some(previous) => put_back(sessions.as_ref(), previous).await,
            None => {
                if let Err(error) = sessions.discard().await {
                    tracing::warn!(%error, "deleting an abandoned OAuth login's store failed");
                }
            }
        }
        drop(tracking);
    }
}

async fn put_back(sessions: &dyn SessionStore, previous: SessionRecord) {
    if let Err(error) = sessions.save(&previous).await {
        tracing::warn!(%error, "putting back the record an OAuth login replaced failed");
    }
}

pub struct StoreConfig {
    location: StoreLocation,
    passphrase: String,
}

enum StoreLocation {
    #[cfg(feature = "sqlite")]
    Sqlite(PathBuf),
    #[cfg(feature = "indexeddb")]
    IndexedDb(String),
}

impl StoreConfig {
    #[cfg(feature = "sqlite")]
    #[must_use]
    pub fn sqlite(path: impl Into<PathBuf>, passphrase: impl Into<String>) -> Self {
        Self {
            location: StoreLocation::Sqlite(path.into()),
            passphrase: passphrase.into(),
        }
    }

    #[cfg(feature = "indexeddb")]
    #[must_use]
    pub fn indexeddb(name: impl Into<String>, passphrase: impl Into<String>) -> Self {
        Self {
            location: StoreLocation::IndexedDb(name.into()),
            passphrase: passphrase.into(),
        }
    }

    /// delete the store's databases, once nothing has them open
    pub async fn delete(&self) -> Result<(), AccountError> {
        match &self.location {
            #[cfg(feature = "sqlite")]
            StoreLocation::Sqlite(path) => crate::session_store::delete_sqlite_store(path)
                .map_err(|error| account_error("deleting the Matrix store", error)),
            #[cfg(feature = "indexeddb")]
            StoreLocation::IndexedDb(name) => crate::session_store::delete_indexeddb_store(name)
                .await
                .map_err(|error| error.into_account_error("deleting the Matrix store")),
        }
    }

    /// taken before the client opens the store, and held until the engine and every
    /// `ClientHandle` are gone
    pub(crate) async fn lock(&self) -> Result<StoreLock, AccountError> {
        match &self.location {
            #[cfg(feature = "sqlite")]
            StoreLocation::Sqlite(path) => StoreLock::file(path),
            #[cfg(feature = "indexeddb")]
            StoreLocation::IndexedDb(name) => StoreLock::web(name).await,
        }
    }

    pub(crate) fn passphrase(&self) -> &str {
        &self.passphrase
    }

    #[cfg(feature = "indexeddb")]
    pub(crate) fn indexeddb_name(&self) -> &str {
        let StoreLocation::IndexedDb(name) = &self.location;
        name
    }
}

/// Serializable authentication secrets. A `SessionStore` keeps it, and the engine
/// replaces it there on every token rotation.
#[derive(Clone, Deserialize, Serialize)]
pub struct SessionRecord {
    homeserver: String,
    authentication: AuthenticationRecord,
}

#[derive(Clone, Deserialize, Serialize)]
#[serde(tag = "type", content = "session", rename_all = "snake_case")]
enum AuthenticationRecord {
    Matrix(MatrixSession),
    OAuth {
        client_id: ClientId,
        user: UserSession,
    },
    SoftLoggedOut {
        meta: SessionMeta,
        client_id: Option<ClientId>,
    },
    /// an oauth login waiting on its redirect. `authorization` holds the pkce verifier
    PendingOAuth {
        client_id: ClientId,
        state: CsrfToken,
        authorization: Box<PendingAuthorization>,
        started_ms: u64,
        /// what the store held before, put back if the login never finishes
        previous: Option<Box<SessionRecord>>,
    },
}

/// authorization codes live for minutes, so a login this old was abandoned
const OAUTH_PENDING_FOR_MS: u64 = 60 * 60 * 1000;

/// the authorization server answers in the query, or the fragment when asked to
pub(crate) fn callback_state(callback: &Url) -> Option<String> {
    let query = callback.query_pairs();
    let fragment = url::form_urlencoded::parse(callback.fragment().unwrap_or_default().as_bytes());
    query
        .chain(fragment)
        .find(|(key, _)| key == "state")
        .map(|(_, state)| state.into_owned())
}

fn now_ms() -> u64 {
    MilliSecondsSinceUnixEpoch::now().get().into()
}

impl SessionRecord {
    #[must_use]
    pub fn homeserver(&self) -> &str {
        &self.homeserver
    }

    /// a pending oauth login is nobody yet, unless it resumes someone
    pub(crate) fn user_id(&self) -> Option<&OwnedUserId> {
        match &self.authentication {
            AuthenticationRecord::Matrix(session) => Some(&session.meta.user_id),
            AuthenticationRecord::OAuth { user, .. } => Some(&user.meta.user_id),
            AuthenticationRecord::SoftLoggedOut { meta, .. } => Some(&meta.user_id),
            AuthenticationRecord::PendingOAuth { previous, .. } => previous.as_ref()?.user_id(),
        }
    }

    /// what a login should resume. a pending oauth login stands in for the record before it
    pub(crate) fn resumable(self) -> Option<Self> {
        match self.authentication {
            AuthenticationRecord::PendingOAuth { previous, .. } => {
                previous.and_then(|previous| previous.resumable())
            }
            _ => Some(self),
        }
    }

    pub(crate) fn pending_oauth_state(&self) -> Option<&str> {
        match &self.authentication {
            AuthenticationRecord::PendingOAuth { state, .. } => Some(state.secret()),
            _ => None,
        }
    }

    pub(crate) fn oauth_expired(&self) -> bool {
        let AuthenticationRecord::PendingOAuth { started_ms, .. } = &self.authentication else {
            return false;
        };
        now_ms().saturating_sub(*started_ms) > OAUTH_PENDING_FOR_MS
    }

    pub(crate) fn soft_logout(&self) -> Option<SoftLogout> {
        let (meta, client_id) = match &self.authentication {
            AuthenticationRecord::SoftLoggedOut { meta, client_id } => (meta, client_id),
            AuthenticationRecord::PendingOAuth { previous, .. } => {
                return previous.as_ref()?.soft_logout();
            }
            _ => return None,
        };
        Some(SoftLogout {
            homeserver: self.homeserver.clone(),
            user_id: meta.user_id.clone(),
            device_id: meta.device_id.clone(),
            client_id: client_id
                .as_ref()
                .map(|client_id| client_id.as_str().to_owned()),
        })
    }

    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,
            pending @ AuthenticationRecord::PendingOAuth { .. } => pending,
        };
        Self {
            homeserver: self.homeserver,
            authentication,
        }
    }
}

pub enum Restore {
    Resumed(Session),
    SoftLoggedOut(SoftLogout),
    /// an oauth login is waiting on its redirect. `Session::finish_oauth` takes the callback
    OAuthPending,
}

/// 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())
            .allow_insecure_loopback(true)
    }

    #[must_use]
    pub fn oauth_login(
        &self,
        redirect_uri: impl Into<String>,
        client_uri: impl Into<String>,
        application_type: OAuthApplicationType,
    ) -> OAuthLogin {
        let login = OAuthLogin::new(
            self.homeserver.clone(),
            redirect_uri,
            client_uri,
            application_type,
        )
        .with_device_id(self.device_id.clone())
        .allow_insecure_loopback(true);
        match &self.client_id {
            Some(client_id) => login.with_client_id(client_id.clone()),
            None => login,
        }
    }
}

#[derive(Debug, Error)]
pub enum AccountError {
    #[error("{context} failed")]
    Operation {
        context: &'static str,
        kind: ErrorKind,
        server: Option<ServerError>,
        #[source]
        source: Box<SourceError>,
    },
    #[error("the homeserver returned no authenticated session")]
    MissingSession,
    #[error("the SDK returned an unsupported authentication session")]
    UnsupportedAuthentication,
    #[error("the OAuth callback was already submitted")]
    OAuthCallbackAlreadySubmitted,
    /// nothing is waiting for this callback. it was finished, abandoned, expired, or begun
    /// somewhere else
    #[error("no OAuth login is waiting for this callback")]
    NoPendingOAuth,
    /// what was typed can't name a homeserver, so nothing was sent anywhere
    #[error("that isn't a usable homeserver, {0}")]
    InvalidHomeserver(&'static str),
    /// `Accounts` already has a live login for them. a second would be another device
    #[error("{0} is already logged in")]
    AlreadyLoggedIn(OwnedUserId),
    /// an IndexedDB delete is waiting on the store's other connections. it goes through
    /// once they close, and opening the store again waits behind it
    #[error("the store is still open elsewhere, it will be deleted once that closes")]
    StoreDeletePending,
    /// another engine, in this process or another, has the store. only one runs per store
    #[error("another engine is using this store")]
    StoreInUse,
    /// the login worked but its first record didn't save. the server already has the
    /// device, so retry the save rather than log in again
    #[error("saving the new login's record failed")]
    Unsaved {
        session: Box<UnsavedSession>,
        #[source]
        source: Box<AccountError>,
    },
    #[error(transparent)]
    Engine(#[from] EngineError),
}

impl AccountError {
    /// what the homeserver said, when it refused
    #[must_use]
    pub fn server(&self) -> Option<&ServerError> {
        match self {
            Self::Operation { server, .. } => server.as_ref(),
            Self::Unsaved { source, .. } => source.server(),
            _ => None,
        }
    }
}

/// a live login whose record never reached its `SessionStore`
pub struct UnsavedSession {
    session: Session,
    sessions: Arc<dyn SessionStore>,
}

impl UnsavedSession {
    pub async fn save(self) -> Result<Session, AccountError> {
        let saved = match session_record(&self.session.client) {
            Ok(record) => self.sessions.save(&record).await,
            Err(error) => Err(error),
        };
        match saved {
            Ok(()) => Ok(self.session),
            Err(source) => Err(AccountError::Unsaved {
                session: Box::new(self),
                source: Box::new(source),
            }),
        }
    }

    /// the record to keep somewhere else, if the store won't take it
    pub fn record(&self) -> Result<SessionRecord, AccountError> {
        session_record(&self.session.client)
    }
}

impl std::fmt::Debug for UnsavedSession {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("UnsavedSession")
            .finish_non_exhaustive()
    }
}

impl Session {
    pub async fn login_password(
        login: PasswordLogin,
        sessions: Arc<dyn SessionStore>,
    ) -> Result<Self, AccountError> {
        homeserver_input(&login.homeserver, login.allow_insecure_loopback)?;
        let store_lock = sessions.store().lock().await?;
        Self::login_password_locked(login, sessions, store_lock).await
    }

    pub(crate) async fn login_password_locked(
        login: PasswordLogin,
        sessions: Arc<dyn SessionStore>,
        store_lock: StoreLock,
    ) -> Result<Self, AccountError> {
        let homeserver = homeserver_input(&login.homeserver, login.allow_insecure_loopback)?;
        let client = matrix_client_builder(sessions.store())
            .server_name_or_homeserver_url(homeserver)
            .build()
            .await
            .map_err(|error| account_error("building the Matrix client", error))?;
        let tracking = Tracking::start(&client, sessions.clone())?;
        let mut request = client
            .matrix_auth()
            .login_username(login.username.trim(), &login.password)
            .request_refresh_token();
        if let Some(name) = login.device_display_name.as_deref() {
            request = request.initial_device_display_name(name);
        }
        if let Some(device_id) = login.device_id.as_deref() {
            request = request.device_id(device_id.as_str());
        }
        request
            .send()
            .await
            .map_err(|error| account_error("password login", error))?;
        Self::saved(client, sessions, tracking, store_lock).await
    }

    /// the pending login lives only in this process, so the one that begins it has to finish it
    pub async fn begin_oauth(
        login: OAuthLogin,
        sessions: Arc<dyn SessionStore>,
    ) -> Result<PendingOAuthLogin, AccountError> {
        homeserver_input(&login.homeserver, login.allow_insecure_loopback)?;
        let store_lock = sessions.store().lock().await?;
        Self::begin_oauth_locked(login, sessions, store_lock).await
    }

    pub(crate) async fn begin_oauth_locked(
        login: OAuthLogin,
        sessions: Arc<dyn SessionStore>,
        store_lock: StoreLock,
    ) -> Result<PendingOAuthLogin, AccountError> {
        let redirect_uri = Url::parse(login.redirect_uri.trim())
            .map_err(|error| account_error("parsing the OAuth redirect URI", error))?;
        let client_uri = Url::parse(login.client_uri.trim())
            .map_err(|error| account_error("parsing the OAuth client URI", error))?;
        let homeserver = homeserver_input(&login.homeserver, login.allow_insecure_loopback)?;
        let client = matrix_client_builder(sessions.store())
            .server_name_or_homeserver_url(homeserver)
            .build()
            .await
            .map_err(|error| account_error("building the Matrix client", error))?;
        let tracking = Tracking::start(&client, sessions.clone())?;
        let application_type = match login.application_type {
            OAuthApplicationType::Native => ApplicationType::Native,
            OAuthApplicationType::Web => ApplicationType::Web,
        };
        let mut metadata = ClientMetadata::new(
            application_type,
            vec![OAuthGrantType::AuthorizationCode {
                redirect_uris: vec![redirect_uri.clone()],
            }],
            Localized::new(client_uri, []),
        );
        metadata.client_name = login.client_name.map(|name| Localized::new(name, []));
        let metadata = Raw::new(&metadata)
            .map_err(|error| account_error("serializing OAuth client metadata", error))?;
        let mut registration = ClientRegistrationData::new(metadata);
        if let Some(client_id) = login.client_id {
            registration.static_registrations = Some(HashMap::from([(
                client.homeserver(),
                ClientId::new(client_id),
            )]));
        }
        let authorization = client
            .oauth()
            .login(redirect_uri, login.device_id, Some(registration), None)
            .build()
            .await
            .map_err(|error| account_error("starting OAuth login", error))?;
        let previous = sessions.load().await?.and_then(SessionRecord::resumable);
        let pending = SessionRecord {
            homeserver: client.homeserver().to_string(),
            authentication: AuthenticationRecord::PendingOAuth {
                client_id: client
                    .oauth()
                    .client_id()
                    .ok_or(AccountError::MissingSession)?
                    .clone(),
                state: authorization.state.clone(),
                authorization: Box::new(
                    client
                        .oauth()
                        .pending_authorization(&authorization.state)
                        .await
                        .ok_or(AccountError::MissingSession)?,
                ),
                started_ms: now_ms(),
                previous: previous.clone().map(Box::new),
            },
        };
        sessions.save(&pending).await?;
        Ok(PendingOAuthLogin {
            client,
            sessions,
            tracking: Some((tracking, store_lock)),
            authorization_url: authorization.url.to_string(),
            state: Some(authorization.state),
            previous,
        })
    }

    /// finishes a login `begin_oauth` started in another process, from the callback the
    /// redirect brought back. the pending login is in `sessions`, so nothing else is needed
    pub async fn finish_oauth(
        sessions: Arc<dyn SessionStore>,
        callback_url: &str,
    ) -> Result<Self, AccountError> {
        let store_lock = sessions.store().lock().await?;
        Self::finish_oauth_locked(sessions, store_lock, callback_url).await
    }

    pub(crate) async fn finish_oauth_locked(
        sessions: Arc<dyn SessionStore>,
        store_lock: StoreLock,
        callback_url: &str,
    ) -> Result<Self, AccountError> {
        let callback = Url::parse(callback_url)
            .map_err(|error| account_error("parsing the OAuth callback URL", error))?;
        let record = sessions.load().await?.ok_or(AccountError::NoPendingOAuth)?;
        if record.pending_oauth_state() != callback_state(&callback).as_deref() {
            return Err(AccountError::NoPendingOAuth);
        }
        let AuthenticationRecord::PendingOAuth {
            client_id,
            state,
            authorization,
            previous,
            ..
        } = record.authentication
        else {
            return Err(AccountError::NoPendingOAuth);
        };
        let client = matrix_client_builder(sessions.store())
            .homeserver_url(&record.homeserver)
            .build()
            .await
            .map_err(|error| account_error("reopening the Matrix store", error))?;
        let tracking = Tracking::start(&client, sessions.clone())?;
        let oauth = client.oauth();
        oauth.restore_registered_client(client_id);
        let finished = match oauth
            .restore_pending_authorization(state, *authorization)
            .await
        {
            Ok(()) => oauth.finish_login(callback.into()).await,
            Err(error) => Err(error.into()),
        };
        if let Err(error) = finished {
            match previous {
                Some(previous) => put_back(sessions.as_ref(), *previous).await,
                None => {
                    drop((tracking, client));
                    if let Err(error) = sessions.discard().await {
                        tracing::warn!(%error, "deleting a failed OAuth login's store failed");
                    }
                }
            }
            return Err(account_error("OAuth login", error));
        }
        Self::saved(client, sessions, tracking, store_lock).await
    }

    /// Restore the record `sessions` holds, or `None` when it holds none.
    /// The caller must also handle rejection and explicit logout.
    pub async fn restore(sessions: Arc<dyn SessionStore>) -> Result<Option<Restore>, AccountError> {
        let Some(record) = sessions.load().await? else {
            return Ok(None);
        };
        let authentication = match record.authentication {
            AuthenticationRecord::Matrix(session) => AuthSession::Matrix(session),
            AuthenticationRecord::OAuth { client_id, user } => {
                OAuthSession { client_id, user }.into()
            }
            AuthenticationRecord::PendingOAuth { .. } if record.oauth_expired() => {
                let previous = record.resumable();
                match previous {
                    Some(previous) => put_back(sessions.as_ref(), previous).await,
                    None => sessions.discard().await?,
                }
                return Box::pin(Self::restore(sessions)).await;
            }
            AuthenticationRecord::PendingOAuth { .. } => return Ok(Some(Restore::OAuthPending)),
            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 store_lock = sessions.store().lock().await?;
        let client = matrix_client_builder(sessions.store())
            .homeserver_url(&record.homeserver)
            .build()
            .await
            .map_err(|error| account_error("reopening the Matrix store", error))?;
        let tracking = Tracking::start(&client, sessions)?;
        client
            .restore_session(authentication)
            .await
            .map_err(|error| account_error("restoring the authenticated session", error))?;
        Ok(Some(Restore::Resumed(Self {
            client,
            tracking,
            store_lock,
        })))
    }

    /// leave the record to the host, which then saves `ClientHandle::session_record()`
    /// on every `SessionTokensChanged`
    #[must_use]
    pub fn without_persistence(mut self) -> Self {
        self.tracking.persistence = None;
        #[cfg(not(target_family = "wasm"))]
        self.tracking.inline.store(false, Ordering::Release);
        self
    }

    pub async fn build(
        self,
        config: EngineConfig,
    ) -> Result<(Engine, ClientHandle, EventStream), AccountError> {
        Engine::with_persistence(
            self.client,
            config,
            self.tracking.session_changes,
            self.tracking.persistence,
            Some(self.store_lock),
        )
        .await
        .map_err(AccountError::from)
    }

    async fn saved(
        client: Client,
        sessions: Arc<dyn SessionStore>,
        tracking: Tracking,
        store_lock: StoreLock,
    ) -> Result<Self, AccountError> {
        UnsavedSession {
            session: Self {
                client,
                tracking,
                store_lock,
            },
            sessions,
        }
        .save()
        .await
    }
}

impl Tracking {
    fn start(client: &Client, sessions: Arc<dyn SessionStore>) -> Result<Self, AccountError> {
        let session_changes = client.subscribe_to_session_changes();
        #[cfg_attr(target_family = "wasm", allow(unused_variables))]
        let (results, inline_results) = mpsc::unbounded_channel();
        #[cfg(not(target_family = "wasm"))]
        let inline = save_inline(client, sessions.clone(), results)?;
        Ok(Self {
            session_changes,
            persistence: Some(Persistence {
                save: Box::new(move |client| {
                    let sessions = sessions.clone();
                    Box::pin(async move {
                        let record = session_record(&client).map_err(save_failed)?;
                        sessions.save(&record).await.map_err(save_failed)
                    })
                }),
                inline: inline_results,
            }),
            #[cfg(not(target_family = "wasm"))]
            inline,
        })
    }
}

/// the sdk calls this inside its refresh, after it has the new tokens and before it uses
/// them, so a store that writes there and then can't lose a refresh token to a crash
#[cfg(not(target_family = "wasm"))]
fn save_inline(
    client: &Client,
    sessions: Arc<dyn SessionStore>,
    results: mpsc::UnboundedSender<Result<(), crate::Error>>,
) -> Result<Arc<AtomicBool>, AccountError> {
    let enabled = Arc::new(AtomicBool::new(true));
    let saving = enabled.clone();
    client
        .set_session_callbacks(
            // only asked for with the cross process refresh lock, which we never enable
            Box::new(|client| {
                client
                    .session_tokens()
                    .ok_or_else(|| AccountError::MissingSession.into())
            }),
            Box::new(move |client| {
                if !saving.load(Ordering::Acquire) {
                    return Ok(());
                }
                let record = session_record(&client)?;
                if let Some(result) = sessions.save_blocking(&record) {
                    let _ = results.send(result.map_err(save_failed));
                }
                Ok(())
            }),
        )
        .map_err(|error| account_error("registering the session callbacks", error))?;
    Ok(enabled)
}

fn save_failed(error: AccountError) -> crate::Error {
    let message = format!("saving the session record failed, {error}");
    crate::Error::with_source(ErrorKind::Store, message, error)
}

pub(crate) fn session_record(client: &Client) -> Result<SessionRecord, AccountError> {
    let authentication = match client.session().ok_or(AccountError::MissingSession)? {
        AuthSession::Matrix(session) => AuthenticationRecord::Matrix(session),
        AuthSession::OAuth(session) => {
            let OAuthSession { client_id, user } = *session;
            AuthenticationRecord::OAuth { client_id, user }
        }
        _ => return Err(AccountError::UnsupportedAuthentication),
    };
    Ok(SessionRecord {
        homeserver: client.homeserver().to_string(),
        authentication,
    })
}

fn encryption_settings() -> EncryptionSettings {
    EncryptionSettings {
        auto_enable_cross_signing: true,
        backup_download_strategy: BackupDownloadStrategy::OneShot,
        auto_enable_backups: true,
    }
}

/// `StoreLock` already keeps every other client off the store, and the sdk's lease would cost
/// a store write per locked section and a task renewing it every 50ms
fn matrix_client_builder(store: &StoreConfig) -> ClientBuilder {
    let builder = Client::builder()
        .with_encryption_settings(encryption_settings())
        .with_threading_support(ThreadingSupport::Enabled {
            with_subscriptions: false,
        })
        .handle_refresh_tokens()
        .cross_process_store_config(CrossProcessLockConfig::SingleProcess);
    match &store.location {
        #[cfg(feature = "sqlite")]
        StoreLocation::Sqlite(path) => builder.sqlite_store(path, Some(&store.passphrase)),
        #[cfg(feature = "indexeddb")]
        StoreLocation::IndexedDb(name) => builder.indexeddb_store(name, Some(&store.passphrase)),
    }
}

/// a bare server name goes through untouched, since that's what makes the sdk try `.well-known`
pub(crate) fn homeserver_input(
    input: &str,
    allow_insecure_loopback: bool,
) -> Result<&str, AccountError> {
    let input = input.trim();
    let invalid = |reason| Err(AccountError::InvalidHomeserver(reason));
    if input.is_empty() {
        return invalid("it's empty");
    }
    if input.contains(char::is_whitespace) {
        return invalid("it has spaces in it");
    }
    if !input.contains("://") {
        return match <&ruma::ServerName>::try_from(input) {
            Ok(_) => Ok(input),
            Err(_) => invalid("it's neither a server name nor a url"),
        };
    }
    let Ok(url) = Url::parse(input) else {
        return invalid("it isn't a valid url");
    };
    if !url.username().is_empty() || url.password().is_some() {
        return invalid("it has a username in it");
    }
    let loopback = match url.host() {
        None => return invalid("it has no host"),
        Some(url::Host::Domain(domain)) => domain.eq_ignore_ascii_case("localhost"),
        Some(url::Host::Ipv4(address)) => address.is_loopback(),
        Some(url::Host::Ipv6(address)) => address.is_loopback(),
    };
    match url.scheme() {
        "https" => Ok(input),
        "http" if allow_insecure_loopback && loopback => Ok(input),
        "http" if allow_insecure_loopback => invalid("plain http only reaches loopback hosts"),
        "http" => invalid("it isn't https"),
        _ => invalid("only http and https are spoken"),
    }
}

pub(crate) fn account_error(
    context: &'static str,
    source: impl std::error::Error + SendOutsideWasm + SyncOutsideWasm + 'static,
) -> AccountError {
    AccountError::Operation {
        context,
        kind: crate::error::classify(&source),
        server: ServerError::find(&source),
        source: Box::new(source),
    }
}