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:

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 npm, see the Downloading and installing Node.js and npm Page.

The binding is compatible with, and tested against, the Node.js versions that are in “current”, “active” or “maintenance” states, according to the Node.js Releases Page, and which are compatible with NAPI v6 (Node.js API). It means that this binding will work with the following versions: 16.0.0, 18.0.0, 19.0.0 and 20.0.0.

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

$ npm install --ignore-scripts
$ npm run build
$ npm run 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:

$ npm run build -- --features tracing

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

$ MATRIX_LOG=debug npm run 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:

$ npm run doc

The documentation is generated in the ./docs directory.