Nurturing Pluto's Martians

    @matrix-org/matrix-sdk-crypto-nodejs
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.0-beta.1 • Public • Published

    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
    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

    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: 14.0.0, 16.0.0 and 18.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
        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.

    Documentation

    To generate the documentation, please run the following command:

    $ npm run doc

    The documentation is generated in the ./docs directory.

    Keywords

    none

    Install

    npm i @matrix-org/matrix-sdk-crypto-nodejs

    DownloadsWeekly Downloads

    458

    Version

    0.1.0-beta.1

    License

    Apache-2.0

    Unpacked Size

    45.1 kB

    Total Files

    6

    Last publish

    Collaborators

    • matrixdotorg