macltok

public

Star0

Fork 0

Watch0

7 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `62fe32759529`

tarball

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

11 files changed+119-33

build: add a wasm32 target with an indexeddb store

The store is picked by an explicit sqlite or indexeddb feature rather than by target, and naming one on the wrong target is a compile_error, so a native build can never quietly end up with a browser store. js comes along with any wasm build, which keeps a storeless wasm build working for callers who bring their own client. StoreConfig takes a lock holder because the sdk calls every client main, and two tabs sharing that name on one IndexedDB store would both believe they hold the crypto store lock.

Added file: .cargo/config.toml+2

@@ -0,0 +1,2 @@

1+[target.wasm32-unknown-unknown]

2+rustflags = ["--cfg", "getrandom_backend=\"wasm_js\""]

Modified file: Cargo.lock+8 additions@@ -1150,9 +1150,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
  "cfg-if",
+ "js-sys",
  "libc",
  "r-efi 5.3.0",
  "wasip2",
+ "wasm-bindgen",
 ]
 
 [[package]]
@@ -1821,12 +1823,16 @@ name = "macltok"
 version = "0.1.0"
 dependencies = [
  "futures-util",
+ "getrandom 0.2.17",
+ "getrandom 0.3.4",
+ "getrandom 0.4.3",
  "http",
  "matrix-sdk",
  "matrix-sdk-crypto",
  "matrix-sdk-test",
  "matrix-sdk-ui",
  "mime",
+ "reqwest",
  "ruma",
  "serde",
  "serde_json",
@@ -1835,6 +1841,7 @@ dependencies = [
  "tokio",
  "tracing",
  "url",
+ "uuid",
  "wiremock",
 ]
 
@@ -2154,6 +2161,7 @@ dependencies = [
  "futures-util",
  "getrandom 0.4.3",
  "gloo-utils",
+ "growable-bloom-filter",
  "hkdf",
  "js-sys",
  "matrix-sdk-base",

Modified file: Cargo.toml+11 additions@@ -9,6 +9,7 @@ default = []
 serde = ["dep:serde"]
 sqlite = ["matrix-sdk/sqlite", "serde", "dep:url"]
 bundled-sqlite = ["sqlite", "matrix-sdk/bundled-sqlite"]
+indexeddb = ["matrix-sdk/indexeddb", "serde", "dep:url"]
 
 [dependencies]
 futures-util = { version = "0.3.31", default-features = false, features = ["std"] }
@@ -25,6 +26,16 @@ tokio = { version = "1.47.1", features = ["macros", "sync"] }
 tracing = "0.1.41"
 url = { version = "2.5.7", optional = true }
 
+[target.'cfg(target_family = "wasm")'.dependencies]
+getrandom = { version = "0.2", features = ["js"] }
+getrandom3 = { package = "getrandom", version = "0.3", features = ["wasm_js"] }
+getrandom4 = { package = "getrandom", version = "0.4", features = ["wasm_js"] }
+matrix-sdk = { version = "0.18.0", default-features = false, features = ["js"] }
+matrix-sdk-ui = { version = "0.18.0", default-features = false, features = ["js"] }
+# the sdk's own wasm reqwest leaves out stream, which the bounded media download needs
+reqwest = { version = "0.13.1", default-features = false, features = ["stream"] }
+uuid = { version = "1", features = ["js"] }
+
 [dev-dependencies]
 matrix-sdk = { version = "0.18.0", default-features = false, features = ["testing"] }
 matrix-sdk-test = "0.18.0"

Modified file: README.md+34 additions−5 deletions@@ -13,7 +13,8 @@ The crate currently provides
 - text, emote, reply, edit, redaction, reaction, receipt and typing operations
 - raw encrypted or unencrypted media acquisition with configurable byte limits
 - encryption state, recovery-key import and SAS verification
-- password login and session restoration with caller-owned encrypted SQLite stores
+- password login and session restoration with caller-owned encrypted SQLite or
+  IndexedDB stores
 
 Matrix room, event, user, device and transaction identifiers remain strongly
 typed. A toolkit timeline identity covers local echoes without pretending they
@@ -32,10 +33,10 @@ start a timeline from `TimelineReset`, then apply `TimelineChanged` diffs with
 `TimelineDiff::try_apply`. when one doesn't fit, stop applying, call `resync`,
 and pick up from the next `TimelineReset`
 
-With `sqlite`, persist the initial `Session::record()` separately from its
-encrypted SQLite store. On `SessionTokensChanged`, obtain a new record from
+With `sqlite` or `indexeddb`, persist the initial `Session::record()`
+separately from its encrypted store. On `SessionTokensChanged`, obtain a new record from
 `ClientHandle::session_record()` and replace the saved record atomically in
-protected storage. Restore with the same store path and passphrase.
+protected storage. Restore with the same store location and passphrase.
 
 `LoggedOut` and `SessionAccessRejected` both stop the engine. after a logout or a
 hard rejection the record and the store are dead, bin them. a soft logout wants
@@ -45,11 +46,39 @@ store directory per login, the sdk won't share a crypto store between devices.
 The headless example is
 login-only; it does not persist sessions across runs.
 
+## wasm
+
+macltok builds for `wasm32-unknown-unknown`. the `indexeddb` feature gives you
+`StoreConfig::indexeddb` in place of `StoreConfig::sqlite`, and asking for either
+on the wrong target won't compile. `Engine::run` hands back a `LocalBoxFuture`
+there, so spawn it with `wasm_bindgen_futures::spawn_local`
+
+getrandom picks its browser backend from a cfg flag, and `.cargo/config.toml`
+only reaches this crate's own builds. every cdylib that pulls macltok in needs
+it too
+
+```toml
+[target.wasm32-unknown-unknown]
+rustflags = ["--cfg", "getrandom_backend=\"wasm_js\""]
+```
+
+what's different in a browser
+
+- a panic aborts the whole instance. natively a panicking command costs its
+  caller an `Interrupted`, here it takes the engine and everything else with it
+- `MediaUploadProgress` only ever reports completion, the sdk's wasm http path
+  has no upload progress
+- the sdk doesn't retry requests or time them out individually. sync still
+  restarts itself with backoff, that part is ours
+- two tabs or workers on one store each need `StoreConfig::with_lock_holder`
+  with a name of their own, or they both think they hold the crypto store
+
 ## Dependency policy
 
 UI frameworks, image decoders, application-directory discovery and logging
 subscribers do not belong in this crate. SQLite remains optional through the
-`sqlite` and `bundled-sqlite` features. Media decoding belongs to the consumer.
+`sqlite` and `bundled-sqlite` features, IndexedDB through `indexeddb`. Media
+decoding belongs to the consumer.
 
 ## Verification
 

Modified file: docs/design-decisions.md+4 additions−3 deletions@@ -30,7 +30,8 @@ doing the work died before it could answer. `challenge` turns up with
 the run loop routes and does nothing slow. every task it spawns is registered
 with a context. a command task that panics costs its caller an `Interrupted`
 and gets logged. a watcher or a room actor that panics takes the engine down,
-emitting `Failed` then `Stopped`
+emitting `Failed` then `Stopped`. natively, anyway. wasm aborts the whole
+instance on any panic and nothing is left to log it
 
 sync restarts itself with backoff after an error or an unexpected stop, and
 `ConnectionChanged` shows `Offline` meanwhile. a run that drops again inside
@@ -141,8 +142,8 @@ watcher there reports them
 ## sessions and secrets
 
 `Session::login_password`, `begin_oauth` and `restore` share one client builder
-with encrypted sqlite, refresh tokens and threads. secret-bearing inputs don't
-derive `Clone`
+with an encrypted store, refresh tokens and threads. the store is sqlite
+natively and indexeddb in a browser. secret-bearing inputs don't derive `Clone`
 
 the caller owns the saved record. save `Session::record()` after login and
 replace it atomically with `ClientHandle::session_record()` on every

Modified file: examples/headless.rs+1−1

@@ -9,7 +9,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {

99 let passphrase = required("MATRIX_STORE_PASSPHRASE")?;

1010 // a real client keeps this somewhere safer, it holds the access token

1111 let record_path = store_path.join("session.json");

12- let store = StoreConfig::new(&store_path, &passphrase);

12+ let store = StoreConfig::sqlite(&store_path, &passphrase);

1313 let session = match std::fs::read(&record_path) {

1414 Ok(saved) => Session::restore(serde_json::from_slice(&saved)?, store).await?,

1515 Err(_) => {

Modified file: src/account.rs+47 additions−17 deletions@@ -1,10 +1,9 @@
-use std::{
-    collections::HashMap,
-    path::{Path, PathBuf},
-};
+use std::collections::HashMap;
+#[cfg(feature = "sqlite")]
+use std::path::PathBuf;
 
 use matrix_sdk::{
-    Client, ClientBuilder, ThreadingSupport,
+    Client, ClientBuilder, SendOutsideWasm, SyncOutsideWasm, ThreadingSupport,
     authentication::{
         AuthSession,
         matrix::MatrixSession,
@@ -13,6 +12,7 @@ use matrix_sdk::{
             registration::{ApplicationType, ClientMetadata, Localized, OAuthGrantType},
         },
     },
+    cross_process_lock::CrossProcessLockConfig,
     encryption::{BackupDownloadStrategy, EncryptionSettings},
     ruma::{OwnedDeviceId, serde::Raw},
 };
@@ -20,7 +20,7 @@ use serde::{Deserialize, Serialize};
 use thiserror::Error;
 use url::Url;
 
-use crate::{ClientHandle, Engine, EngineConfig, EngineError, EventStream};
+use crate::{ClientHandle, Engine, EngineConfig, EngineError, EventStream, error::SourceError};
 
 pub struct Session {
     client: Client,
@@ -173,27 +173,49 @@ impl PendingOAuthLogin {
 }
 
 pub struct StoreConfig {
-    path: PathBuf,
+    location: StoreLocation,
     passphrase: String,
+    lock_holder: Option<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(),
+            lock_holder: None,
+        }
+    }
+
+    #[cfg(feature = "indexeddb")]
     #[must_use]
-    pub fn new(path: impl Into<PathBuf>, passphrase: impl Into<String>) -> Self {
+    pub fn indexeddb(name: impl Into<String>, passphrase: impl Into<String>) -> Self {
         Self {
-            path: path.into(),
+            location: StoreLocation::IndexedDb(name.into()),
             passphrase: passphrase.into(),
+            lock_holder: None,
         }
     }
 
+    /// the sdk names every client `main`, so two tabs on one store would both think they hold its lock
     #[must_use]
-    pub fn path(&self) -> &Path {
-        &self.path
+    pub fn with_lock_holder(mut self, holder: impl Into<String>) -> Self {
+        self.lock_holder = Some(holder.into());
+        self
     }
 }
 
 /// Serializable authentication secrets. Store this separately from the
-/// encrypted SQLite store in protected, preferably encrypted storage.
+/// encrypted store in protected, preferably encrypted storage.
 /// A saved record must be replaced when `Event::SessionTokensChanged` arrives.
 #[derive(Clone, Deserialize, Serialize)]
 pub struct SessionRecord {
@@ -224,7 +246,7 @@ pub enum AccountError {
     Operation {
         context: &'static str,
         #[source]
-        source: Box<dyn std::error::Error + Send + Sync>,
+        source: Box<SourceError>,
     },
     #[error("the homeserver returned no authenticated session")]
     MissingSession,
@@ -377,18 +399,26 @@ fn encryption_settings() -> EncryptionSettings {
 }
 
 fn matrix_client_builder(store: &StoreConfig) -> ClientBuilder {
-    Client::builder()
+    let mut builder = Client::builder()
         .with_encryption_settings(encryption_settings())
         .with_threading_support(ThreadingSupport::Enabled {
             with_subscriptions: false,
         })
-        .handle_refresh_tokens()
-        .sqlite_store(&store.path, Some(&store.passphrase))
+        .handle_refresh_tokens();
+    if let Some(holder) = &store.lock_holder {
+        builder = builder.cross_process_store_config(CrossProcessLockConfig::multi_process(holder));
+    }
+    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)),
+    }
 }
 
 fn account_error(
     context: &'static str,
-    source: impl std::error::Error + Send + Sync + 'static,
+    source: impl std::error::Error + SendOutsideWasm + SyncOutsideWasm + 'static,
 ) -> AccountError {
     AccountError::Operation {
         context,

Modified file: src/error.rs+2 additions−2 deletions@@ -19,9 +19,9 @@ use crate::InteractiveAuthChallenge;
 
 /// the sdk's `SendOutsideWasm` isn't an auto trait, so it can't go in a trait object
 #[cfg(not(target_family = "wasm"))]
-type SourceError = dyn std::error::Error + Send + Sync;
+pub(crate) type SourceError = dyn std::error::Error + Send + Sync;
 #[cfg(target_family = "wasm")]
-type SourceError = dyn std::error::Error;
+pub(crate) type SourceError = dyn std::error::Error;
 
 /// the one thing that goes wrong, for commands and queries alike. match on `kind`, show `message`
 #[derive(Clone, Debug, thiserror::Error)]

Modified file: src/lib.rs+7 additions−2 deletions@@ -9,10 +9,15 @@ mod transport;
 mod uiaa;
 mod upload;
 
-#[cfg(feature = "sqlite")]
+#[cfg(all(feature = "sqlite", target_family = "wasm"))]
+compile_error!("sqlite has no filesystem to live on in wasm, use indexeddb");
+#[cfg(all(feature = "indexeddb", not(target_family = "wasm")))]
+compile_error!("indexeddb only exists in a browser, use sqlite");
+
+#[cfg(any(feature = "sqlite", feature = "indexeddb"))]
 mod account;
 
-#[cfg(feature = "sqlite")]
+#[cfg(any(feature = "sqlite", feature = "indexeddb"))]
 pub use account::{
     AccountError, OAuthApplicationType, OAuthLogin, PasswordLogin, PendingOAuthLogin, Session,
     SessionRecord, StoreConfig,

Modified file: src/transport.rs+1−1

@@ -76,7 +76,7 @@ impl Future for Pending {

7676

7777 impl ClientHandle {

7878 /// current credentials. persist this atomically on `Event::SessionTokensChanged`, it holds secrets

79- #[cfg(feature = "sqlite")]

79+ #[cfg(any(feature = "sqlite", feature = "indexeddb"))]

8080 pub fn session_record(&self) -> Result<crate::SessionRecord, crate::AccountError> {

8181 crate::account::session_record(&self.client)

8282 }

Modified file: tests/account.rs+2 additions−2 deletions@@ -27,7 +27,7 @@ async fn password_session_round_trips_through_an_encrypted_store() {
     let session = Session::login_password(
         PasswordLogin::new(server.uri(), "example", "wordpass")
             .with_device_display_name("macltok test"),
-        StoreConfig::new(&store_path, "test store passphrase"),
+        StoreConfig::sqlite(&store_path, "test store passphrase"),
     )
     .await
     .unwrap();
@@ -48,7 +48,7 @@ async fn password_session_round_trips_through_an_encrypted_store() {
 
     let session = Session::restore(
         record,
-        StoreConfig::new(&store_path, "test store passphrase"),
+        StoreConfig::sqlite(&store_path, "test store passphrase"),
     )
     .await
     .unwrap();

macltok

Commit 62fe32759529

Commit `62fe32759529`