No description
  • Rust 62.1%
  • TypeScript 23.2%
  • JavaScript 14.5%
  • Shell 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Richard van der Hoff b75b321a4d
Merge pull request #372 from matrix-org/rav/pnpm_12
Update to pnpm 12
2026-11-13 10:49:30 +00:00
.cargo Fix nightly sdk compatibility build, again (#242) 2025-06-20 15:47:31 +01:00
.github Support older release branches in the release workflow (#370) 2026-11-10 17:33:10 +00:00
scripts Stop deleting build results during rebuilds (#175) 2024-12-05 16:47:22 +00:00
src Update rust-sdk to 0c235703 2026-11-11 14:13:09 +00:00
tests Update rust-sdk to 12f7c8353 2026-09-30 13:05:55 +01:00
xtask chore: Reformat with nightly rustfmt 2026-09-02 14:13:50 +02:00
.eslintrc.cjs Fix splitbrain between .js being ESM & CJS inconsistently (#189) 2025-01-13 13:09:55 +00:00
.gitignore Harden CI with pinned action versions and Zizmor (#303) 2026-03-10 17:45:42 +00:00
.prettierignore chore: Add pnpm-workspace.yaml to .prettierignore 2026-03-12 11:26:56 +00:00
.prettierrc.cjs Publish a dual CJS/ESM package with platform-specific loaders (#167) 2024-12-02 20:31:23 +00:00
.rustfmt.toml Import rustfmt configuration from matrix-rust-sdk 2023-07-13 13:09:40 +02:00
babel.config.cjs Fix splitbrain between .js being ESM & CJS inconsistently (#189) 2025-01-13 13:09:55 +00:00
build.rs Fix building outside of a git worktree 2026-10-11 10:02:47 +02:00
Cargo.lock Update rust-sdk to 0c235703 2026-11-11 14:13:09 +00:00
Cargo.toml Update rust-sdk to 8a6fb702c2 2026-09-29 14:51:28 +01:00
CHANGELOG.md Update rust-sdk to 0c235703 2026-11-11 14:13:09 +00:00
CONTRIBUTING.md Add a Developer Certificate of Origin (DCO) statement 2024-07-26 10:36:17 +01:00
index-wasm-esm.mjs Add another entrypoint using wasm-as-esm support (#178) 2024-12-11 12:57:59 +00:00
index.cjs Fix: initAsync param can be string or URL 2025-05-16 09:55:02 -03:00
index.d.ts Improve type declarations (#305) 2026-03-11 11:22:45 +00:00
index.mjs Fix: initAsync param can be string or URL 2025-05-16 09:55:02 -03:00
LICENSE Add license file 2023-07-13 13:09:40 +02:00
node.cjs Fix splitbrain between .js being ESM & CJS inconsistently (#189) 2025-01-13 13:09:55 +00:00
node.mjs Use asynchronous wasm instantiation methods where possible (#174) 2024-12-10 17:29:16 +00:00
package.json Update to pnpm 12 2026-11-10 21:48:01 +00:00
pnpm-lock.yaml Update to pnpm 12 2026-11-10 21:48:01 +00:00
pnpm-workspace.yaml Update pnpm-workspace to use pnpm12 settings 2026-11-12 17:26:56 +00:00
README.md Mention the HPKE support in the readme 2026-09-23 13:58:26 +02:00
RELEASING.md docs: Update RELEASING.md to document correct pnpm usage (#308) 2026-03-11 14:35:33 +00:00
tsconfig.json fix: Set noEmit to true in tsconfig 2026-03-06 10:57:56 +00:00

matrix-sdk-crypto-wasm

Welcome to the WebAssembly + JavaScript binding for the Rust matrix-sdk-crypto library! WebAssembly can run anywhere, but these bindings are designed to run on a JavaScript host. These bindings are part of the matrix-rust-sdk project, which is a library implementation of a Matrix client-server.

matrix-sdk-crypto is a no-network-IO implementation of a state machine, named OlmMachine, that handles E2EE (End-to-End Encryption) for Matrix clients.

Usage

  1. Install in your project:

    npm install --save @matrix-org/matrix-sdk-crypto-wasm
    

    or:

    pnpm add @matrix-org/matrix-sdk-crypto-wasm
    
  2. Import the library into your project and initialise it.

    On Web platforms, the library must be initialised by calling initAsync before it can be used, else it will throw an error. This is also recommended on other platforms, as it allows the WebAssembly module to be loaded asynchronously.

    import { initAsync, Tracing, LoggerLevel, OlmMachine, UserId, DeviceId } from "@matrix-org/matrix-sdk-crypto-wasm";
    
    async function loadCrypto(userId, deviceId) {
        // Do this before any other calls to the library
        await initAsync();
    
        // Optional: enable tracing in the rust-sdk
        new Tracing(LoggerLevel.Trace).turnOn();
    
        // Create a new OlmMachine
        //
        // The following will use an in-memory store. It is recommended to use
        // indexedDB where that is available.
        // See https://matrix-org.github.io/matrix-sdk-crypto-wasm/classes/OlmMachine.html#initialize
        const olmMachine = await OlmMachine.initialize(new UserId(userId), new DeviceId(deviceId));
    
        return olmMachine;
    }
    

    See the API documentation for more information.

  3. Build your project.

    The packaging of this library aims to "just work" the same as any plain-javascript project would: it includes separate entry points for Node.js-like environments (which read the WASM file via fs.readFile()) and web-like environments (which download the WASM file with fetch()). There are both CommonJS and ES Module entry points for each environment; an appropriate entrypoint should be selected automatically.

    If your environment supports the experimental ES Module Integration Proposal for WebAssembly, you can instead use that, by setting the matrix-org:wasm-esm custom export condition. This is only supported when the library is imported as an ES Module. For example:

HPKE support

The library exposes bindings for HPKE (Hybrid Public Key Encryption), which can be used to implement MSC4388.

The following HPKE related classes are available:

See the API documentation for details and examples.

Building matrix-sdk-crypto-wasm

These WebAssembly bindings are written in Rust. To build them, you need to install the Rust compiler, see the Install Rust Page. Then, the workflow is pretty classical by using pnpm, see the Downloading and installing Node.js and npm Page and installing pnpm.

Once the Rust compiler, Node.js and pnpm are installed, you can run the following commands:

$ pnpm install
$ pnpm build  # or 'pnpm build:dev' to make an unoptimised build
$ pnpm test

The compiled output should be generated in the pkg/ directory.

Local development with matrix-rust-sdk

To build based on a local matrix-rust-sdk, add something like this to your .cargo/config file:

[patch.'https://github.com/matrix-org/matrix-rust-sdk']
matrix-sdk-base = { path = "../matrix-rust-sdk/crates/matrix-sdk-base" }
matrix-sdk-common = { path = "../matrix-rust-sdk/crates/matrix-sdk-common" }
matrix-sdk-crypto = { path = "../matrix-rust-sdk/crates/matrix-sdk-crypto" }
matrix-sdk-indexeddb = { path = "../matrix-rust-sdk/crates/matrix-sdk-indexeddb" }
matrix-sdk-qrcode = { path = "../matrix-rust-sdk/crates/matrix-sdk-qrcode" }

Documentation

The documentation can be found online.

To generate the documentation locally, please run the following command:

$ pnpm doc

The documentation is generated in the ./docs directory.

Contributing

Thank you! See the contributing doc for more info.