matrix-sdk-crypto-nodejs

Welcome to the Node.js binding for the Rust matrix-sdk-crypto library! This binding is part of the matrix-rust-sdk project, which is a library implementation of a Matrix client-server.

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

Usage

Just add the latest release to your package.json:

$ npm install --save @matrix-org/matrix-sdk-crypto-nodejs

When installing, NPM will download the corresponding prebuilt Rust library for your current host system. The following are supported:

Platform	Architecture	Triple	Prebuilt available
Linux	aarch	aarch64-unknown-linux-gnu	✅
		arm-unknown-linux-gnueabihf	✅
	amd	x86_64-unknown-linux-gnu	✅
		x86_64-unknown-linux-musl	✅
		i686-unknown-linux-gnu	✅
	s390x	s390x-unknown-linux-gnu	✅
riscv64	riscv64gc-unknown-linux-gnu	✅
macOS	aarch	arch64-apple-darwin	✅
	amd	x86_64-apple-darwin	✅
Windows	aarch	aarch64-pc-windows-msvc	✅
	amd	x86_64-pc-windows-msvc	✅
		i686-pc-windows-msvc	✅

Custom downloads base URL

By default, prebuilt binaries are downloaded from https://github.com/matrix-org/matrix-rust-sdk-crypto-nodejs/releases/download. If you need to fetch them from a mirror or a private host (for example, in a corporate network or a region with restricted access to GitHub), set the MATRIX_SDK_CRYPTO_DOWNLOADS_BASE_URL environment variable before running npm install:

$ export MATRIX_SDK_CRYPTO_DOWNLOADS_BASE_URL="https://npmmirror.com/mirrors/@matrix-org/matrix-sdk-crypto-nodejs"
$ npm install --save @matrix-org/matrix-sdk-crypto-nodejs

The downloader appends /v<version>/<filename> to this base URL, so the mirror must preserve the same directory layout as the GitHub Releases page.

Development

This Node.js binding is written in Rust. To build this binding, you need to install the Rust compiler: see the Install Rust Page. Then, the workflow is pretty classical by using pnpm: see the Node.js download page and the pnpm installation page.

The binding is compatible with, and tested against, the Node.js versions that are in “current” or “active” states, according to the Node.js Releases Page, and which are compatible with Node-API (formerly N-API) v8). It means that this binding will work with the following versions: v24 and v26.

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

$ pnpm install --ignore-scripts
$ pnpm build
$ pnpm test

An index.js, index.d.ts and a *.node files should be generated. At the same level of those files, you can edit a file and try this:

const { OlmMachine } = require("./index.js");

// Let's see what we can do.

The OlmMachine state machine works in a push/pull manner:

• You push state changes and events retrieved from a Matrix homeserver /sync response, into the state machine,
• You pull requests that you will need to send back to the homeserver out of the state machine.

const { OlmMachine, UserId, DeviceId, RoomId, DeviceLists } = require("./index.js");

async function main() {
    // Define a user ID.
    const alice = new UserId("@alice:example.org");

    // Define a device ID.
    const device = new DeviceId("DEVICEID");

    // Let's create the `OlmMachine` state machine.
    const machine = await OlmMachine.initialize(alice, device);

    // Let's pretend we have received changes and events from a
    // `/sync` endpoint of a Matrix homeserver, …
    const toDeviceEvents = "[]"; // JSON-encoded list of events
    const changedDevices = new DeviceLists();
    const oneTimeKeyCounts = {};
    const unusedFallbackKeys = [];

    // … and push them into the state machine.
    const decryptedToDevice = await machine.receiveSyncChanges(
        toDeviceEvents,
        changedDevices,
        oneTimeKeyCounts,
        unusedFallbackKeys,
    );

    // Now, let's pull requests that we need to send out to the Matrix
    // homeserver.
    const outgoingRequests = await machine.outgoingRequests();

    // To complete the workflow, send the requests here out and call
    // `machine.markRequestAsSent`.
}

main();

With tracing (experimental)

If you want to enable tracing, i.e. to get the logs, you should re-compile the extension with the tracing feature turned on:

$ pnpm build -- --features tracing

Now, you can use the MATRIX_LOG environment variable to tweak the log filtering, such as:

$ MATRIX_LOG=debug pnpm test

See tracing-subscriber to learn more about the RUST_LOG/MATRIX_LOG environment variable.

Using tracing in dependent projects

To enable tracing in client applications that import these bindings, here's how to do it in a local development environment:

• In this directory, run npm link to make your local build of the bindings available to other Node projects on your system
• In your client app's source directory, run npm link @matrix-org/matrix-sdk-crypto-nodejs to make it use your trace-enabled local build of the bindings
• In your client app's source code, add a call to initTracing near startup time
• Run your app with the MATRIX_LOG environment variable set to the desired log level

Either npm link command may be substituted with yarn link.

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.