@textrp/briij-js-sdk 41.0.0

package/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,477 @@
+[![npm](https://img.shields.io/npm/v/@textrp/briij-js-sdk)](https://www.npmjs.com/package/@textrp/briij-js-sdk)
+![Tests](https://github.com/xurgedigitallab/briij-js-sdk/actions/workflows/tests.yml/badge.svg)
+![Static Analysis](https://github.com/xurgedigitallab/briij-js-sdk/actions/workflows/static_analysis.yml/badge.svg)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=@textrp/briij-js-sdk&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=@textrp/briij-js-sdk)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=@textrp/briij-js-sdk&metric=coverage)](https://sonarcloud.io/summary/new_code?id=@textrp/briij-js-sdk)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=@textrp/briij-js-sdk&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=@textrp/briij-js-sdk)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=@textrp/briij-js-sdk&metric=bugs)](https://sonarcloud.io/summary/new_code?id=@textrp/briij-js-sdk)
+
+# Briij JavaScript SDK
+
+This is the [Matrix](https://matrix.org) Client-Server SDK for JavaScript and TypeScript. This SDK can be run in a
+browser or in Node.js.
+
+---
+
+<picture>
+  <source srcset="contrib/element-logo-light.png" media="(prefers-color-scheme: dark)">
+  <source srcset="contrib/element-logo-dark.png" media="(prefers-color-scheme: light)">
+  <img src="contrib/element-logo-fallback.png" alt="Element logo">
+</picture>
+
+<br>
+
+Development and maintenance is proudly sponsored by [Element](https://element.io). Element uses the SDK in their flagship [web](https://github.com/element-hq/element-web) and [desktop](https://github.com/element-hq/element-desktop) clients.
+
+The SDK is also the basis for multiple Matrix projects and we welcome contributions from all.
+
+---
+
+#### Minimum Matrix server version: v1.1
+
+The Matrix specification is constantly evolving - while this SDK aims for maximum backwards compatibility, it only
+guarantees that a feature will be supported for at least 4 spec releases. For example, if a feature the js-sdk supports
+is removed in v1.4 then the feature is _eligible_ for removal from the SDK when v1.8 is released. This SDK has no
+guarantee on implementing all features of any particular spec release, currently. This can mean that the SDK will call
+endpoints from before Matrix 1.1, for example.
+
+# Quickstart
+
+> [!IMPORTANT]
+> Servers may require or use authenticated endpoints for media (images, files, avatars, etc). See the
+> [Authenticated Media](#authenticated-media) section for information on how to enable support for this.
+
+Using `pnpm` instead of `npm` is recommended. Please see the pnpm [install
+guide](https://pnpm.io/installation#using-corepack) if you do not have it already.
+
+`pnpm add @textrp/briij-js-sdk`
+
+```javascript
+import * as sdk from "@textrp/briij-js-sdk";
+const client = sdk.createClient({ baseUrl: "https://matrix.org" });
+client.publicRooms(function (err, data) {
+    console.log("Public Rooms: %s", JSON.stringify(data));
+});
+```
+
+See [below](#end-to-end-encryption-support) for how to enable end-to-end-encryption, or check
+[the Node.js terminal app](https://github.com/xurgedigitallab/briij-js-sdk/tree/develop/examples/node) for a more complex example.
+
+To start the client:
+
+```javascript
+await client.startClient({ initialSyncLimit: 10 });
+```
+
+You can perform a call to `/sync` to get the current state of the client:
+
+```javascript
+client.once(ClientEvent.sync, function (state, prevState, res) {
+    if (state === "PREPARED") {
+        console.log("prepared");
+    } else {
+        console.log(state);
+        process.exit(1);
+    }
+});
+```
+
+To send a message:
+
+```javascript
+const content = {
+    body: "message text",
+    msgtype: "m.text",
+};
+client.sendEvent("roomId", "m.room.message", content, "", (err, res) => {
+    console.log(err);
+});
+```
+
+To listen for message events:
+
+```javascript
+client.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {
+    if (event.getType() !== "m.room.message") {
+        return; // only use messages
+    }
+    console.log(event.event.content.body);
+});
+```
+
+By default, the `@textrp/briij-js-sdk` client uses the `MemoryStore` to store events as they are received. For example to iterate through the currently stored timeline for a room:
+
+```javascript
+Object.keys(client.store.rooms).forEach((roomId) => {
+    client.getRoom(roomId).timeline.forEach((t) => {
+        console.log(t.event);
+    });
+});
+```
+
+## Authenticated media
+
+Servers supporting [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916) (Matrix 1.11) will require clients, like
+yours, to include an `Authorization` header when `/download`ing or `/thumbnail`ing media. For NodeJS environments this
+may be as easy as the following code snippet, though web browsers may need to use [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+to append the header when using the endpoints in `<img />` elements and similar.
+
+```javascript
+const downloadUrl = client.mxcUrlToHttp(
+    /*mxcUrl=*/ "mxc://example.org/abc123", // the MXC URI to download/thumbnail, typically from an event or profile
+    /*width=*/ undefined, // part of the thumbnail API. Use as required.
+    /*height=*/ undefined, // part of the thumbnail API. Use as required.
+    /*resizeMethod=*/ undefined, // part of the thumbnail API. Use as required.
+    /*allowDirectLinks=*/ false, // should generally be left `false`.
+    /*allowRedirects=*/ true, // implied supported with authentication
+    /*useAuthentication=*/ true, // the flag we're after in this example
+);
+const img = await fetch(downloadUrl, {
+    headers: {
+        Authorization: `Bearer ${client.getAccessToken()}`,
+    },
+});
+// Do something with `img`.
+```
+
+> [!WARNING]
+> In future the js-sdk will _only_ return authentication-required URLs, mandating population of the `Authorization` header.
+
+## What does this SDK do?
+
+This SDK provides a full object model around the Matrix Client-Server API and emits
+events for incoming data and state changes. Aside from wrapping the HTTP API, it:
+
+- Handles syncing (via `/sync`)
+- Handles the generation of "friendly" room and member names.
+- Handles historical `RoomMember` information (e.g. display names).
+- Manages room member state across multiple events (e.g. it handles typing, power
+  levels and membership changes).
+- Exposes high-level objects like `Rooms`, `RoomState`, `RoomMembers` and `Users`
+  which can be listened to for things like name changes, new messages, membership
+  changes, presence changes, and more.
+- Handle "local echo" of messages sent using the SDK. This means that messages
+  that have just been sent will appear in the timeline as 'sending', until it
+  completes. This is beneficial because it prevents there being a gap between
+  hitting the send button and having the "remote echo" arrive.
+- Mark messages which failed to send as not sent.
+- Automatically retry requests to send messages due to network errors.
+- Automatically retry requests to send messages due to rate limiting errors.
+- Handle queueing of messages.
+- Handles pagination.
+- Handle assigning push actions for events.
+- Handles room initial sync on accepting invites.
+- Handles WebRTC calling.
+
+# Usage
+
+## Supported platforms
+
+`@textrp/briij-js-sdk` can be used in either Node.js applications (ensure you have the latest LTS version of Node.js installed),
+or in browser applications, via a bundler such as Webpack or Vite.
+
+You can also use the sdk with [Deno](https://deno.land/) (`import npm:@textrp/briij-js-sdk`) but its not officially supported.
+
+## Emitted events
+
+The SDK raises notifications to the application using
+[`EventEmitter`s](https://nodejs.org/api/events.html#class-eventemitter). The `BriijClient` itself
+implements `EventEmitter`, as do many of the high-level abstractions such as `Room` and `RoomMember`.
+
+```javascript
+// Listen for low-level BriijEvents
+client.on(ClientEvent.Event, function (event) {
+    console.log(event.getType());
+});
+
+// Listen for typing changes
+client.on(RoomMemberEvent.Typing, function (event, member) {
+    if (member.typing) {
+        console.log(member.name + " is typing...");
+    } else {
+        console.log(member.name + " stopped typing.");
+    }
+});
+
+// start the client to setup the connection to the server
+client.startClient();
+```
+
+## Entry points
+
+As well as the primary entry point (`@textrp/briij-js-sdk`), there are several other entry points which may be useful:
+
+| Entry point                    | Description                                                                                         |
+| ------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `@textrp/briij-js-sdk`                | Primary entry point. High-level functionality, and lots of historical clutter in need of a cleanup. |
+| `@textrp/briij-js-sdk/lib/crypto-api` | Cryptography functionality.                                                                         |
+| `@textrp/briij-js-sdk/lib/types`      | Low-level types, reflecting data structures defined in the Matrix spec.                             |
+| `@textrp/briij-js-sdk/lib/testing`    | Test utilities, which may be useful in test code but should not be used in production code.         |
+| `@textrp/briij-js-sdk/lib/utils/*.js` | A set of modules exporting standalone functions (and their types).                                  |
+
+## Examples
+
+This section provides some useful code snippets which demonstrate the
+core functionality of the SDK. These examples assume the SDK is set up like this:
+
+```javascript
+import * as sdk from "@textrp/briij-js-sdk";
+const myUserId = "@example:localhost";
+const myAccessToken = "QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP";
+const matrixClient = sdk.createClient({
+    baseUrl: "http://localhost:8008",
+    accessToken: myAccessToken,
+    userId: myUserId,
+});
+```
+
+### Automatically join rooms when invited
+
+```javascript
+matrixClient.on(RoomEvent.MyMembership, function (room, membership, prevMembership) {
+    if (membership === KnownMembership.Invite) {
+        matrixClient.joinRoom(room.roomId).then(function () {
+            console.log("Auto-joined %s", room.roomId);
+        });
+    }
+});
+
+matrixClient.startClient();
+```
+
+### Print out messages for all rooms
+
+```javascript
+matrixClient.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {
+    if (toStartOfTimeline) {
+        return; // don't print paginated results
+    }
+    if (event.getType() !== "m.room.message") {
+        return; // only print messages
+    }
+    console.log(
+        // the room name will update with m.room.name events automatically
+        "(%s) %s :: %s",
+        room.name,
+        event.getSender(),
+        event.getContent().body,
+    );
+});
+
+matrixClient.startClient();
+```
+
+Output:
+
+```
+  (My Room) @megan:localhost :: Hello world
+  (My Room) @megan:localhost :: how are you?
+  (My Room) @example:localhost :: I am good
+  (My Room) @example:localhost :: change the room name
+  (My New Room) @megan:localhost :: done
+```
+
+### Print out membership lists whenever they are changed
+
+```javascript
+matrixClient.on(RoomStateEvent.Members, function (event, state, member) {
+    const room = matrixClient.getRoom(state.roomId);
+    if (!room) {
+        return;
+    }
+    const memberList = state.getMembers();
+    console.log(room.name);
+    console.log(Array(room.name.length + 1).join("=")); // underline
+    for (var i = 0; i < memberList.length; i++) {
+        console.log("(%s) %s", memberList[i].membership, memberList[i].name);
+    }
+});
+
+matrixClient.startClient();
+```
+
+Output:
+
+```
+  My Room
+  =======
+  (join) @example:localhost
+  (leave) @alice:localhost
+  (join) Bob
+  (invite) @charlie:localhost
+```
+
+# API Reference
+
+A hosted reference can be found at
+https://xurgedigitallab.github.io/briij-js-sdk/ (when published). See also the [repository](https://github.com/xurgedigitallab/briij-js-sdk).
+
+This SDK uses [Typedoc](https://typedoc.org/guides/doccomments) doc comments. You can manually build and
+host the API reference from the source files like this:
+
+```
+  $ pnpm gendoc
+  $ cd docs
+  $ python -m http.server 8005
+```
+
+Then visit `http://localhost:8005` to see the API docs.
+
+# End-to-end encryption support
+
+`@textrp/briij-js-sdk`'s end-to-end encryption support is based on the [WebAssembly bindings](https://github.com/matrix-org/matrix-rust-sdk-crypto-wasm) of the Rust [matrix-sdk-crypto](https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto) library.
+
+## Initialization
+
+To initialize the end-to-end encryption support in the matrix client:
+
+```javascript
+// Create a new matrix client
+const matrixClient = sdk.createClient({
+    baseUrl: "http://localhost:8008",
+    accessToken: myAccessToken,
+    userId: myUserId,
+});
+
+// Initialize to enable end-to-end encryption support.
+await matrixClient.initRustCrypto();
+```
+
+Note that by default it will attempt to use the Indexed DB provided by the browser as a crypto store. If running outside the browser, you will need to pass [an options object](https://briij.github.io/@textrp/briij-js-sdk/classes/briij.BriijClient.html#initrustcrypto) which includes `useIndexedDB: false`, to use an ephemeral in-memory store instead. Note that without a persistent store, you'll need to create a new device on the server side (with [`BriijClient.loginRequest`](https://briij.github.io/@textrp/briij-js-sdk/classes/briij.BriijClient.html#loginrequest)) each time your application starts.
+
+After calling `initRustCrypto`, you can obtain a reference to the [`CryptoApi`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoApi.html) interface, which is the main entry point for end-to-end encryption, by calling [`BriijClient.getCrypto`](https://briij.github.io/@textrp/briij-js-sdk/classes/briij.BriijClient.html#getCrypto).
+
+**WARNING**: the cryptography stack is not thread-safe. Having multiple `BriijClient` instances connected to the same Indexed DB will cause data corruption and decryption failures. The application layer is responsible for ensuring that only one `BriijClient` issue is instantiated at a time.
+
+## Secret storage
+
+You should normally set up [secret storage](https://spec.matrix.org/v1.12/client-server-api/#secret-storage) before using the end-to-end encryption. To do this, call [`CryptoApi.bootstrapSecretStorage`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoApi.html#bootstrapSecretStorage).
+`bootstrapSecretStorage` can be called unconditionally: it will only set up the secret storage if it is not already set up (unless you use the `setupNewSecretStorage` parameter).
+
+```javascript
+const matrixClient = sdk.createClient({
+    ...,
+    cryptoCallbacks: {
+        getSecretStorageKey: async (keys) => {
+            // This function should prompt the user to enter their secret storage key.
+            return mySecretStorageKeys;
+        },
+    },
+});
+
+matrixClient.getCrypto().bootstrapSecretStorage({
+    // This function will be called if a new secret storage key (aka recovery key) is needed.
+    // You should prompt the user to save the key somewhere, because they will need it to unlock secret storage in future.
+    createSecretStorageKey: async () => {
+        return mySecretStorageKey;
+    },
+});
+```
+
+The example above will create a new secret storage key if secret storage was not previously set up.
+The secret storage data will be encrypted using the secret storage key returned in [`createSecretStorageKey`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CreateSecretStorageOpts.html#createSecretStorageKey).
+
+We recommend that you prompt the user to re-enter this key when [`CryptoCallbacks.getSecretStorageKey`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoCallbacks.html#getSecretStorageKey) is called (when the secret storage access is needed).
+
+## Set up cross-signing
+
+To set up cross-signing to verify devices and other users, call
+[`CryptoApi.bootstrapCrossSigning`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoApi.html#bootstrapCrossSigning):
+
+```javascript
+matrixClient.getCrypto().bootstrapCrossSigning({
+    authUploadDeviceSigningKeys: async (makeRequest) => {
+        return makeRequest(authDict);
+    },
+});
+```
+
+The [`authUploadDeviceSigningKeys`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.BootstrapCrossSigningOpts.html#authUploadDeviceSigningKeys)
+callback is required in order to upload newly-generated public cross-signing keys to the server.
+
+## Key backup
+
+If the user doesn't already have a [key backup](https://spec.matrix.org/v1.12/client-server-api/#server-side-key-backups) you should create one:
+
+```javascript
+// Check if we have a key backup.
+// If checkKeyBackupAndEnable returns null, there is no key backup.
+const hasKeyBackup = (await matrixClient.getCrypto().checkKeyBackupAndEnable()) !== null;
+
+// Create the key backup
+await matrixClient.getCrypto().resetKeyBackup();
+```
+
+## Verify a new device
+
+Once the cross-signing is set up on one of your devices, you can verify another device with two methods:
+
+1. Use `CryptoApi.bootstrapCrossSigning`.
+
+    `bootstrapCrossSigning` will call the [CryptoCallbacks.getSecretStorageKey](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoCallbacks.html#getSecretStorageKey) callback. The device is verified with the private cross-signing keys fetched from the secret storage.
+
+2. Request an interactive verification against existing devices, by calling [CryptoApi.requestOwnUserVerification](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoApi.html#requestOwnUserVerification).
+
+## Migrating from the legacy crypto stack to Rust crypto
+
+If your application previously used the legacy crypto stack, (i.e, it called `BriijClient.initLegacyCrypto()`), you will
+need to migrate existing devices to the Rust crypto stack.
+
+This migration happens automatically when you call `initRustCrypto()` instead of `initLegacyCrypto()`,
+but you need to provide the legacy [`cryptoStore`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/briij.ICreateClientOpts.html#cryptoStore) and [`pickleKey`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/briij.ICreateClientOpts.html#pickleKey) to [`createClient`](https://briij.github.io/@textrp/briij-js-sdk/functions/briij.createClient.html):
+
+```javascript
+// You should provide the legacy crypto store and the pickle key to the matrix client in order to migrate the data.
+const matrixClient = sdk.createClient({
+    cryptoStore: myCryptoStore,
+    pickleKey: myPickleKey,
+    baseUrl: "http://localhost:8008",
+    accessToken: myAccessToken,
+    userId: myUserId,
+});
+
+// The migration will be done automatically when you call `initRustCrypto`.
+await matrixClient.initRustCrypto();
+```
+
+To follow the migration progress, you can listen to the [`CryptoEvent.LegacyCryptoStoreMigrationProgress`](https://briij.github.io/@textrp/briij-js-sdk/enums/crypto_api.CryptoEvent.html#LegacyCryptoStoreMigrationProgress) event:
+
+```javascript
+// When progress === total === -1, the migration is finished.
+matrixClient.on(CryptoEvent.LegacyCryptoStoreMigrationProgress, (progress, total) => {
+    ...
+});
+```
+
+The Rust crypto stack is not supported in a lot of deprecated methods of [`BriijClient`](https://briij.github.io/@textrp/briij-js-sdk/classes/briij.BriijClient.html). If you use them, you should migrate to the [`CryptoApi`](https://briij.github.io/@textrp/briij-js-sdk/interfaces/crypto_api.CryptoApi.html). Also, the legacy `BriijClient.crypto` object is not available any more: you should use `BriijClient.getCrypto()` instead.
+
+# Contributing
+
+_This section is for people who want to modify the SDK. If you just
+want to use this SDK, skip this section._
+
+First, you need to pull in the right build tools:
+
+```
+ $ pnpm install
+```
+
+## Building
+
+To build a browser version from scratch when developing:
+
+```
+ $ pnpm build
+```
+
+To run tests:
+
+```
+ $ pnpm test
+```
+
+To run linting:
+
+```
+ $ pnpm lint
+```

package/lib/@types/AESEncryptedSecretStoragePayload.d.ts

@@ -0,0 +1,14 @@
+/**
+ * An AES-encrypted secret storage payload.
+ * See https://spec.matrix.org/v1.11/client-server-api/#msecret_storagev1aes-hmac-sha2-1
+ */
+export interface AESEncryptedSecretStoragePayload {
+    [key: string]: any;
+    /** the initialization vector in base64 */
+    iv: string;
+    /** the ciphertext in base64 */
+    ciphertext: string;
+    /** the HMAC in base64 */
+    mac: string;
+}
+//# sourceMappingURL=AESEncryptedSecretStoragePayload.d.ts.map

package/lib/@types/AESEncryptedSecretStoragePayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AESEncryptedSecretStoragePayload.d.ts","sourceRoot":"","sources":["../../src/@types/AESEncryptedSecretStoragePayload.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC7C,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;CACf"}

package/lib/@types/AESEncryptedSecretStoragePayload.js

@@ -0,0 +1 @@
+export {};

package/lib/@types/AESEncryptedSecretStoragePayload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AESEncryptedSecretStoragePayload.js","names":[],"sources":["../../src/@types/AESEncryptedSecretStoragePayload.ts"],"sourcesContent":["/*\r\n * Copyright 2024 The Matrix.org Foundation C.I.C.\r\n *\r\n * Licensed under the Apache License, Version 2.0 (the \"License\");\r\n * you may not use this file except in compliance with the License.\r\n * You may obtain a copy of the License at\r\n *\r\n *     http://www.apache.org/licenses/LICENSE-2.0\r\n *\r\n * Unless required by applicable law or agreed to in writing, software\r\n * distributed under the License is distributed on an \"AS IS\" BASIS,\r\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r\n * See the License for the specific language governing permissions and\r\n * limitations under the License.\r\n */\r\n\r\n/**\r\n * An AES-encrypted secret storage payload.\r\n * See https://spec.matrix.org/v1.11/client-server-api/#msecret_storagev1aes-hmac-sha2-1\r\n */\r\nexport interface AESEncryptedSecretStoragePayload {\r\n    [key: string]: any; // extensible\r\n    /** the initialization vector in base64 */\r\n    iv: string;\r\n    /** the ciphertext in base64 */\r\n    ciphertext: string;\r\n    /** the HMAC in base64 */\r\n    mac: string;\r\n}\r\n"],"mappings":"","ignoreList":[]}