226 lines
6.6 KiB
Markdown
226 lines
6.6 KiB
Markdown
# `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](https://en.wikipedia.org/wiki/End-to-end_encryption)) for
|
||
[Matrix] clients.
|
||
|
||
## Usage
|
||
|
||
Just add the latest release to your `package.json`:
|
||
|
||
```sh
|
||
$ 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:
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Platform</th>
|
||
<th>Architecture</th>
|
||
<th>Triple</th>
|
||
<th>Prebuilt available</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td rowspan="6">Linux</td>
|
||
<td rowspan="2"><code>aarch</code></td>
|
||
<td><code>aarch64-unknown-linux-gnu</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>arm-unknown-linux-gnueabihf</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="3"><code>amd</code></td>
|
||
<td><code>x86_64-unknown-linux-gnu</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>x86_64-unknown-linux-musl</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>i686-unknown-linux-gnu</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="1"><code>s390x</code></td>
|
||
<td><code>s390x-unknown-linux-gnu</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2">macOS</td>
|
||
<td><code>aarch</code></td>
|
||
<td><code>arch64-apple-darwin</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>amd</code></td>
|
||
<td><code>x86_64-apple-darwin</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="3">Windows</td>
|
||
<td><code>aarch</code></td>
|
||
<td><code>aarch64-pc-windows-msvc</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td rowspan="2"><code>amd</code></td>
|
||
<td><code>x86_64-pc-windows-msvc</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>i686-pc-windows-msvc</code></td>
|
||
<td>✅</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
## 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](https://www.rust-lang.org/tools/install). Then, the workflow is
|
||
pretty classical by using [npm], see [the Downloading and installing
|
||
Node.js and npm
|
||
Page](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
|
||
|
||
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](https://nodejs.org/en/about/releases/), _and_ which are
|
||
compatible with [NAPI v6 (Node.js
|
||
API)](https://nodejs.org/api/n-api.html#node-api-version-matrix). It
|
||
means that this binding will work with the following versions:
|
||
18.0.0, 20.0.0 and 22.0.0.
|
||
|
||
Once the Rust compiler, Node.js and npm are installed, you can run the
|
||
following commands:
|
||
|
||
```sh
|
||
$ 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:
|
||
|
||
```javascript
|
||
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.
|
||
|
||
```javascript
|
||
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](https://tracing.rs), i.e. to get the
|
||
logs, you should re-compile the extension with the `tracing` feature
|
||
turned on:
|
||
|
||
```sh
|
||
$ npm run build -- --features tracing
|
||
```
|
||
|
||
Now, you can use the `MATRIX_LOG` environment variable to tweak the log filtering, such as:
|
||
|
||
```sh
|
||
$ MATRIX_LOG=debug npm run test
|
||
```
|
||
|
||
See
|
||
[`tracing-subscriber`](https://tracing.rs/tracing_subscriber/index.html)
|
||
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](https://matrix-org.github.io/matrix-rust-sdk-crypto-nodejs/).
|
||
|
||
To generate the documentation locally, please run the following
|
||
command:
|
||
|
||
```sh
|
||
$ npm run doc
|
||
```
|
||
|
||
The documentation is generated in the `./docs` directory.
|
||
|
||
[Node.js]: https://nodejs.org/
|
||
[`matrix-sdk-crypto`]: https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto
|
||
[`matrix-rust-sdk`]: https://github.com/matrix-org/matrix-rust-sdk
|
||
[Matrix]: https://matrix.org/
|
||
[Rust]: https://www.rust-lang.org/
|
||
[npm]: https://www.npmjs.com/
|