v12.2.0-rc.1

Update ESLint config

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+<!-- Please read https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md before submitting your pull request -->
+
+<!-- Include a Sign-Off as described in https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md#sign-off -->
+
+<!-- To specify text for the changelog entry (otherwise the PR title will be used):
+Notes:
+-->

.gitignore

@@ -16,3 +16,6 @@ out
 # version file and tarball created by `npm pack` / `yarn pack`
 /git-revision.txt
 /matrix-js-sdk-*.tgz
+
+.vscode
+.vscode/

CHANGELOG.md

@@ -1,3 +1,135 @@
+Changes in [12.2.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v12.2.0-rc.1) (2021-07-27)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v12.1.0...v12.2.0-rc.1)
+
+ * Update ESLint config
+   [\#1810](https://github.com/matrix-org/matrix-js-sdk/pull/1810)
+ * Clean up Event.clearEvent handling to fix a bug where malformed events with
+   falsey content wouldn't be considered decrypted
+   [\#1807](https://github.com/matrix-org/matrix-js-sdk/pull/1807)
+ * Update matrix-org-eslint-plugin and tighten max warning limit
+   [\#1806](https://github.com/matrix-org/matrix-js-sdk/pull/1806)
+ * Initial MSC3244 support and type cleanup
+   [\#1745](https://github.com/matrix-org/matrix-js-sdk/pull/1745)
+ * Functional members
+   [\#1771](https://github.com/matrix-org/matrix-js-sdk/pull/1771)
+ * yarn upgrade
+   [\#1802](https://github.com/matrix-org/matrix-js-sdk/pull/1802)
+ * Improve calculateRoomName performances by using Intl.Collator
+   [\#1801](https://github.com/matrix-org/matrix-js-sdk/pull/1801)
+ * Conform to new typescript eslint rules
+   [\#1798](https://github.com/matrix-org/matrix-js-sdk/pull/1798)
+ * Actually print IndexedDB command error if there is one
+   [\#1799](https://github.com/matrix-org/matrix-js-sdk/pull/1799)
+ * Update eslint-plugin-matrix-org
+   [\#1796](https://github.com/matrix-org/matrix-js-sdk/pull/1796)
+ * Add minimal types for "notification settings" UI
+   [\#1778](https://github.com/matrix-org/matrix-js-sdk/pull/1778)
+ * Switch from `url` to URL constructor
+   [\#1791](https://github.com/matrix-org/matrix-js-sdk/pull/1791)
+ * Switch callEventHandler from listening on `event` to `Room.timeline`
+   [\#1789](https://github.com/matrix-org/matrix-js-sdk/pull/1789)
+ * Contributing guidelines for new changelog generation
+   [\#1787](https://github.com/matrix-org/matrix-js-sdk/pull/1787)
+ * Fix link to CONTRIBUTING.md
+   [\#1786](https://github.com/matrix-org/matrix-js-sdk/pull/1786)
+ * Use an unstable prefix for MSC2885: Hidden read receipts
+   [\#1788](https://github.com/matrix-org/matrix-js-sdk/pull/1788)
+ * Standardise spelling and casing of homeserver, identity server, and
+   integration manager
+   [\#1782](https://github.com/matrix-org/matrix-js-sdk/pull/1782)
+ * Convert CONTRIBUTING to markdown
+   [\#1785](https://github.com/matrix-org/matrix-js-sdk/pull/1785)
+ * Use webpack worker-loader instead of homegrown hack
+   [\#1780](https://github.com/matrix-org/matrix-js-sdk/pull/1780)
+ * Convert IndexedDB store & worker to Typescript
+   [\#1779](https://github.com/matrix-org/matrix-js-sdk/pull/1779)
+ * Expose MatrixEvent's internal clearEvent as a function
+   [\#1784](https://github.com/matrix-org/matrix-js-sdk/pull/1784)
+ * Improve and consolidate typing
+   [\#1777](https://github.com/matrix-org/matrix-js-sdk/pull/1777)
+
+Changes in [12.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v12.1.0) (2021-07-19)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v12.1.0-rc.1...v12.1.0)
+
+ * No changes from rc.1
+
+Changes in [12.1.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v12.1.0-rc.1) (2021-07-14)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v12.0.1...v12.1.0-rc.1)
+
+ * Add VS Code to gitignore
+   [\#1783](https://github.com/matrix-org/matrix-js-sdk/pull/1783)
+ * Make `Crypto::inRoomVerificationRequests` public
+   [\#1781](https://github.com/matrix-org/matrix-js-sdk/pull/1781)
+ * Call `setEventMetadata()` for filtered `timelineSet`s
+   [\#1765](https://github.com/matrix-org/matrix-js-sdk/pull/1765)
+ * Symmetric backup
+   [\#1775](https://github.com/matrix-org/matrix-js-sdk/pull/1775)
+ * Attempt to fix megolm key not being in SSSS
+   [\#1776](https://github.com/matrix-org/matrix-js-sdk/pull/1776)
+ * Convert SecretStorage to TypeScript
+   [\#1774](https://github.com/matrix-org/matrix-js-sdk/pull/1774)
+ * Strip hash from urls being previewed to de-duplicate
+   [\#1721](https://github.com/matrix-org/matrix-js-sdk/pull/1721)
+ * Do not generate a lockfile when running in CI
+   [\#1773](https://github.com/matrix-org/matrix-js-sdk/pull/1773)
+ * Tidy up secret requesting code
+   [\#1766](https://github.com/matrix-org/matrix-js-sdk/pull/1766)
+ * Convert Sync and SyncAccumulator to Typescript
+   [\#1763](https://github.com/matrix-org/matrix-js-sdk/pull/1763)
+ * Convert EventTimeline, EventTimelineSet and TimelineWindow to TS
+   [\#1762](https://github.com/matrix-org/matrix-js-sdk/pull/1762)
+ * Comply with new member-delimiter-style rule
+   [\#1764](https://github.com/matrix-org/matrix-js-sdk/pull/1764)
+ * Do not honor string power levels
+   [\#1754](https://github.com/matrix-org/matrix-js-sdk/pull/1754)
+ * Typescriptify some crypto stuffs
+   [\#1508](https://github.com/matrix-org/matrix-js-sdk/pull/1508)
+ * Make filterId read/write and optional
+   [\#1760](https://github.com/matrix-org/matrix-js-sdk/pull/1760)
+
+Changes in [12.0.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v12.0.1) (2021-07-05)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v12.0.1-rc.1...v12.0.1)
+
+ * No changes from rc.1
+
+Changes in [12.0.1-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v12.0.1-rc.1) (2021-06-29)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v12.0.0...v12.0.1-rc.1)
+
+ * Fix broken /messages filtering due to internal field changes in
+   FilterComponent
+   [\#1759](https://github.com/matrix-org/matrix-js-sdk/pull/1759)
+ * Convert crypto index to TS
+   [\#1749](https://github.com/matrix-org/matrix-js-sdk/pull/1749)
+ * Fix typescript return types for membership update events
+   [\#1739](https://github.com/matrix-org/matrix-js-sdk/pull/1739)
+ * Fix types of MatrixEvent sender & target
+   [\#1753](https://github.com/matrix-org/matrix-js-sdk/pull/1753)
+ * Add keysharing on invites to File Tree Spaces
+   [\#1744](https://github.com/matrix-org/matrix-js-sdk/pull/1744)
+ * Convert Room and RoomState to Typescript
+   [\#1746](https://github.com/matrix-org/matrix-js-sdk/pull/1746)
+ * Improve type of IContent msgtype
+   [\#1752](https://github.com/matrix-org/matrix-js-sdk/pull/1752)
+ * Add PR template
+   [\#1747](https://github.com/matrix-org/matrix-js-sdk/pull/1747)
+ * Add functions to assist in immutability of Event objects
+   [\#1738](https://github.com/matrix-org/matrix-js-sdk/pull/1738)
+ * Convert Event Context to TS
+   [\#1742](https://github.com/matrix-org/matrix-js-sdk/pull/1742)
+ * Bump lodash from 4.17.20 to 4.17.21
+   [\#1743](https://github.com/matrix-org/matrix-js-sdk/pull/1743)
+ * Add invite retries to file trees
+   [\#1740](https://github.com/matrix-org/matrix-js-sdk/pull/1740)
+ * Convert IndexedDBStore to TS
+   [\#1741](https://github.com/matrix-org/matrix-js-sdk/pull/1741)
+ * Convert additional files to typescript
+   [\#1736](https://github.com/matrix-org/matrix-js-sdk/pull/1736)
+
 Changes in [12.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v12.0.0) (2021-06-21)
 ==================================================================================================
 [Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v12.0.0-rc.1...v12.0.0)

CONTRIBUTING.md

@@ -0,0 +1,194 @@
+Contributing code to matrix-js-sdk
+==================================
+
+Everyone is welcome to contribute code to matrix-js-sdk, provided that they are
+willing to license their contributions under the same license as the project
+itself. We follow a simple 'inbound=outbound' model for contributions: the act
+of submitting an 'inbound' contribution means that the contributor agrees to
+license the code under the same terms as the project's overall 'outbound'
+license - in this case, Apache Software License v2 (see
+[LICENSE](LICENSE)).
+
+How to contribute
+-----------------
+
+The preferred and easiest way to contribute changes to the project is to fork
+it on github, and then create a pull request to ask us to pull your changes
+into our repo (https://help.github.com/articles/using-pull-requests/)
+
+We use GitHub's pull request workflow to review the contribution, and either
+ask you to make any refinements needed or merge it and make them ourselves.
+
+Things that should go into your PR description:
+ * A changelog entry in the `Notes` section (see below)
+ * References to any bugs fixed by the change (in GitHub's `Fixes` notation)
+ * Notes for the reviewer that might help them to understand why the change is
+   necessary or how they might better review it.
+
+Things that should *not* go into your PR description:
+ * Any information on how the code works or why you chose to do it the way
+   you did. If this isn't obvious from your code, you haven't written enough
+   comments.
+
+We rely on information in pull request to populate the information that goes
+into the changelogs our users see, both for the JS SDK itself and also for some
+projects based on it. This is picked up from both labels on the pull request and
+the `Notes:` annotation in the description. By default, the PR title will be
+used for the changelog entry, but you can specify more options, as follows.
+
+To add a longer, more detailed description of the change for the changelog:
+
+
+*Fix llama herding bug*
+
+```
+Notes: Fix a bug (https://github.com/matrix-org/notaproject/issues/123) where the 'Herd' button would not herd more than 8 Llamas if the moon was in the waxing gibbous phase
+```
+
+For some PRs, it's not useful to have an entry in the user-facing changelog (this is
+the default for PRs labelled with `T-Task`):
+
+*Remove outdated comment from `Ungulates.ts`*
+```
+Notes: none
+```
+
+Sometimes, you're fixing a bug in a downstream project, in which case you want
+an entry in that project's changelog. You can do that too:
+
+*Fix another herding bug*
+```
+Notes: Fix a bug where the `herd()` function would only work on Tuesdays
+element-web notes: Fix a bug where the 'Herd' button only worked on Tuesdays
+```
+
+This example is for Element Web. You can specify:
+ * matrix-react-sdk
+ * element-web
+ * element-desktop
+
+If your PR introduces a breaking change, use the `Notes` section in the same
+way, additionally adding the `X-Breaking-Change` label (see below). There's no need
+to specify in the notes that it's a breaking change - this will be added
+automatically based on the label - but remember to tell the developer how to
+migrate:
+
+*Remove legacy class*
+
+```
+Notes: Remove legacy `Camelopard` class. `Giraffe` should be used instead.
+```
+
+Other metadata can be added using labels.
+ * `X-Breaking-Change`: A breaking change - adding this label will mean the change causes a *major* version bump.
+ * `T-Enhancement`: A new feature - adding this label will mean the change causes a *minor* version bump.
+ * `T-Defect`: A bug fix (in either code or docs).
+ * `T-Task`: No user-facing changes, eg. code comments, CI fixes, refactors or tests. Won't have a changelog entry unless you specify one.
+
+If you don't have permission to add labels, your PR reviewer(s) can work with you
+to add them: ask in the PR description or comments.
+
+We use continuous integration, and all pull requests get automatically tested:
+if your change breaks the build, then the PR will show that there are failed
+checks, so please check back after a few minutes.
+
+Code style
+----------
+The js-sdk aims to target TypeScript/ES6. All new files should be written in
+TypeScript and existing files should use ES6 principles where possible.
+
+Members should not be exported as a default export in general - it causes problems
+with the architecture of the SDK (index file becomes less clear) and could
+introduce naming problems (as default exports get aliased upon import). In
+general, avoid using `export default`.
+
+The remaining code-style for matrix-js-sdk is not formally documented, but
+contributors are encouraged to read the
+[code style document for matrix-react-sdk](https://github.com/matrix-org/matrix-react-sdk/blob/master/code_style.md)
+and follow the principles set out there.
+
+Please ensure your changes match the cosmetic style of the existing project,
+and ***never*** mix cosmetic and functional changes in the same commit, as it
+makes it horribly hard to review otherwise.
+
+Attribution
+-----------
+Everyone who contributes anything to Matrix is welcome to be listed in the
+AUTHORS.rst file for the project in question. Please feel free to include a
+change to AUTHORS.rst in your pull request to list yourself and a short
+description of the area(s) you've worked on. Also, we sometimes have swag to
+give away to contributors - if you feel that Matrix-branded apparel is missing
+from your life, please mail us your shipping address to matrix at matrix.org
+and we'll try to fix it :)
+
+Sign off
+--------
+In order to have a concrete record that your contribution is intentional
+and you agree to license it under the same terms as the project's license, we've
+adopted the same lightweight approach that the Linux Kernel
+(https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker
+(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
+projects use: the DCO (Developer Certificate of Origin:
+http://developercertificate.org/). This is a simple declaration that you wrote
+the contribution or otherwise have the right to contribute it to Matrix:
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+660 York Street, Suite 102,
+San Francisco, CA 94110 USA
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+If you agree to this for your contribution, then all that's needed is to
+include the line in your commit or pull request comment:
+
+```
+Signed-off-by: Your Name <your@email.example.org>
+```
+
+We accept contributions under a legally identifiable name, such as your name on
+government documentation or common-law names (names claimed by legitimate usage
+or repute). Unfortunately, we cannot accept anonymous contributions at this
+time.
+
+Git allows you to add this signoff automatically when using the `-s` flag to
+`git commit`, which uses the name and email set in your `user.name` and
+`user.email` git configs.
+
+If you forgot to sign off your commits before making your pull request and are
+on Git 2.17+ you can mass signoff using rebase:
+
+```
+git rebase --signoff origin/develop
+```

CONTRIBUTING.rst

@@ -1,131 +0,0 @@
-Contributing code to matrix-js-sdk
-==================================
-
-Everyone is welcome to contribute code to matrix-js-sdk, provided that they are
-willing to license their contributions under the same license as the project
-itself. We follow a simple 'inbound=outbound' model for contributions: the act
-of submitting an 'inbound' contribution means that the contributor agrees to
-license the code under the same terms as the project's overall 'outbound'
-license - in this case, Apache Software License v2 (see `<LICENSE>`_).
-
-How to contribute
-~~~~~~~~~~~~~~~~~
-
-The preferred and easiest way to contribute changes to the project is to fork
-it on github, and then create a pull request to ask us to pull your changes
-into our repo (https://help.github.com/articles/using-pull-requests/)
-
-**The single biggest thing you need to know is: please base your changes on
-the develop branch - /not/ master.**
-
-We use the master branch to track the most recent release, so that folks who
-blindly clone the repo and automatically check out master get something that
-works. Develop is the unstable branch where all the development actually
-happens: the workflow is that contributors should fork the develop branch to
-make a 'feature' branch for a particular contribution, and then make a pull
-request to merge this back into the matrix.org 'official' develop branch. We
-use GitHub's pull request workflow to review the contribution, and either ask
-you to make any refinements needed or merge it and make them ourselves. The
-changes will then land on master when we next do a release.
-
-We use continuous integration, and all pull requests get automatically tested:
-if your change breaks the build, then the PR will show that there are failed
-checks, so please check back after a few minutes.
-
-Code style
-~~~~~~~~~~
-
-The js-sdk aims to target TypeScript/ES6. All new files should be written in
-TypeScript and existing files should use ES6 principles where possible.
-
-Members should not be exported as a default export in general - it causes problems
-with the architecture of the SDK (index file becomes less clear) and could
-introduce naming problems (as default exports get aliased upon import). In
-general, avoid using `export default`.
-
-The remaining code-style for matrix-js-sdk is not formally documented, but
-contributors are encouraged to read the code style document for matrix-react-sdk
-(`<https://github.com/matrix-org/matrix-react-sdk/blob/master/code_style.md>`_)
-and follow the principles set out there.
-
-Please ensure your changes match the cosmetic style of the existing project,
-and **never** mix cosmetic and functional changes in the same commit, as it
-makes it horribly hard to review otherwise.
-
-Attribution
-~~~~~~~~~~~
-
-Everyone who contributes anything to Matrix is welcome to be listed in the
-AUTHORS.rst file for the project in question. Please feel free to include a
-change to AUTHORS.rst in your pull request to list yourself and a short
-description of the area(s) you've worked on. Also, we sometimes have swag to
-give away to contributors - if you feel that Matrix-branded apparel is missing
-from your life, please mail us your shipping address to matrix at matrix.org
-and we'll try to fix it :)
-
-Sign off
-~~~~~~~~
-
-In order to have a concrete record that your contribution is intentional
-and you agree to license it under the same terms as the project's license, we've
-adopted the same lightweight approach that the Linux Kernel
-(https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker
-(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
-projects use: the DCO (Developer Certificate of Origin:
-http://developercertificate.org/). This is a simple declaration that you wrote
-the contribution or otherwise have the right to contribute it to Matrix::
-
-    Developer Certificate of Origin
-    Version 1.1
-
-    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
-    660 York Street, Suite 102,
-    San Francisco, CA 94110 USA
-
-    Everyone is permitted to copy and distribute verbatim copies of this
-    license document, but changing it is not allowed.
-
-    Developer's Certificate of Origin 1.1
-
-    By making a contribution to this project, I certify that:
-
-    (a) The contribution was created in whole or in part by me and I
-        have the right to submit it under the open source license
-        indicated in the file; or
-
-    (b) The contribution is based upon previous work that, to the best
-        of my knowledge, is covered under an appropriate open source
-        license and I have the right under that license to submit that
-        work with modifications, whether created in whole or in part
-        by me, under the same open source license (unless I am
-        permitted to submit under a different license), as indicated
-        in the file; or
-
-    (c) The contribution was provided directly to me by some other
-        person who certified (a), (b) or (c) and I have not modified
-        it.
-
-    (d) I understand and agree that this project and the contribution
-        are public and that a record of the contribution (including all
-        personal information I submit with it, including my sign-off) is
-        maintained indefinitely and may be redistributed consistent with
-        this project or the open source license(s) involved.
-
-If you agree to this for your contribution, then all that's needed is to
-include the line in your commit or pull request comment::
-
-    Signed-off-by: Your Name <your@email.example.org>
-
-We accept contributions under a legally identifiable name, such as your name on
-government documentation or common-law names (names claimed by legitimate usage
-or repute). Unfortunately, we cannot accept anonymous contributions at this
-time.
-
-Git allows you to add this signoff automatically when using the ``-s`` flag to
-``git commit``, which uses the name and email set in your ``user.name`` and
-``user.email`` git configs.
-
-If you forgot to sign off your commits before making your pull request and are
-on Git 2.17+ you can mass signoff using rebase::
-
-    git rebase --signoff origin/develop

package.json

@@ -1,6 +1,6 @@
 {
   "name": "matrix-js-sdk",
-  "version": "12.0.0",
+  "version": "12.2.0-rc.1",
   "description": "Matrix Client-Server SDK for Javascript",
   "scripts": {
     "prepublishOnly": "yarn build",
@@ -15,7 +15,8 @@
     "build:minify-browser": "terser dist/browser-matrix.js --compress --mangle --source-map --output dist/browser-matrix.min.js",
     "gendoc": "jsdoc -c jsdoc.json -P package.json",
     "lint": "yarn lint:types && yarn lint:js",
-    "lint:js": "eslint --max-warnings 57 src spec",
+    "lint:js": "eslint --max-warnings 7 src spec",
+    "lint:js-fix": "eslint --fix src spec",
     "lint:types": "tsc --noEmit",
     "test": "jest",
     "test:watch": "jest --watch",
@@ -55,6 +56,7 @@
     "bs58": "^4.0.1",
     "content-type": "^1.0.4",
     "loglevel": "^1.7.1",
+    "p-retry": "^4.5.0",
     "qs": "^6.9.6",
     "request": "^2.88.2",
     "unhomoglyph": "^1.0.6"
@@ -73,6 +75,7 @@
     "@babel/preset-typescript": "^7.12.7",
     "@babel/register": "^7.12.10",
     "@matrix-org/olm": "https://gitlab.matrix.org/api/v4/projects/27/packages/npm/@matrix-org/olm/-/@matrix-org/olm-3.2.3.tgz",
+    "@types/bs58": "^4.0.1",
     "@types/jest": "^26.0.20",
     "@types/node": "12",
     "@types/request": "^2.48.5",

release.sh

@@ -100,7 +100,7 @@ fi
 # global cache here to ensure we get the right thing.
 yarn cache clean
 # Ensure all dependencies are updated
-yarn install --ignore-scripts
+yarn install --ignore-scripts --pure-lockfile
 
 if [ -z "$skip_changelog" ]; then
     # update_changelog doesn't have a --version flag
@@ -225,7 +225,7 @@ if [ $dodist -eq 0 ]; then
     pushd "$builddir"
     git clone "$projdir" .
     git checkout "$rel_branch"
-    yarn install
+    yarn install --pure-lockfile
     # We haven't tagged yet, so tell the dist script what version
     # it's building
     DIST_VERSION="$tag" yarn dist

spec/integ/devicelist-integ-spec.js

@@ -165,7 +165,7 @@ describe("DeviceList management:", function() {
                    aliceTestClient.httpBackend.flush('/keys/query', 1).then(
                        () => aliceTestClient.httpBackend.flush('/send/', 1),
                    ),
-                   aliceTestClient.client.crypto._deviceList.saveIfDirty(),
+                   aliceTestClient.client.crypto.deviceList.saveIfDirty(),
                ]);
            }).then(() => {
                aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
@@ -202,7 +202,7 @@ describe("DeviceList management:", function() {
                return aliceTestClient.httpBackend.flush('/keys/query', 1);
            }).then((flushed) => {
                expect(flushed).toEqual(0);
-               return aliceTestClient.client.crypto._deviceList.saveIfDirty();
+               return aliceTestClient.client.crypto.deviceList.saveIfDirty();
            }).then(() => {
                aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                    const bobStat = data.trackingStatus['@bob:xyz'];
@@ -235,7 +235,7 @@ describe("DeviceList management:", function() {
                // wait for the client to stop processing the response
                return aliceTestClient.client.downloadKeys(['@bob:xyz']);
            }).then(() => {
-               return aliceTestClient.client.crypto._deviceList.saveIfDirty();
+               return aliceTestClient.client.crypto.deviceList.saveIfDirty();
            }).then(() => {
                aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                    const bobStat = data.trackingStatus['@bob:xyz'];
@@ -256,7 +256,7 @@ describe("DeviceList management:", function() {
                // wait for the client to stop processing the response
                return aliceTestClient.client.downloadKeys(['@chris:abc']);
            }).then(() => {
-               return aliceTestClient.client.crypto._deviceList.saveIfDirty();
+               return aliceTestClient.client.crypto.deviceList.saveIfDirty();
            }).then(() => {
                aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                    const bobStat = data.trackingStatus['@bob:xyz'];
@@ -286,7 +286,7 @@ describe("DeviceList management:", function() {
                 },
             );
             await aliceTestClient.httpBackend.flush('/keys/query', 1);
-            await aliceTestClient.client.crypto._deviceList.saveIfDirty();
+            await aliceTestClient.client.crypto.deviceList.saveIfDirty();
 
             aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                 const bobStat = data.trackingStatus['@bob:xyz'];
@@ -322,7 +322,7 @@ describe("DeviceList management:", function() {
             );
 
             await aliceTestClient.flushSync();
-            await aliceTestClient.client.crypto._deviceList.saveIfDirty();
+            await aliceTestClient.client.crypto.deviceList.saveIfDirty();
 
             aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                 const bobStat = data.trackingStatus['@bob:xyz'];
@@ -358,7 +358,7 @@ describe("DeviceList management:", function() {
             );
 
             await aliceTestClient.flushSync();
-            await aliceTestClient.client.crypto._deviceList.saveIfDirty();
+            await aliceTestClient.client.crypto.deviceList.saveIfDirty();
 
             aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                 const bobStat = data.trackingStatus['@bob:xyz'];
@@ -379,7 +379,7 @@ describe("DeviceList management:", function() {
                 anotherTestClient.httpBackend.when('GET', '/sync').respond(
                     200, getSyncResponse([]));
                 await anotherTestClient.flushSync();
-                await anotherTestClient.client.crypto._deviceList.saveIfDirty();
+                await anotherTestClient.client.crypto.deviceList.saveIfDirty();
 
                 anotherTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
                     const bobStat = data.trackingStatus['@bob:xyz'];

spec/integ/matrix-client-crypto.spec.js

@@ -159,7 +159,7 @@ function aliDownloadsKeys() {
     // check that the localStorage is updated as we expect (not sure this is
     // an integration test, but meh)
     return Promise.all([p1, p2]).then(() => {
-        return aliTestClient.client.crypto._deviceList.saveIfDirty();
+        return aliTestClient.client.crypto.deviceList.saveIfDirty();
     }).then(() => {
         aliTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
             const devices = data.devices[bobUserId];

spec/integ/matrix-client-methods.spec.js

@@ -336,7 +336,7 @@ describe("MatrixClient", function() {
                 var b = JSON.parse(JSON.stringify(o));
                 delete(b.signatures);
                 delete(b.unsigned);
-                return client.crypto._olmDevice.sign(anotherjson.stringify(b));
+                return client.crypto.olmDevice.sign(anotherjson.stringify(b));
             };
 
             logger.log("Ed25519: " + ed25519key);

spec/integ/megolm-integ.spec.js

@@ -1012,8 +1012,8 @@ describe("megolm", function() {
                 },
                 event: true,
             });
-            event._senderCurve25519Key = testSenderKey;
-            return testClient.client.crypto._onRoomKeyEvent(event);
+            event.senderCurve25519Key = testSenderKey;
+            return testClient.client.crypto.onRoomKeyEvent(event);
         }).then(() => {
             const event = testUtils.mkEvent({
                 event: true,
@@ -1025,4 +1025,68 @@ describe("megolm", function() {
             });
         });
     });
+
+    it("Alice can decrypt a message with falsey content", function() {
+        return aliceTestClient.start().then(() => {
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((p2pSession) => {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+
+            // make the room_key event
+            const roomKeyEncrypted = encryptGroupSessionKey({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            const plaintext = {
+                type: "m.room.message",
+                content: undefined,
+                room_id: ROOM_ID,
+            };
+
+            const messageEncrypted = {
+                event_id: 'test_megolm_event',
+                content: {
+                    algorithm: "m.megolm.v1.aes-sha2",
+                    ciphertext: groupSession.encrypt(JSON.stringify(plaintext)),
+                    device_id: "testDevice",
+                    sender_key: testSenderKey,
+                    session_id: groupSession.session_id(),
+                },
+                type: "m.room.encrypted",
+            };
+
+            // Alice gets both the events in a single sync
+            const syncResponse = {
+                next_batch: 1,
+                to_device: {
+                    events: [roomKeyEncrypted],
+                },
+                rooms: {
+                    join: {},
+                },
+            };
+            syncResponse.rooms.join[ROOM_ID] = {
+                timeline: {
+                    events: [messageEncrypted],
+                },
+            };
+
+            aliceTestClient.httpBackend.when("GET", "/sync").respond(200, syncResponse);
+            return aliceTestClient.flushSync();
+        }).then(function() {
+            const room = aliceTestClient.client.getRoom(ROOM_ID);
+            const event = room.getLiveTimeline().getEvents()[0];
+            expect(event.isEncrypted()).toBe(true);
+            return testUtils.awaitDecryption(event);
+        }).then((event) => {
+            expect(event.getRoomId()).toEqual(ROOM_ID);
+            expect(event.getContent()).toEqual({});
+            expect(event.getClearContent()).toBeUndefined();
+        });
+    });
 });

spec/test-utils.js

@@ -51,7 +51,7 @@ export function mock(constr, name) {
     result.toString = function() {
         return "mock" + (name ? " of " + name : "");
     };
-    for (const key in constr.prototype) { // eslint-disable-line guard-for-in
+    for (const key of Object.getOwnPropertyNames(constr.prototype)) { // eslint-disable-line guard-for-in
         try {
             if (constr.prototype[key] instanceof Function) {
                 result[key] = jest.fn();
@@ -91,7 +91,7 @@ export function mkEvent(opts) {
         event.state_key = opts.skey;
     } else if (["m.room.name", "m.room.topic", "m.room.create", "m.room.join_rules",
          "m.room.power_levels", "m.room.topic",
-         "com.example.state"].indexOf(opts.type) !== -1) {
+         "com.example.state"].includes(opts.type)) {
         event.state_key = "";
     }
     return opts.event ? new MatrixEvent(event) : event;

spec/unit/crypto.spec.js

@@ -65,7 +65,7 @@ describe("Crypto", function() {
                 'YmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmI';
             device.keys["ed25519:FLIBBLE"] =
                 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
-            client.crypto._deviceList.getDeviceByIdentityKey = () => device;
+            client.crypto.deviceList.getDeviceByIdentityKey = () => device;
 
             encryptionInfo = client.getEventEncryptionInfo(event);
             expect(encryptionInfo.encrypted).toBeTruthy();
@@ -213,7 +213,7 @@ describe("Crypto", function() {
 
                 async function keyshareEventForEvent(event, index) {
                     const eventContent = event.getWireContent();
-                    const key = await aliceClient.crypto._olmDevice
+                    const key = await aliceClient.crypto.olmDevice
                         .getInboundGroupSessionKey(
                             roomId, eventContent.sender_key, eventContent.session_id,
                             index,
@@ -234,7 +234,7 @@ describe("Crypto", function() {
                         },
                     });
                     // make onRoomKeyEvent think this was an encrypted event
-                    ksEvent._senderCurve25519Key = "akey";
+                    ksEvent.senderCurve25519Key = "akey";
                     return ksEvent;
                 }
 
@@ -274,9 +274,9 @@ describe("Crypto", function() {
                     // alice encrypts each event, and then bob tries to decrypt
                     // them without any keys, so that they'll be in pending
                     await aliceClient.crypto.encryptEvent(event, aliceRoom);
-                    event._clearEvent = {};
-                    event._senderCurve25519Key = null;
-                    event._claimedEd25519Key = null;
+                    event.clearEvent = undefined;
+                    event.senderCurve25519Key = null;
+                    event.claimedEd25519Key = null;
                     try {
                         await bobClient.crypto.decryptEvent(event);
                     } catch (e) {
@@ -285,7 +285,7 @@ describe("Crypto", function() {
                     }
                 }));
 
-                const bobDecryptor = bobClient.crypto._getRoomDecryptor(
+                const bobDecryptor = bobClient.crypto.getRoomDecryptor(
                     roomId, olmlib.MEGOLM_ALGORITHM,
                 );
 
@@ -377,7 +377,7 @@ describe("Crypto", function() {
             // key requests get queued until the sync has finished, but we don't
             // let the client set up enough for that to happen, so gut-wrench a bit
             // to force it to send now.
-            aliceClient.crypto._outgoingRoomKeyRequestManager.sendQueuedRequests();
+            aliceClient.crypto.outgoingRoomKeyRequestManager.sendQueuedRequests();
             jest.runAllTimers();
             await Promise.resolve();
             expect(aliceClient.sendToDevice).toBeCalledTimes(1);

spec/unit/crypto/algorithms/megolm.spec.js

@@ -257,7 +257,7 @@ describe("MegolmDecryption", function() {
         });
 
         it("re-uses sessions for sequential messages", async function() {
-            mockCrypto._backupManager = {
+            mockCrypto.backupManager = {
                 backupGroupSession: () => {},
             };
             const mockStorage = new MockStorageApi();
@@ -365,9 +365,9 @@ describe("MegolmDecryption", function() {
             bobClient1.initCrypto(),
             bobClient2.initCrypto(),
         ]);
-        const aliceDevice = aliceClient.crypto._olmDevice;
-        const bobDevice1 = bobClient1.crypto._olmDevice;
-        const bobDevice2 = bobClient2.crypto._olmDevice;
+        const aliceDevice = aliceClient.crypto.olmDevice;
+        const bobDevice1 = bobClient1.crypto.olmDevice;
+        const bobDevice2 = bobClient2.crypto.olmDevice;
 
         const encryptionCfg = {
             "algorithm": "m.megolm.v1.aes-sha2",
@@ -404,11 +404,11 @@ describe("MegolmDecryption", function() {
             },
         };
 
-        aliceClient.crypto._deviceList.storeDevicesForUser(
+        aliceClient.crypto.deviceList.storeDevicesForUser(
             "@bob:example.com", BOB_DEVICES,
         );
-        aliceClient.crypto._deviceList.downloadKeys = async function(userIds) {
-            return this._getDevicesFromStore(userIds);
+        aliceClient.crypto.deviceList.downloadKeys = async function(userIds) {
+            return this.getDevicesFromStore(userIds);
         };
 
         let run = false;
@@ -468,8 +468,8 @@ describe("MegolmDecryption", function() {
             aliceClient.initCrypto(),
             bobClient.initCrypto(),
         ]);
-        const aliceDevice = aliceClient.crypto._olmDevice;
-        const bobDevice = bobClient.crypto._olmDevice;
+        const aliceDevice = aliceClient.crypto.olmDevice;
+        const bobDevice = bobClient.crypto.olmDevice;
 
         const encryptionCfg = {
             "algorithm": "m.megolm.v1.aes-sha2",
@@ -508,11 +508,11 @@ describe("MegolmDecryption", function() {
             },
         };
 
-        aliceClient.crypto._deviceList.storeDevicesForUser(
+        aliceClient.crypto.deviceList.storeDevicesForUser(
             "@bob:example.com", BOB_DEVICES,
         );
-        aliceClient.crypto._deviceList.downloadKeys = async function(userIds) {
-            return this._getDevicesFromStore(userIds);
+        aliceClient.crypto.deviceList.downloadKeys = async function(userIds) {
+            return this.getDevicesFromStore(userIds);
         };
 
         aliceClient.claimOneTimeKeys = async () => {
@@ -561,11 +561,11 @@ describe("MegolmDecryption", function() {
             aliceClient.initCrypto(),
             bobClient.initCrypto(),
         ]);
-        const bobDevice = bobClient.crypto._olmDevice;
+        const bobDevice = bobClient.crypto.olmDevice;
 
         const roomId = "!someroom";
 
-        aliceClient.crypto._onToDeviceEvent(new MatrixEvent({
+        aliceClient.crypto.onToDeviceEvent(new MatrixEvent({
             type: "org.matrix.room_key.withheld",
             sender: "@bob:example.com",
             content: {
@@ -605,13 +605,13 @@ describe("MegolmDecryption", function() {
             bobClient.initCrypto(),
         ]);
         aliceClient.crypto.downloadKeys = async () => {};
-        const bobDevice = bobClient.crypto._olmDevice;
+        const bobDevice = bobClient.crypto.olmDevice;
 
         const roomId = "!someroom";
 
         const now = Date.now();
 
-        aliceClient.crypto._onToDeviceEvent(new MatrixEvent({
+        aliceClient.crypto.onToDeviceEvent(new MatrixEvent({
             type: "org.matrix.room_key.withheld",
             sender: "@bob:example.com",
             content: {
@@ -655,7 +655,7 @@ describe("MegolmDecryption", function() {
             aliceClient.initCrypto(),
             bobClient.initCrypto(),
         ]);
-        const bobDevice = bobClient.crypto._olmDevice;
+        const bobDevice = bobClient.crypto.olmDevice;
         aliceClient.crypto.downloadKeys = async () => {};
 
         const roomId = "!someroom";
@@ -663,7 +663,7 @@ describe("MegolmDecryption", function() {
         const now = Date.now();
 
         // pretend we got an event that we can't decrypt
-        aliceClient.crypto._onToDeviceEvent(new MatrixEvent({
+        aliceClient.crypto.onToDeviceEvent(new MatrixEvent({
             type: "m.room.encrypted",
             sender: "@bob:example.com",
             content: {

spec/unit/crypto/backup.spec.js

@@ -52,7 +52,7 @@ const ENCRYPTED_EVENT = new MatrixEvent({
     origin_server_ts: 1507753886000,
 });
 
-const KEY_BACKUP_DATA = {
+const CURVE25519_KEY_BACKUP_DATA = {
     first_message_index: 0,
     forwarded_count: 0,
     is_verified: false,
@@ -73,7 +73,26 @@ const KEY_BACKUP_DATA = {
     },
 };
 
-const BACKUP_INFO = {
+const AES256_KEY_BACKUP_DATA = {
+    first_message_index: 0,
+    forwarded_count: 0,
+    is_verified: false,
+    session_data: {
+        iv: 'b3Jqqvm5S9QdmXrzssspLQ',
+        ciphertext: 'GOOASO3E9ThogkG0zMjEduGLM3u9jHZTkS7AvNNbNj3q1znwk4OlaVKXce'
+            + '7ynofiiYIiS865VlOqrKEEXv96XzRyUpgn68e3WsicwYl96EtjIEh/iY003PG2Qd'
+            + 'EluT899Ax7PydpUHxEktbWckMppYomUR5q8x1KI1SsOQIiJaIGThmIMPANRCFiK0'
+            + 'WQj+q+dnhzx4lt9AFqU5bKov8qKnw2qGYP7/+6RmJ0Kpvs8tG6lrcNDEHtFc2r0r'
+            + 'KKubDypo0Vc8EWSwsAHdKa36ewRavpreOuE8Z9RLfY0QIR1ecXrMqW0CdGFr7H3P'
+            + 'vcjF8sjwvQAavzxEKT1WMGizSMLeKWo2mgZ5cKnwV5HGUAw596JQvKs9laG2U89K'
+            + 'YrT0sH30vi62HKzcBLcDkWkUSNYPz7UiZ1MM0L380UA+1ZOXSOmtBA9xxzzbc8Xd'
+            + 'fRimVgklGdxrxjzuNLYhL2BvVH4oPWonD9j0bvRwE6XkimdbGQA8HB7UmXXjE8WA'
+            + 'RgaDHkfzoA3g3aeQ',
+        mac: 'uR988UYgGL99jrvLLPX3V1ows+UYbktTmMxPAo2kxnU',
+    },
+};
+
+const CURVE25519_BACKUP_INFO = {
     algorithm: "m.megolm_backup.v1.curve25519-aes-sha2",
     version: 1,
     auth_data: {
@@ -81,6 +100,14 @@ const BACKUP_INFO = {
     },
 };
 
+const AES256_BACKUP_INFO = {
+    algorithm: "org.matrix.msc3270.v1.aes-hmac-sha2",
+    version: 1,
+    auth_data: {
+        // FIXME: add iv and mac
+    },
+};
+
 const keys = {};
 
 function getCrossSigningKey(type) {
@@ -139,12 +166,12 @@ describe("MegolmBackup", function() {
     let megolmDecryption;
     beforeEach(async function() {
         mockCrypto = testUtils.mock(Crypto, 'Crypto');
-        mockCrypto._backupManager = testUtils.mock(BackupManager, "BackupManager");
+        mockCrypto.backupManager = testUtils.mock(BackupManager, "BackupManager");
         mockCrypto.backupKey = new Olm.PkEncryption();
         mockCrypto.backupKey.set_recipient_key(
             "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
         );
-        mockCrypto.backupInfo = BACKUP_INFO;
+        mockCrypto.backupInfo = CURVE25519_BACKUP_INFO;
 
         mockStorage = new MockStorageApi();
         sessionStore = new WebStorageSessionStore(mockStorage);
@@ -217,18 +244,18 @@ describe("MegolmBackup", function() {
             };
             mockCrypto.cancelRoomKeyRequest = function() {};
 
-            mockCrypto._backupManager = {
+            mockCrypto.backupManager = {
                 backupGroupSession: jest.fn(),
             };
 
             return event.attemptDecryption(mockCrypto).then(() => {
                 return megolmDecryption.onRoomKeyEvent(event);
             }).then(() => {
-                expect(mockCrypto._backupManager.backupGroupSession).toHaveBeenCalled();
+                expect(mockCrypto.backupManager.backupGroupSession).toHaveBeenCalled();
             });
         });
 
-        it('sends backups to the server', function() {
+        it('sends backups to the server (Curve25519 version)', function() {
             const groupSession = new Olm.OutboundGroupSession();
             groupSession.create();
             const ibGroupSession = new Olm.InboundGroupSession();
@@ -296,7 +323,89 @@ describe("MegolmBackup", function() {
                             resolve();
                             return Promise.resolve({});
                         };
-                        client.crypto._backupManager.backupGroupSession(
+                        client.crypto.backupManager.backupGroupSession(
+                            "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
+                            groupSession.session_id(),
+                        );
+                    }).then(() => {
+                        expect(numCalls).toBe(1);
+                    });
+                });
+        });
+
+        it('sends backups to the server (AES-256 version)', function() {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+            const ibGroupSession = new Olm.InboundGroupSession();
+            ibGroupSession.create(groupSession.session_key());
+
+            const client = makeTestClient(sessionStore, cryptoStore);
+
+            megolmDecryption = new MegolmDecryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: client,
+                roomId: ROOM_ID,
+            });
+
+            megolmDecryption.olmlib = mockOlmLib;
+
+            return client.initCrypto()
+                .then(() => {
+                    return client.crypto.storeSessionBackupPrivateKey(new Uint8Array(32));
+                })
+                .then(() => {
+                    return cryptoStore.doTxn(
+                        "readwrite",
+                        [cryptoStore.STORE_SESSION],
+                        (txn) => {
+                            cryptoStore.addEndToEndInboundGroupSession(
+                                "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
+                                groupSession.session_id(),
+                                {
+                                    forwardingCurve25519KeyChain: undefined,
+                                    keysClaimed: {
+                                        ed25519: "SENDER_ED25519",
+                                    },
+                                    room_id: ROOM_ID,
+                                    session: ibGroupSession.pickle(olmDevice._pickleKey),
+                                },
+                                txn);
+                        });
+                })
+                .then(() => {
+                    client.enableKeyBackup({
+                        algorithm: "org.matrix.msc3270.v1.aes-hmac-sha2",
+                        version: 1,
+                        auth_data: {
+                            iv: "PsCAtR7gMc4xBd9YS3A9Ow",
+                            mac: "ZSDsTFEZK7QzlauCLMleUcX96GQZZM7UNtk4sripSqQ",
+                        },
+                    });
+                    let numCalls = 0;
+                    return new Promise((resolve, reject) => {
+                        client.http.authedRequest = function(
+                            callback, method, path, queryParams, data, opts,
+                        ) {
+                            ++numCalls;
+                            expect(numCalls).toBeLessThanOrEqual(1);
+                            if (numCalls >= 2) {
+                                // exit out of retry loop if there's something wrong
+                                reject(new Error("authedRequest called too many timmes"));
+                                return Promise.resolve({});
+                            }
+                            expect(method).toBe("PUT");
+                            expect(path).toBe("/room_keys/keys");
+                            expect(queryParams.version).toBe(1);
+                            expect(data.rooms[ROOM_ID].sessions).toBeDefined();
+                            expect(data.rooms[ROOM_ID].sessions).toHaveProperty(
+                                groupSession.session_id(),
+                            );
+                            resolve();
+                            return Promise.resolve({});
+                        };
+                        client.crypto.backupManager.backupGroupSession(
                             "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
                             groupSession.session_id(),
                         );
@@ -478,7 +587,7 @@ describe("MegolmBackup", function() {
                                 );
                             }
                         };
-                        client.crypto._backupManager.backupGroupSession(
+                        client.crypto.backupManager.backupGroupSession(
                             "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
                             groupSession.session_id(),
                         );
@@ -512,30 +621,47 @@ describe("MegolmBackup", function() {
             client.stopClient();
         });
 
-        it('can restore from backup', function() {
+        it('can restore from backup (Curve25519 version)', function() {
             client.http.authedRequest = function() {
-                return Promise.resolve(KEY_BACKUP_DATA);
+                return Promise.resolve(CURVE25519_KEY_BACKUP_DATA);
             };
             return client.restoreKeyBackupWithRecoveryKey(
                 "EsTc LW2K PGiF wKEA 3As5 g5c4 BXwk qeeJ ZJV8 Q9fu gUMN UE4d",
                 ROOM_ID,
                 SESSION_ID,
-                BACKUP_INFO,
+                CURVE25519_BACKUP_INFO,
             ).then(() => {
                 return megolmDecryption.decryptEvent(ENCRYPTED_EVENT);
             }).then((res) => {
                 expect(res.clearEvent.content).toEqual('testytest');
-                expect(res.untrusted).toBeTruthy(); // keys from backup are untrusted
+                expect(res.untrusted).toBeTruthy(); // keys from Curve25519 backup are untrusted
             });
         });
 
-        it('can restore backup by room', function() {
+        it('can restore from backup (AES-256 version)', function() {
+            client.http.authedRequest = function() {
+                return Promise.resolve(AES256_KEY_BACKUP_DATA);
+            };
+            return client.restoreKeyBackupWithRecoveryKey(
+                "EsTc LW2K PGiF wKEA 3As5 g5c4 BXwk qeeJ ZJV8 Q9fu gUMN UE4d",
+                ROOM_ID,
+                SESSION_ID,
+                AES256_BACKUP_INFO,
+            ).then(() => {
+                return megolmDecryption.decryptEvent(ENCRYPTED_EVENT);
+            }).then((res) => {
+                expect(res.clearEvent.content).toEqual('testytest');
+                expect(res.untrusted).toBeFalsy(); // keys from AES backup are trusted
+            });
+        });
+
+        it('can restore backup by room (Curve25519 version)', function() {
             client.http.authedRequest = function() {
                 return Promise.resolve({
                     rooms: {
                         [ROOM_ID]: {
                             sessions: {
-                                [SESSION_ID]: KEY_BACKUP_DATA,
+                                [SESSION_ID]: CURVE25519_KEY_BACKUP_DATA,
                             },
                         },
                     },
@@ -543,7 +669,7 @@ describe("MegolmBackup", function() {
             };
             return client.restoreKeyBackupWithRecoveryKey(
                 "EsTc LW2K PGiF wKEA 3As5 g5c4 BXwk qeeJ ZJV8 Q9fu gUMN UE4d",
-                null, null, BACKUP_INFO,
+                null, null, CURVE25519_BACKUP_INFO,
             ).then(() => {
                 return megolmDecryption.decryptEvent(ENCRYPTED_EVENT);
             }).then((res) => {
@@ -562,14 +688,14 @@ describe("MegolmBackup", function() {
             const cachedNull = await client.crypto.getSessionBackupPrivateKey();
             expect(cachedNull).toBeNull();
             client.http.authedRequest = function() {
-                return Promise.resolve(KEY_BACKUP_DATA);
+                return Promise.resolve(CURVE25519_KEY_BACKUP_DATA);
             };
             await new Promise((resolve) => {
                 client.restoreKeyBackupWithRecoveryKey(
                     "EsTc LW2K PGiF wKEA 3As5 g5c4 BXwk qeeJ ZJV8 Q9fu gUMN UE4d",
                     ROOM_ID,
                     SESSION_ID,
-                    BACKUP_INFO,
+                    CURVE25519_BACKUP_INFO,
                     { cacheCompleteCallback: resolve },
                 );
             });
@@ -578,11 +704,11 @@ describe("MegolmBackup", function() {
         });
 
         it("fails if an known algorithm is used", async function() {
-            const BAD_BACKUP_INFO = Object.assign({}, BACKUP_INFO, {
+            const BAD_BACKUP_INFO = Object.assign({}, CURVE25519_BACKUP_INFO, {
                 algorithm: "this.algorithm.does.not.exist",
             });
             client.http.authedRequest = function() {
-                return Promise.resolve(KEY_BACKUP_DATA);
+                return Promise.resolve(CURVE25519_KEY_BACKUP_DATA);
             };
 
             await expect(client.restoreKeyBackupWithRecoveryKey(

spec/unit/crypto/cross-signing.spec.js

@@ -64,8 +64,8 @@ describe("Cross Signing", function() {
         );
         alice.uploadDeviceSigningKeys = jest.fn(async (auth, keys) => {
             await olmlib.verifySignature(
-                alice.crypto._olmDevice, keys.master_key, "@alice:example.com",
-                "Osborne2", alice.crypto._olmDevice.deviceEd25519Key,
+                alice.crypto.olmDevice, keys.master_key, "@alice:example.com",
+                "Osborne2", alice.crypto.olmDevice.deviceEd25519Key,
             );
         });
         alice.uploadKeySignatures = async () => {};
@@ -138,7 +138,7 @@ describe("Cross Signing", function() {
         // set Alice's cross-signing key
         await resetCrossSigningKeys(alice);
         // Alice downloads Bob's device key
-        alice.crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeCrossSigningForUser("@bob:example.com", {
             keys: {
                 master: {
                     user_id: "@bob:example.com",
@@ -203,12 +203,12 @@ describe("Cross Signing", function() {
             alice.uploadKeySignatures = jest.fn(async (content) => {
                 try {
                     await olmlib.verifySignature(
-                        alice.crypto._olmDevice,
+                        alice.crypto.olmDevice,
                         content["@alice:example.com"][
                             "nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk"
                             ],
                         "@alice:example.com",
-                        "Osborne2", alice.crypto._olmDevice.deviceEd25519Key,
+                        "Osborne2", alice.crypto.olmDevice.deviceEd25519Key,
                     );
                     olmlib.pkVerify(
                         content["@alice:example.com"]["Osborne2"],
@@ -222,7 +222,7 @@ describe("Cross Signing", function() {
             });
         });
 
-        const deviceInfo = alice.crypto._deviceList._devices["@alice:example.com"]
+        const deviceInfo = alice.crypto.deviceList.devices["@alice:example.com"]
             .Osborne2;
         const aliceDevice = {
             user_id: "@alice:example.com",
@@ -230,7 +230,7 @@ describe("Cross Signing", function() {
         };
         aliceDevice.keys = deviceInfo.keys;
         aliceDevice.algorithms = deviceInfo.algorithms;
-        await alice.crypto._signObject(aliceDevice);
+        await alice.crypto.signObject(aliceDevice);
         olmlib.pkSign(aliceDevice, selfSigningKey, "@alice:example.com");
 
         // feed sync result that includes master key, ssk, device key
@@ -358,7 +358,7 @@ describe("Cross Signing", function() {
                 ["ed25519:" + bobMasterPubkey]: sskSig,
             },
         };
-        alice.crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeCrossSigningForUser("@bob:example.com", {
             keys: {
                 master: {
                     user_id: "@bob:example.com",
@@ -387,7 +387,7 @@ describe("Cross Signing", function() {
                 ["ed25519:" + bobPubkey]: sig,
             },
         };
-        alice.crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeDevicesForUser("@bob:example.com", {
             Dynabook: bobDevice,
         });
         // Bob's device key should be TOFU
@@ -421,8 +421,8 @@ describe("Cross Signing", function() {
             null,
             aliceKeys,
         );
-        alice.crypto._deviceList.startTrackingDeviceList("@bob:example.com");
-        alice.crypto._deviceList.stopTrackingAllDeviceLists = () => {};
+        alice.crypto.deviceList.startTrackingDeviceList("@bob:example.com");
+        alice.crypto.deviceList.stopTrackingAllDeviceLists = () => {};
         alice.uploadDeviceSigningKeys = async () => {};
         alice.uploadKeySignatures = async () => {};
 
@@ -437,14 +437,14 @@ describe("Cross Signing", function() {
         ]);
 
         const keyChangePromise = new Promise((resolve, reject) => {
-            alice.crypto._deviceList.once("userCrossSigningUpdated", (userId) => {
+            alice.crypto.deviceList.once("userCrossSigningUpdated", (userId) => {
                 if (userId === "@bob:example.com") {
                     resolve();
                 }
             });
         });
 
-        const deviceInfo = alice.crypto._deviceList._devices["@alice:example.com"]
+        const deviceInfo = alice.crypto.deviceList.devices["@alice:example.com"]
             .Osborne2;
         const aliceDevice = {
             user_id: "@alice:example.com",
@@ -452,7 +452,7 @@ describe("Cross Signing", function() {
         };
         aliceDevice.keys = deviceInfo.keys;
         aliceDevice.algorithms = deviceInfo.algorithms;
-        await alice.crypto._signObject(aliceDevice);
+        await alice.crypto.signObject(aliceDevice);
 
         const bobOlmAccount = new global.Olm.Account();
         bobOlmAccount.create();
@@ -606,7 +606,7 @@ describe("Cross Signing", function() {
                 ["ed25519:" + bobMasterPubkey]: sskSig,
             },
         };
-        alice.crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeCrossSigningForUser("@bob:example.com", {
             keys: {
                 master: {
                     user_id: "@bob:example.com",
@@ -629,7 +629,7 @@ describe("Cross Signing", function() {
                 "ed25519:Dynabook": "someOtherPubkey",
             },
         };
-        alice.crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeDevicesForUser("@bob:example.com", {
             Dynabook: bobDevice,
         });
         // Bob's device key should be untrusted
@@ -673,7 +673,7 @@ describe("Cross Signing", function() {
                 ["ed25519:" + bobMasterPubkey]: sskSig,
             },
         };
-        alice.crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeCrossSigningForUser("@bob:example.com", {
             keys: {
                 master: {
                     user_id: "@bob:example.com",
@@ -701,7 +701,7 @@ describe("Cross Signing", function() {
         bobDevice.signatures = {};
         bobDevice.signatures["@bob:example.com"] = {};
         bobDevice.signatures["@bob:example.com"]["ed25519:" + bobPubkey] = sig;
-        alice.crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeDevicesForUser("@bob:example.com", {
             Dynabook: bobDevice,
         });
         // Alice verifies Bob's SSK
@@ -733,7 +733,7 @@ describe("Cross Signing", function() {
                 ["ed25519:" + bobMasterPubkey2]: sskSig2,
             },
         };
-        alice.crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeCrossSigningForUser("@bob:example.com", {
             keys: {
                 master: {
                     user_id: "@bob:example.com",
@@ -770,7 +770,7 @@ describe("Cross Signing", function() {
         // Alice gets new signature for device
         const sig2 = bobSigning2.sign(bobDeviceString);
         bobDevice.signatures["@bob:example.com"]["ed25519:" + bobPubkey2] = sig2;
-        alice.crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeDevicesForUser("@bob:example.com", {
             Dynabook: bobDevice,
         });
 
@@ -805,20 +805,20 @@ describe("Cross Signing", function() {
         bob.uploadKeySignatures = async () => {};
         // set Bob's cross-signing key
         await resetCrossSigningKeys(bob);
-        alice.crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+        alice.crypto.deviceList.storeDevicesForUser("@bob:example.com", {
             Dynabook: {
                 algorithms: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"],
                 keys: {
-                    "curve25519:Dynabook": bob.crypto._olmDevice.deviceCurve25519Key,
-                    "ed25519:Dynabook": bob.crypto._olmDevice.deviceEd25519Key,
+                    "curve25519:Dynabook": bob.crypto.olmDevice.deviceCurve25519Key,
+                    "ed25519:Dynabook": bob.crypto.olmDevice.deviceEd25519Key,
                 },
                 verified: 1,
                 known: true,
             },
         });
-        alice.crypto._deviceList.storeCrossSigningForUser(
+        alice.crypto.deviceList.storeCrossSigningForUser(
             "@bob:example.com",
-            bob.crypto._crossSigningInfo.toStorage(),
+            bob.crypto.crossSigningInfo.toStorage(),
         );
 
         alice.uploadDeviceSigningKeys = async () => {};
@@ -838,7 +838,7 @@ describe("Cross Signing", function() {
         expect(bobTrust.isTofu()).toBeTruthy();
 
         // "forget" that Bob is trusted
-        delete alice.crypto._deviceList._crossSigningInfo["@bob:example.com"]
+        delete alice.crypto.deviceList.crossSigningInfo["@bob:example.com"]
             .keys.master.signatures["@alice:example.com"];
 
         const bobTrust2 = alice.checkUserTrust("@bob:example.com");
@@ -848,7 +848,7 @@ describe("Cross Signing", function() {
         upgradePromise = new Promise((resolve) => {
             upgradeResolveFunc = resolve;
         });
-        alice.crypto._deviceList.emit("userCrossSigningUpdated", "@bob:example.com");
+        alice.crypto.deviceList.emit("userCrossSigningUpdated", "@bob:example.com");
         await new Promise((resolve) => {
             alice.crypto.on("userTrustStatusChanged", resolve);
         });

spec/unit/crypto/crypto-utils.js

@@ -8,26 +8,26 @@ export async function resetCrossSigningKeys(client, {
 } = {}) {
     const crypto = client.crypto;
 
-    const oldKeys = Object.assign({}, crypto._crossSigningInfo.keys);
+    const oldKeys = Object.assign({}, crypto.crossSigningInfo.keys);
     try {
-        await crypto._crossSigningInfo.resetKeys(level);
-        await crypto._signObject(crypto._crossSigningInfo.keys.master);
+        await crypto.crossSigningInfo.resetKeys(level);
+        await crypto.signObject(crypto.crossSigningInfo.keys.master);
         // write a copy locally so we know these are trusted keys
-        await crypto._cryptoStore.doTxn(
+        await crypto.cryptoStore.doTxn(
             'readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT],
             (txn) => {
-                crypto._cryptoStore.storeCrossSigningKeys(
-                    txn, crypto._crossSigningInfo.keys);
+                crypto.cryptoStore.storeCrossSigningKeys(
+                    txn, crypto.crossSigningInfo.keys);
             },
         );
     } catch (e) {
         // If anything failed here, revert the keys so we know to try again from the start
         // next time.
-        crypto._crossSigningInfo.keys = oldKeys;
+        crypto.crossSigningInfo.keys = oldKeys;
         throw e;
     }
-    crypto._baseApis.emit("crossSigning.keysChanged", {});
-    await crypto._afterCrossSigningLocalKeyChange();
+    crypto.baseApis.emit("crossSigning.keysChanged", {});
+    await crypto.afterCrossSigningLocalKeyChange();
 }
 
 export async function createSecretStorageKey() {

spec/unit/crypto/outgoing-room-key-requests.spec.js

@@ -21,25 +21,23 @@ import { MemoryCryptoStore } from '../../../src/crypto/store/memory-crypto-store
 import 'fake-indexeddb/auto';
 import 'jest-localstorage-mock';
 
-import {
-    ROOM_KEY_REQUEST_STATES,
-} from '../../../src/crypto/OutgoingRoomKeyRequestManager';
+import { RoomKeyRequestState } from '../../../src/crypto/OutgoingRoomKeyRequestManager';
 
 const requests = [
     {
         requestId: "A",
         requestBody: { session_id: "A", room_id: "A" },
-        state: ROOM_KEY_REQUEST_STATES.SENT,
+        state: RoomKeyRequestState.Sent,
     },
     {
         requestId: "B",
         requestBody: { session_id: "B", room_id: "B" },
-        state: ROOM_KEY_REQUEST_STATES.SENT,
+        state: RoomKeyRequestState.Sent,
     },
     {
         requestId: "C",
         requestBody: { session_id: "C", room_id: "C" },
-        state: ROOM_KEY_REQUEST_STATES.UNSENT,
+        state: RoomKeyRequestState.Unsent,
     },
 ];
 
@@ -68,9 +66,9 @@ describe.each([
     it("getAllOutgoingRoomKeyRequestsByState retrieves all entries in a given state",
     async () => {
         const r = await
-            store.getAllOutgoingRoomKeyRequestsByState(ROOM_KEY_REQUEST_STATES.SENT);
+            store.getAllOutgoingRoomKeyRequestsByState(RoomKeyRequestState.Sent);
         expect(r).toHaveLength(2);
-        requests.filter((e) => e.state == ROOM_KEY_REQUEST_STATES.SENT).forEach((e) => {
+        requests.filter((e) => e.state === RoomKeyRequestState.Sent).forEach((e) => {
             expect(r).toContainEqual(e);
         });
     });
@@ -78,10 +76,10 @@ describe.each([
     test("getOutgoingRoomKeyRequestByState retrieves any entry in a given state",
     async () => {
         const r =
-            await store.getOutgoingRoomKeyRequestByState([ROOM_KEY_REQUEST_STATES.SENT]);
+            await store.getOutgoingRoomKeyRequestByState([RoomKeyRequestState.Sent]);
         expect(r).not.toBeNull();
         expect(r).not.toBeUndefined();
-        expect(r.state).toEqual(ROOM_KEY_REQUEST_STATES.SENT);
+        expect(r.state).toEqual(RoomKeyRequestState.Sent);
         expect(requests).toContainEqual(r);
     });
 });

spec/unit/crypto/secrets.spec.js

@@ -99,11 +99,11 @@ describe("Secrets", function() {
                 },
             },
         );
-        alice.crypto._crossSigningInfo.setKeys({
+        alice.crypto.crossSigningInfo.setKeys({
             master: signingkeyInfo,
         });
 
-        const secretStorage = alice.crypto._secretStorage;
+        const secretStorage = alice.crypto.secretStorage;
 
         alice.setAccountData = async function(eventType, contents, callback) {
             alice.store.storeAccountDataEvents([
@@ -120,7 +120,7 @@ describe("Secrets", function() {
         const keyAccountData = {
             algorithm: SECRET_STORAGE_ALGORITHM_V1_AES,
         };
-        await alice.crypto._crossSigningInfo.signObject(keyAccountData, 'master');
+        await alice.crypto.crossSigningInfo.signObject(keyAccountData, 'master');
 
         alice.store.storeAccountDataEvents([
             new MatrixEvent({
@@ -234,11 +234,11 @@ describe("Secrets", function() {
             },
         );
 
-        const vaxDevice = vax.client.crypto._olmDevice;
-        const osborne2Device = osborne2.client.crypto._olmDevice;
-        const secretStorage = osborne2.client.crypto._secretStorage;
+        const vaxDevice = vax.client.crypto.olmDevice;
+        const osborne2Device = osborne2.client.crypto.olmDevice;
+        const secretStorage = osborne2.client.crypto.secretStorage;
 
-        osborne2.client.crypto._deviceList.storeDevicesForUser("@alice:example.com", {
+        osborne2.client.crypto.deviceList.storeDevicesForUser("@alice:example.com", {
             "VAX": {
                 user_id: "@alice:example.com",
                 device_id: "VAX",
@@ -249,7 +249,7 @@ describe("Secrets", function() {
                 },
             },
         });
-        vax.client.crypto._deviceList.storeDevicesForUser("@alice:example.com", {
+        vax.client.crypto.deviceList.storeDevicesForUser("@alice:example.com", {
             "Osborne2": {
                 user_id: "@alice:example.com",
                 device_id: "Osborne2",
@@ -265,7 +265,7 @@ describe("Secrets", function() {
         const otks = (await osborne2Device.getOneTimeKeys()).curve25519;
         await osborne2Device.markKeysAsPublished();
 
-        await vax.client.crypto._olmDevice.createOutboundSession(
+        await vax.client.crypto.olmDevice.createOutboundSession(
             osborne2Device.deviceCurve25519Key,
             Object.values(otks)[0],
         );
@@ -334,8 +334,8 @@ describe("Secrets", function() {
                 createSecretStorageKey,
             });
 
-            const crossSigning = bob.crypto._crossSigningInfo;
-            const secretStorage = bob.crypto._secretStorage;
+            const crossSigning = bob.crypto.crossSigningInfo;
+            const secretStorage = bob.crypto.secretStorage;
 
             expect(crossSigning.getId()).toBeTruthy();
             expect(await crossSigning.isStoredInSecretStorage(secretStorage))
@@ -376,10 +376,10 @@ describe("Secrets", function() {
                 ]);
                 this.emit("accountData", event);
             };
-            bob.crypto._backupManager.checkKeyBackup = async () => {};
+            bob.crypto.backupManager.checkKeyBackup = async () => {};
 
-            const crossSigning = bob.crypto._crossSigningInfo;
-            const secretStorage = bob.crypto._secretStorage;
+            const crossSigning = bob.crypto.crossSigningInfo;
+            const secretStorage = bob.crypto.secretStorage;
 
             // Set up cross-signing keys from scratch with specific storage key
             await bob.bootstrapCrossSigning({
@@ -394,7 +394,7 @@ describe("Secrets", function() {
             });
 
             // Clear local cross-signing keys and read from secret storage
-            bob.crypto._deviceList.storeCrossSigningForUser(
+            bob.crypto.deviceList.storeCrossSigningForUser(
                 "@bob:example.com",
                 crossSigning.toStorage(),
             );
@@ -479,7 +479,7 @@ describe("Secrets", function() {
                     },
                 }),
             ]);
-            alice.crypto._deviceList.storeCrossSigningForUser("@alice:example.com", {
+            alice.crypto.deviceList.storeCrossSigningForUser("@alice:example.com", {
                 keys: {
                     master: {
                         user_id: "@alice:example.com",
@@ -619,7 +619,7 @@ describe("Secrets", function() {
                     },
                 }),
             ]);
-            alice.crypto._deviceList.storeCrossSigningForUser("@alice:example.com", {
+            alice.crypto.deviceList.storeCrossSigningForUser("@alice:example.com", {
                 keys: {
                     master: {
                         user_id: "@alice:example.com",

spec/unit/crypto/verification/request.spec.js

@@ -49,7 +49,7 @@ describe("verification request integration tests with crypto layer", function()
                 verificationMethods: [verificationMethods.SAS],
             },
         );
-        alice.client.crypto._deviceList.getRawStoredDevicesForUser = function() {
+        alice.client.crypto.deviceList.getRawStoredDevicesForUser = function() {
             return {
                 Dynabook: {
                     keys: {

spec/unit/crypto/verification/sas.spec.js

@@ -87,8 +87,8 @@ describe("SAS verification", function() {
                 },
             );
 
-            const aliceDevice = alice.client.crypto._olmDevice;
-            const bobDevice = bob.client.crypto._olmDevice;
+            const aliceDevice = alice.client.crypto.olmDevice;
+            const bobDevice = bob.client.crypto.olmDevice;
 
             ALICE_DEVICES = {
                 Osborne2: {
@@ -114,14 +114,14 @@ describe("SAS verification", function() {
                 },
             };
 
-            alice.client.crypto._deviceList.storeDevicesForUser(
+            alice.client.crypto.deviceList.storeDevicesForUser(
                 "@bob:example.com", BOB_DEVICES,
             );
             alice.client.downloadKeys = () => {
                 return Promise.resolve();
             };
 
-            bob.client.crypto._deviceList.storeDevicesForUser(
+            bob.client.crypto.deviceList.storeDevicesForUser(
                 "@alice:example.com", ALICE_DEVICES,
             );
             bob.client.downloadKeys = () => {
@@ -296,9 +296,9 @@ describe("SAS verification", function() {
 
             await resetCrossSigningKeys(bob.client);
 
-            bob.client.crypto._deviceList.storeCrossSigningForUser(
+            bob.client.crypto.deviceList.storeCrossSigningForUser(
                 "@alice:example.com", {
-                    keys: alice.client.crypto._crossSigningInfo.keys,
+                    keys: alice.client.crypto.crossSigningInfo.keys,
                 },
             );
 

spec/unit/crypto/verification/secret_request.spec.js

@@ -48,18 +48,18 @@ describe("self-verifications", () => {
             storeCrossSigningKeyCache: jest.fn(),
         };
 
-        const _crossSigningInfo = new CrossSigningInfo(
+        const crossSigningInfo = new CrossSigningInfo(
             userId,
             {},
             cacheCallbacks,
         );
-        _crossSigningInfo.keys = {
+        crossSigningInfo.keys = {
             master: { keys: { X: testKeyPub } },
             self_signing: { keys: { X: testKeyPub } },
             user_signing: { keys: { X: testKeyPub } },
         };
 
-        const _secretStorage = {
+        const secretStorage = {
             request: jest.fn().mockReturnValue({
                 promise: Promise.resolve(encodeBase64(testKey)),
             }),
@@ -70,12 +70,12 @@ describe("self-verifications", () => {
 
         const client = {
             crypto: {
-                _crossSigningInfo,
-                _secretStorage,
+                crossSigningInfo,
+                secretStorage,
                 storeSessionBackupPrivateKey,
                 getSessionBackupPrivateKey: () => null,
             },
-            requestSecret: _secretStorage.request.bind(_secretStorage),
+            requestSecret: secretStorage.request.bind(secretStorage),
             getUserId: () => userId,
             getKeyBackupVersion: () => Promise.resolve({}),
             restoreKeyBackupWithCache,
@@ -99,7 +99,7 @@ describe("self-verifications", () => {
 
         /* We should request, and store, 3 cross signing keys and the key backup key */
         expect(cacheCallbacks.storeCrossSigningKeyCache.mock.calls.length).toBe(3);
-        expect(_secretStorage.request.mock.calls.length).toBe(4);
+        expect(secretStorage.request.mock.calls.length).toBe(4);
 
         expect(cacheCallbacks.storeCrossSigningKeyCache.mock.calls[0][1])
           .toEqual(testKey);

spec/unit/event-timeline.spec.js

@@ -3,8 +3,8 @@ import { EventTimeline } from "../../src/models/event-timeline";
 import { RoomState } from "../../src/models/room-state";
 
 function mockRoomStates(timeline) {
-    timeline._startState = utils.mock(RoomState, "startState");
-    timeline._endState = utils.mock(RoomState, "endState");
+    timeline.startState = utils.mock(RoomState, "startState");
+    timeline.endState = utils.mock(RoomState, "endState");
 }
 
 describe("EventTimeline", function() {
@@ -48,10 +48,10 @@ describe("EventTimeline", function() {
                 }),
             ];
             timeline.initialiseState(events);
-            expect(timeline._startState.setStateEvents).toHaveBeenCalledWith(
+            expect(timeline.startState.setStateEvents).toHaveBeenCalledWith(
                 events,
             );
-            expect(timeline._endState.setStateEvents).toHaveBeenCalledWith(
+            expect(timeline.endState.setStateEvents).toHaveBeenCalledWith(
                 events,
             );
         });

spec/unit/models/MSC3089TreeSpace.spec.ts

@@ -25,6 +25,7 @@ import {
 } from "../../../src/models/MSC3089TreeSpace";
 import { DEFAULT_ALPHABET } from "../../../src/utils";
 import { MockBlob } from "../../MockBlob";
+import { MatrixError } from "../../../src/http-api";
 
 describe("MSC3089TreeSpace", () => {
     let client: MatrixClient;
@@ -93,7 +94,7 @@ describe("MSC3089TreeSpace", () => {
             });
         client.sendStateEvent = fn;
         await tree.setName(newName);
-        expect(fn.mock.calls.length).toBe(1);
+        expect(fn).toHaveBeenCalledTimes(1);
     });
 
     it('should support inviting users to the space', async () => {
@@ -104,8 +105,113 @@ describe("MSC3089TreeSpace", () => {
             return Promise.resolve();
         });
         client.invite = fn;
-        await tree.invite(target);
-        expect(fn.mock.calls.length).toBe(1);
+        await tree.invite(target, false, false);
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should retry invites to the space', async () => {
+        const target = targetUser;
+        const fn = jest.fn().mockImplementation((inviteRoomId: string, userId: string) => {
+            expect(inviteRoomId).toEqual(roomId);
+            expect(userId).toEqual(target);
+            if (fn.mock.calls.length === 1) return Promise.reject(new Error("Sample Failure"));
+            return Promise.resolve();
+        });
+        client.invite = fn;
+        await tree.invite(target, false, false);
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not retry invite permission errors', async () => {
+        const target = targetUser;
+        const fn = jest.fn().mockImplementation((inviteRoomId: string, userId: string) => {
+            expect(inviteRoomId).toEqual(roomId);
+            expect(userId).toEqual(target);
+            return Promise.reject(new MatrixError({ errcode: "M_FORBIDDEN", error: "Sample Failure" }));
+        });
+        client.invite = fn;
+        try {
+            await tree.invite(target, false, false);
+
+            // noinspection ExceptionCaughtLocallyJS
+            throw new Error("Failed to fail");
+        } catch (e) {
+            expect(e.errcode).toEqual("M_FORBIDDEN");
+        }
+
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should invite to subspaces', async () => {
+        const target = targetUser;
+        const fn = jest.fn().mockImplementation((inviteRoomId: string, userId: string) => {
+            expect(inviteRoomId).toEqual(roomId);
+            expect(userId).toEqual(target);
+            return Promise.resolve();
+        });
+        client.invite = fn;
+        tree.getDirectories = () => [
+            // Bare minimum overrides. We proxy to our mock function manually so we can
+            // count the calls, not to ensure accuracy. The invite function behaving correctly
+            // is covered by another test.
+            { invite: (userId) => fn(tree.roomId, userId) } as MSC3089TreeSpace,
+            { invite: (userId) => fn(tree.roomId, userId) } as MSC3089TreeSpace,
+            { invite: (userId) => fn(tree.roomId, userId) } as MSC3089TreeSpace,
+        ];
+
+        await tree.invite(target, true, false);
+        expect(fn).toHaveBeenCalledTimes(4);
+    });
+
+    it('should share keys with invitees', async () => {
+        const target = targetUser;
+        const sendKeysFn = jest.fn().mockImplementation((inviteRoomId: string, userIds: string[]) => {
+            expect(inviteRoomId).toEqual(roomId);
+            expect(userIds).toMatchObject([target]);
+            return Promise.resolve();
+        });
+        client.invite = () => Promise.resolve(); // we're not testing this here - see other tests
+        client.sendSharedHistoryKeys = sendKeysFn;
+
+        // Mock the history check as best as possible
+        const historyVis = "shared";
+        const historyFn = jest.fn().mockImplementation((eventType: string, stateKey?: string) => {
+            // We're not expecting a super rigid test: the function that calls this internally isn't
+            // really being tested here.
+            expect(eventType).toEqual(EventType.RoomHistoryVisibility);
+            expect(stateKey).toEqual("");
+            return { getContent: () => ({ history_visibility: historyVis }) }; // eslint-disable-line camelcase
+        });
+        room.currentState.getStateEvents = historyFn;
+
+        // Note: inverse test is implicit from other tests, which disable the call stack of this
+        // test in order to pass.
+        await tree.invite(target, false, true);
+        expect(sendKeysFn).toHaveBeenCalledTimes(1);
+        expect(historyFn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not share keys with invitees if inappropriate history visibility', async () => {
+        const target = targetUser;
+        const sendKeysFn = jest.fn().mockImplementation((inviteRoomId: string, userIds: string[]) => {
+            expect(inviteRoomId).toEqual(roomId);
+            expect(userIds).toMatchObject([target]);
+            return Promise.resolve();
+        });
+        client.invite = () => Promise.resolve(); // we're not testing this here - see other tests
+        client.sendSharedHistoryKeys = sendKeysFn;
+
+        const historyVis = "joined"; // NOTE: Changed.
+        const historyFn = jest.fn().mockImplementation((eventType: string, stateKey?: string) => {
+            expect(eventType).toEqual(EventType.RoomHistoryVisibility);
+            expect(stateKey).toEqual("");
+            return { getContent: () => ({ history_visibility: historyVis }) }; // eslint-disable-line camelcase
+        });
+        room.currentState.getStateEvents = historyFn;
+
+        await tree.invite(target, false, true);
+        expect(sendKeysFn).toHaveBeenCalledTimes(0);
+        expect(historyFn).toHaveBeenCalledTimes(1);
     });
 
     async function evaluatePowerLevels(pls: any, role: TreePermissions, expectedPl: number) {

spec/unit/models/event.spec.ts

@@ -0,0 +1,60 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { MatrixEvent } from "../../../src/models/event";
+
+describe('MatrixEvent', () => {
+    it('should create copies of itself', () => {
+        const a = new MatrixEvent({
+            type: "com.example.test",
+            content: {
+                isTest: true,
+                num: 42,
+            },
+        });
+
+        const clone = a.toSnapshot();
+        expect(clone).toBeDefined();
+        expect(clone).not.toBe(a);
+        expect(clone.event).not.toBe(a.event);
+        expect(clone.event).toMatchObject(a.event);
+
+        // The other properties we're not super interested in, honestly.
+    });
+
+    it('should compare itself to other events using json', () => {
+        const a = new MatrixEvent({
+            type: "com.example.test",
+            content: {
+                isTest: true,
+                num: 42,
+            },
+        });
+        const b = new MatrixEvent({
+            type: "com.example.test______B",
+            content: {
+                isTest: true,
+                num: 42,
+            },
+        });
+        expect(a.isEquivalentTo(b)).toBe(false);
+        expect(a.isEquivalentTo(a)).toBe(true);
+        expect(b.isEquivalentTo(a)).toBe(false);
+        expect(b.isEquivalentTo(b)).toBe(true);
+        expect(a.toSnapshot().isEquivalentTo(a)).toBe(true);
+        expect(a.toSnapshot().isEquivalentTo(b)).toBe(false);
+    });
+});

spec/unit/room-member.spec.js

@@ -124,6 +124,34 @@ describe("RoomMember", function() {
             expect(member.powerLevel).toEqual(0);
             expect(emitCount).toEqual(1);
         });
+
+        it("should not honor string power levels.",
+        function() {
+            const event = utils.mkEvent({
+                type: "m.room.power_levels",
+                room: roomId,
+                user: userA,
+                content: {
+                    users_default: 20,
+                    users: {
+                        "@alice:bar": "5",
+                    },
+                },
+                event: true,
+            });
+            let emitCount = 0;
+
+            member.on("RoomMember.powerLevel", function(emitEvent, emitMember) {
+                emitCount += 1;
+                expect(emitMember.userId).toEqual('@alice:bar');
+                expect(emitMember.powerLevel).toEqual(20);
+                expect(emitEvent).toEqual(event);
+            });
+
+            member.setPowerLevelEvent(event);
+            expect(member.powerLevel).toEqual(20);
+            expect(emitCount).toEqual(1);
+        });
     });
 
     describe("setTypingEvent", function() {

spec/unit/room-state.spec.js

@@ -1,6 +1,5 @@
 import * as utils from "../test-utils";
 import { RoomState } from "../../src/models/room-state";
-import { RoomMember } from "../../src/models/room-member";
 
 describe("RoomState", function() {
     const roomId = "!foo:bar";
@@ -193,12 +192,7 @@ describe("RoomState", function() {
             expect(emitCount).toEqual(2);
         });
 
-        it("should call setPowerLevelEvent on each RoomMember for m.room.power_levels",
-        function() {
-            // mock up the room members
-            state.members[userA] = utils.mock(RoomMember);
-            state.members[userB] = utils.mock(RoomMember);
-
+        it("should call setPowerLevelEvent on each RoomMember for m.room.power_levels", function() {
             const powerLevelEvent = utils.mkEvent({
                 type: "m.room.power_levels", room: roomId, user: userA, event: true,
                 content: {
@@ -208,18 +202,16 @@ describe("RoomState", function() {
                 },
             });
 
+            // spy on the room members
+            jest.spyOn(state.members[userA], "setPowerLevelEvent");
+            jest.spyOn(state.members[userB], "setPowerLevelEvent");
             state.setStateEvents([powerLevelEvent]);
 
-            expect(state.members[userA].setPowerLevelEvent).toHaveBeenCalledWith(
-                powerLevelEvent,
-            );
-            expect(state.members[userB].setPowerLevelEvent).toHaveBeenCalledWith(
-                powerLevelEvent,
-            );
+            expect(state.members[userA].setPowerLevelEvent).toHaveBeenCalledWith(powerLevelEvent);
+            expect(state.members[userB].setPowerLevelEvent).toHaveBeenCalledWith(powerLevelEvent);
         });
 
-        it("should call setPowerLevelEvent on a new RoomMember if power levels exist",
-        function() {
+        it("should call setPowerLevelEvent on a new RoomMember if power levels exist", function() {
             const memberEvent = utils.mkMembership({
                 mship: "join", user: userC, room: roomId, event: true,
             });
@@ -243,13 +235,12 @@ describe("RoomState", function() {
         });
 
         it("should call setMembershipEvent on the right RoomMember", function() {
-            // mock up the room members
-            state.members[userA] = utils.mock(RoomMember);
-            state.members[userB] = utils.mock(RoomMember);
-
             const memberEvent = utils.mkMembership({
                 user: userB, mship: "leave", room: roomId, event: true,
             });
+            // spy on the room members
+            jest.spyOn(state.members[userA], "setMembershipEvent");
+            jest.spyOn(state.members[userB], "setMembershipEvent");
             state.setStateEvents([memberEvent]);
 
             expect(state.members[userA].setMembershipEvent).not.toHaveBeenCalled();
@@ -374,17 +365,13 @@ describe("RoomState", function() {
                     user_ids: [userA],
                 },
             });
-            // mock up the room members
-            state.members[userA] = utils.mock(RoomMember);
-            state.members[userB] = utils.mock(RoomMember);
+            // spy on the room members
+            jest.spyOn(state.members[userA], "setTypingEvent");
+            jest.spyOn(state.members[userB], "setTypingEvent");
             state.setTypingEvent(typingEvent);
 
-            expect(state.members[userA].setTypingEvent).toHaveBeenCalledWith(
-                typingEvent,
-            );
-            expect(state.members[userB].setTypingEvent).toHaveBeenCalledWith(
-                typingEvent,
-            );
+            expect(state.members[userA].setTypingEvent).toHaveBeenCalledWith(typingEvent);
+            expect(state.members[userB].setTypingEvent).toHaveBeenCalledWith(typingEvent);
         });
     });
 

spec/unit/room.spec.js

@@ -1,8 +1,9 @@
 import * as utils from "../test-utils";
-import { EventStatus, MatrixEvent } from "../../src/models/event";
+import { EventStatus, MatrixEvent } from "../../src";
 import { EventTimeline } from "../../src/models/event-timeline";
-import { RoomState } from "../../src/models/room-state";
-import { Room } from "../../src/models/room";
+import { RoomState } from "../../src";
+import { Room } from "../../src";
+import { UNSTABLE_ELEMENT_FUNCTIONAL_USERS } from "../../src/@types/event";
 import { TestClient } from "../TestClient";
 
 describe("Room", function() {
@@ -16,9 +17,9 @@ describe("Room", function() {
     beforeEach(function() {
         room = new Room(roomId);
         // mock RoomStates
-        room.oldState = room.getLiveTimeline()._startState =
+        room.oldState = room.getLiveTimeline().startState =
             utils.mock(RoomState, "oldState");
-        room.currentState = room.getLiveTimeline()._endState =
+        room.currentState = room.getLiveTimeline().endState =
             utils.mock(RoomState, "currentState");
     });
 
@@ -86,9 +87,11 @@ describe("Room", function() {
         ];
 
         it("should call RoomState.setTypingEvent on m.typing events", function() {
-            room.currentState = utils.mock(RoomState);
             const typing = utils.mkEvent({
-                room: roomId, type: "m.typing", event: true, content: {
+                room: roomId,
+                type: "m.typing",
+                event: true,
+                content: {
                     user_ids: [userA],
                 },
             });
@@ -140,8 +143,8 @@ describe("Room", function() {
             expect(callCount).toEqual(2);
         });
 
-        it("should call setStateEvents on the right RoomState with the right " +
-        "forwardLooking value for new events", function() {
+        it("should call setStateEvents on the right RoomState with the right forwardLooking value for new events",
+        function() {
             const events = [
                 utils.mkMembership({
                     room: roomId, mship: "invite", user: userB, skey: userA, event: true,
@@ -652,7 +655,8 @@ describe("Room", function() {
                 const roomName = "flibble";
 
                 const event = addMember(userA, "invite");
-                event.event.invite_room_state = [
+                event.event.unsigned = {};
+                event.event.unsigned.invite_room_state = [
                     {
                         type: "m.room.name",
                         state_key: "",
@@ -671,7 +675,8 @@ describe("Room", function() {
                 const roomName = "flibble";
                 setRoomName(roomName);
                 const roomNameToIgnore = "ignoreme";
-                event.event.invite_room_state = [
+                event.event.unsigned = {};
+                event.event.unsigned.invite_room_state = [
                     {
                         type: "m.room.name",
                         state_key: "",
@@ -1452,4 +1457,291 @@ describe("Room", function() {
             expect(room.maySendMessage()).toEqual(true);
         });
     });
+
+    describe("getDefaultRoomName", function() {
+        it("should return 'Empty room' if a user is the only member",
+        function() {
+            const room = new Room(roomId, null, userA);
+            expect(room.getDefaultRoomName(userA)).toEqual("Empty room");
+        });
+
+        it("should return a display name if one other member is in the room",
+        function() {
+            const room = new Room(roomId, null, userA);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userA, mship: "join",
+                    room: roomId, event: true, name: "User A",
+                }),
+                utils.mkMembership({
+                    user: userB, mship: "join",
+                    room: roomId, event: true, name: "User B",
+                }),
+            ]);
+            expect(room.getDefaultRoomName(userA)).toEqual("User B");
+        });
+
+        it("should return a display name if one other member is banned",
+        function() {
+            const room = new Room(roomId, null, userA);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userA, mship: "join",
+                    room: roomId, event: true, name: "User A",
+                }),
+                utils.mkMembership({
+                    user: userB, mship: "ban",
+                    room: roomId, event: true, name: "User B",
+                }),
+            ]);
+            expect(room.getDefaultRoomName(userA)).toEqual("Empty room (was User B)");
+        });
+
+        it("should return a display name if one other member is invited",
+        function() {
+            const room = new Room(roomId, null, userA);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userA, mship: "join",
+                    room: roomId, event: true, name: "User A",
+                }),
+                utils.mkMembership({
+                    user: userB, mship: "invite",
+                    room: roomId, event: true, name: "User B",
+                }),
+            ]);
+            expect(room.getDefaultRoomName(userA)).toEqual("User B");
+        });
+
+        it("should return 'Empty room (was User B)' if User B left the room",
+        function() {
+            const room = new Room(roomId, null, userA);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userA, mship: "join",
+                    room: roomId, event: true, name: "User A",
+                }),
+                utils.mkMembership({
+                    user: userB, mship: "leave",
+                    room: roomId, event: true, name: "User B",
+                }),
+            ]);
+            expect(room.getDefaultRoomName(userA)).toEqual("Empty room (was User B)");
+        });
+
+        it("should return 'User B and User C' if in a room with two other users",
+        function() {
+            const room = new Room(roomId, null, userA);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userA, mship: "join",
+                    room: roomId, event: true, name: "User A",
+                }),
+                utils.mkMembership({
+                    user: userB, mship: "join",
+                    room: roomId, event: true, name: "User B",
+                }),
+                utils.mkMembership({
+                    user: userC, mship: "join",
+                    room: roomId, event: true, name: "User C",
+                }),
+            ]);
+            expect(room.getDefaultRoomName(userA)).toEqual("User B and User C");
+        });
+
+        it("should return 'User B and 2 others' if in a room with three other users",
+        function() {
+            const room = new Room(roomId, null, userA);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userA, mship: "join",
+                    room: roomId, event: true, name: "User A",
+                }),
+                utils.mkMembership({
+                    user: userB, mship: "join",
+                    room: roomId, event: true, name: "User B",
+                }),
+                utils.mkMembership({
+                    user: userC, mship: "join",
+                    room: roomId, event: true, name: "User C",
+                }),
+                utils.mkMembership({
+                    user: userD, mship: "join",
+                    room: roomId, event: true, name: "User D",
+                }),
+            ]);
+            expect(room.getDefaultRoomName(userA)).toEqual("User B and 2 others");
+        });
+
+        describe("io.element.functional_users", function() {
+            it("should return a display name (default behaviour) if no one is marked as a functional member",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true,
+                        content: {
+                            service_members: [],
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("User B");
+            });
+
+            it("should return a display name (default behaviour) if service members is a number (invalid)",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true,
+                        content: {
+                            service_members: 1,
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("User B");
+            });
+
+            it("should return a display name (default behaviour) if service members is a string (invalid)",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true,
+                        content: {
+                            service_members: userB,
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("User B");
+            });
+
+            it("should return 'Empty room' if the only other member is a functional member",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true,
+                        content: {
+                            service_members: [userB],
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("Empty room");
+            });
+
+            it("should return 'User B' if User B is the only other member who isn't a functional member",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkMembership({
+                        user: userC, mship: "join",
+                        room: roomId, event: true, name: "User C",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true, user: userA,
+                        content: {
+                            service_members: [userC],
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("User B");
+            });
+
+            it("should return 'Empty room' if all other members are functional members",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkMembership({
+                        user: userC, mship: "join",
+                        room: roomId, event: true, name: "User C",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true, user: userA,
+                        content: {
+                            service_members: [userB, userC],
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("Empty room");
+            });
+
+            it("should not break if an unjoined user is marked as a service user",
+            function() {
+                const room = new Room(roomId, null, userA);
+                room.addLiveEvents([
+                    utils.mkMembership({
+                        user: userA, mship: "join",
+                        room: roomId, event: true, name: "User A",
+                    }),
+                    utils.mkMembership({
+                        user: userB, mship: "join",
+                        room: roomId, event: true, name: "User B",
+                    }),
+                    utils.mkEvent({
+                        type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name, skey: "",
+                        room: roomId, event: true, user: userA,
+                        content: {
+                            service_members: [userC],
+                        },
+                    }),
+                ]);
+                expect(room.getDefaultRoomName(userA)).toEqual("User B");
+            });
+        });
+    });
 });

spec/unit/utils.spec.ts

@@ -3,10 +3,12 @@ import {
     alphabetPad,
     averageBetweenStrings,
     baseToString,
+    deepSortedObjectEntries,
     DEFAULT_ALPHABET,
     lexicographicCompare,
     nextString,
     prevString,
+    simpleRetryOperation,
     stringToBase,
 } from "../../src/utils";
 import { logger } from "../../src/logger";
@@ -267,6 +269,34 @@ describe("utils", function() {
         });
     });
 
+    describe('simpleRetryOperation', () => {
+        it('should retry', async () => {
+            let count = 0;
+            const val = {};
+            const fn = (attempt) => {
+                count++;
+
+                // If this expectation fails then it can appear as a Jest Timeout due to
+                // the retry running beyond the test limit.
+                expect(attempt).toEqual(count);
+
+                if (count > 1) {
+                    return Promise.resolve(val);
+                } else {
+                    return Promise.reject(new Error("Iterative failure"));
+                }
+            };
+
+            const ret = await simpleRetryOperation(fn);
+            expect(ret).toBe(val);
+            expect(count).toEqual(2);
+        });
+
+        // We don't test much else of the function because then we're just testing that the
+        // underlying library behaves, which should be tested on its own. Our API surface is
+        // all that concerns us.
+    });
+
     describe('DEFAULT_ALPHABET', () => {
         it('should be usefully printable ASCII in order', () => {
             expect(DEFAULT_ALPHABET).toEqual(
@@ -429,4 +459,38 @@ describe("utils", function() {
             expect(lexicographicCompare('a', 'A') > 0).toBe(true);
         });
     });
+
+    describe('deepSortedObjectEntries', () => {
+        it('should auto-return non-objects', () => {
+            expect(deepSortedObjectEntries(42)).toEqual(42);
+            expect(deepSortedObjectEntries("not object")).toEqual("not object");
+            expect(deepSortedObjectEntries(true)).toEqual(true);
+            expect(deepSortedObjectEntries([42])).toEqual([42]);
+            expect(deepSortedObjectEntries(null)).toEqual(null);
+            expect(deepSortedObjectEntries(undefined)).toEqual(undefined);
+        });
+
+        it('should sort objects appropriately', () => {
+            const input = {
+                a: 42,
+                b: {
+                    d: {},
+                    a: "test",
+                    b: "alpha",
+                },
+                [72]: "test",
+            };
+            const output = [
+                ["72", "test"],
+                ["a", 42],
+                ["b", [
+                    ["a", "test"],
+                    ["b", "alpha"],
+                    ["d", []],
+                ]],
+            ];
+
+            expect(deepSortedObjectEntries(input)).toMatchObject(output);
+        });
+    });
 });

src/@types/PushRules.ts

@@ -0,0 +1,164 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// allow camelcase as these are things that go onto the wire
+/* eslint-disable camelcase */
+
+export enum PushRuleActionName {
+    DontNotify = "dont_notify",
+    Notify = "notify",
+    Coalesce = "coalesce",
+}
+
+export enum TweakName {
+    Highlight = "highlight",
+    Sound = "sound",
+}
+
+export type Tweak<N extends TweakName, V> = {
+    set_tweak: N;
+    value: V;
+};
+
+export type TweakHighlight = Tweak<TweakName.Highlight, boolean>;
+export type TweakSound = Tweak<TweakName.Sound, string>;
+
+export type Tweaks = TweakHighlight | TweakSound;
+
+export enum ConditionOperator {
+    ExactEquals = "==",
+    LessThan = "<",
+    GreaterThan = ">",
+    GreaterThanOrEqual = ">=",
+    LessThanOrEqual = "<=",
+}
+
+export type PushRuleAction = Tweaks | PushRuleActionName;
+
+export type MemberCountCondition
+    <N extends number, Op extends ConditionOperator = ConditionOperator.ExactEquals>
+    = `${Op}${N}` | (Op extends ConditionOperator.ExactEquals ? `${N}` : never);
+
+export type AnyMemberCountCondition = MemberCountCondition<number, ConditionOperator>;
+
+export const DMMemberCountCondition: MemberCountCondition<2> = "2";
+
+export function isDmMemberCountCondition(condition: AnyMemberCountCondition): boolean {
+    return condition === "==2" || condition === "2";
+}
+
+export enum ConditionKind {
+    EventMatch = "event_match",
+    ContainsDisplayName = "contains_display_name",
+    RoomMemberCount = "room_member_count",
+    SenderNotificationPermission = "sender_notification_permission",
+}
+
+export interface IPushRuleCondition<N extends ConditionKind | string> {
+    [k: string]: any; // for custom conditions, there can be other fields here
+    kind: N;
+}
+
+export interface IEventMatchCondition extends IPushRuleCondition<ConditionKind.EventMatch> {
+    key: string;
+    pattern: string;
+}
+
+export interface IContainsDisplayNameCondition extends IPushRuleCondition<ConditionKind.ContainsDisplayName> {
+    // no additional fields
+}
+
+export interface IRoomMemberCountCondition extends IPushRuleCondition<ConditionKind.RoomMemberCount> {
+    is: AnyMemberCountCondition;
+}
+
+export interface ISenderNotificationPermissionCondition
+    extends IPushRuleCondition<ConditionKind.SenderNotificationPermission> {
+    key: string;
+}
+
+export type PushRuleCondition = IPushRuleCondition<string>
+    | IEventMatchCondition
+    | IContainsDisplayNameCondition
+    | IRoomMemberCountCondition
+    | ISenderNotificationPermissionCondition;
+
+export enum PushRuleKind {
+    Override = "override",
+    ContentSpecific = "content",
+    RoomSpecific = "room",
+    SenderSpecific = "sender",
+    Underride = "underride",
+}
+
+export enum RuleId {
+    Master = ".m.rule.master",
+    ContainsDisplayName = ".m.rule.contains_display_name",
+    ContainsUserName = ".m.rule.contains_user_name",
+    AtRoomNotification = ".m.rule.roomnotif",
+    DM = ".m.rule.room_one_to_one",
+    EncryptedDM = ".m.rule.encrypted_room_one_to_one",
+    Message = ".m.rule.message",
+    EncryptedMessage = ".m.rule.encrypted",
+    InviteToSelf = ".m.rule.invite_for_me",
+    MemberEvent = ".m.rule.member_event",
+    IncomingCall = ".m.rule.call",
+    SuppressNotices = ".m.rule.suppress_notices",
+    Tombstone = ".m.rule.tombstone",
+}
+
+export type PushRuleSet = {
+    [k in PushRuleKind]?: IPushRule[];
+};
+
+export interface IPushRule {
+    actions: PushRuleAction[];
+    conditions?: PushRuleCondition[];
+    default: boolean;
+    enabled: boolean;
+    pattern?: string;
+    rule_id: RuleId | string;
+}
+
+export interface IAnnotatedPushRule extends IPushRule {
+    kind: PushRuleKind;
+}
+
+export interface IPushRules {
+    global: PushRuleSet;
+    device?: PushRuleSet;
+}
+
+export interface IPusher {
+    app_display_name: string;
+    app_id: string;
+    data: {
+        format?: string; // TODO: Types
+        url?: string; // TODO: Required if kind==http
+        brand?: string; // TODO: For email notifications only?
+    };
+    device_display_name: string;
+    kind: string; // TODO: Types
+    lang: string;
+    profile_tag?: string;
+    pushkey: string;
+}
+
+export interface IPusherRequest extends IPusher {
+    append?: boolean;
+}
+
+/* eslint-enable camelcase */

src/@types/another-json.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -14,7 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-export const SERVICE_TYPES = Object.freeze({
-    IS: 'SERVICE_TYPE_IS', // An Identity Service
-    IM: 'SERVICE_TYPE_IM', // An Integration Manager
-});
+declare module "another-json" {
+    export function stringify(o: object): string;
+}

src/@types/event.ts

@@ -87,6 +87,11 @@ export enum EventType {
     Dummy = "m.dummy",
 }
 
+export enum RelationType {
+    Annotation = "m.annotation",
+    Replace = "m.replace",
+}
+
 export enum MsgType {
     Text = "m.text",
     Emote = "m.emote",
@@ -139,6 +144,28 @@ export const UNSTABLE_MSC3089_LEAF = new UnstableValue("m.leaf", "org.matrix.msc
  */
 export const UNSTABLE_MSC3089_BRANCH = new UnstableValue("m.branch", "org.matrix.msc3089.branch");
 
+/**
+ * Functional members type for declaring a purpose of room members (e.g. helpful bots).
+ * Note that this reference is UNSTABLE and subject to breaking changes, including its
+ * eventual removal.
+ *
+ * Schema (TypeScript):
+ * {
+ *   service_members?: string[]
+ * }
+ *
+ * Example:
+ * {
+ *   "service_members": [
+ *     "@helperbot:localhost",
+ *     "@reminderbot:alice.tdl"
+ *   ]
+ * }
+ */
+export const UNSTABLE_ELEMENT_FUNCTIONAL_USERS = new UnstableValue(
+    "io.element.functional_members",
+    "io.element.functional_members");
+
 export interface IEncryptedFile {
     url: string;
     mimetype?: string;

src/@types/global.d.ts

@@ -15,11 +15,17 @@ limitations under the License.
 */
 
 // this is needed to tell TS about global.Olm
-import * as Olm from "@matrix-org/olm"; // eslint-disable-line @typescript-eslint/no-unused-vars
+import "@matrix-org/olm";
 
 export {};
 
 declare global {
+    // use `number` as the return type in all cases for global.set{Interval,Timeout},
+    // so we don't accidentally use the methods on NodeJS.Timeout - they only exist in a subset of environments.
+    // The overload for clear{Interval,Timeout} is resolved as expected.
+    function setInterval(handler: TimerHandler, timeout: number, ...arguments: any[]): number;
+    function setTimeout(handler: TimerHandler, timeout: number, ...arguments: any[]): number;
+
     namespace NodeJS {
         interface Global {
             localStorage: Storage;
@@ -34,6 +40,10 @@ declare global {
         getDesktopCapturerSources(options: GetSourcesOptions): Promise<Array<DesktopCapturerSource>>;
     }
 
+    interface Crypto {
+        webkitSubtle?: Window["crypto"]["subtle"];
+    }
+
     interface MediaDevices {
         // This is experimental and types don't know about it yet
         // https://github.com/microsoft/TypeScript/issues/33232
@@ -84,4 +94,17 @@ declare global {
         // on webkit: we should check if we still need to do this
         webkitGetUserMedia: DummyInterfaceWeShouldntBeUsingThis;
     }
+
+    export interface ISettledFulfilled<T> {
+        status: "fulfilled";
+        value: T;
+    }
+    export interface ISettledRejected {
+        status: "rejected";
+        reason: any;
+    }
+
+    interface PromiseConstructor {
+        allSettled<T>(promises: Promise<T>[]): Promise<Array<ISettledFulfilled<T> | ISettledRejected>>;
+    }
 }

src/@types/partials.ts

@@ -37,3 +37,40 @@ export enum Preset {
     TrustedPrivateChat = "trusted_private_chat",
     PublicChat = "public_chat",
 }
+
+export type ResizeMethod = "crop" | "scale";
+
+// TODO move to http-api after TSification
+export interface IAbortablePromise<T> extends Promise<T> {
+    abort(): void;
+}
+
+export type IdServerUnbindResult = "no-support" | "success";
+
+// Knock and private are reserved keywords which are not yet implemented.
+export enum JoinRule {
+    Public = "public",
+    Invite = "invite",
+    /**
+     * @deprecated Reserved keyword. Should not be used. Not yet implemented.
+     */
+    Private = "private",
+    Knock = "knock", // MSC2403 - only valid inside experimental room versions at this time.
+    Restricted = "restricted", // MSC3083 - only valid inside experimental room versions at this time.
+}
+
+export enum RestrictedAllowType {
+    RoomMembership = "m.room_membership", // MSC3083 - only valid inside experimental room versions at this time.
+}
+
+export enum GuestAccess {
+    CanJoin = "can_join",
+    Forbidden = "forbidden",
+}
+
+export enum HistoryVisibility {
+    Invited = "invited",
+    Joined = "joined",
+    Shared = "shared",
+    WorldReadable = "world_readable",
+}

src/@types/requests.ts

@@ -15,9 +15,12 @@ limitations under the License.
 */
 
 import { Callback } from "../client";
+import { IContent } from "../models/event";
 import { Preset, Visibility } from "./partials";
+import { SearchKey } from "./search";
+import { IRoomEventFilter } from "../filter";
 
-// allow camelcase as these are things go onto the wire
+// allow camelcase as these are things that go onto the wire
 /* eslint-disable camelcase */
 
 export interface IJoinRoomOpts {
@@ -63,12 +66,12 @@ export interface IGuestAccessOpts {
 }
 
 export interface ISearchOpts {
-    keys?: string[];
+    keys?: SearchKey[];
     query: string;
 }
 
 export interface IEventSearchOpts {
-    filter: any; // TODO: Types
+    filter?: IRoomEventFilter;
     term: string;
 }
 
@@ -82,7 +85,7 @@ export interface IInvite3PID {
 export interface ICreateRoomStateEvent {
     type: string;
     state_key?: string; // defaults to an empty string
-    content: object;
+    content: IContent;
 }
 
 export interface ICreateRoomOpts {
@@ -104,9 +107,11 @@ export interface IRoomDirectoryOptions {
     server?: string;
     limit?: number;
     since?: string;
-
-    // TODO: Proper types
-    filter?: any & {generic_search_term: string};
+    filter?: {
+        generic_search_term: string;
+    };
+    include_all_networks?: boolean;
+    third_party_instance_id?: string;
 }
 
 export interface IUploadOpts {
@@ -119,4 +124,19 @@ export interface IUploadOpts {
     progressHandler?: (state: {loaded: number, total: number}) => void;
 }
 
+export interface IAddThreePidOnlyBody {
+    auth?: {
+        type: string;
+        session?: string;
+    };
+    client_secret: string;
+    sid: string;
+}
+
+export interface IBindThreePidBody {
+    client_secret: string;
+    id_server: string;
+    id_access_token: string;
+    sid: string;
+}
 /* eslint-enable camelcase */

src/@types/search.ts

@@ -0,0 +1,118 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Types relating to the /search API
+
+import { IRoomEvent, IStateEvent } from "../sync-accumulator";
+import { IRoomEventFilter } from "../filter";
+import { SearchResult } from "../models/search-result";
+
+/* eslint-disable camelcase */
+export interface IEventWithRoomId extends IRoomEvent {
+    room_id: string;
+}
+
+export interface IStateEventWithRoomId extends IStateEvent {
+    room_id: string;
+}
+
+export interface IMatrixProfile {
+    avatar_url?: string;
+    displayname?: string;
+}
+
+export interface IResultContext {
+    events_before: IEventWithRoomId[];
+    events_after: IEventWithRoomId[];
+    profile_info: Record<string, IMatrixProfile>;
+    start?: string;
+    end?: string;
+}
+
+export interface ISearchResult {
+    rank: number;
+    result: IEventWithRoomId;
+    context: IResultContext;
+}
+
+enum GroupKey {
+    RoomId = "room_id",
+    Sender = "sender",
+}
+
+export interface IResultRoomEvents {
+    count: number;
+    highlights: string[];
+    results: ISearchResult[];
+    state?: { [roomId: string]: IStateEventWithRoomId[] };
+    groups?: {
+        [groupKey in GroupKey]: {
+            [value: string]: {
+                next_batch?: string;
+                order: number;
+                results: string[];
+            };
+        };
+    };
+    next_batch?: string;
+}
+
+interface IResultCategories {
+    room_events: IResultRoomEvents;
+}
+
+export type SearchKey = "content.body" | "content.name" | "content.topic";
+
+export enum SearchOrderBy {
+    Recent = "recent",
+    Rank = "rank",
+}
+
+export interface ISearchRequestBody {
+    search_categories: {
+        room_events: {
+            search_term: string;
+            keys?: SearchKey[];
+            filter?: IRoomEventFilter;
+            order_by?: SearchOrderBy;
+            event_context?: {
+                before_limit?: number;
+                after_limit?: number;
+                include_profile?: boolean;
+            };
+            include_state?: boolean;
+            groupings?: {
+                group_by: {
+                    key: GroupKey;
+                }[];
+            };
+        };
+    };
+}
+
+export interface ISearchResponse {
+    search_categories: IResultCategories;
+}
+
+export interface ISearchResults {
+    _query?: ISearchRequestBody;
+    results: SearchResult[];
+    highlights: string[];
+    count?: number;
+    next_batch?: string;
+    pendingRequest?: Promise<ISearchResults>;
+}
+/* eslint-enable camelcase */

src/@types/signed.ts

@@ -19,3 +19,7 @@ export interface ISignatures {
         [keyId: string]: string;
     };
 }
+
+export interface ISigned {
+    signatures?: ISignatures;
+}

src/@types/spaces.ts

@@ -0,0 +1,40 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { IPublicRoomsChunkRoom } from "../client";
+
+// Types relating to Rooms of type `m.space` and related APIs
+
+/* eslint-disable camelcase */
+export interface ISpaceSummaryRoom extends IPublicRoomsChunkRoom {
+    num_refs: number;
+    room_type: string;
+}
+
+export interface ISpaceSummaryEvent {
+    room_id: string;
+    event_id: string;
+    origin_server_ts: number;
+    type: string;
+    state_key: string;
+    content: {
+        order?: string;
+        suggested?: boolean;
+        auto_join?: boolean;
+        via?: string[];
+    };
+}
+/* eslint-enable camelcase */

src/@types/synapse.ts

@@ -0,0 +1,40 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { IdServerUnbindResult } from "./partials";
+
+// Types relating to Synapse Admin APIs
+
+/* eslint-disable camelcase */
+export interface ISynapseAdminWhoisResponse {
+    user_id: string;
+    devices: {
+        [deviceId: string]: {
+            sessions: {
+                connections: {
+                    ip: string;
+                    last_seen: number; // millis since epoch
+                    user_agent: string;
+                }[];
+            }[];
+        };
+    };
+}
+
+export interface ISynapseAdminDeactivateResponse {
+    id_server_unbind_result: IdServerUnbindResult;
+}
+/* eslint-enable camelcase */

src/@types/threepids.ts

@@ -0,0 +1,28 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export enum ThreepidMedium {
+    Email = "email",
+    Phone = "msisdn",
+}
+
+// TODO: Are these types universal, or specific to just /account/3pid?
+export interface IThreepid {
+    medium: ThreepidMedium;
+    address: string;
+    validated_at: number; // eslint-disable-line camelcase
+    added_at: number; // eslint-disable-line camelcase
+}

src/content-helpers.ts

@@ -1,6 +1,6 @@
 /*
 Copyright 2018 New Vector Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2018 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -17,15 +17,17 @@ limitations under the License.
 
 /** @module ContentHelpers */
 
+import { MsgType } from "./@types/event";
+
 /**
  * Generates the content for a HTML Message event
  * @param {string} body the plaintext body of the message
  * @param {string} htmlBody the HTML representation of the message
  * @returns {{msgtype: string, format: string, body: string, formatted_body: string}}
  */
-export function makeHtmlMessage(body, htmlBody) {
+export function makeHtmlMessage(body: string, htmlBody: string) {
     return {
-        msgtype: "m.text",
+        msgtype: MsgType.Text,
         format: "org.matrix.custom.html",
         body: body,
         formatted_body: htmlBody,
@@ -38,9 +40,9 @@ export function makeHtmlMessage(body, htmlBody) {
  * @param {string} htmlBody the HTML representation of the notice
  * @returns {{msgtype: string, format: string, body: string, formatted_body: string}}
  */
-export function makeHtmlNotice(body, htmlBody) {
+export function makeHtmlNotice(body: string, htmlBody: string) {
     return {
-        msgtype: "m.notice",
+        msgtype: MsgType.Notice,
         format: "org.matrix.custom.html",
         body: body,
         formatted_body: htmlBody,
@@ -53,9 +55,9 @@ export function makeHtmlNotice(body, htmlBody) {
  * @param {string} htmlBody the HTML representation of the emote
  * @returns {{msgtype: string, format: string, body: string, formatted_body: string}}
  */
-export function makeHtmlEmote(body, htmlBody) {
+export function makeHtmlEmote(body: string, htmlBody: string) {
     return {
-        msgtype: "m.emote",
+        msgtype: MsgType.Emote,
         format: "org.matrix.custom.html",
         body: body,
         formatted_body: htmlBody,
@@ -67,9 +69,9 @@ export function makeHtmlEmote(body, htmlBody) {
  * @param {string} body the plaintext body of the emote
  * @returns {{msgtype: string, body: string}}
  */
-export function makeTextMessage(body) {
+export function makeTextMessage(body: string) {
     return {
-        msgtype: "m.text",
+        msgtype: MsgType.Text,
         body: body,
     };
 }
@@ -79,9 +81,9 @@ export function makeTextMessage(body) {
  * @param {string} body the plaintext body of the notice
  * @returns {{msgtype: string, body: string}}
  */
-export function makeNotice(body) {
+export function makeNotice(body: string) {
     return {
-        msgtype: "m.notice",
+        msgtype: MsgType.Notice,
         body: body,
     };
 }
@@ -91,9 +93,9 @@ export function makeNotice(body) {
  * @param {string} body the plaintext body of the emote
  * @returns {{msgtype: string, body: string}}
  */
-export function makeEmoteMessage(body) {
+export function makeEmoteMessage(body: string) {
     return {
-        msgtype: "m.emote",
+        msgtype: MsgType.Emote,
         body: body,
     };
 }

src/content-repo.ts

@@ -1,6 +1,5 @@
 /*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -34,8 +33,14 @@ import * as utils from "./utils";
  * for such URLs.
  * @return {string} The complete URL to the content.
  */
-export function getHttpUriForMxc(baseUrl, mxc, width, height,
-                           resizeMethod, allowDirectLinks) {
+export function getHttpUriForMxc(
+    baseUrl: string,
+    mxc: string,
+    width: number,
+    height: number,
+    resizeMethod: string,
+    allowDirectLinks = false,
+): string {
     if (typeof mxc !== "string" || !mxc) {
         return '';
     }
@@ -51,13 +56,13 @@ export function getHttpUriForMxc(baseUrl, mxc, width, height,
     const params = {};
 
     if (width) {
-        params.width = Math.round(width);
+        params["width"] = Math.round(width);
     }
     if (height) {
-        params.height = Math.round(height);
+        params["height"] = Math.round(height);
     }
     if (resizeMethod) {
-        params.method = resizeMethod;
+        params["method"] = resizeMethod;
     }
     if (Object.keys(params).length > 0) {
         // these are thumbnailing params so they probably want the
@@ -71,7 +76,7 @@ export function getHttpUriForMxc(baseUrl, mxc, width, height,
         fragment = serverAndMediaId.substr(fragmentOffset);
         serverAndMediaId = serverAndMediaId.substr(0, fragmentOffset);
     }
-    return baseUrl + prefix + serverAndMediaId +
-        (Object.keys(params).length === 0 ? "" :
-        ("?" + utils.encodeParams(params))) + fragment;
+
+    const urlParams = (Object.keys(params).length === 0 ? "" : ("?" + utils.encodeParams(params)));
+    return baseUrl + prefix + serverAndMediaId + urlParams + fragment;
 }

src/crypto/CrossSigning.ts

@@ -1,6 +1,5 @@
 /*
-Copyright 2019 New Vector Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2019 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -20,22 +19,44 @@ limitations under the License.
  * @module crypto/CrossSigning
  */
 
-import { decodeBase64, encodeBase64, pkSign, pkVerify } from './olmlib';
 import { EventEmitter } from 'events';
+
+import { decodeBase64, encodeBase64, pkSign, pkVerify } from './olmlib';
 import { logger } from '../logger';
 import { IndexedDBCryptoStore } from '../crypto/store/indexeddb-crypto-store';
 import { decryptAES, encryptAES } from './aes';
+import { PkSigning } from "@matrix-org/olm";
+import { DeviceInfo } from "./deviceinfo";
+import { SecretStorage } from "./SecretStorage";
+import { CryptoStore, ICrossSigningKey, ISignedKey, MatrixClient } from "../client";
+import { OlmDevice } from "./OlmDevice";
+import { ICryptoCallbacks } from "../matrix";
+import { ISignatures } from "../@types/signed";
 
 const KEY_REQUEST_TIMEOUT_MS = 1000 * 60;
 
-function publicKeyFromKeyInfo(keyInfo) {
+function publicKeyFromKeyInfo(keyInfo: ICrossSigningKey): string {
     // `keys` is an object with { [`ed25519:${pubKey}`]: pubKey }
     // We assume only a single key, and we want the bare form without type
     // prefix, so we select the values.
     return Object.values(keyInfo.keys)[0];
 }
 
+export interface ICacheCallbacks {
+    getCrossSigningKeyCache?(type: string, expectedPublicKey?: string): Promise<Uint8Array>;
+    storeCrossSigningKeyCache?(type: string, key: Uint8Array): Promise<void>;
+}
+
 export class CrossSigningInfo extends EventEmitter {
+    public keys: Record<string, ICrossSigningKey> = {};
+    public firstUse = true;
+    // This tracks whether we've ever verified this user with any identity.
+    // When you verify a user, any devices online at the time that receive
+    // the verifying signature via the homeserver will latch this to true
+    // and can use it in the future to detect cases where the user has
+    // become unverified later for any reason.
+    private crossSigningVerifiedBefore = false;
+
     /**
      * Information about a user's cross-signing keys
      *
@@ -46,27 +67,15 @@ export class CrossSigningInfo extends EventEmitter {
      *     Requires getCrossSigningKey and saveCrossSigningKeys
      * @param {object} cacheCallbacks Callbacks used to interact with the cache
      */
-    constructor(userId, callbacks, cacheCallbacks) {
+    constructor(
+        public readonly userId: string,
+        private callbacks: ICryptoCallbacks = {},
+        private cacheCallbacks: ICacheCallbacks = {},
+    ) {
         super();
-
-        // you can't change the userId
-        Object.defineProperty(this, 'userId', {
-            enumerable: true,
-            value: userId,
-        });
-        this._callbacks = callbacks || {};
-        this._cacheCallbacks = cacheCallbacks || {};
-        this.keys = {};
-        this.firstUse = true;
-        // This tracks whether we've ever verified this user with any identity.
-        // When you verify a user, any devices online at the time that receive
-        // the verifying signature via the homeserver will latch this to true
-        // and can use it in the future to detect cases where the user has
-        // become unverifed later for any reason.
-        this.crossSigningVerifiedBefore = false;
     }
 
-    static fromStorage(obj, userId) {
+    public static fromStorage(obj: object, userId: string): CrossSigningInfo {
         const res = new CrossSigningInfo(userId);
         for (const prop in obj) {
             if (obj.hasOwnProperty(prop)) {
@@ -76,7 +85,7 @@ export class CrossSigningInfo extends EventEmitter {
         return res;
     }
 
-    toStorage() {
+    public toStorage(): object {
         return {
             keys: this.keys,
             firstUse: this.firstUse,
@@ -92,10 +101,10 @@ export class CrossSigningInfo extends EventEmitter {
      *     the stored public key for the given key type.
      * @returns {Array} An array with [ public key, Olm.PkSigning ]
      */
-    async getCrossSigningKey(type, expectedPubkey) {
+    public async getCrossSigningKey(type: string, expectedPubkey?: string): Promise<[string, PkSigning]> {
         const shouldCache = ["master", "self_signing", "user_signing"].indexOf(type) >= 0;
 
-        if (!this._callbacks.getCrossSigningKey) {
+        if (!this.callbacks.getCrossSigningKey) {
             throw new Error("No getCrossSigningKey callback supplied");
         }
 
@@ -103,7 +112,7 @@ export class CrossSigningInfo extends EventEmitter {
             expectedPubkey = this.getId(type);
         }
 
-        function validateKey(key) {
+        function validateKey(key: Uint8Array): [string, PkSigning] {
             if (!key) return;
             const signing = new global.Olm.PkSigning();
             const gotPubkey = signing.init_with_seed(key);
@@ -114,9 +123,8 @@ export class CrossSigningInfo extends EventEmitter {
         }
 
         let privkey;
-        if (this._cacheCallbacks.getCrossSigningKeyCache && shouldCache) {
-            privkey = await this._cacheCallbacks
-              .getCrossSigningKeyCache(type, expectedPubkey);
+        if (this.cacheCallbacks.getCrossSigningKeyCache && shouldCache) {
+            privkey = await this.cacheCallbacks.getCrossSigningKeyCache(type, expectedPubkey);
         }
 
         const cacheresult = validateKey(privkey);
@@ -124,11 +132,11 @@ export class CrossSigningInfo extends EventEmitter {
             return cacheresult;
         }
 
-        privkey = await this._callbacks.getCrossSigningKey(type, expectedPubkey);
+        privkey = await this.callbacks.getCrossSigningKey(type, expectedPubkey);
         const result = validateKey(privkey);
         if (result) {
-            if (this._cacheCallbacks.storeCrossSigningKeyCache && shouldCache) {
-                await this._cacheCallbacks.storeCrossSigningKeyCache(type, privkey);
+            if (this.cacheCallbacks.storeCrossSigningKeyCache && shouldCache) {
+                await this.cacheCallbacks.storeCrossSigningKeyCache(type, privkey);
             }
             return result;
         }
@@ -156,10 +164,9 @@ export class CrossSigningInfo extends EventEmitter {
      *     with, or null if it is not present or not encrypted with a trusted
      *     key
      */
-    async isStoredInSecretStorage(secretStorage) {
+    public async isStoredInSecretStorage(secretStorage: SecretStorage): Promise<Record<string, object>> {
         // check what SSSS keys have encrypted the master key (if any)
-        const stored =
-              await secretStorage.isStored("m.cross_signing.master", false) || {};
+        const stored = await secretStorage.isStored("m.cross_signing.master", false) || {};
         // then check which of those SSSS keys have also encrypted the SSK and USK
         function intersect(s) {
             for (const k of Object.keys(stored)) {
@@ -169,9 +176,7 @@ export class CrossSigningInfo extends EventEmitter {
             }
         }
         for (const type of ["self_signing", "user_signing"]) {
-            intersect(
-                await secretStorage.isStored(`m.cross_signing.${type}`, false) || {},
-            );
+            intersect(await secretStorage.isStored(`m.cross_signing.${type}`, false) || {});
         }
         return Object.keys(stored).length ? stored : null;
     }
@@ -184,7 +189,10 @@ export class CrossSigningInfo extends EventEmitter {
      * @param {Map} keys The keys to store
      * @param {SecretStorage} secretStorage The secret store using account data
      */
-    static async storeInSecretStorage(keys, secretStorage) {
+    public static async storeInSecretStorage(
+        keys: Map<string, Uint8Array>,
+        secretStorage: SecretStorage,
+    ): Promise<void> {
         for (const [type, privateKey] of keys) {
             const encodedKey = encodeBase64(privateKey);
             await secretStorage.store(`m.cross_signing.${type}`, encodedKey);
@@ -200,7 +208,7 @@ export class CrossSigningInfo extends EventEmitter {
      * @param {SecretStorage} secretStorage The secret store using account data
      * @return {Uint8Array} The private key
      */
-    static async getFromSecretStorage(type, secretStorage) {
+    public static async getFromSecretStorage(type: string, secretStorage: SecretStorage): Promise<Uint8Array> {
         const encodedKey = await secretStorage.get(`m.cross_signing.${type}`);
         if (!encodedKey) {
             return null;
@@ -215,8 +223,8 @@ export class CrossSigningInfo extends EventEmitter {
      * "self_signing", or "user_signing". Optional, will check all by default.
      * @returns {boolean} True if all keys are stored in the local cache.
      */
-    async isStoredInKeyCache(type) {
-        const cacheCallbacks = this._cacheCallbacks;
+    public async isStoredInKeyCache(type?: string): Promise<boolean> {
+        const cacheCallbacks = this.cacheCallbacks;
         if (!cacheCallbacks) return false;
         const types = type ? [type] : ["master", "self_signing", "user_signing"];
         for (const t of types) {
@@ -232,9 +240,9 @@ export class CrossSigningInfo extends EventEmitter {
      *
      * @returns {Map} A map from key type (string) to private key (Uint8Array)
      */
-    async getCrossSigningKeysFromCache() {
+    public async getCrossSigningKeysFromCache(): Promise<Map<string, Uint8Array>> {
         const keys = new Map();
-        const cacheCallbacks = this._cacheCallbacks;
+        const cacheCallbacks = this.cacheCallbacks;
         if (!cacheCallbacks) return keys;
         for (const type of ["master", "self_signing", "user_signing"]) {
             const privKey = await cacheCallbacks.getCrossSigningKeyCache(type);
@@ -255,8 +263,7 @@ export class CrossSigningInfo extends EventEmitter {
      *
      * @return {string} the ID
      */
-    getId(type) {
-        type = type || "master";
+    public getId(type = "master"): string {
         if (!this.keys[type]) return null;
         const keyInfo = this.keys[type];
         return publicKeyFromKeyInfo(keyInfo);
@@ -269,8 +276,8 @@ export class CrossSigningInfo extends EventEmitter {
      *
      * @param {CrossSigningLevel} level The key types to reset
      */
-    async resetKeys(level) {
-        if (!this._callbacks.saveCrossSigningKeys) {
+    public async resetKeys(level?: CrossSigningLevel): Promise<void> {
+        if (!this.callbacks.saveCrossSigningKeys) {
             throw new Error("No saveCrossSigningKeys callback supplied");
         }
 
@@ -285,12 +292,12 @@ export class CrossSigningInfo extends EventEmitter {
                 CrossSigningLevel.USER_SIGNING |
                 CrossSigningLevel.SELF_SIGNING
             );
-        } else if (level === 0) {
+        } else if (level === 0 as CrossSigningLevel) {
             return;
         }
 
-        const privateKeys = {};
-        const keys = {};
+        const privateKeys: Record<string, Uint8Array> = {};
+        const keys: Record<string, any> = {}; // TODO types
         let masterSigning;
         let masterPub;
 
@@ -347,7 +354,7 @@ export class CrossSigningInfo extends EventEmitter {
             }
 
             Object.assign(this.keys, keys);
-            this._callbacks.saveCrossSigningKeys(privateKeys);
+            this.callbacks.saveCrossSigningKeys(privateKeys);
         } finally {
             if (masterSigning) {
                 masterSigning.free();
@@ -358,12 +365,12 @@ export class CrossSigningInfo extends EventEmitter {
     /**
      * unsets the keys, used when another session has reset the keys, to disable cross-signing
      */
-    clearKeys() {
+    public clearKeys(): void {
         this.keys = {};
     }
 
-    setKeys(keys) {
-        const signingKeys = {};
+    public setKeys(keys: Record<string, ICrossSigningKey>): void {
+        const signingKeys: Record<string, ICrossSigningKey> = {};
         if (keys.master) {
             if (keys.master.user_id !== this.userId) {
                 const error = "Mismatched user ID " + keys.master.user_id +
@@ -434,7 +441,7 @@ export class CrossSigningInfo extends EventEmitter {
         }
     }
 
-    updateCrossSigningVerifiedBefore(isCrossSigningVerified) {
+    public updateCrossSigningVerifiedBefore(isCrossSigningVerified: boolean): void {
         // It is critical that this value latches forward from false to true but
         // never back to false to avoid a downgrade attack.
         if (!this.crossSigningVerifiedBefore && isCrossSigningVerified) {
@@ -442,7 +449,7 @@ export class CrossSigningInfo extends EventEmitter {
         }
     }
 
-    async signObject(data, type) {
+    public async signObject<T extends object>(data: T, type: string): Promise<T & { signatures: ISignatures }> {
         if (!this.keys[type]) {
             throw new Error(
                 "Attempted to sign with " + type + " key but no such key present",
@@ -451,13 +458,13 @@ export class CrossSigningInfo extends EventEmitter {
         const [pubkey, signing] = await this.getCrossSigningKey(type);
         try {
             pkSign(data, signing, this.userId, pubkey);
-            return data;
+            return data as T & { signatures: ISignatures };
         } finally {
             signing.free();
         }
     }
 
-    async signUser(key) {
+    public async signUser(key: CrossSigningInfo): Promise<ICrossSigningKey> {
         if (!this.keys.user_signing) {
             logger.info("No user signing key: not signing user");
             return;
@@ -465,7 +472,7 @@ export class CrossSigningInfo extends EventEmitter {
         return this.signObject(key.keys.master, "user_signing");
     }
 
-    async signDevice(userId, device) {
+    public async signDevice(userId: string, device: DeviceInfo): Promise<ISignedKey> {
         if (userId !== this.userId) {
             throw new Error(
                 `Trying to sign ${userId}'s device; can only sign our own device`,
@@ -475,7 +482,7 @@ export class CrossSigningInfo extends EventEmitter {
             logger.info("No self signing key: not signing device");
             return;
         }
-        return this.signObject(
+        return this.signObject<Omit<ISignedKey, "signatures">>(
             {
                 algorithms: device.algorithms,
                 keys: device.keys,
@@ -492,7 +499,7 @@ export class CrossSigningInfo extends EventEmitter {
      *
      * @returns {UserTrustLevel}
      */
-    checkUserTrust(userCrossSigning) {
+    public checkUserTrust(userCrossSigning: CrossSigningInfo): UserTrustLevel {
         // if we're checking our own key, then it's trusted if the master key
         // and self-signing key match
         if (this.userId === userCrossSigning.userId
@@ -530,12 +537,17 @@ export class CrossSigningInfo extends EventEmitter {
      *
      * @param {CrossSigningInfo} userCrossSigning Cross signing info for user
      * @param {module:crypto/deviceinfo} device The device to check
-     * @param {bool} localTrust Whether the device is trusted locally
-     * @param {bool} trustCrossSignedDevices Whether we trust cross signed devices
+     * @param {boolean} localTrust Whether the device is trusted locally
+     * @param {boolean} trustCrossSignedDevices Whether we trust cross signed devices
      *
      * @returns {DeviceTrustLevel}
      */
-    checkDeviceTrust(userCrossSigning, device, localTrust, trustCrossSignedDevices) {
+    public checkDeviceTrust(
+        userCrossSigning: CrossSigningInfo,
+        device: DeviceInfo,
+        localTrust: boolean,
+        trustCrossSignedDevices: boolean,
+    ): DeviceTrustLevel {
         const userTrust = this.checkUserTrust(userCrossSigning);
 
         const userSSK = userCrossSigning.keys.self_signing;
@@ -552,29 +564,23 @@ export class CrossSigningInfo extends EventEmitter {
             // if we can verify the user's SSK from their master key...
             pkVerify(userSSK, userCrossSigning.getId(), userCrossSigning.userId);
             // ...and this device's key from their SSK...
-            pkVerify(
-                deviceObj, publicKeyFromKeyInfo(userSSK), userCrossSigning.userId,
-            );
+            pkVerify(deviceObj, publicKeyFromKeyInfo(userSSK), userCrossSigning.userId);
             // ...then we trust this device as much as far as we trust the user
-            return DeviceTrustLevel.fromUserTrustLevel(
-                userTrust, localTrust, trustCrossSignedDevices,
-            );
+            return DeviceTrustLevel.fromUserTrustLevel(userTrust, localTrust, trustCrossSignedDevices);
         } catch (e) {
-            return new DeviceTrustLevel(
-                false, false, localTrust, trustCrossSignedDevices,
-            );
+            return new DeviceTrustLevel(false, false, localTrust, trustCrossSignedDevices);
         }
     }
 
     /**
      * @returns {object} Cache callbacks
      */
-    getCacheCallbacks() {
-        return this._cacheCallbacks;
+    public getCacheCallbacks(): ICacheCallbacks {
+        return this.cacheCallbacks;
     }
 }
 
-function deviceToObject(device, userId) {
+function deviceToObject(device: DeviceInfo, userId: string) {
     return {
         algorithms: device.algorithms,
         keys: device.keys,
@@ -584,49 +590,49 @@ function deviceToObject(device, userId) {
     };
 }
 
-export const CrossSigningLevel = {
-    MASTER: 4,
-    USER_SIGNING: 2,
-    SELF_SIGNING: 1,
-};
+export enum CrossSigningLevel {
+    MASTER = 4,
+    USER_SIGNING = 2,
+    SELF_SIGNING = 1,
+}
 
 /**
  * Represents the ways in which we trust a user
  */
 export class UserTrustLevel {
-    constructor(crossSigningVerified, crossSigningVerifiedBefore, tofu) {
-        this._crossSigningVerified = crossSigningVerified;
-        this._crossSigningVerifiedBefore = crossSigningVerifiedBefore;
-        this._tofu = tofu;
-    }
+    constructor(
+        private readonly crossSigningVerified: boolean,
+        private readonly crossSigningVerifiedBefore: boolean,
+        private readonly tofu: boolean,
+    ) {}
 
     /**
-     * @returns {bool} true if this user is verified via any means
+     * @returns {boolean} true if this user is verified via any means
      */
-    isVerified() {
+    public isVerified(): boolean {
         return this.isCrossSigningVerified();
     }
 
     /**
-     * @returns {bool} true if this user is verified via cross signing
+     * @returns {boolean} true if this user is verified via cross signing
      */
-    isCrossSigningVerified() {
-        return this._crossSigningVerified;
+    public isCrossSigningVerified(): boolean {
+        return this.crossSigningVerified;
     }
 
     /**
-     * @returns {bool} true if we ever verified this user before (at least for
+     * @returns {boolean} true if we ever verified this user before (at least for
      * the history of verifications observed by this device).
      */
-    wasCrossSigningVerified() {
-        return this._crossSigningVerifiedBefore;
+    public wasCrossSigningVerified(): boolean {
+        return this.crossSigningVerifiedBefore;
     }
 
     /**
-     * @returns {bool} true if this user's key is trusted on first use
+     * @returns {boolean} true if this user's key is trusted on first use
      */
-    isTofu() {
-        return this._tofu;
+    public isTofu(): boolean {
+        return this.tofu;
     }
 }
 
@@ -634,58 +640,62 @@ export class UserTrustLevel {
  * Represents the ways in which we trust a device
  */
 export class DeviceTrustLevel {
-    constructor(crossSigningVerified, tofu, localVerified, trustCrossSignedDevices) {
-        this._crossSigningVerified = crossSigningVerified;
-        this._tofu = tofu;
-        this._localVerified = localVerified;
-        this._trustCrossSignedDevices = trustCrossSignedDevices;
-    }
+    constructor(
+        public readonly crossSigningVerified: boolean,
+        public readonly tofu: boolean,
+        private readonly localVerified: boolean,
+        private readonly trustCrossSignedDevices: boolean,
+    ) {}
 
-    static fromUserTrustLevel(userTrustLevel, localVerified, trustCrossSignedDevices) {
+    public static fromUserTrustLevel(
+        userTrustLevel: UserTrustLevel,
+        localVerified: boolean,
+        trustCrossSignedDevices: boolean,
+    ): DeviceTrustLevel {
         return new DeviceTrustLevel(
-            userTrustLevel._crossSigningVerified,
-            userTrustLevel._tofu,
+            userTrustLevel.isCrossSigningVerified(),
+            userTrustLevel.isTofu(),
             localVerified,
             trustCrossSignedDevices,
         );
     }
 
     /**
-     * @returns {bool} true if this device is verified via any means
+     * @returns {boolean} true if this device is verified via any means
      */
-    isVerified() {
+    public isVerified(): boolean {
         return Boolean(this.isLocallyVerified() || (
-            this._trustCrossSignedDevices && this.isCrossSigningVerified()
+            this.trustCrossSignedDevices && this.isCrossSigningVerified()
         ));
     }
 
     /**
-     * @returns {bool} true if this device is verified via cross signing
+     * @returns {boolean} true if this device is verified via cross signing
      */
-    isCrossSigningVerified() {
-        return this._crossSigningVerified;
+    public isCrossSigningVerified(): boolean {
+        return this.crossSigningVerified;
     }
 
     /**
-     * @returns {bool} true if this device is verified locally
+     * @returns {boolean} true if this device is verified locally
      */
-    isLocallyVerified() {
-        return this._localVerified;
+    public isLocallyVerified(): boolean {
+        return this.localVerified;
     }
 
     /**
-     * @returns {bool} true if this device is trusted from a user's key
+     * @returns {boolean} true if this device is trusted from a user's key
      * that is trusted on first use
      */
-    isTofu() {
-        return this._tofu;
+    public isTofu(): boolean {
+        return this.tofu;
     }
 }
 
-export function createCryptoStoreCacheCallbacks(store, olmdevice) {
+export function createCryptoStoreCacheCallbacks(store: CryptoStore, olmDevice: OlmDevice): ICacheCallbacks {
     return {
-        getCrossSigningKeyCache: async function(type, _expectedPublicKey) {
-            const key = await new Promise((resolve) => {
+        getCrossSigningKeyCache: async function(type: string, _expectedPublicKey: string): Promise<Uint8Array> {
+            const key = await new Promise<any>((resolve) => {
                 return store.doTxn(
                     'readonly',
                     [IndexedDBCryptoStore.STORE_ACCOUNT],
@@ -696,26 +706,26 @@ export function createCryptoStoreCacheCallbacks(store, olmdevice) {
             });
 
             if (key && key.ciphertext) {
-                const pickleKey = Buffer.from(olmdevice._pickleKey);
+                const pickleKey = Buffer.from(olmDevice._pickleKey);
                 const decrypted = await decryptAES(key, pickleKey, type);
                 return decodeBase64(decrypted);
             } else {
                 return key;
             }
         },
-        storeCrossSigningKeyCache: async function(type, key) {
+        storeCrossSigningKeyCache: async function(type: string, key: Uint8Array): Promise<void> {
             if (!(key instanceof Uint8Array)) {
                 throw new Error(
                     `storeCrossSigningKeyCache expects Uint8Array, got ${key}`,
                 );
             }
-            const pickleKey = Buffer.from(olmdevice._pickleKey);
-            key = await encryptAES(encodeBase64(key), pickleKey, type);
+            const pickleKey = Buffer.from(olmDevice._pickleKey);
+            const encryptedKey = await encryptAES(encodeBase64(key), pickleKey, type);
             return store.doTxn(
                 'readwrite',
                 [IndexedDBCryptoStore.STORE_ACCOUNT],
                 (txn) => {
-                    store.storeSecretStorePrivateKey(txn, type, key);
+                    store.storeSecretStorePrivateKey(txn, type, encryptedKey);
                 },
             );
         },
@@ -729,7 +739,7 @@ export function createCryptoStoreCacheCallbacks(store, olmdevice) {
  * @param {string} userId The user ID being verified
  * @param {string} deviceId The device ID being verified
  */
-export async function requestKeysDuringVerification(baseApis, userId, deviceId) {
+export async function requestKeysDuringVerification(baseApis: MatrixClient, userId: string, deviceId: string) {
     // If this is a self-verification, ask the other party for keys
     if (baseApis.getUserId() !== userId) {
         return;
@@ -739,7 +749,7 @@ export async function requestKeysDuringVerification(baseApis, userId, deviceId)
     // it.  We return here in order to test.
     return new Promise((resolve, reject) => {
         const client = baseApis;
-        const original = client.crypto._crossSigningInfo;
+        const original = client.crypto.crossSigningInfo;
 
         // We already have all of the infrastructure we need to validate and
         // cache cross-signing keys, so instead of replicating that, here we set
@@ -748,8 +758,7 @@ export async function requestKeysDuringVerification(baseApis, userId, deviceId)
         const crossSigning = new CrossSigningInfo(
             original.userId,
             { getCrossSigningKey: async (type) => {
-                logger.debug("Cross-signing: requesting secret",
-                                type, deviceId);
+                logger.debug("Cross-signing: requesting secret", type, deviceId);
                 const { promise } = client.requestSecret(
                     `m.cross_signing.${type}`, [deviceId],
                 );
@@ -757,7 +766,7 @@ export async function requestKeysDuringVerification(baseApis, userId, deviceId)
                 const decoded = decodeBase64(result);
                 return Uint8Array.from(decoded);
             } },
-            original._cacheCallbacks,
+            original.getCacheCallbacks(),
         );
         crossSigning.keys = original.keys;
 
@@ -774,7 +783,7 @@ export async function requestKeysDuringVerification(baseApis, userId, deviceId)
         });
 
         // also request and cache the key backup key
-        const backupKeyPromise = new Promise(async resolve => {
+        const backupKeyPromise = (async () => {
             const cachedKey = await client.crypto.getSessionBackupPrivateKey();
             if (!cachedKey) {
                 logger.info("No cached backup key found. Requesting...");
@@ -791,14 +800,11 @@ export async function requestKeysDuringVerification(baseApis, userId, deviceId)
                 logger.info("Backup key stored. Starting backup restore...");
                 const backupInfo = await client.getKeyBackupVersion();
                 // no need to await for this - just let it go in the bg
-                client.restoreKeyBackupWithCache(
-                    undefined, undefined, backupInfo,
-                ).then(() => {
+                client.restoreKeyBackupWithCache(undefined, undefined, backupInfo).then(() => {
                     logger.info("Backup restored.");
                 });
             }
-            resolve();
-        });
+        })();
 
         // We call getCrossSigningKey() for its side-effects
         return Promise.race([

src/crypto/EncryptionSetup.ts

@@ -1,11 +1,40 @@
+/*
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
 import { logger } from "../logger";
 import { MatrixEvent } from "../models/event";
 import { EventEmitter } from "events";
-import { createCryptoStoreCacheCallbacks } from "./CrossSigning";
+import { createCryptoStoreCacheCallbacks, ICacheCallbacks } from "./CrossSigning";
 import { IndexedDBCryptoStore } from './store/indexeddb-crypto-store';
+import { PREFIX_UNSTABLE } from "../http-api";
+import { Crypto, IBootstrapCrossSigningOpts } from "./index";
 import {
-    PREFIX_UNSTABLE,
-} from "../http-api";
+    CrossSigningKeys,
+    ICrossSigningKey,
+    ICryptoCallbacks,
+    ISignedKey,
+    KeySignatures,
+} from "../matrix";
+import { ISecretStorageKeyInfo } from "./api";
+import { IKeyBackupInfo } from "./keybackup";
+
+interface ICrossSigningKeys {
+    authUpload: IBootstrapCrossSigningOpts["authUploadDeviceSigningKeys"];
+    keys: Record<string, ICrossSigningKey>;
+}
 
 /**
  * Builds an EncryptionSetupOperation by calling any of the add.. methods.
@@ -17,18 +46,23 @@ import {
  * more than once.
  */
 export class EncryptionSetupBuilder {
+    public readonly accountDataClientAdapter: AccountDataClientAdapter;
+    public readonly crossSigningCallbacks: CrossSigningCallbacks;
+    public readonly ssssCryptoCallbacks: SSSSCryptoCallbacks;
+
+    private crossSigningKeys: ICrossSigningKeys = null;
+    private keySignatures: KeySignatures = null;
+    private keyBackupInfo: IKeyBackupInfo = null;
+    private sessionBackupPrivateKey: Uint8Array;
+
     /**
      * @param {Object.<String, MatrixEvent>} accountData pre-existing account data, will only be read, not written.
      * @param {CryptoCallbacks} delegateCryptoCallbacks crypto callbacks to delegate to if the key isn't in cache yet
      */
-    constructor(accountData, delegateCryptoCallbacks) {
+    constructor(accountData: Record<string, MatrixEvent>, delegateCryptoCallbacks: ICryptoCallbacks) {
         this.accountDataClientAdapter = new AccountDataClientAdapter(accountData);
         this.crossSigningCallbacks = new CrossSigningCallbacks();
         this.ssssCryptoCallbacks = new SSSSCryptoCallbacks(delegateCryptoCallbacks);
-
-        this._crossSigningKeys = null;
-        this._keySignatures = null;
-        this._keyBackupInfo = null;
     }
 
     /**
@@ -42,8 +76,8 @@ export class EncryptionSetupBuilder {
      *     an empty authDict, to obtain the flows.
      * @param {Object} keys the new keys
      */
-    addCrossSigningKeys(authUpload, keys) {
-        this._crossSigningKeys = { authUpload, keys };
+    public addCrossSigningKeys(authUpload: ICrossSigningKeys["authUpload"], keys: ICrossSigningKeys["keys"]): void {
+        this.crossSigningKeys = { authUpload, keys };
     }
 
     /**
@@ -54,8 +88,8 @@ export class EncryptionSetupBuilder {
      *
      * @param {Object} keyBackupInfo as received from/sent to the server
      */
-    addSessionBackup(keyBackupInfo) {
-        this._keyBackupInfo = keyBackupInfo;
+    public addSessionBackup(keyBackupInfo: IKeyBackupInfo): void {
+        this.keyBackupInfo = keyBackupInfo;
     }
 
     /**
@@ -65,8 +99,8 @@ export class EncryptionSetupBuilder {
      *
      * @param {Uint8Array} privateKey
      */
-    addSessionBackupPrivateKeyToCache(privateKey) {
-        this._sessionBackupPrivateKey = privateKey;
+    public addSessionBackupPrivateKeyToCache(privateKey: Uint8Array): void {
+        this.sessionBackupPrivateKey = privateKey;
     }
 
     /**
@@ -75,14 +109,14 @@ export class EncryptionSetupBuilder {
      *
      * @param {String} userId
      * @param {String} deviceId
-     * @param {String} signature
+     * @param {Object} signature
      */
-    addKeySignature(userId, deviceId, signature) {
-        if (!this._keySignatures) {
-            this._keySignatures = {};
+    public addKeySignature(userId: string, deviceId: string, signature: ISignedKey): void {
+        if (!this.keySignatures) {
+            this.keySignatures = {};
         }
-        const userSignatures = this._keySignatures[userId] || {};
-        this._keySignatures[userId] = userSignatures;
+        const userSignatures = this.keySignatures[userId] || {};
+        this.keySignatures[userId] = userSignatures;
         userSignatures[deviceId] = signature;
     }
 
@@ -91,21 +125,21 @@ export class EncryptionSetupBuilder {
      * @param {Object} content
      * @return {Promise}
      */
-    setAccountData(type, content) {
-        return this.accountDataClientAdapter.setAccountData(type, content);
+    public async setAccountData(type: string, content: object): Promise<void> {
+        await this.accountDataClientAdapter.setAccountData(type, content);
     }
 
     /**
      * builds the operation containing all the parts that have been added to the builder
      * @return {EncryptionSetupOperation}
      */
-    buildOperation() {
-        const accountData = this.accountDataClientAdapter._values;
+    public buildOperation(): EncryptionSetupOperation {
+        const accountData = this.accountDataClientAdapter.values;
         return new EncryptionSetupOperation(
             accountData,
-            this._crossSigningKeys,
-            this._keyBackupInfo,
-            this._keySignatures,
+            this.crossSigningKeys,
+            this.keyBackupInfo,
+            this.keySignatures,
         );
     }
 
@@ -118,28 +152,27 @@ export class EncryptionSetupBuilder {
      * @param  {Crypto} crypto
      * @return {Promise}
      */
-    async persist(crypto) {
+    public async persist(crypto: Crypto): Promise<void> {
         // store private keys in cache
-        if (this._crossSigningKeys) {
-            const cacheCallbacks = createCryptoStoreCacheCallbacks(
-                crypto._cryptoStore, crypto._olmDevice);
+        if (this.crossSigningKeys) {
+            const cacheCallbacks = createCryptoStoreCacheCallbacks(crypto.cryptoStore, crypto.olmDevice);
             for (const type of ["master", "self_signing", "user_signing"]) {
                 logger.log(`Cache ${type} cross-signing private key locally`);
                 const privateKey = this.crossSigningCallbacks.privateKeys.get(type);
                 await cacheCallbacks.storeCrossSigningKeyCache(type, privateKey);
             }
             // store own cross-sign pubkeys as trusted
-            await crypto._cryptoStore.doTxn(
+            await crypto.cryptoStore.doTxn(
                 'readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT],
                 (txn) => {
-                    crypto._cryptoStore.storeCrossSigningKeys(
-                        txn, this._crossSigningKeys.keys);
+                    crypto.cryptoStore.storeCrossSigningKeys(
+                        txn, this.crossSigningKeys.keys);
                 },
             );
         }
         // store session backup key in cache
-        if (this._sessionBackupPrivateKey) {
-            await crypto.storeSessionBackupPrivateKey(this._sessionBackupPrivateKey);
+        if (this.sessionBackupPrivateKey) {
+            await crypto.storeSessionBackupPrivateKey(this.sessionBackupPrivateKey);
         }
     }
 }
@@ -157,58 +190,58 @@ export class EncryptionSetupOperation {
      * @param  {Object} keyBackupInfo
      * @param  {Object} keySignatures
      */
-    constructor(accountData, crossSigningKeys, keyBackupInfo, keySignatures) {
-        this._accountData = accountData;
-        this._crossSigningKeys = crossSigningKeys;
-        this._keyBackupInfo = keyBackupInfo;
-        this._keySignatures = keySignatures;
-    }
+    constructor(
+        private readonly accountData: Map<string, object>,
+        private readonly crossSigningKeys: ICrossSigningKeys,
+        private readonly keyBackupInfo: IKeyBackupInfo,
+        private readonly keySignatures: KeySignatures,
+    ) {}
 
     /**
      * Runs the (remaining part of, in the future) operation by sending requests to the server.
-     * @param  {Crypto} crypto
+     * @param {Crypto} crypto
      */
-    async apply(crypto) {
-        const baseApis = crypto._baseApis;
+    public async apply(crypto: Crypto): Promise<void> {
+        const baseApis = crypto.baseApis;
         // upload cross-signing keys
-        if (this._crossSigningKeys) {
-            const keys = {};
-            for (const [name, key] of Object.entries(this._crossSigningKeys.keys)) {
+        if (this.crossSigningKeys) {
+            const keys: Partial<CrossSigningKeys> = {};
+            for (const [name, key] of Object.entries(this.crossSigningKeys.keys)) {
                 keys[name + "_key"] = key;
             }
 
             // We must only call `uploadDeviceSigningKeys` from inside this auth
             // helper to ensure we properly handle auth errors.
-            await this._crossSigningKeys.authUpload(authDict => {
-                return baseApis.uploadDeviceSigningKeys(authDict, keys);
+            await this.crossSigningKeys.authUpload(authDict => {
+                return baseApis.uploadDeviceSigningKeys(authDict, keys as CrossSigningKeys);
             });
 
             // pass the new keys to the main instance of our own CrossSigningInfo.
-            crypto._crossSigningInfo.setKeys(this._crossSigningKeys.keys);
+            crypto.crossSigningInfo.setKeys(this.crossSigningKeys.keys);
         }
         // set account data
-        if (this._accountData) {
-            for (const [type, content] of this._accountData) {
+        if (this.accountData) {
+            for (const [type, content] of this.accountData) {
                 await baseApis.setAccountData(type, content);
             }
         }
         // upload first cross-signing signatures with the new key
         // (e.g. signing our own device)
-        if (this._keySignatures) {
-            await baseApis.uploadKeySignatures(this._keySignatures);
+        if (this.keySignatures) {
+            await baseApis.uploadKeySignatures(this.keySignatures);
         }
         // need to create/update key backup info
-        if (this._keyBackupInfo) {
-            if (this._keyBackupInfo.version) {
+        if (this.keyBackupInfo) {
+            if (this.keyBackupInfo.version) {
                 // session backup signature
                 // The backup is trusted because the user provided the private key.
                 // Sign the backup with the cross signing key so the key backup can
                 // be trusted via cross-signing.
                 await baseApis.http.authedRequest(
-                    undefined, "PUT", "/room_keys/version/" + this._keyBackupInfo.version,
+                    undefined, "PUT", "/room_keys/version/" + this.keyBackupInfo.version,
                     undefined, {
-                        algorithm: this._keyBackupInfo.algorithm,
-                        auth_data: this._keyBackupInfo.auth_data,
+                        algorithm: this.keyBackupInfo.algorithm,
+                        auth_data: this.keyBackupInfo.auth_data,
                     },
                     { prefix: PREFIX_UNSTABLE },
                 );
@@ -216,7 +249,7 @@ export class EncryptionSetupOperation {
                 // add new key backup
                 await baseApis.http.authedRequest(
                     undefined, "POST", "/room_keys/version",
-                    undefined, this._keyBackupInfo,
+                    undefined, this.keyBackupInfo,
                     { prefix: PREFIX_UNSTABLE },
                 );
             }
@@ -229,20 +262,20 @@ export class EncryptionSetupOperation {
  * implementing the methods related to account data in MatrixClient
  */
 class AccountDataClientAdapter extends EventEmitter {
+    public readonly values = new Map<string, MatrixEvent>();
+
     /**
-     * @param  {Object.<String, MatrixEvent>} accountData existing account data
+     * @param  {Object.<String, MatrixEvent>} existingValues existing account data
      */
-    constructor(accountData) {
+    constructor(private readonly existingValues: Record<string, MatrixEvent>) {
         super();
-        this._existingValues = accountData;
-        this._values = new Map();
     }
 
     /**
      * @param  {String} type
      * @return {Promise<Object>} the content of the account data
      */
-    getAccountDataFromServer(type) {
+    public getAccountDataFromServer(type: string): Promise<any> {
         return Promise.resolve(this.getAccountData(type));
     }
 
@@ -250,12 +283,12 @@ class AccountDataClientAdapter extends EventEmitter {
      * @param  {String} type
      * @return {Object} the content of the account data
      */
-    getAccountData(type) {
-        const modifiedValue = this._values.get(type);
+    public getAccountData(type: string): MatrixEvent {
+        const modifiedValue = this.values.get(type);
         if (modifiedValue) {
             return modifiedValue;
         }
-        const existingValue = this._existingValues[type];
+        const existingValue = this.existingValues[type];
         if (existingValue) {
             return existingValue.getContent();
         }
@@ -267,15 +300,16 @@ class AccountDataClientAdapter extends EventEmitter {
      * @param {Object} content
      * @return {Promise}
      */
-    setAccountData(type, content) {
-        const lastEvent = this._values.get(type);
-        this._values.set(type, content);
+    public setAccountData(type: string, content: any): Promise<{}> {
+        const lastEvent = this.values.get(type);
+        this.values.set(type, content);
         // ensure accountData is emitted on the next tick,
         // as SecretStorage listens for it while calling this method
         // and it seems to rely on this.
         return Promise.resolve().then(() => {
             const event = new MatrixEvent({ type, content });
             this.emit("accountData", event, lastEvent);
+            return {};
         });
     }
 }
@@ -285,27 +319,25 @@ class AccountDataClientAdapter extends EventEmitter {
  * by both cache callbacks (see createCryptoStoreCacheCallbacks) as non-cache callbacks.
  * See CrossSigningInfo constructor
  */
-class CrossSigningCallbacks {
-    constructor() {
-        this.privateKeys = new Map();
-    }
+class CrossSigningCallbacks implements ICryptoCallbacks, ICacheCallbacks {
+    public readonly privateKeys = new Map<string, Uint8Array>();
 
     // cache callbacks
-    getCrossSigningKeyCache(type, expectedPublicKey) {
+    public getCrossSigningKeyCache(type: string, expectedPublicKey: string): Promise<Uint8Array> {
         return this.getCrossSigningKey(type, expectedPublicKey);
     }
 
-    storeCrossSigningKeyCache(type, key) {
+    public storeCrossSigningKeyCache(type: string, key: Uint8Array): Promise<void> {
         this.privateKeys.set(type, key);
         return Promise.resolve();
     }
 
     // non-cache callbacks
-    getCrossSigningKey(type, _expectedPubkey) {
+    public getCrossSigningKey(type: string, expectedPubkey: string): Promise<Uint8Array> {
         return Promise.resolve(this.privateKeys.get(type));
     }
 
-    saveCrossSigningKeys(privateKeys) {
+    public saveCrossSigningKeys(privateKeys: Record<string, Uint8Array>) {
         for (const [type, privateKey] of Object.entries(privateKeys)) {
             this.privateKeys.set(type, privateKey);
         }
@@ -317,39 +349,36 @@ class CrossSigningCallbacks {
  * the SecretStorage crypto callbacks
  */
 class SSSSCryptoCallbacks {
-    constructor(delegateCryptoCallbacks) {
-        this._privateKeys = new Map();
-        this._delegateCryptoCallbacks = delegateCryptoCallbacks;
-    }
+    private readonly privateKeys = new Map<string, Uint8Array>();
 
-    async getSecretStorageKey({ keys }, name) {
+    constructor(private readonly delegateCryptoCallbacks: ICryptoCallbacks) {}
+
+    public async getSecretStorageKey(
+        { keys }: { keys: Record<string, ISecretStorageKeyInfo> },
+        name: string,
+    ): Promise<[string, Uint8Array]> {
         for (const keyId of Object.keys(keys)) {
-            const privateKey = this._privateKeys.get(keyId);
+            const privateKey = this.privateKeys.get(keyId);
             if (privateKey) {
                 return [keyId, privateKey];
             }
         }
         // if we don't have the key cached yet, ask
         // for it to the general crypto callbacks and cache it
-        if (this._delegateCryptoCallbacks) {
-            const result = await this._delegateCryptoCallbacks.
+        if (this.delegateCryptoCallbacks) {
+            const result = await this.delegateCryptoCallbacks.
                 getSecretStorageKey({ keys }, name);
             if (result) {
                 const [keyId, privateKey] = result;
-                this._privateKeys.set(keyId, privateKey);
+                this.privateKeys.set(keyId, privateKey);
             }
             return result;
         }
     }
 
-    addPrivateKey(keyId, keyInfo, privKey) {
-        this._privateKeys.set(keyId, privKey);
+    public addPrivateKey(keyId: string, keyInfo: ISecretStorageKeyInfo, privKey: Uint8Array): void {
+        this.privateKeys.set(keyId, privKey);
         // Also pass along to application to cache if it wishes
-        if (
-            this._delegateCryptoCallbacks &&
-            this._delegateCryptoCallbacks.cacheSecretStorageKey
-        ) {
-            this._delegateCryptoCallbacks.cacheSecretStorageKey(keyId, keyInfo, privKey);
-        }
+        this.delegateCryptoCallbacks?.cacheSecretStorageKey?.(keyId, keyInfo, privKey);
     }
 }

src/crypto/OutgoingRoomKeyRequestManager.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2017 Vector Creations Ltd
+Copyright 2017 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -15,6 +15,10 @@ limitations under the License.
 */
 
 import { logger } from '../logger';
+import { CryptoStore, MatrixClient } from "../client";
+import { IRoomKeyRequestBody, IRoomKeyRequestRecipient } from "./index";
+import { OutgoingRoomKeyRequest } from './store/base';
+import { EventType } from "../@types/event";
 
 /**
  * Internal module. Management of outgoing room key requests.
@@ -57,61 +61,58 @@ const SEND_KEY_REQUESTS_DELAY_MS = 500;
  *
  * @enum {number}
  */
-export const ROOM_KEY_REQUEST_STATES = {
+export enum RoomKeyRequestState {
     /** request not yet sent */
-    UNSENT: 0,
-
+    Unsent,
     /** request sent, awaiting reply */
-    SENT: 1,
-
+    Sent,
     /** reply received, cancellation not yet sent */
-    CANCELLATION_PENDING: 2,
-
+    CancellationPending,
     /**
      * Cancellation not yet sent and will transition to UNSENT instead of
      * being deleted once the cancellation has been sent.
      */
-    CANCELLATION_PENDING_AND_WILL_RESEND: 3,
-};
+    CancellationPendingAndWillResend,
+}
 
 export class OutgoingRoomKeyRequestManager {
-    constructor(baseApis, deviceId, cryptoStore) {
-        this._baseApis = baseApis;
-        this._deviceId = deviceId;
-        this._cryptoStore = cryptoStore;
+    // handle for the delayed call to sendOutgoingRoomKeyRequests. Non-null
+    // if the callback has been set, or if it is still running.
+    private sendOutgoingRoomKeyRequestsTimer: number = null;
 
-        // handle for the delayed call to _sendOutgoingRoomKeyRequests. Non-null
-        // if the callback has been set, or if it is still running.
-        this._sendOutgoingRoomKeyRequestsTimer = null;
+    // sanity check to ensure that we don't end up with two concurrent runs
+    // of sendOutgoingRoomKeyRequests
+    private sendOutgoingRoomKeyRequestsRunning = false;
 
-        // sanity check to ensure that we don't end up with two concurrent runs
-        // of _sendOutgoingRoomKeyRequests
-        this._sendOutgoingRoomKeyRequestsRunning = false;
+    private clientRunning = false;
 
-        this._clientRunning = false;
-    }
+    constructor(
+        private readonly baseApis: MatrixClient,
+        private readonly deviceId: string,
+        private readonly cryptoStore: CryptoStore,
+    ) {}
 
     /**
      * Called when the client is started. Sets background processes running.
      */
-    start() {
-        this._clientRunning = true;
+    public start(): void {
+        this.clientRunning = true;
     }
 
     /**
      * Called when the client is stopped. Stops any running background processes.
      */
-    stop() {
+    public stop(): void {
         logger.log('stopping OutgoingRoomKeyRequestManager');
         // stop the timer on the next run
-        this._clientRunning = false;
+        this.clientRunning = false;
     }
 
     /**
      * Send any requests that have been queued
      */
-    sendQueuedRequests() {
-        this._startTimer();
+    public sendQueuedRequests(): void {
+        this.startTimer();
     }
 
     /**
@@ -131,95 +132,99 @@ export class OutgoingRoomKeyRequestManager {
      *    pending list (or we have established that a similar request already
      *    exists)
      */
-    async queueRoomKeyRequest(requestBody, recipients, resend=false) {
-        const req = await this._cryptoStore.getOutgoingRoomKeyRequest(
+    public async queueRoomKeyRequest(
+        requestBody: IRoomKeyRequestBody,
+        recipients: IRoomKeyRequestRecipient[],
+        resend = false,
+    ): Promise<void> {
+        const req = await this.cryptoStore.getOutgoingRoomKeyRequest(
             requestBody,
         );
         if (!req) {
-            await this._cryptoStore.getOrAddOutgoingRoomKeyRequest({
+            await this.cryptoStore.getOrAddOutgoingRoomKeyRequest({
                 requestBody: requestBody,
                 recipients: recipients,
-                requestId: this._baseApis.makeTxnId(),
-                state: ROOM_KEY_REQUEST_STATES.UNSENT,
+                requestId: this.baseApis.makeTxnId(),
+                state: RoomKeyRequestState.Unsent,
             });
         } else {
             switch (req.state) {
-            case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND:
-            case ROOM_KEY_REQUEST_STATES.UNSENT:
-                // nothing to do here, since we're going to send a request anyways
-                return;
+                case RoomKeyRequestState.CancellationPendingAndWillResend:
+                case RoomKeyRequestState.Unsent:
+                    // nothing to do here, since we're going to send a request anyways
+                    return;
 
-            case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING: {
-                // existing request is about to be cancelled.  If we want to
-                // resend, then change the state so that it resends after
-                // cancelling.  Otherwise, just cancel the cancellation.
-                const state = resend ?
-                    ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND :
-                    ROOM_KEY_REQUEST_STATES.SENT;
-                await this._cryptoStore.updateOutgoingRoomKeyRequest(
-                    req.requestId, ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING, {
-                        state,
-                        cancellationTxnId: this._baseApis.makeTxnId(),
-                    },
-                );
-                break;
-            }
-            case ROOM_KEY_REQUEST_STATES.SENT: {
-                // a request has already been sent.  If we don't want to
-                // resend, then do nothing.  If we do want to, then cancel the
-                // existing request and send a new one.
-                if (resend) {
-                    const state =
-                          ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND;
-                    const updatedReq =
-                          await this._cryptoStore.updateOutgoingRoomKeyRequest(
-                              req.requestId, ROOM_KEY_REQUEST_STATES.SENT, {
-                                  state,
-                                  cancellationTxnId: this._baseApis.makeTxnId(),
-                                  // need to use a new transaction ID so that
-                                  // the request gets sent
-                                  requestTxnId: this._baseApis.makeTxnId(),
-                              },
-                          );
-                    if (!updatedReq) {
-                        // updateOutgoingRoomKeyRequest couldn't find the request
-                        // in state ROOM_KEY_REQUEST_STATES.SENT, so we must have
-                        // raced with another tab to mark the request cancelled.
-                        // Try again, to make sure the request is resent.
-                        return await this.queueRoomKeyRequest(
-                            requestBody, recipients, resend,
-                        );
-                    }
-
-                    // We don't want to wait for the timer, so we send it
-                    // immediately. (We might actually end up racing with the timer,
-                    // but that's ok: even if we make the request twice, we'll do it
-                    // with the same transaction_id, so only one message will get
-                    // sent).
-                    //
-                    // (We also don't want to wait for the response from the server
-                    // here, as it will slow down processing of received keys if we
-                    // do.)
-                    try {
-                        await this._sendOutgoingRoomKeyRequestCancellation(
-                            updatedReq,
-                            true,
-                        );
-                    } catch (e) {
-                        logger.error(
-                            "Error sending room key request cancellation;"
-                                + " will retry later.", e,
-                        );
-                    }
-                    // The request has transitioned from
-                    // CANCELLATION_PENDING_AND_WILL_RESEND to UNSENT. We
-                    // still need to resend the request which is now UNSENT, so
-                    // start the timer if it isn't already started.
+                case RoomKeyRequestState.CancellationPending: {
+                    // existing request is about to be cancelled.  If we want to
+                    // resend, then change the state so that it resends after
+                    // cancelling.  Otherwise, just cancel the cancellation.
+                    const state = resend ?
+                        RoomKeyRequestState.CancellationPendingAndWillResend :
+                        RoomKeyRequestState.Sent;
+                    await this.cryptoStore.updateOutgoingRoomKeyRequest(
+                        req.requestId, RoomKeyRequestState.CancellationPending, {
+                            state,
+                            cancellationTxnId: this.baseApis.makeTxnId(),
+                        },
+                    );
+                    break;
                 }
-                break;
-            }
-            default:
-                throw new Error('unhandled state: ' + req.state);
+                case RoomKeyRequestState.Sent: {
+                    // a request has already been sent.  If we don't want to
+                    // resend, then do nothing.  If we do want to, then cancel the
+                    // existing request and send a new one.
+                    if (resend) {
+                        const state =
+                              RoomKeyRequestState.CancellationPendingAndWillResend;
+                        const updatedReq =
+                              await this.cryptoStore.updateOutgoingRoomKeyRequest(
+                                  req.requestId, RoomKeyRequestState.Sent, {
+                                      state,
+                                      cancellationTxnId: this.baseApis.makeTxnId(),
+                                      // need to use a new transaction ID so that
+                                      // the request gets sent
+                                      requestTxnId: this.baseApis.makeTxnId(),
+                                  },
+                              );
+                        if (!updatedReq) {
+                            // updateOutgoingRoomKeyRequest couldn't find the request
+                            // in state ROOM_KEY_REQUEST_STATES.SENT, so we must have
+                            // raced with another tab to mark the request cancelled.
+                            // Try again, to make sure the request is resent.
+                            return await this.queueRoomKeyRequest(
+                                requestBody, recipients, resend,
+                            );
+                        }
+
+                        // We don't want to wait for the timer, so we send it
+                        // immediately. (We might actually end up racing with the timer,
+                        // but that's ok: even if we make the request twice, we'll do it
+                        // with the same transaction_id, so only one message will get
+                        // sent).
+                        //
+                        // (We also don't want to wait for the response from the server
+                        // here, as it will slow down processing of received keys if we
+                        // do.)
+                        try {
+                            await this.sendOutgoingRoomKeyRequestCancellation(
+                                updatedReq,
+                                true,
+                            );
+                        } catch (e) {
+                            logger.error(
+                                "Error sending room key request cancellation;"
+                                    + " will retry later.", e,
+                            );
+                        }
+                        // The request has transitioned from
+                        // CANCELLATION_PENDING_AND_WILL_RESEND to UNSENT. We
+                        // still need to resend the request which is now UNSENT, so
+                        // start the timer if it isn't already started.
+                    }
+                    break;
+                }
+                default:
+                    throw new Error('unhandled state: ' + req.state);
             }
         }
     }
@@ -232,8 +237,8 @@ export class OutgoingRoomKeyRequestManager {
      * @returns {Promise} resolves when the request has been updated in our
      *    pending list.
      */
-    cancelRoomKeyRequest(requestBody) {
-        return this._cryptoStore.getOutgoingRoomKeyRequest(
+    public cancelRoomKeyRequest(requestBody: IRoomKeyRequestBody): Promise<void> {
+        return this.cryptoStore.getOutgoingRoomKeyRequest(
             requestBody,
         ).then((req) => {
             if (!req) {
@@ -241,12 +246,12 @@ export class OutgoingRoomKeyRequestManager {
                 return;
             }
             switch (req.state) {
-                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING:
-                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND:
+                case RoomKeyRequestState.CancellationPending:
+                case RoomKeyRequestState.CancellationPendingAndWillResend:
                     // nothing to do here
                     return;
 
-                case ROOM_KEY_REQUEST_STATES.UNSENT:
+                case RoomKeyRequestState.Unsent:
                     // just delete it
 
                     // FIXME: ghahah we may have attempted to send it, and
@@ -258,16 +263,16 @@ export class OutgoingRoomKeyRequestManager {
                         'deleting unnecessary room key request for ' +
                         stringifyRequestBody(requestBody),
                     );
-                    return this._cryptoStore.deleteOutgoingRoomKeyRequest(
-                        req.requestId, ROOM_KEY_REQUEST_STATES.UNSENT,
+                    return this.cryptoStore.deleteOutgoingRoomKeyRequest(
+                        req.requestId, RoomKeyRequestState.Unsent,
                     );
 
-                case ROOM_KEY_REQUEST_STATES.SENT: {
+                case RoomKeyRequestState.Sent: {
                     // send a cancellation.
-                    return this._cryptoStore.updateOutgoingRoomKeyRequest(
-                        req.requestId, ROOM_KEY_REQUEST_STATES.SENT, {
-                            state: ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING,
-                            cancellationTxnId: this._baseApis.makeTxnId(),
+                    return this.cryptoStore.updateOutgoingRoomKeyRequest(
+                        req.requestId, RoomKeyRequestState.Sent, {
+                            state: RoomKeyRequestState.CancellationPending,
+                            cancellationTxnId: this.baseApis.makeTxnId(),
                         },
                     ).then((updatedReq) => {
                         if (!updatedReq) {
@@ -294,14 +299,14 @@ export class OutgoingRoomKeyRequestManager {
                         // (We also don't want to wait for the response from the server
                         // here, as it will slow down processing of received keys if we
                         // do.)
-                        this._sendOutgoingRoomKeyRequestCancellation(
+                        this.sendOutgoingRoomKeyRequestCancellation(
                             updatedReq,
                         ).catch((e) => {
                             logger.error(
                                 "Error sending room key request cancellation;"
                                 + " will retry later.", e,
                             );
-                            this._startTimer();
+                            this.startTimer();
                         });
                     });
                 }
@@ -320,10 +325,8 @@ export class OutgoingRoomKeyRequestManager {
      * @return {Promise} resolves to a list of all the
      *    {@link module:crypto/store/base~OutgoingRoomKeyRequest}
      */
-    getOutgoingSentRoomKeyRequest(userId, deviceId) {
-        return this._cryptoStore.getOutgoingRoomKeyRequestsByTarget(
-            userId, deviceId, [ROOM_KEY_REQUEST_STATES.SENT],
-        );
+    public getOutgoingSentRoomKeyRequest(userId: string, deviceId: string): OutgoingRoomKeyRequest[] {
+        return this.cryptoStore.getOutgoingRoomKeyRequestsByTarget(userId, deviceId, [RoomKeyRequestState.Sent]);
     }
 
     /**
@@ -333,29 +336,27 @@ export class OutgoingRoomKeyRequestManager {
      * For example, after initialization or self-verification.
      * @return {Promise} An array of `queueRoomKeyRequest` outputs.
      */
-    async cancelAndResendAllOutgoingRequests() {
-        const outgoings = await this._cryptoStore.getAllOutgoingRoomKeyRequestsByState(
-            ROOM_KEY_REQUEST_STATES.SENT,
-        );
+    public async cancelAndResendAllOutgoingRequests(): Promise<void[]> {
+        const outgoings = await this.cryptoStore.getAllOutgoingRoomKeyRequestsByState(RoomKeyRequestState.Sent);
         return Promise.all(outgoings.map(({ requestBody, recipients }) =>
             this.queueRoomKeyRequest(requestBody, recipients, true)));
     }
 
     // start the background timer to send queued requests, if the timer isn't
     // already running
-    _startTimer() {
-        if (this._sendOutgoingRoomKeyRequestsTimer) {
+    private startTimer(): void {
+        if (this.sendOutgoingRoomKeyRequestsTimer) {
             return;
         }
 
         const startSendingOutgoingRoomKeyRequests = () => {
-            if (this._sendOutgoingRoomKeyRequestsRunning) {
+            if (this.sendOutgoingRoomKeyRequestsRunning) {
                 throw new Error("RoomKeyRequestSend already in progress!");
             }
-            this._sendOutgoingRoomKeyRequestsRunning = true;
+            this.sendOutgoingRoomKeyRequestsRunning = true;
 
-            this._sendOutgoingRoomKeyRequests().finally(() => {
-                this._sendOutgoingRoomKeyRequestsRunning = false;
+            this.sendOutgoingRoomKeyRequests().finally(() => {
+                this.sendOutgoingRoomKeyRequestsRunning = false;
             }).catch((e) => {
                 // this should only happen if there is an indexeddb error,
                 // in which case we're a bit stuffed anyway.
@@ -365,7 +366,7 @@ export class OutgoingRoomKeyRequestManager {
             });
         };
 
-        this._sendOutgoingRoomKeyRequestsTimer = global.setTimeout(
+        this.sendOutgoingRoomKeyRequestsTimer = setTimeout(
             startSendingOutgoingRoomKeyRequests,
             SEND_KEY_REQUESTS_DELAY_MS,
         );
@@ -374,47 +375,47 @@ export class OutgoingRoomKeyRequestManager {
     // look for and send any queued requests. Runs itself recursively until
     // there are no more requests, or there is an error (in which case, the
     // timer will be restarted before the promise resolves).
-    _sendOutgoingRoomKeyRequests() {
-        if (!this._clientRunning) {
-            this._sendOutgoingRoomKeyRequestsTimer = null;
+    private sendOutgoingRoomKeyRequests(): Promise<void> {
+        if (!this.clientRunning) {
+            this.sendOutgoingRoomKeyRequestsTimer = null;
             return Promise.resolve();
         }
 
-        return this._cryptoStore.getOutgoingRoomKeyRequestByState([
-            ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING,
-            ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND,
-            ROOM_KEY_REQUEST_STATES.UNSENT,
-        ]).then((req) => {
+        return this.cryptoStore.getOutgoingRoomKeyRequestByState([
+            RoomKeyRequestState.CancellationPending,
+            RoomKeyRequestState.CancellationPendingAndWillResend,
+            RoomKeyRequestState.Unsent,
+        ]).then((req: OutgoingRoomKeyRequest) => {
             if (!req) {
-                this._sendOutgoingRoomKeyRequestsTimer = null;
+                this.sendOutgoingRoomKeyRequestsTimer = null;
                 return;
             }
 
             let prom;
             switch (req.state) {
-                case ROOM_KEY_REQUEST_STATES.UNSENT:
-                    prom = this._sendOutgoingRoomKeyRequest(req);
+                case RoomKeyRequestState.Unsent:
+                    prom = this.sendOutgoingRoomKeyRequest(req);
                     break;
-                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING:
-                    prom = this._sendOutgoingRoomKeyRequestCancellation(req);
+                case RoomKeyRequestState.CancellationPending:
+                    prom = this.sendOutgoingRoomKeyRequestCancellation(req);
                     break;
-                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND:
-                    prom = this._sendOutgoingRoomKeyRequestCancellation(req, true);
+                case RoomKeyRequestState.CancellationPendingAndWillResend:
+                    prom = this.sendOutgoingRoomKeyRequestCancellation(req, true);
                     break;
             }
 
             return prom.then(() => {
                 // go around the loop again
-                return this._sendOutgoingRoomKeyRequests();
+                return this.sendOutgoingRoomKeyRequests();
             }).catch((e) => {
                 logger.error("Error sending room key request; will retry later.", e);
-                this._sendOutgoingRoomKeyRequestsTimer = null;
+                this.sendOutgoingRoomKeyRequestsTimer = null;
             });
         });
     }
 
     // given a RoomKeyRequest, send it and update the request record
-    _sendOutgoingRoomKeyRequest(req) {
+    private sendOutgoingRoomKeyRequest(req: OutgoingRoomKeyRequest): Promise<void> {
         logger.log(
             `Requesting keys for ${stringifyRequestBody(req.requestBody)}` +
             ` from ${stringifyRecipientList(req.recipients)}` +
@@ -423,24 +424,24 @@ export class OutgoingRoomKeyRequestManager {
 
         const requestMessage = {
             action: "request",
-            requesting_device_id: this._deviceId,
+            requesting_device_id: this.deviceId,
             request_id: req.requestId,
             body: req.requestBody,
         };
 
-        return this._sendMessageToDevices(
+        return this.sendMessageToDevices(
             requestMessage, req.recipients, req.requestTxnId || req.requestId,
         ).then(() => {
-            return this._cryptoStore.updateOutgoingRoomKeyRequest(
-                req.requestId, ROOM_KEY_REQUEST_STATES.UNSENT,
-                { state: ROOM_KEY_REQUEST_STATES.SENT },
+            return this.cryptoStore.updateOutgoingRoomKeyRequest(
+                req.requestId, RoomKeyRequestState.Unsent,
+                { state: RoomKeyRequestState.Sent },
             );
         });
     }
 
     // Given a RoomKeyRequest, cancel it and delete the request record unless
     // andResend is set, in which case transition to UNSENT.
-    _sendOutgoingRoomKeyRequestCancellation(req, andResend) {
+    private sendOutgoingRoomKeyRequestCancellation(req: OutgoingRoomKeyRequest, andResend = false): Promise<void> {
         logger.log(
             `Sending cancellation for key request for ` +
             `${stringifyRequestBody(req.requestBody)} to ` +
@@ -450,30 +451,30 @@ export class OutgoingRoomKeyRequestManager {
 
         const requestMessage = {
             action: "request_cancellation",
-            requesting_device_id: this._deviceId,
+            requesting_device_id: this.deviceId,
             request_id: req.requestId,
         };
 
-        return this._sendMessageToDevices(
+        return this.sendMessageToDevices(
             requestMessage, req.recipients, req.cancellationTxnId,
         ).then(() => {
             if (andResend) {
                 // We want to resend, so transition to UNSENT
-                return this._cryptoStore.updateOutgoingRoomKeyRequest(
+                return this.cryptoStore.updateOutgoingRoomKeyRequest(
                     req.requestId,
-                    ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND,
-                    { state: ROOM_KEY_REQUEST_STATES.UNSENT },
+                    RoomKeyRequestState.CancellationPendingAndWillResend,
+                    { state: RoomKeyRequestState.Unsent },
                 );
             }
-            return this._cryptoStore.deleteOutgoingRoomKeyRequest(
-                req.requestId, ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING,
+            return this.cryptoStore.deleteOutgoingRoomKeyRequest(
+                req.requestId, RoomKeyRequestState.CancellationPending,
             );
         });
     }
 
     // send a RoomKeyRequest to a list of recipients
-    _sendMessageToDevices(message, recipients, txnId) {
-        const contentMap = {};
+    private sendMessageToDevices(message, recipients, txnId: string): Promise<{}> {
+        const contentMap: Record<string, Record<string, Record<string, any>>> = {};
         for (const recip of recipients) {
             if (!contentMap[recip.userId]) {
                 contentMap[recip.userId] = {};
@@ -481,9 +482,7 @@ export class OutgoingRoomKeyRequestManager {
             contentMap[recip.userId][recip.deviceId] = message;
         }
 
-        return this._baseApis.sendToDevice(
-            'm.room_key_request', contentMap, txnId,
-        );
+        return this.baseApis.sendToDevice(EventType.RoomKeyRequest, contentMap, txnId);
     }
 }
 

src/crypto/RoomList.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2018, 2019 New Vector Ltd
+Copyright 2018 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -21,44 +21,51 @@ limitations under the License.
  */
 
 import { IndexedDBCryptoStore } from './store/indexeddb-crypto-store';
+import { CryptoStore } from "../client";
+
+/* eslint-disable camelcase */
+export interface IRoomEncryption {
+    algorithm: string;
+    rotation_period_ms?: number;
+    rotation_period_msgs?: number;
+}
+/* eslint-enable camelcase */
 
 /**
  * @alias module:crypto/RoomList
  */
 export class RoomList {
-    constructor(cryptoStore) {
-        this._cryptoStore = cryptoStore;
+    // Object of roomId -> room e2e info object (body of the m.room.encryption event)
+    private roomEncryption: Record<string, IRoomEncryption> = {};
 
-        // Object of roomId -> room e2e info object (body of the m.room.encryption event)
-        this._roomEncryption = {};
-    }
+    constructor(private readonly cryptoStore: CryptoStore) {}
 
-    async init() {
-        await this._cryptoStore.doTxn(
+    public async init(): Promise<void> {
+        await this.cryptoStore.doTxn(
             'readwrite', [IndexedDBCryptoStore.STORE_ROOMS], (txn) => {
-                this._cryptoStore.getEndToEndRooms(txn, (result) => {
-                    this._roomEncryption = result;
+                this.cryptoStore.getEndToEndRooms(txn, (result) => {
+                    this.roomEncryption = result;
                 });
             },
         );
     }
 
-    getRoomEncryption(roomId) {
-        return this._roomEncryption[roomId] || null;
+    public getRoomEncryption(roomId: string): IRoomEncryption {
+        return this.roomEncryption[roomId] || null;
     }
 
-    isRoomEncrypted(roomId) {
+    public isRoomEncrypted(roomId: string): boolean {
         return Boolean(this.getRoomEncryption(roomId));
     }
 
-    async setRoomEncryption(roomId, roomInfo) {
+    public async setRoomEncryption(roomId: string, roomInfo: IRoomEncryption): Promise<void> {
         // important that this happens before calling into the store
         // as it prevents the Crypto::setRoomEncryption from calling
         // this twice for consecutive m.room.encryption events
-        this._roomEncryption[roomId] = roomInfo;
-        await this._cryptoStore.doTxn(
+        this.roomEncryption[roomId] = roomInfo;
+        await this.cryptoStore.doTxn(
             'readwrite', [IndexedDBCryptoStore.STORE_ROOMS], (txn) => {
-                this._cryptoStore.storeEndToEndRoom(roomId, roomInfo, txn);
+                this.cryptoStore.storeEndToEndRoom(roomId, roomInfo, txn);
             },
         );
     }

src/crypto/SecretStorage.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2019, 2020 The Matrix.org Foundation C.I.C.
+Copyright 2019 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -14,61 +14,95 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { EventEmitter } from 'events';
 import { logger } from '../logger';
 import * as olmlib from './olmlib';
 import { randomString } from '../randomstring';
-import { encryptAES, decryptAES } from './aes';
+import { encryptAES, decryptAES, IEncryptedPayload, calculateKeyCheck } from './aes';
 import { encodeBase64 } from "./olmlib";
+import { ICryptoCallbacks, MatrixClient, MatrixEvent } from '../matrix';
+import { IAddSecretStorageKeyOpts, ISecretStorageKeyInfo } from './api';
+import { EventEmitter } from 'stream';
 
-export const SECRET_STORAGE_ALGORITHM_V1_AES
-    = "m.secret_storage.v1.aes-hmac-sha2";
+export const SECRET_STORAGE_ALGORITHM_V1_AES = "m.secret_storage.v1.aes-hmac-sha2";
 
-const ZERO_STR = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
+// Some of the key functions use a tuple and some use an object...
+export type SecretStorageKeyTuple = [keyId: string, keyInfo: ISecretStorageKeyInfo];
+export type SecretStorageKeyObject = {keyId: string, keyInfo: ISecretStorageKeyInfo};
+
+export interface ISecretRequest {
+    requestId: string;
+    promise: Promise<string>;
+    cancel: (reason: string) => void;
+}
+
+export interface IAccountDataClient extends EventEmitter {
+    // Subset of MatrixClient (which also uses any for the event content)
+    getAccountDataFromServer: (eventType: string) => Promise<Record<string, any>>;
+    getAccountData: (eventType: string) => MatrixEvent;
+    setAccountData: (eventType: string, content: any) => Promise<{}>;
+}
+
+interface ISecretRequestInternal {
+    name: string;
+    devices: string[];
+    resolve: (reason: string) => void;
+    reject: (error: Error) => void;
+}
+
+interface IDecryptors {
+    encrypt: (plaintext: string) => Promise<IEncryptedPayload>;
+    decrypt: (ciphertext: IEncryptedPayload) => Promise<string>;
+}
 
 /**
  * Implements Secure Secret Storage and Sharing (MSC1946)
  * @module crypto/SecretStorage
  */
-export class SecretStorage extends EventEmitter {
-    constructor(baseApis, cryptoCallbacks) {
-        super();
-        this._baseApis = baseApis;
-        this._cryptoCallbacks = cryptoCallbacks;
-        this._requests = {};
-        this._incomingRequests = {};
-    }
+export class SecretStorage {
+    private requests = new Map<string, ISecretRequestInternal>();
 
-    async getDefaultKeyId() {
-        const defaultKey = await this._baseApis.getAccountDataFromServer(
+    // In it's pure javascript days, this was relying on some proper Javascript-style
+    // type-abuse where sometimes we'd pass in a fake client object with just the account
+    // data methods implemented, which is all this class needs unless you use the secret
+    // sharing code, so it was fine. As a low-touch TypeScript migration, this now has
+    // an extra, optional param for a real matrix client, so you can not pass it as long
+    // as you don't request any secrets.
+    // A better solution would probably be to split this class up into secret storage and
+    // secret sharing which are really two separate things, even though they share an MSC.
+    constructor(
+        private readonly accountDataAdapter: IAccountDataClient,
+        private readonly cryptoCallbacks: ICryptoCallbacks,
+        private readonly baseApis?: MatrixClient,
+    ) {}
+
+    public async getDefaultKeyId(): Promise<string> {
+        const defaultKey = await this.accountDataAdapter.getAccountDataFromServer(
             'm.secret_storage.default_key',
         );
         if (!defaultKey) return null;
         return defaultKey.key;
     }
 
-    setDefaultKeyId(keyId) {
-        return new Promise(async (resolve, reject) => {
-            const listener = (ev) => {
+    public setDefaultKeyId(keyId: string): Promise<void> {
+        return new Promise<void>((resolve, reject) => {
+            const listener = (ev: MatrixEvent): void => {
                 if (
                     ev.getType() === 'm.secret_storage.default_key' &&
                     ev.getContent().key === keyId
                 ) {
-                    this._baseApis.removeListener('accountData', listener);
+                    this.accountDataAdapter.removeListener('accountData', listener);
                     resolve();
                 }
             };
-            this._baseApis.on('accountData', listener);
+            this.accountDataAdapter.on('accountData', listener);
 
-            try {
-                await this._baseApis.setAccountData(
-                    'm.secret_storage.default_key',
-                    { key: keyId },
-                );
-            } catch (e) {
-                this._baseApis.removeListener('accountData', listener);
+            this.accountDataAdapter.setAccountData(
+                'm.secret_storage.default_key',
+                { key: keyId },
+            ).catch(e => {
+                this.accountDataAdapter.removeListener('accountData', listener);
                 reject(e);
-            }
+            });
         });
     }
 
@@ -85,10 +119,14 @@ export class SecretStorage extends EventEmitter {
      *     keyId: {string} the ID of the key
      *     keyInfo: {object} details about the key (iv, mac, passphrase)
      */
-    async addKey(algorithm, opts, keyId) {
-        const keyInfo = { algorithm };
+    public async addKey(
+        algorithm: string,
+        opts: IAddSecretStorageKeyOpts,
+        keyId?: string,
+    ): Promise<SecretStorageKeyObject> {
+        const keyInfo = { algorithm } as ISecretStorageKeyInfo;
 
-        if (!opts) opts = {};
+        if (!opts) opts = {} as IAddSecretStorageKeyOpts;
 
         if (opts.name) {
             keyInfo.name = opts.name;
@@ -99,25 +137,25 @@ export class SecretStorage extends EventEmitter {
                 keyInfo.passphrase = opts.passphrase;
             }
             if (opts.key) {
-                const { iv, mac } = await SecretStorage._calculateKeyCheck(opts.key);
+                const { iv, mac } = await calculateKeyCheck(opts.key);
                 keyInfo.iv = iv;
                 keyInfo.mac = mac;
             }
         } else {
-            throw new Error(`Unknown key algorithm ${opts.algorithm}`);
+            throw new Error(`Unknown key algorithm ${algorithm}`);
         }
 
         if (!keyId) {
             do {
                 keyId = randomString(32);
             } while (
-                await this._baseApis.getAccountDataFromServer(
+                await this.accountDataAdapter.getAccountDataFromServer(
                     `m.secret_storage.key.${keyId}`,
                 )
             );
         }
 
-        await this._baseApis.setAccountData(
+        await this.accountDataAdapter.setAccountData(
             `m.secret_storage.key.${keyId}`, keyInfo,
         );
 
@@ -134,8 +172,9 @@ export class SecretStorage extends EventEmitter {
      *     for. Defaults to the default key ID if not provided.
      * @returns {Array?} If the key was found, the return value is an array of
      *     the form [keyId, keyInfo].  Otherwise, null is returned.
+     *     XXX: why is this an array when addKey returns an object?
      */
-    async getKey(keyId) {
+    public async getKey(keyId: string): Promise<SecretStorageKeyTuple | null> {
         if (!keyId) {
             keyId = await this.getDefaultKeyId();
         }
@@ -143,9 +182,9 @@ export class SecretStorage extends EventEmitter {
             return null;
         }
 
-        const keyInfo = await this._baseApis.getAccountDataFromServer(
+        const keyInfo = await this.accountDataAdapter.getAccountDataFromServer(
             "m.secret_storage.key." + keyId,
-        );
+        ) as ISecretStorageKeyInfo;
         return keyInfo ? [keyId, keyInfo] : null;
     }
 
@@ -156,8 +195,8 @@ export class SecretStorage extends EventEmitter {
      *     for. Defaults to the default key ID if not provided.
      * @return {boolean} Whether we have the key.
      */
-    async hasKey(keyId) {
-        return !!(await this.getKey(keyId));
+    public async hasKey(keyId?: string): Promise<boolean> {
+        return Boolean(await this.getKey(keyId));
     }
 
     /**
@@ -168,10 +207,10 @@ export class SecretStorage extends EventEmitter {
      *
      * @return {boolean} whether or not the key matches
      */
-    async checkKey(key, info) {
+    public async checkKey(key: Uint8Array, info: ISecretStorageKeyInfo): Promise<boolean> {
         if (info.algorithm === SECRET_STORAGE_ALGORITHM_V1_AES) {
             if (info.mac) {
-                const { mac } = await SecretStorage._calculateKeyCheck(key, info.iv);
+                const { mac } = await calculateKeyCheck(key, info.iv);
                 return info.mac.replace(/=+$/g, '') === mac.replace(/=+$/g, '');
             } else {
                 // if we have no information, we have to assume the key is right
@@ -182,10 +221,6 @@ export class SecretStorage extends EventEmitter {
         }
     }
 
-    static async _calculateKeyCheck(key, iv) {
-        return await encryptAES(ZERO_STR, key, "", iv);
-    }
-
     /**
      * Store an encrypted secret on the server
      *
@@ -194,7 +229,7 @@ export class SecretStorage extends EventEmitter {
      * @param {Array} keys The IDs of the keys to use to encrypt the secret
      *     or null/undefined to use the default key.
      */
-    async store(name, secret, keys) {
+    public async store(name: string, secret: string, keys?: string[]): Promise<void> {
         const encrypted = {};
 
         if (!keys) {
@@ -211,9 +246,9 @@ export class SecretStorage extends EventEmitter {
 
         for (const keyId of keys) {
             // get key information from key storage
-            const keyInfo = await this._baseApis.getAccountDataFromServer(
+            const keyInfo = await this.accountDataAdapter.getAccountDataFromServer(
                 "m.secret_storage.key." + keyId,
-            );
+            ) as ISecretStorageKeyInfo;
             if (!keyInfo) {
                 throw new Error("Unknown key: " + keyId);
             }
@@ -221,7 +256,7 @@ export class SecretStorage extends EventEmitter {
             // encrypt secret, based on the algorithm
             if (keyInfo.algorithm === SECRET_STORAGE_ALGORITHM_V1_AES) {
                 const keys = { [keyId]: keyInfo };
-                const [, encryption] = await this._getSecretStorageKey(keys, name);
+                const [, encryption] = await this.getSecretStorageKey(keys, name);
                 encrypted[keyId] = await encryption.encrypt(secret);
             } else {
                 logger.warn("unknown algorithm for secret storage key " + keyId
@@ -231,34 +266,7 @@ export class SecretStorage extends EventEmitter {
         }
 
         // save encrypted secret
-        await this._baseApis.setAccountData(name, { encrypted });
-    }
-
-    /**
-     * Temporary method to fix up existing accounts where secrets
-     * are incorrectly stored without the 'encrypted' level
-     *
-     * @param {string} name The name of the secret
-     * @param {object} secretInfo The account data object
-     * @returns {object} The fixed object or null if no fix was performed
-     */
-    async _fixupStoredSecret(name, secretInfo) {
-        // We assume the secret was only stored passthrough for 1
-        // key - this was all the broken code supported.
-        const keys = Object.keys(secretInfo);
-        if (
-            keys.length === 1 && keys[0] !== 'encrypted' &&
-            secretInfo[keys[0]].passthrough
-        ) {
-            const hasKey = await this.hasKey(keys[0]);
-            if (hasKey) {
-                logger.log("Fixing up passthrough secret: " + name);
-                await this.storePassthrough(name, keys[0]);
-                const newData = await this._baseApis.getAccountDataFromServer(name);
-                return newData;
-            }
-        }
-        return null;
+        await this.accountDataAdapter.setAccountData(name, { encrypted });
     }
 
     /**
@@ -268,24 +276,20 @@ export class SecretStorage extends EventEmitter {
      *
      * @return {string} the contents of the secret
      */
-    async get(name) {
-        let secretInfo = await this._baseApis.getAccountDataFromServer(name);
+    public async get(name: string): Promise<string> {
+        const secretInfo = await this.accountDataAdapter.getAccountDataFromServer(name);
         if (!secretInfo) {
             return;
         }
         if (!secretInfo.encrypted) {
-            // try to fix it up
-            secretInfo = await this._fixupStoredSecret(name, secretInfo);
-            if (!secretInfo || !secretInfo.encrypted) {
-                throw new Error("Content is not encrypted!");
-            }
+            throw new Error("Content is not encrypted!");
         }
 
         // get possible keys to decrypt
         const keys = {};
         for (const keyId of Object.keys(secretInfo.encrypted)) {
             // get key information from key storage
-            const keyInfo = await this._baseApis.getAccountDataFromServer(
+            const keyInfo = await this.accountDataAdapter.getAccountDataFromServer(
                 "m.secret_storage.key." + keyId,
             );
             const encInfo = secretInfo.encrypted[keyId];
@@ -306,7 +310,7 @@ export class SecretStorage extends EventEmitter {
         let decryption;
         try {
             // fetch private key from app
-            [keyId, decryption] = await this._getSecretStorageKey(keys, name);
+            [keyId, decryption] = await this.getSecretStorageKey(keys, name);
 
             const encInfo = secretInfo.encrypted[keyId];
 
@@ -331,16 +335,12 @@ export class SecretStorage extends EventEmitter {
      *     with, or null if it is not present or not encrypted with a trusted
      *     key
      */
-    async isStored(name, checkKey) {
+    public async isStored(name: string, checkKey: boolean): Promise<Record<string, ISecretStorageKeyInfo>> {
         // check if secret exists
-        let secretInfo = await this._baseApis.getAccountDataFromServer(name);
+        const secretInfo = await this.accountDataAdapter.getAccountDataFromServer(name);
         if (!secretInfo) return null;
         if (!secretInfo.encrypted) {
-            // try to fix it up
-            secretInfo = await this._fixupStoredSecret(name, secretInfo);
-            if (!secretInfo || !secretInfo.encrypted) {
-                return null;
-            }
+            return null;
         }
 
         if (checkKey === undefined) checkKey = true;
@@ -350,7 +350,7 @@ export class SecretStorage extends EventEmitter {
         // filter secret encryption keys with supported algorithm
         for (const keyId of Object.keys(secretInfo.encrypted)) {
             // get key information from key storage
-            const keyInfo = await this._baseApis.getAccountDataFromServer(
+            const keyInfo = await this.accountDataAdapter.getAccountDataFromServer(
                 "m.secret_storage.key." + keyId,
             );
             if (!keyInfo) continue;
@@ -371,45 +371,48 @@ export class SecretStorage extends EventEmitter {
      *
      * @param {string} name the name of the secret to request
      * @param {string[]} devices the devices to request the secret from
-     *
-     * @return {string} the contents of the secret
      */
-    request(name, devices) {
-        const requestId = this._baseApis.makeTxnId();
+    public request(name: string, devices: string[]): ISecretRequest {
+        const requestId = this.baseApis.makeTxnId();
 
-        const requestControl = this._requests[requestId] = {
+        let resolve: (string) => void;
+        let reject: (Error) => void;
+        const promise = new Promise<string>((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.requests.set(requestId, {
             name,
             devices,
-        };
-        const promise = new Promise((resolve, reject) => {
-            requestControl.resolve = resolve;
-            requestControl.reject = reject;
+            resolve,
+            reject,
         });
-        const cancel = (reason) => {
+
+        const cancel = (reason: string) => {
             // send cancellation event
             const cancelData = {
                 action: "request_cancellation",
-                requesting_device_id: this._baseApis.deviceId,
+                requesting_device_id: this.baseApis.deviceId,
                 request_id: requestId,
             };
             const toDevice = {};
             for (const device of devices) {
                 toDevice[device] = cancelData;
             }
-            this._baseApis.sendToDevice("m.secret.request", {
-                [this._baseApis.getUserId()]: toDevice,
+            this.baseApis.sendToDevice("m.secret.request", {
+                [this.baseApis.getUserId()]: toDevice,
             });
 
             // and reject the promise so that anyone waiting on it will be
             // notified
-            requestControl.reject(new Error(reason || "Cancelled"));
+            reject(new Error(reason || "Cancelled"));
         };
 
         // send request to devices
         const requestData = {
             name,
             action: "request",
-            requesting_device_id: this._baseApis.deviceId,
+            requesting_device_id: this.baseApis.deviceId,
             request_id: requestId,
         };
         const toDevice = {};
@@ -417,21 +420,21 @@ export class SecretStorage extends EventEmitter {
             toDevice[device] = requestData;
         }
         logger.info(`Request secret ${name} from ${devices}, id ${requestId}`);
-        this._baseApis.sendToDevice("m.secret.request", {
-            [this._baseApis.getUserId()]: toDevice,
+        this.baseApis.sendToDevice("m.secret.request", {
+            [this.baseApis.getUserId()]: toDevice,
         });
 
         return {
-            request_id: requestId,
+            requestId,
             promise,
             cancel,
         };
     }
 
-    async _onRequestReceived(event) {
+    public async onRequestReceived(event: MatrixEvent): Promise<void> {
         const sender = event.getSender();
         const content = event.getContent();
-        if (sender !== this._baseApis.getUserId()
+        if (sender !== this.baseApis.getUserId()
             || !(content.name && content.action
                  && content.requesting_device_id && content.request_id)) {
             // ignore requests from anyone else, for now
@@ -440,34 +443,45 @@ export class SecretStorage extends EventEmitter {
         const deviceId = content.requesting_device_id;
         // check if it's a cancel
         if (content.action === "request_cancellation") {
+            /*
+            Looks like we intended to emit events when we got cancelations, but
+            we never put anything in the _incomingRequests object, and the request
+            itself doesn't use events anyway so if we were to wire up cancellations,
+            they probably ought to use the same callback interface. I'm leaving them
+            disabled for now while converting this file to typescript.
             if (this._incomingRequests[deviceId]
                 && this._incomingRequests[deviceId][content.request_id]) {
-                logger.info("received request cancellation for secret (" + sender
-                            + ", " + deviceId + ", " + content.request_id + ")");
-                this._baseApis.emit("crypto.secrets.requestCancelled", {
+                logger.info(
+                    "received request cancellation for secret (" + sender +
+                    ", " + deviceId + ", " + content.request_id + ")",
+                );
+                this.baseApis.emit("crypto.secrets.requestCancelled", {
                     user_id: sender,
                     device_id: deviceId,
                     request_id: content.request_id,
                 });
             }
+            */
         } else if (content.action === "request") {
-            if (deviceId === this._baseApis.deviceId) {
+            if (deviceId === this.baseApis.deviceId) {
                 // no point in trying to send ourself the secret
                 return;
             }
 
             // check if we have the secret
-            logger.info("received request for secret (" + sender
-                        + ", " + deviceId + ", " + content.request_id + ")");
-            if (!this._cryptoCallbacks.onSecretRequested) {
+            logger.info(
+                "received request for secret (" + sender +
+                ", " + deviceId + ", " + content.request_id + ")",
+            );
+            if (!this.cryptoCallbacks.onSecretRequested) {
                 return;
             }
-            const secret = await this._cryptoCallbacks.onSecretRequested(
+            const secret = await this.cryptoCallbacks.onSecretRequested(
                 sender,
                 deviceId,
                 content.request_id,
                 content.name,
-                this._baseApis.checkDeviceTrust(sender, deviceId),
+                this.baseApis.checkDeviceTrust(sender, deviceId),
             );
             if (secret) {
                 logger.info(`Preparing ${content.name} secret for ${deviceId}`);
@@ -480,25 +494,25 @@ export class SecretStorage extends EventEmitter {
                 };
                 const encryptedContent = {
                     algorithm: olmlib.OLM_ALGORITHM,
-                    sender_key: this._baseApis.crypto._olmDevice.deviceCurve25519Key,
+                    sender_key: this.baseApis.crypto.olmDevice.deviceCurve25519Key,
                     ciphertext: {},
                 };
                 await olmlib.ensureOlmSessionsForDevices(
-                    this._baseApis.crypto._olmDevice,
-                    this._baseApis,
+                    this.baseApis.crypto.olmDevice,
+                    this.baseApis,
                     {
                         [sender]: [
-                            this._baseApis.getStoredDevice(sender, deviceId),
+                            this.baseApis.getStoredDevice(sender, deviceId),
                         ],
                     },
                 );
                 await olmlib.encryptMessageForDevice(
                     encryptedContent.ciphertext,
-                    this._baseApis.getUserId(),
-                    this._baseApis.deviceId,
-                    this._baseApis.crypto._olmDevice,
+                    this.baseApis.getUserId(),
+                    this.baseApis.deviceId,
+                    this.baseApis.crypto.olmDevice,
                     sender,
-                    this._baseApis.getStoredDevice(sender, deviceId),
+                    this.baseApis.getStoredDevice(sender, deviceId),
                     payload,
                 );
                 const contentMap = {
@@ -508,26 +522,26 @@ export class SecretStorage extends EventEmitter {
                 };
 
                 logger.info(`Sending ${content.name} secret for ${deviceId}`);
-                this._baseApis.sendToDevice("m.room.encrypted", contentMap);
+                this.baseApis.sendToDevice("m.room.encrypted", contentMap);
             } else {
                 logger.info(`Request denied for ${content.name} secret for ${deviceId}`);
             }
         }
     }
 
-    _onSecretReceived(event) {
-        if (event.getSender() !== this._baseApis.getUserId()) {
+    public onSecretReceived(event: MatrixEvent): void {
+        if (event.getSender() !== this.baseApis.getUserId()) {
             // we shouldn't be receiving secrets from anyone else, so ignore
             // because someone could be trying to send us bogus data
             return;
         }
         const content = event.getContent();
         logger.log("got secret share for request", content.request_id);
-        const requestControl = this._requests[content.request_id];
+        const requestControl = this.requests.get(content.request_id);
         if (requestControl) {
             // make sure that the device that sent it is one of the devices that
             // we requested from
-            const deviceInfo = this._baseApis.crypto._deviceList.getDeviceByIdentityKey(
+            const deviceInfo = this.baseApis.crypto.deviceList.getDeviceByIdentityKey(
                 olmlib.OLM_ALGORITHM,
                 event.getSenderKey(),
             );
@@ -550,12 +564,15 @@ export class SecretStorage extends EventEmitter {
         }
     }
 
-    async _getSecretStorageKey(keys, name) {
-        if (!this._cryptoCallbacks.getSecretStorageKey) {
+    private async getSecretStorageKey(
+        keys: Record<string, ISecretStorageKeyInfo>,
+        name: string,
+    ): Promise<[string, IDecryptors]> {
+        if (!this.cryptoCallbacks.getSecretStorageKey) {
             throw new Error("No getSecretStorageKey callback supplied");
         }
 
-        const returned = await this._cryptoCallbacks.getSecretStorageKey({ keys }, name);
+        const returned = await this.cryptoCallbacks.getSecretStorageKey({ keys }, name);
 
         if (!returned) {
             throw new Error("getSecretStorageKey callback returned falsey");
@@ -571,10 +588,10 @@ export class SecretStorage extends EventEmitter {
 
         if (keys[keyId].algorithm === SECRET_STORAGE_ALGORITHM_V1_AES) {
             const decryption = {
-                encrypt: async function(secret) {
+                encrypt: async function(secret: string): Promise<IEncryptedPayload> {
                     return await encryptAES(secret, privateKey, name);
                 },
-                decrypt: async function(encInfo) {
+                decrypt: async function(encInfo: IEncryptedPayload): Promise<string> {
                     return await decryptAES(encInfo, privateKey, name);
                 },
             };

src/crypto/aes.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2020 The Matrix.org Foundation C.I.C.
+Copyright 2020 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -14,6 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import type { BinaryLike } from "crypto";
+
 import { getCrypto } from '../utils';
 import { decodeBase64, encodeBase64 } from './olmlib';
 
@@ -21,7 +23,13 @@ const subtleCrypto = (typeof window !== "undefined" && window.crypto) ?
     (window.crypto.subtle || window.crypto.webkitSubtle) : null;
 
 // salt for HKDF, with 8 bytes of zeros
-const zerosalt = new Uint8Array(8);
+const zeroSalt = new Uint8Array(8);
+
+export interface IEncryptedPayload {
+    iv: string;
+    ciphertext: string;
+    mac: string;
+}
 
 /**
  * encrypt a string in Node.js
@@ -31,7 +39,7 @@ const zerosalt = new Uint8Array(8);
  * @param {string} name the name of the secret
  * @param {string} ivStr the initialization vector to use
  */
-async function encryptNode(data, key, name, ivStr) {
+async function encryptNode(data: string, key: Uint8Array, name: string, ivStr?: string): Promise<IEncryptedPayload> {
     const crypto = getCrypto();
     if (!crypto) {
         throw new Error("No usable crypto implementation");
@@ -52,15 +60,17 @@ async function encryptNode(data, key, name, ivStr) {
     const [aesKey, hmacKey] = deriveKeysNode(key, name);
 
     const cipher = crypto.createCipheriv("aes-256-ctr", aesKey, iv);
-    const ciphertext = cipher.update(data, "utf-8", "base64")
-          + cipher.final("base64");
+    const ciphertext = Buffer.concat([
+        cipher.update(data, "utf8"),
+        cipher.final(),
+    ]);
 
     const hmac = crypto.createHmac("sha256", hmacKey)
-        .update(ciphertext, "base64").digest("base64");
+        .update(ciphertext).digest("base64");
 
     return {
         iv: encodeBase64(iv),
-        ciphertext: ciphertext,
+        ciphertext: ciphertext.toString("base64"),
         mac: hmac,
     };
 }
@@ -75,7 +85,7 @@ async function encryptNode(data, key, name, ivStr) {
  * @param {Uint8Array} key the encryption key to use
  * @param {string} name the name of the secret
  */
-async function decryptNode(data, key, name) {
+async function decryptNode(data: IEncryptedPayload, key: Uint8Array, name: string): Promise<string> {
     const crypto = getCrypto();
     if (!crypto) {
         throw new Error("No usable crypto implementation");
@@ -84,7 +94,8 @@ async function decryptNode(data, key, name) {
     const [aesKey, hmacKey] = deriveKeysNode(key, name);
 
     const hmac = crypto.createHmac("sha256", hmacKey)
-        .update(data.ciphertext, "base64").digest("base64").replace(/=+$/g, '');
+        .update(Buffer.from(data.ciphertext, "base64"))
+        .digest("base64").replace(/=+$/g, '');
 
     if (hmac !== data.mac.replace(/=+$/g, '')) {
         throw new Error(`Error decrypting secret ${name}: bad MAC`);
@@ -93,21 +104,20 @@ async function decryptNode(data, key, name) {
     const decipher = crypto.createDecipheriv(
         "aes-256-ctr", aesKey, decodeBase64(data.iv),
     );
-    return decipher.update(data.ciphertext, "base64", "utf-8")
-          + decipher.final("utf-8");
+    return decipher.update(data.ciphertext, "base64", "utf8")
+          + decipher.final("utf8");
 }
 
-function deriveKeysNode(key, name) {
+function deriveKeysNode(key: BinaryLike, name: string): [Buffer, Buffer] {
     const crypto = getCrypto();
-    const prk = crypto.createHmac("sha256", zerosalt)
-        .update(key).digest();
+    const prk = crypto.createHmac("sha256", zeroSalt).update(key).digest();
 
     const b = Buffer.alloc(1, 1);
     const aesKey = crypto.createHmac("sha256", prk)
-        .update(name, "utf-8").update(b).digest();
+        .update(name, "utf8").update(b).digest();
     b[0] = 2;
     const hmacKey = crypto.createHmac("sha256", prk)
-        .update(aesKey).update(name, "utf-8").update(b).digest();
+        .update(aesKey).update(name, "utf8").update(b).digest();
 
     return [aesKey, hmacKey];
 }
@@ -120,7 +130,7 @@ function deriveKeysNode(key, name) {
  * @param {string} name the name of the secret
  * @param {string} ivStr the initialization vector to use
  */
-async function encryptBrowser(data, key, name, ivStr) {
+async function encryptBrowser(data: string, key: Uint8Array, name: string, ivStr?: string): Promise<IEncryptedPayload> {
     let iv;
     if (ivStr) {
         iv = decodeBase64(ivStr);
@@ -170,7 +180,7 @@ async function encryptBrowser(data, key, name, ivStr) {
  * @param {Uint8Array} key the encryption key to use
  * @param {string} name the name of the secret
  */
-async function decryptBrowser(data, key, name) {
+async function decryptBrowser(data: IEncryptedPayload, key: Uint8Array, name: string): Promise<string> {
     const [aesKey, hmacKey] = await deriveKeysBrowser(key, name);
 
     const ciphertext = decodeBase64(data.ciphertext);
@@ -197,7 +207,7 @@ async function decryptBrowser(data, key, name) {
     return new TextDecoder().decode(new Uint8Array(plaintext));
 }
 
-async function deriveKeysBrowser(key, name) {
+async function deriveKeysBrowser(key: Uint8Array, name: string): Promise<[CryptoKey, CryptoKey]> {
     const hkdfkey = await subtleCrypto.importKey(
         'raw',
         key,
@@ -208,7 +218,9 @@ async function deriveKeysBrowser(key, name) {
     const keybits = await subtleCrypto.deriveBits(
         {
             name: "HKDF",
-            salt: zerosalt,
+            salt: zeroSalt,
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore: https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/879
             info: (new TextEncoder().encode(name)),
             hash: "SHA-256",
         },
@@ -241,11 +253,24 @@ async function deriveKeysBrowser(key, name) {
     return await Promise.all([aesProm, hmacProm]);
 }
 
-export function encryptAES(...args) {
-    return subtleCrypto ? encryptBrowser(...args) : encryptNode(...args);
+export function encryptAES(data: string, key: Uint8Array, name: string, ivStr?: string): Promise<IEncryptedPayload> {
+    return subtleCrypto ? encryptBrowser(data, key, name, ivStr) : encryptNode(data, key, name, ivStr);
 }
 
-export function decryptAES(...args) {
-    return subtleCrypto ? decryptBrowser(...args) : decryptNode(...args);
+export function decryptAES(data: IEncryptedPayload, key: Uint8Array, name: string): Promise<string> {
+    return subtleCrypto ? decryptBrowser(data, key, name) : decryptNode(data, key, name);
 }
 
+// string of zeroes, for calculating the key check
+const ZERO_STR = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
+
+/** Calculate the MAC for checking the key.
+ *
+ * @param {Uint8Array} key the key to use
+ * @param {string} [iv] The initialization vector as a base64-encoded string.
+ *     If omitted, a random initialization vector will be created.
+ * @return {Promise<object>} An object that contains, `mac` and `iv` properties.
+ */
+export function calculateKeyCheck(key: Uint8Array, iv?: string): Promise<IEncryptedPayload> {
+    return encryptAES(ZERO_STR, key, "", iv);
+}

src/crypto/algorithms/base.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2016 OpenMarket Ltd
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -20,13 +20,23 @@ limitations under the License.
  * @module
  */
 
+import { MatrixClient } from "../../client";
+import { Room } from "../../models/room";
+import { OlmDevice } from "../OlmDevice";
+import { MatrixEvent, RoomMember } from "../..";
+import { Crypto, IEventDecryptionResult, IMegolmSessionData, IncomingRoomKeyRequest } from "..";
+import { DeviceInfo } from "../deviceinfo";
+import { IRoomEncryption } from "../RoomList";
+
 /**
  * map of registered encryption algorithm classes. A map from string to {@link
  * module:crypto/algorithms/base.EncryptionAlgorithm|EncryptionAlgorithm} class
  *
  * @type {Object.<string, function(new: module:crypto/algorithms/base.EncryptionAlgorithm)>}
  */
-export const ENCRYPTION_CLASSES = {};
+export const ENCRYPTION_CLASSES: Record<string, new (params: IParams) => EncryptionAlgorithm> = {};
+
+type DecryptionClassParams = Omit<IParams, "deviceId" | "config">;
 
 /**
  * map of registered encryption algorithm classes. Map from string to {@link
@@ -34,7 +44,17 @@ export const ENCRYPTION_CLASSES = {};
  *
  * @type {Object.<string, function(new: module:crypto/algorithms/base.DecryptionAlgorithm)>}
  */
-export const DECRYPTION_CLASSES = {};
+export const DECRYPTION_CLASSES: Record<string, new (params: DecryptionClassParams) => DecryptionAlgorithm> = {};
+
+interface IParams {
+    userId: string;
+    deviceId: string;
+    crypto: Crypto;
+    olmDevice: OlmDevice;
+    baseApis: MatrixClient;
+    roomId: string;
+    config: IRoomEncryption & object;
+}
 
 /**
  * base type for encryption implementations
@@ -50,14 +70,21 @@ export const DECRYPTION_CLASSES = {};
  * @param {string} params.roomId  The ID of the room we will be sending to
  * @param {object} params.config  The body of the m.room.encryption event
  */
-export class EncryptionAlgorithm {
-    constructor(params) {
-        this._userId = params.userId;
-        this._deviceId = params.deviceId;
-        this._crypto = params.crypto;
-        this._olmDevice = params.olmDevice;
-        this._baseApis = params.baseApis;
-        this._roomId = params.roomId;
+export abstract class EncryptionAlgorithm {
+    protected readonly userId: string;
+    protected readonly deviceId: string;
+    protected readonly crypto: Crypto;
+    protected readonly olmDevice: OlmDevice;
+    protected readonly baseApis: MatrixClient;
+    protected readonly roomId: string;
+
+    constructor(params: IParams) {
+        this.userId = params.userId;
+        this.deviceId = params.deviceId;
+        this.crypto = params.crypto;
+        this.olmDevice = params.olmDevice;
+        this.baseApis = params.baseApis;
+        this.roomId = params.roomId;
     }
 
     /**
@@ -66,21 +93,22 @@ export class EncryptionAlgorithm {
      *
      * @param {module:models/room} room the room the event is in
      */
-    prepareToEncrypt(room) {
-    }
+    public prepareToEncrypt(room: Room): void {}
 
     /**
      * Encrypt a message event
      *
      * @method module:crypto/algorithms/base.EncryptionAlgorithm.encryptMessage
+     * @public
      * @abstract
      *
      * @param {module:models/room} room
      * @param {string} eventType
-     * @param {object} plaintext event content
+     * @param {object} content event content
      *
      * @return {Promise} Promise which resolves to the new event body
      */
+    public abstract encryptMessage(room: Room, eventType: string, content: object): Promise<object>;
 
     /**
      * Called when the membership of a member of the room changes.
@@ -89,9 +117,18 @@ export class EncryptionAlgorithm {
      * @param {module:models/room-member} member  user whose membership changed
      * @param {string=} oldMembership  previous membership
      * @public
+     * @abstract
      */
-     onRoomMembership(event, member, oldMembership) {
-     }
+    public onRoomMembership(event: MatrixEvent, member: RoomMember, oldMembership?: string): void {}
+
+    public reshareKeyWithDevice?(
+        senderKey: string,
+        sessionId: string,
+        userId: string,
+        device: DeviceInfo,
+    ): Promise<void>;
+
+    public forceDiscardSession?(): void;
 }
 
 /**
@@ -106,13 +143,19 @@ export class EncryptionAlgorithm {
  * @param {string=} params.roomId The ID of the room we will be receiving
  *     from. Null for to-device events.
  */
-export class DecryptionAlgorithm {
-    constructor(params) {
-        this._userId = params.userId;
-        this._crypto = params.crypto;
-        this._olmDevice = params.olmDevice;
-        this._baseApis = params.baseApis;
-        this._roomId = params.roomId;
+export abstract class DecryptionAlgorithm {
+    protected readonly userId: string;
+    protected readonly crypto: Crypto;
+    protected readonly olmDevice: OlmDevice;
+    protected readonly baseApis: MatrixClient;
+    protected readonly roomId: string;
+
+    constructor(params: DecryptionClassParams) {
+        this.userId = params.userId;
+        this.crypto = params.crypto;
+        this.olmDevice = params.olmDevice;
+        this.baseApis = params.baseApis;
+        this.roomId = params.roomId;
     }
 
     /**
@@ -127,6 +170,7 @@ export class DecryptionAlgorithm {
      * resolves once we have finished decrypting. Rejects with an
      * `algorithms.DecryptionError` if there is a problem decrypting the event.
      */
+    public abstract decryptEvent(event: MatrixEvent): Promise<IEventDecryptionResult>;
 
     /**
      * Handle a key event
@@ -135,7 +179,7 @@ export class DecryptionAlgorithm {
      *
      * @param {module:models/event.MatrixEvent} params event key event
      */
-    onRoomKeyEvent(params) {
+    public onRoomKeyEvent(params: MatrixEvent): void {
         // ignore by default
     }
 
@@ -143,8 +187,9 @@ export class DecryptionAlgorithm {
      * Import a room key
      *
      * @param {module:crypto/OlmDevice.MegolmSessionData} session
+     * @param {object} opts object
      */
-    importRoomKey(session) {
+    public async importRoomKey(session: IMegolmSessionData, opts: object): Promise<void> {
         // ignore by default
     }
 
@@ -155,7 +200,7 @@ export class DecryptionAlgorithm {
      * @return {Promise<boolean>} true if we have the keys and could (theoretically) share
      *  them; else false.
      */
-    hasKeysForKeyRequest(keyRequest) {
+    public hasKeysForKeyRequest(keyRequest: IncomingRoomKeyRequest): Promise<boolean> {
         return Promise.resolve(false);
     }
 
@@ -164,7 +209,7 @@ export class DecryptionAlgorithm {
      *
      * @param {module:crypto~IncomingRoomKeyRequest} keyRequest
      */
-    shareKeysWithDevice(keyRequest) {
+    public shareKeysWithDevice(keyRequest: IncomingRoomKeyRequest): void {
         throw new Error("shareKeysWithDevice not supported for this DecryptionAlgorithm");
     }
 
@@ -174,9 +219,13 @@ export class DecryptionAlgorithm {
      *
      * @param {string} senderKey the sender's key
      */
-    async retryDecryptionFromSender(senderKey) {
+    public async retryDecryptionFromSender(senderKey: string): Promise<boolean> {
         // ignore by default
+        return false;
     }
+
+    public onRoomKeyWithheldEvent?(event: MatrixEvent): Promise<void>;
+    public sendSharedHistoryInboundSessions?(devicesByUser: Record<string, DeviceInfo[]>): Promise<void>;
 }
 
 /**
@@ -191,22 +240,21 @@ export class DecryptionAlgorithm {
  * @extends Error
  */
 export class DecryptionError extends Error {
-    constructor(code, msg, details) {
+    public readonly detailedString: string;
+
+    constructor(public readonly code: string, msg: string, details?: Record<string, string>) {
         super(msg);
         this.code = code;
         this.name = 'DecryptionError';
-        this.detailedString = _detailedStringForDecryptionError(this, details);
+        this.detailedString = detailedStringForDecryptionError(this, details);
     }
 }
 
-function _detailedStringForDecryptionError(err, details) {
+function detailedStringForDecryptionError(err: DecryptionError, details?: Record<string, string>): string {
     let result = err.name + '[msg: ' + err.message;
 
     if (details) {
-        result += ', ' +
-            Object.keys(details).map(
-                (k) => k + ': ' + details[k],
-            ).join(', ');
+        result += ', ' + Object.keys(details).map((k) => k + ': ' + details[k]).join(', ');
     }
 
     result += ']';
@@ -224,7 +272,7 @@ function _detailedStringForDecryptionError(err, details) {
  * @extends Error
  */
 export class UnknownDeviceError extends Error {
-    constructor(msg, devices) {
+    constructor(msg: string, public readonly devices: Record<string, Record<string, object>>) {
         super(msg);
         this.name = "UnknownDeviceError";
         this.devices = devices;
@@ -244,7 +292,11 @@ export class UnknownDeviceError extends Error {
  *     module:crypto/algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm}
  *     implementation
  */
-export function registerAlgorithm(algorithm, encryptor, decryptor) {
+export function registerAlgorithm(
+    algorithm: string,
+    encryptor: new (params: IParams) => EncryptionAlgorithm,
+    decryptor: new (params: Omit<IParams, "deviceId">) => DecryptionAlgorithm,
+): void {
     ENCRYPTION_CLASSES[algorithm] = encryptor;
     DECRYPTION_CLASSES[algorithm] = decryptor;
 }

src/crypto/algorithms/index.ts

@@ -1,6 +1,5 @@
 /*
-Copyright 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

src/crypto/algorithms/olm.js

@@ -1,361 +0,0 @@
-/*
-Copyright 2016 OpenMarket Ltd
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * Defines m.olm encryption/decryption
- *
- * @module crypto/algorithms/olm
- */
-
-import { logger } from '../../logger';
-import * as utils from "../../utils";
-import { polyfillSuper } from "../../utils";
-import * as olmlib from "../olmlib";
-import { DeviceInfo } from "../deviceinfo";
-import {
-    DecryptionAlgorithm,
-    DecryptionError,
-    EncryptionAlgorithm,
-    registerAlgorithm,
-} from "./base";
-
-const DeviceVerification = DeviceInfo.DeviceVerification;
-
-/**
- * Olm encryption implementation
- *
- * @constructor
- * @extends {module:crypto/algorithms/EncryptionAlgorithm}
- *
- * @param {object} params parameters, as per
- *     {@link module:crypto/algorithms/EncryptionAlgorithm}
- */
-function OlmEncryption(params) {
-    polyfillSuper(this, EncryptionAlgorithm, params);
-    this._sessionPrepared = false;
-    this._prepPromise = null;
-}
-utils.inherits(OlmEncryption, EncryptionAlgorithm);
-
-/**
- * @private
-
- * @param {string[]} roomMembers list of currently-joined users in the room
- * @return {Promise} Promise which resolves when setup is complete
- */
-OlmEncryption.prototype._ensureSession = function(roomMembers) {
-    if (this._prepPromise) {
-        // prep already in progress
-        return this._prepPromise;
-    }
-
-    if (this._sessionPrepared) {
-        // prep already done
-        return Promise.resolve();
-    }
-
-    const self = this;
-    this._prepPromise = self._crypto.downloadKeys(roomMembers).then(function(res) {
-        return self._crypto.ensureOlmSessionsForUsers(roomMembers);
-    }).then(function() {
-        self._sessionPrepared = true;
-    }).finally(function() {
-        self._prepPromise = null;
-    });
-    return this._prepPromise;
-};
-
-/**
- * @inheritdoc
- *
- * @param {module:models/room} room
- * @param {string} eventType
- * @param {object} content plaintext event content
- *
- * @return {Promise} Promise which resolves to the new event body
- */
-OlmEncryption.prototype.encryptMessage = async function(room, eventType, content) {
-    // pick the list of recipients based on the membership list.
-    //
-    // TODO: there is a race condition here! What if a new user turns up
-    // just as you are sending a secret message?
-
-    const members = await room.getEncryptionTargetMembers();
-
-    const users = members.map(function(u) {
-        return u.userId;
-    });
-
-    const self = this;
-    await this._ensureSession(users);
-
-    const payloadFields = {
-        room_id: room.roomId,
-        type: eventType,
-        content: content,
-    };
-
-    const encryptedContent = {
-        algorithm: olmlib.OLM_ALGORITHM,
-        sender_key: self._olmDevice.deviceCurve25519Key,
-        ciphertext: {},
-    };
-
-    const promises = [];
-
-    for (let i = 0; i < users.length; ++i) {
-        const userId = users[i];
-        const devices = self._crypto.getStoredDevicesForUser(userId);
-
-        for (let j = 0; j < devices.length; ++j) {
-            const deviceInfo = devices[j];
-            const key = deviceInfo.getIdentityKey();
-            if (key == self._olmDevice.deviceCurve25519Key) {
-                // don't bother sending to ourself
-                continue;
-            }
-            if (deviceInfo.verified == DeviceVerification.BLOCKED) {
-                // don't bother setting up sessions with blocked users
-                continue;
-            }
-
-            promises.push(
-                olmlib.encryptMessageForDevice(
-                    encryptedContent.ciphertext,
-                    self._userId, self._deviceId, self._olmDevice,
-                    userId, deviceInfo, payloadFields,
-                ),
-            );
-        }
-    }
-
-    return await Promise.all(promises).then(() => encryptedContent);
-};
-
-/**
- * Olm decryption implementation
- *
- * @constructor
- * @extends {module:crypto/algorithms/DecryptionAlgorithm}
- * @param {object} params parameters, as per
- *     {@link module:crypto/algorithms/DecryptionAlgorithm}
- */
-function OlmDecryption(params) {
-    polyfillSuper(this, DecryptionAlgorithm, params);
-}
-utils.inherits(OlmDecryption, DecryptionAlgorithm);
-
-/**
- * @inheritdoc
- *
- * @param {MatrixEvent} event
- *
- * returns a promise which resolves to a
- * {@link module:crypto~EventDecryptionResult} once we have finished
- * decrypting. Rejects with an `algorithms.DecryptionError` if there is a
- * problem decrypting the event.
- */
-OlmDecryption.prototype.decryptEvent = async function(event) {
-    const content = event.getWireContent();
-    const deviceKey = content.sender_key;
-    const ciphertext = content.ciphertext;
-
-    if (!ciphertext) {
-        throw new DecryptionError(
-            "OLM_MISSING_CIPHERTEXT",
-            "Missing ciphertext",
-        );
-    }
-
-    if (!(this._olmDevice.deviceCurve25519Key in ciphertext)) {
-        throw new DecryptionError(
-            "OLM_NOT_INCLUDED_IN_RECIPIENTS",
-            "Not included in recipients",
-        );
-    }
-    const message = ciphertext[this._olmDevice.deviceCurve25519Key];
-    let payloadString;
-
-    try {
-        payloadString = await this._decryptMessage(deviceKey, message);
-    } catch (e) {
-        throw new DecryptionError(
-            "OLM_BAD_ENCRYPTED_MESSAGE",
-            "Bad Encrypted Message", {
-                sender: deviceKey,
-                err: e,
-            },
-        );
-    }
-
-    const payload = JSON.parse(payloadString);
-
-    // check that we were the intended recipient, to avoid unknown-key attack
-    // https://github.com/vector-im/vector-web/issues/2483
-    if (payload.recipient != this._userId) {
-        throw new DecryptionError(
-            "OLM_BAD_RECIPIENT",
-            "Message was intented for " + payload.recipient,
-        );
-    }
-
-    if (payload.recipient_keys.ed25519 != this._olmDevice.deviceEd25519Key) {
-        throw new DecryptionError(
-            "OLM_BAD_RECIPIENT_KEY",
-            "Message not intended for this device", {
-                intended: payload.recipient_keys.ed25519,
-                our_key: this._olmDevice.deviceEd25519Key,
-            },
-        );
-    }
-
-    // check that the original sender matches what the homeserver told us, to
-    // avoid people masquerading as others.
-    // (this check is also provided via the sender's embedded ed25519 key,
-    // which is checked elsewhere).
-    if (payload.sender != event.getSender()) {
-        throw new DecryptionError(
-            "OLM_FORWARDED_MESSAGE",
-            "Message forwarded from " + payload.sender, {
-                reported_sender: event.getSender(),
-            },
-        );
-    }
-
-    // Olm events intended for a room have a room_id.
-    if (payload.room_id !== event.getRoomId()) {
-        throw new DecryptionError(
-            "OLM_BAD_ROOM",
-            "Message intended for room " + payload.room_id, {
-                reported_room: event.room_id,
-            },
-        );
-    }
-
-    const claimedKeys = payload.keys || {};
-
-    return {
-        clearEvent: payload,
-        senderCurve25519Key: deviceKey,
-        claimedEd25519Key: claimedKeys.ed25519 || null,
-    };
-};
-
-/**
- * Attempt to decrypt an Olm message
- *
- * @param {string} theirDeviceIdentityKey  Curve25519 identity key of the sender
- * @param {object} message  message object, with 'type' and 'body' fields
- *
- * @return {string} payload, if decrypted successfully.
- */
-OlmDecryption.prototype._decryptMessage = async function(
-    theirDeviceIdentityKey, message,
-) {
-    // This is a wrapper that serialises decryptions of prekey messages, because
-    // otherwise we race between deciding we have no active sessions for the message
-    // and creating a new one, which we can only do once because it removes the OTK.
-    if (message.type !== 0) {
-        // not a prekey message: we can safely just try & decrypt it
-        return this._reallyDecryptMessage(theirDeviceIdentityKey, message);
-    } else {
-        const myPromise = this._olmDevice._olmPrekeyPromise.then(() => {
-            return this._reallyDecryptMessage(theirDeviceIdentityKey, message);
-        });
-        // we want the error, but don't propagate it to the next decryption
-        this._olmDevice._olmPrekeyPromise = myPromise.catch(() => {});
-        return await myPromise;
-    }
-};
-
-OlmDecryption.prototype._reallyDecryptMessage = async function(
-    theirDeviceIdentityKey, message,
-) {
-    const sessionIds = await this._olmDevice.getSessionIdsForDevice(
-        theirDeviceIdentityKey,
-    );
-
-    // try each session in turn.
-    const decryptionErrors = {};
-    for (let i = 0; i < sessionIds.length; i++) {
-        const sessionId = sessionIds[i];
-        try {
-            const payload = await this._olmDevice.decryptMessage(
-                theirDeviceIdentityKey, sessionId, message.type, message.body,
-            );
-            logger.log(
-                "Decrypted Olm message from " + theirDeviceIdentityKey +
-                    " with session " + sessionId,
-            );
-            return payload;
-        } catch (e) {
-            const foundSession = await this._olmDevice.matchesSession(
-                theirDeviceIdentityKey, sessionId, message.type, message.body,
-            );
-
-            if (foundSession) {
-                // decryption failed, but it was a prekey message matching this
-                // session, so it should have worked.
-                throw new Error(
-                    "Error decrypting prekey message with existing session id " +
-                        sessionId + ": " + e.message,
-                );
-            }
-
-            // otherwise it's probably a message for another session; carry on, but
-            // keep a record of the error
-            decryptionErrors[sessionId] = e.message;
-        }
-    }
-
-    if (message.type !== 0) {
-        // not a prekey message, so it should have matched an existing session, but it
-        // didn't work.
-
-        if (sessionIds.length === 0) {
-            throw new Error("No existing sessions");
-        }
-
-        throw new Error(
-            "Error decrypting non-prekey message with existing sessions: " +
-                JSON.stringify(decryptionErrors),
-        );
-    }
-
-    // prekey message which doesn't match any existing sessions: make a new
-    // session.
-
-    let res;
-    try {
-        res = await this._olmDevice.createInboundSession(
-            theirDeviceIdentityKey, message.type, message.body,
-        );
-    } catch (e) {
-        decryptionErrors["(new)"] = e.message;
-        throw new Error(
-            "Error decrypting prekey message: " +
-                JSON.stringify(decryptionErrors),
-        );
-    }
-
-    logger.log(
-        "created new inbound Olm session ID " +
-            res.session_id + " with " + theirDeviceIdentityKey,
-    );
-    return res.payload;
-};
-
-registerAlgorithm(olmlib.OLM_ALGORITHM, OlmEncryption, OlmDecryption);

src/crypto/algorithms/olm.ts

@@ -0,0 +1,355 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * Defines m.olm encryption/decryption
+ *
+ * @module crypto/algorithms/olm
+ */
+
+import { logger } from '../../logger';
+import * as olmlib from "../olmlib";
+import { DeviceInfo } from "../deviceinfo";
+import {
+    DecryptionAlgorithm,
+    DecryptionError,
+    EncryptionAlgorithm,
+    registerAlgorithm,
+} from "./base";
+import { Room } from '../../models/room';
+import { MatrixEvent } from "../..";
+import { IEventDecryptionResult } from "../index";
+
+const DeviceVerification = DeviceInfo.DeviceVerification;
+
+interface IMessage {
+    type: number | string;
+    body: string;
+}
+
+/**
+ * Olm encryption implementation
+ *
+ * @constructor
+ * @extends {module:crypto/algorithms/EncryptionAlgorithm}
+ *
+ * @param {object} params parameters, as per
+ *     {@link module:crypto/algorithms/EncryptionAlgorithm}
+ */
+class OlmEncryption extends EncryptionAlgorithm {
+    private sessionPrepared = false;
+    private prepPromise: Promise<void> = null;
+
+    /**
+     * @private
+
+     * @param {string[]} roomMembers list of currently-joined users in the room
+     * @return {Promise} Promise which resolves when setup is complete
+     */
+    private ensureSession(roomMembers: string[]): Promise<void> {
+        if (this.prepPromise) {
+            // prep already in progress
+            return this.prepPromise;
+        }
+
+        if (this.sessionPrepared) {
+            // prep already done
+            return Promise.resolve();
+        }
+
+        this.prepPromise = this.crypto.downloadKeys(roomMembers).then((res) => {
+            return this.crypto.ensureOlmSessionsForUsers(roomMembers);
+        }).then(() => {
+            this.sessionPrepared = true;
+        }).finally(() => {
+            this.prepPromise = null;
+        });
+
+        return this.prepPromise;
+    }
+
+    /**
+     * @inheritdoc
+     *
+     * @param {module:models/room} room
+     * @param {string} eventType
+     * @param {object} content plaintext event content
+     *
+     * @return {Promise} Promise which resolves to the new event body
+     */
+    public async encryptMessage(room: Room, eventType: string, content: object): Promise<object> {
+        // pick the list of recipients based on the membership list.
+        //
+        // TODO: there is a race condition here! What if a new user turns up
+        // just as you are sending a secret message?
+
+        const members = await room.getEncryptionTargetMembers();
+
+        const users = members.map(function(u) {
+            return u.userId;
+        });
+
+        await this.ensureSession(users);
+
+        const payloadFields = {
+            room_id: room.roomId,
+            type: eventType,
+            content: content,
+        };
+
+        const encryptedContent = {
+            algorithm: olmlib.OLM_ALGORITHM,
+            sender_key: this.olmDevice.deviceCurve25519Key,
+            ciphertext: {},
+        };
+
+        const promises = [];
+
+        for (let i = 0; i < users.length; ++i) {
+            const userId = users[i];
+            const devices = this.crypto.getStoredDevicesForUser(userId);
+
+            for (let j = 0; j < devices.length; ++j) {
+                const deviceInfo = devices[j];
+                const key = deviceInfo.getIdentityKey();
+                if (key == this.olmDevice.deviceCurve25519Key) {
+                    // don't bother sending to ourself
+                    continue;
+                }
+                if (deviceInfo.verified == DeviceVerification.BLOCKED) {
+                    // don't bother setting up sessions with blocked users
+                    continue;
+                }
+
+                promises.push(
+                    olmlib.encryptMessageForDevice(
+                        encryptedContent.ciphertext,
+                        this.userId, this.deviceId, this.olmDevice,
+                        userId, deviceInfo, payloadFields,
+                    ),
+                );
+            }
+        }
+
+        return await Promise.all(promises).then(() => encryptedContent);
+    }
+}
+
+/**
+ * Olm decryption implementation
+ *
+ * @constructor
+ * @extends {module:crypto/algorithms/DecryptionAlgorithm}
+ * @param {object} params parameters, as per
+ *     {@link module:crypto/algorithms/DecryptionAlgorithm}
+ */
+class OlmDecryption extends DecryptionAlgorithm {
+    /**
+     * @inheritdoc
+     *
+     * @param {MatrixEvent} event
+     *
+     * returns a promise which resolves to a
+     * {@link module:crypto~EventDecryptionResult} once we have finished
+     * decrypting. Rejects with an `algorithms.DecryptionError` if there is a
+     * problem decrypting the event.
+     */
+    public async decryptEvent(event: MatrixEvent): Promise<IEventDecryptionResult> {
+        const content = event.getWireContent();
+        const deviceKey = content.sender_key;
+        const ciphertext = content.ciphertext;
+
+        if (!ciphertext) {
+            throw new DecryptionError(
+                "OLM_MISSING_CIPHERTEXT",
+                "Missing ciphertext",
+            );
+        }
+
+        if (!(this.olmDevice.deviceCurve25519Key in ciphertext)) {
+            throw new DecryptionError(
+                "OLM_NOT_INCLUDED_IN_RECIPIENTS",
+                "Not included in recipients",
+            );
+        }
+        const message = ciphertext[this.olmDevice.deviceCurve25519Key];
+        let payloadString;
+
+        try {
+            payloadString = await this.decryptMessage(deviceKey, message);
+        } catch (e) {
+            throw new DecryptionError(
+                "OLM_BAD_ENCRYPTED_MESSAGE",
+                "Bad Encrypted Message", {
+                    sender: deviceKey,
+                    err: e,
+                },
+            );
+        }
+
+        const payload = JSON.parse(payloadString);
+
+        // check that we were the intended recipient, to avoid unknown-key attack
+        // https://github.com/vector-im/vector-web/issues/2483
+        if (payload.recipient != this.userId) {
+            throw new DecryptionError(
+                "OLM_BAD_RECIPIENT",
+                "Message was intented for " + payload.recipient,
+            );
+        }
+
+        if (payload.recipient_keys.ed25519 != this.olmDevice.deviceEd25519Key) {
+            throw new DecryptionError(
+                "OLM_BAD_RECIPIENT_KEY",
+                "Message not intended for this device", {
+                    intended: payload.recipient_keys.ed25519,
+                    our_key: this.olmDevice.deviceEd25519Key,
+                },
+            );
+        }
+
+        // check that the original sender matches what the homeserver told us, to
+        // avoid people masquerading as others.
+        // (this check is also provided via the sender's embedded ed25519 key,
+        // which is checked elsewhere).
+        if (payload.sender != event.getSender()) {
+            throw new DecryptionError(
+                "OLM_FORWARDED_MESSAGE",
+                "Message forwarded from " + payload.sender, {
+                    reported_sender: event.getSender(),
+                },
+            );
+        }
+
+        // Olm events intended for a room have a room_id.
+        if (payload.room_id !== event.getRoomId()) {
+            throw new DecryptionError(
+                "OLM_BAD_ROOM",
+                "Message intended for room " + payload.room_id, {
+                    reported_room: event.getRoomId(),
+                },
+            );
+        }
+
+        const claimedKeys = payload.keys || {};
+
+        return {
+            clearEvent: payload,
+            senderCurve25519Key: deviceKey,
+            claimedEd25519Key: claimedKeys.ed25519 || null,
+        };
+    }
+
+    /**
+     * Attempt to decrypt an Olm message
+     *
+     * @param {string} theirDeviceIdentityKey  Curve25519 identity key of the sender
+     * @param {object} message  message object, with 'type' and 'body' fields
+     *
+     * @return {string} payload, if decrypted successfully.
+     */
+    private async decryptMessage(theirDeviceIdentityKey: string, message: IMessage): Promise<string> {
+        // This is a wrapper that serialises decryptions of prekey messages, because
+        // otherwise we race between deciding we have no active sessions for the message
+        // and creating a new one, which we can only do once because it removes the OTK.
+        if (message.type !== 0) {
+            // not a prekey message: we can safely just try & decrypt it
+            return this.reallyDecryptMessage(theirDeviceIdentityKey, message);
+        } else {
+            const myPromise = this.olmDevice._olmPrekeyPromise.then(() => {
+                return this.reallyDecryptMessage(theirDeviceIdentityKey, message);
+            });
+            // we want the error, but don't propagate it to the next decryption
+            this.olmDevice._olmPrekeyPromise = myPromise.catch(() => {});
+            return await myPromise;
+        }
+    }
+
+    private async reallyDecryptMessage(theirDeviceIdentityKey: string, message: IMessage): Promise<string> {
+        const sessionIds = await this.olmDevice.getSessionIdsForDevice(theirDeviceIdentityKey);
+
+        // try each session in turn.
+        const decryptionErrors = {};
+        for (let i = 0; i < sessionIds.length; i++) {
+            const sessionId = sessionIds[i];
+            try {
+                const payload = await this.olmDevice.decryptMessage(
+                    theirDeviceIdentityKey, sessionId, message.type, message.body,
+                );
+                logger.log(
+                    "Decrypted Olm message from " + theirDeviceIdentityKey +
+                    " with session " + sessionId,
+                );
+                return payload;
+            } catch (e) {
+                const foundSession = await this.olmDevice.matchesSession(
+                    theirDeviceIdentityKey, sessionId, message.type, message.body,
+                );
+
+                if (foundSession) {
+                    // decryption failed, but it was a prekey message matching this
+                    // session, so it should have worked.
+                    throw new Error(
+                        "Error decrypting prekey message with existing session id " +
+                        sessionId + ": " + e.message,
+                    );
+                }
+
+                // otherwise it's probably a message for another session; carry on, but
+                // keep a record of the error
+                decryptionErrors[sessionId] = e.message;
+            }
+        }
+
+        if (message.type !== 0) {
+            // not a prekey message, so it should have matched an existing session, but it
+            // didn't work.
+
+            if (sessionIds.length === 0) {
+                throw new Error("No existing sessions");
+            }
+
+            throw new Error(
+                "Error decrypting non-prekey message with existing sessions: " +
+                JSON.stringify(decryptionErrors),
+            );
+        }
+
+        // prekey message which doesn't match any existing sessions: make a new
+        // session.
+
+        let res;
+        try {
+            res = await this.olmDevice.createInboundSession(
+                theirDeviceIdentityKey, message.type, message.body,
+            );
+        } catch (e) {
+            decryptionErrors["(new)"] = e.message;
+            throw new Error(
+                "Error decrypting prekey message: " +
+                JSON.stringify(decryptionErrors),
+            );
+        }
+
+        logger.log(
+            "created new inbound Olm session ID " +
+            res.session_id + " with " + theirDeviceIdentityKey,
+        );
+        return res.payload;
+    }
+}
+
+registerAlgorithm(olmlib.OLM_ALGORITHM, OlmEncryption, OlmDecryption);

src/crypto/api.ts

@@ -15,8 +15,7 @@ limitations under the License.
 */
 
 import { DeviceInfo } from "./deviceinfo";
-import { IKeyBackupVersion } from "./keybackup";
-import { ISecretStorageKeyInfo } from "../matrix";
+import { IKeyBackupInfo } from "./keybackup";
 
 // TODO: Merge this with crypto.js once converted
 
@@ -60,7 +59,7 @@ export interface IEncryptedEventInfo {
 
 export interface IRecoveryKey {
     keyInfo: {
-        pubkey: Uint8Array;
+        pubkey: string;
         passphrase?: {
             algorithm: string;
             iterations: number;
@@ -85,7 +84,7 @@ export interface ICreateSecretStorageOpts {
      * The current key backup object. If passed,
      * the passphrase and recovery key from this backup will be used.
      */
-    keyBackupInfo?: IKeyBackupVersion;
+    keyBackupInfo?: IKeyBackupInfo;
 
     /**
      * If true, a new key backup version will be
@@ -107,14 +106,32 @@ export interface ICreateSecretStorageOpts {
     getKeyBackupPassphrase?: () => Promise<Uint8Array>;
 }
 
+export interface ISecretStorageKeyInfo {
+    name: string;
+    algorithm: string;
+    // technically the below are specific to AES keys. If we ever introduce another type,
+    // we can split into separate interfaces.
+    iv: string;
+    mac: string;
+    passphrase: IPassphraseInfo;
+}
+
 export interface ISecretStorageKey {
     keyId: string;
     keyInfo: ISecretStorageKeyInfo;
 }
 
+export interface IPassphraseInfo {
+    algorithm: "m.pbkdf2";
+    iterations: number;
+    salt: string;
+    bits: number;
+}
+
 export interface IAddSecretStorageKeyOpts {
-    // depends on algorithm
-    // TODO: Types
+    name: string;
+    passphrase: IPassphraseInfo;
+    key: Uint8Array;
 }
 
 export interface IImportOpts {

src/crypto/backup.ts

@@ -29,33 +29,45 @@ import { keyFromPassphrase } from './key_passphrase';
 import { sleep } from "../utils";
 import { IndexedDBCryptoStore } from './store/indexeddb-crypto-store';
 import { encodeRecoveryKey } from './recoverykey';
+import { encryptAES, decryptAES, calculateKeyCheck } from './aes';
+import { getCrypto } from '../utils';
+import { ICurve25519AuthData, IAes256AuthData, IKeyBackupInfo, IKeyBackupSession } from "./keybackup";
+import { UnstableValue } from "../NamespacedValue";
 
 const KEY_BACKUP_KEYS_PER_REQUEST = 200;
 
-type AuthData = Record<string, any>;
-
-type BackupInfo = {
-    algorithm: string,
-    auth_data: AuthData, // eslint-disable-line camelcase
-    [properties: string]: any,
-};
+type AuthData = IKeyBackupInfo["auth_data"];
 
 type SigInfo = {
-    deviceId: string,
-    valid?: boolean | null, // true: valid, false: invalid, null: cannot attempt validation
-    device?: DeviceInfo | null,
-    crossSigningId?: boolean,
-    deviceTrust?: DeviceTrustLevel,
+    deviceId: string;
+    valid?: boolean | null; // true: valid, false: invalid, null: cannot attempt validation
+    device?: DeviceInfo | null;
+    crossSigningId?: boolean;
+    deviceTrust?: DeviceTrustLevel;
 };
 
-type TrustInfo = {
-    usable: boolean, // is the backup trusted, true iff there is a sig that is valid & from a trusted device
-    sigs: SigInfo[],
+export type TrustInfo = {
+    usable: boolean; // is the backup trusted, true iff there is a sig that is valid & from a trusted device
+    sigs: SigInfo[];
 };
 
+export interface IKeyBackupCheck {
+    backupInfo: IKeyBackupInfo;
+    trustInfo: TrustInfo;
+}
+
+/* eslint-disable camelcase */
+export interface IPreparedKeyBackupVersion {
+    algorithm: string;
+    auth_data: AuthData;
+    recovery_key: string;
+    privateKey: Uint8Array;
+}
+/* eslint-enable camelcase */
+
 /** A function used to get the secret key for a backup.
  */
-type GetKey = () => Promise<Uint8Array>;
+type GetKey = () => Promise<ArrayLike<number>>;
 
 interface BackupAlgorithmClass {
     algorithmName: string;
@@ -66,22 +78,35 @@ interface BackupAlgorithmClass {
     prepare(
         key: string | Uint8Array | null,
     ): Promise<[Uint8Array, AuthData]>;
+
+    checkBackupVersion(info: IKeyBackupInfo): void;
 }
 
 interface BackupAlgorithm {
+    untrusted: boolean;
     encryptSession(data: Record<string, any>): Promise<any>;
-    decryptSessions(ciphertexts: Record<string, any>): Promise<Record<string, any>[]>;
+    decryptSessions(ciphertexts: Record<string, IKeyBackupSession>): Promise<Record<string, any>[]>;
     authData: AuthData;
-    keyMatches(key: Uint8Array): Promise<boolean>;
+    keyMatches(key: ArrayLike<number>): Promise<boolean>;
     free(): void;
 }
 
+export interface IKeyBackup {
+    rooms: {
+        [roomId: string]: {
+            sessions: {
+                [sessionId: string]: IKeyBackupSession;
+            };
+        };
+    };
+}
+
 /**
  * Manages the key backup.
  */
 export class BackupManager {
     private algorithm: BackupAlgorithm | undefined;
-    private backupInfo: BackupInfo | undefined; // The info dict from /room_keys/version
+    public backupInfo: IKeyBackupInfo | undefined; // The info dict from /room_keys/version
     public checkedForBackup: boolean; // Have we checked the server for a backup we can use?
     private sendingBackups: boolean; // Are we currently sending backups?
     constructor(private readonly baseApis: MatrixClient, public readonly getKey: GetKey) {
@@ -93,7 +118,25 @@ export class BackupManager {
         return this.backupInfo && this.backupInfo.version;
     }
 
-    public static async makeAlgorithm(info: BackupInfo, getKey: GetKey): Promise<BackupAlgorithm> {
+    /**
+     * Performs a quick check to ensure that the backup info looks sane.
+     *
+     * Throws an error if a problem is detected.
+     *
+     * @param {IKeyBackupInfo} info the key backup info
+     */
+    public static checkBackupVersion(info: IKeyBackupInfo): void {
+        const Algorithm = algorithmsByName[info.algorithm];
+        if (!Algorithm) {
+            throw new Error("Unknown backup algorithm: " + info.algorithm);
+        }
+        if (!(typeof info.auth_data === "object")) {
+            throw new Error("Invalid backup data returned");
+        }
+        return Algorithm.checkBackupVersion(info);
+    }
+
+    public static async makeAlgorithm(info: IKeyBackupInfo, getKey: GetKey): Promise<BackupAlgorithm> {
         const Algorithm = algorithmsByName[info.algorithm];
         if (!Algorithm) {
             throw new Error("Unknown backup algorithm");
@@ -101,7 +144,7 @@ export class BackupManager {
         return await Algorithm.init(info.auth_data, getKey);
     }
 
-    public async enableKeyBackup(info: BackupInfo): Promise<void> {
+    public async enableKeyBackup(info: IKeyBackupInfo): Promise<void> {
         this.backupInfo = info;
         if (this.algorithm) {
             this.algorithm.free();
@@ -140,7 +183,8 @@ export class BackupManager {
     public async prepareKeyBackupVersion(
         key?: string | Uint8Array | null,
         algorithm?: string | undefined,
-    ): Promise<BackupInfo> {
+        // eslint-disable-next-line camelcase
+    ): Promise<IPreparedKeyBackupVersion> {
         const Algorithm = algorithm ? algorithmsByName[algorithm] : DefaultAlgorithm;
         if (!Algorithm) {
             throw new Error("Unknown backup algorithm");
@@ -156,7 +200,7 @@ export class BackupManager {
         };
     }
 
-    public async createKeyBackupVersion(info: BackupInfo): Promise<void> {
+    public async createKeyBackupVersion(info: IKeyBackupInfo): Promise<void> {
         this.algorithm = await BackupManager.makeAlgorithm(info, this.getKey);
     }
 
@@ -166,14 +210,14 @@ export class BackupManager {
      * one of the user's verified devices, start backing up
      * to it.
      */
-    public async checkAndStart(): Promise<{backupInfo: BackupInfo, trustInfo: TrustInfo}> {
+    public async checkAndStart(): Promise<IKeyBackupCheck> {
         logger.log("Checking key backup status...");
         if (this.baseApis.isGuest()) {
             logger.log("Skipping key backup check since user is guest");
             this.checkedForBackup = true;
             return null;
         }
-        let backupInfo: BackupInfo;
+        let backupInfo: IKeyBackupInfo;
         try {
             backupInfo = await this.baseApis.getKeyBackupVersion();
         } catch (e) {
@@ -232,7 +276,7 @@ export class BackupManager {
      *     trust information (as returned by isKeyBackupTrusted)
      *     in trustInfo.
      */
-    public async checkKeyBackup(): Promise<{backupInfo: BackupInfo, trustInfo: TrustInfo}> {
+    public async checkKeyBackup(): Promise<IKeyBackupCheck> {
         this.checkedForBackup = false;
         return this.checkAndStart();
     }
@@ -240,7 +284,7 @@ export class BackupManager {
     /**
      * Check if the given backup info is trusted.
      *
-     * @param {object} backupInfo key backup info dict from /room_keys/version
+     * @param {IKeyBackupInfo} backupInfo key backup info dict from /room_keys/version
      * @return {object} {
      *     usable: [bool], // is the backup trusted, true iff there is a sig that is valid & from a trusted device
      *     sigs: [
@@ -250,7 +294,7 @@ export class BackupManager {
      *     ]
      * }
      */
-    public async isKeyBackupTrusted(backupInfo: BackupInfo): Promise<TrustInfo> {
+    public async isKeyBackupTrusted(backupInfo: IKeyBackupInfo): Promise<TrustInfo> {
         const ret = {
             usable: false,
             trusted_locally: false,
@@ -261,16 +305,15 @@ export class BackupManager {
             !backupInfo ||
                 !backupInfo.algorithm ||
                 !backupInfo.auth_data ||
-                !backupInfo.auth_data.public_key ||
                 !backupInfo.auth_data.signatures
         ) {
             logger.info("Key backup is absent or missing required data");
             return ret;
         }
 
-        const trustedPubkey = this.baseApis.crypto._sessionStore.getLocalTrustedBackupPubKey();
+        const trustedPubkey = this.baseApis.crypto.sessionStore.getLocalTrustedBackupPubKey();
 
-        if (backupInfo.auth_data.public_key === trustedPubkey) {
+        if ("public_key" in backupInfo.auth_data && backupInfo.auth_data.public_key === trustedPubkey) {
             logger.info("Backup public key " + trustedPubkey + " is trusted locally");
             ret.trusted_locally = true;
         }
@@ -288,12 +331,12 @@ export class BackupManager {
             const sigInfo: SigInfo = { deviceId: keyIdParts[1] };
 
             // first check to see if it's from our cross-signing key
-            const crossSigningId = this.baseApis.crypto._crossSigningInfo.getId();
+            const crossSigningId = this.baseApis.crypto.crossSigningInfo.getId();
             if (crossSigningId === sigInfo.deviceId) {
                 sigInfo.crossSigningId = true;
                 try {
                     await verifySignature(
-                        this.baseApis.crypto._olmDevice,
+                        this.baseApis.crypto.olmDevice,
                         backupInfo.auth_data,
                         this.baseApis.getUserId(),
                         sigInfo.deviceId,
@@ -313,7 +356,7 @@ export class BackupManager {
             // Now look for a sig from a device
             // At some point this can probably go away and we'll just support
             // it being signed by the cross-signing master key
-            const device = this.baseApis.crypto._deviceList.getStoredDevice(
+            const device = this.baseApis.crypto.deviceList.getStoredDevice(
                 this.baseApis.getUserId(), sigInfo.deviceId,
             );
             if (device) {
@@ -323,7 +366,7 @@ export class BackupManager {
                 );
                 try {
                     await verifySignature(
-                        this.baseApis.crypto._olmDevice,
+                        this.baseApis.crypto.olmDevice,
                         backupInfo.auth_data,
                         this.baseApis.getUserId(),
                         device.deviceId,
@@ -423,22 +466,22 @@ export class BackupManager {
      * @returns {integer} Number of sessions backed up
      */
     private async backupPendingKeys(limit: number): Promise<number> {
-        const sessions = await this.baseApis.crypto._cryptoStore.getSessionsNeedingBackup(limit);
+        const sessions = await this.baseApis.crypto.cryptoStore.getSessionsNeedingBackup(limit);
         if (!sessions.length) {
             return 0;
         }
 
-        let remaining = await this.baseApis.crypto._cryptoStore.countSessionsNeedingBackup();
+        let remaining = await this.baseApis.crypto.cryptoStore.countSessionsNeedingBackup();
         this.baseApis.crypto.emit("crypto.keyBackupSessionsRemaining", remaining);
 
-        const data = {};
+        const rooms: IKeyBackup["rooms"] = {};
         for (const session of sessions) {
             const roomId = session.sessionData.room_id;
-            if (data[roomId] === undefined) {
-                data[roomId] = { sessions: {} };
+            if (rooms[roomId] === undefined) {
+                rooms[roomId] = { sessions: {} };
             }
 
-            const sessionData = await this.baseApis.crypto._olmDevice.exportInboundGroupSession(
+            const sessionData = await this.baseApis.crypto.olmDevice.exportInboundGroupSession(
                 session.senderKey, session.sessionId, session.sessionData,
             );
             sessionData.algorithm = MEGOLM_ALGORITHM;
@@ -446,15 +489,15 @@ export class BackupManager {
             const forwardedCount =
                 (sessionData.forwarding_curve25519_key_chain || []).length;
 
-            const userId = this.baseApis.crypto._deviceList.getUserByIdentityKey(
+            const userId = this.baseApis.crypto.deviceList.getUserByIdentityKey(
                 MEGOLM_ALGORITHM, session.senderKey,
             );
-            const device = this.baseApis.crypto._deviceList.getDeviceByIdentityKey(
+            const device = this.baseApis.crypto.deviceList.getDeviceByIdentityKey(
                 MEGOLM_ALGORITHM, session.senderKey,
             );
-            const verified = this.baseApis.crypto._checkDeviceInfoTrust(userId, device).isVerified();
+            const verified = this.baseApis.crypto.checkDeviceInfoTrust(userId, device).isVerified();
 
-            data[roomId]['sessions'][session.sessionId] = {
+            rooms[roomId]['sessions'][session.sessionId] = {
                 first_message_index: sessionData.first_known_index,
                 forwarded_count: forwardedCount,
                 is_verified: verified,
@@ -462,13 +505,10 @@ export class BackupManager {
             };
         }
 
-        await this.baseApis.sendKeyBackup(
-            undefined, undefined, this.backupInfo.version,
-            { rooms: data },
-        );
+        await this.baseApis.sendKeyBackup(undefined, undefined, this.backupInfo.version, { rooms });
 
-        await this.baseApis.crypto._cryptoStore.unmarkSessionsNeedingBackup(sessions);
-        remaining = await this.baseApis.crypto._cryptoStore.countSessionsNeedingBackup();
+        await this.baseApis.crypto.cryptoStore.unmarkSessionsNeedingBackup(sessions);
+        remaining = await this.baseApis.crypto.cryptoStore.countSessionsNeedingBackup();
         this.baseApis.crypto.emit("crypto.keyBackupSessionsRemaining", remaining);
 
         return sessions.length;
@@ -477,7 +517,7 @@ export class BackupManager {
     public async backupGroupSession(
         senderKey: string, sessionId: string,
     ): Promise<void> {
-        await this.baseApis.crypto._cryptoStore.markSessionsNeedingBackup([{
+        await this.baseApis.crypto.cryptoStore.markSessionsNeedingBackup([{
             senderKey: senderKey,
             sessionId: sessionId,
         }]);
@@ -509,22 +549,22 @@ export class BackupManager {
      *     (which will be equal to the number of sessions in the store).
      */
     public async flagAllGroupSessionsForBackup(): Promise<number> {
-        await this.baseApis.crypto._cryptoStore.doTxn(
+        await this.baseApis.crypto.cryptoStore.doTxn(
             'readwrite',
             [
                 IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS,
                 IndexedDBCryptoStore.STORE_BACKUP,
             ],
             (txn) => {
-                this.baseApis.crypto._cryptoStore.getAllEndToEndInboundGroupSessions(txn, (session) => {
+                this.baseApis.crypto.cryptoStore.getAllEndToEndInboundGroupSessions(txn, (session) => {
                     if (session !== null) {
-                        this.baseApis.crypto._cryptoStore.markSessionsNeedingBackup([session], txn);
+                        this.baseApis.crypto.cryptoStore.markSessionsNeedingBackup([session], txn);
                     }
                 });
             },
         );
 
-        const remaining = await this.baseApis.crypto._cryptoStore.countSessionsNeedingBackup();
+        const remaining = await this.baseApis.crypto.cryptoStore.countSessionsNeedingBackup();
         this.baseApis.emit("crypto.keyBackupSessionsRemaining", remaining);
         return remaining;
     }
@@ -534,7 +574,7 @@ export class BackupManager {
      * @returns {Promise<int>} Resolves to the number of sessions requiring backup
      */
     public countSessionsNeedingBackup(): Promise<number> {
-        return this.baseApis.crypto._cryptoStore.countSessionsNeedingBackup();
+        return this.baseApis.crypto.cryptoStore.countSessionsNeedingBackup();
     }
 }
 
@@ -542,7 +582,7 @@ export class Curve25519 implements BackupAlgorithm {
     public static algorithmName = "m.megolm_backup.v1.curve25519-aes-sha2";
 
     constructor(
-        public authData: AuthData,
+        public authData: ICurve25519AuthData,
         private publicKey: any, // FIXME: PkEncryption
         private getKey: () => Promise<Uint8Array>,
     ) {}
@@ -551,12 +591,12 @@ export class Curve25519 implements BackupAlgorithm {
         authData: AuthData,
         getKey: () => Promise<Uint8Array>,
     ): Promise<Curve25519> {
-        if (!authData || !authData.public_key) {
+        if (!authData || !("public_key" in authData)) {
             throw new Error("auth_data missing required information");
         }
         const publicKey = new global.Olm.PkEncryption();
         publicKey.set_recipient_key(authData.public_key);
-        return new Curve25519(authData, publicKey, getKey);
+        return new Curve25519(authData as ICurve25519AuthData, publicKey, getKey);
     }
 
     public static async prepare(
@@ -564,7 +604,7 @@ export class Curve25519 implements BackupAlgorithm {
     ): Promise<[Uint8Array, AuthData]> {
         const decryption = new global.Olm.PkDecryption();
         try {
-            const authData: AuthData = {};
+            const authData: Partial<ICurve25519AuthData> = {};
             if (!key) {
                 authData.public_key = decryption.generate_key();
             } else if (key instanceof Uint8Array) {
@@ -580,13 +620,21 @@ export class Curve25519 implements BackupAlgorithm {
 
             return [
                 decryption.get_private_key(),
-                authData,
+                authData as AuthData,
             ];
         } finally {
             decryption.free();
         }
     }
 
+    public static checkBackupVersion(info: IKeyBackupInfo): void {
+        if (!("public_key" in info.auth_data)) {
+            throw new Error("Invalid backup data returned");
+        }
+    }
+
+    public get untrusted() { return true; }
+
     public async encryptSession(data: Record<string, any>): Promise<any> {
         const plainText: Record<string, any> = Object.assign({}, data);
         delete plainText.session_id;
@@ -595,7 +643,9 @@ export class Curve25519 implements BackupAlgorithm {
         return this.publicKey.encrypt(JSON.stringify(plainText));
     }
 
-    public async decryptSessions(sessions: Record<string, Record<string, any>>): Promise<Record<string, any>[]> {
+    public async decryptSessions(
+        sessions: Record<string, IKeyBackupSession>,
+    ): Promise<Record<string, any>[]> {
         const privKey = await this.getKey();
         const decryption = new global.Olm.PkDecryption();
         try {
@@ -644,8 +694,120 @@ export class Curve25519 implements BackupAlgorithm {
     }
 }
 
+function randomBytes(size: number): Uint8Array {
+    const crypto: {randomBytes: (n: number) => Uint8Array} | undefined = getCrypto() as any;
+    if (crypto) {
+        // nodejs version
+        return crypto.randomBytes(size);
+    }
+    if (window?.crypto) {
+        // browser version
+        const buf = new Uint8Array(size);
+        window.crypto.getRandomValues(buf);
+        return buf;
+    }
+    throw new Error("No usable crypto implementation");
+}
+
+const UNSTABLE_MSC3270_NAME = new UnstableValue(null, "org.matrix.msc3270.v1.aes-hmac-sha2");
+
+export class Aes256 implements BackupAlgorithm {
+    public static algorithmName = UNSTABLE_MSC3270_NAME.name;
+
+    constructor(
+        public readonly authData: IAes256AuthData,
+        private readonly key: Uint8Array,
+    ) {}
+
+    public static async init(
+        authData: IAes256AuthData,
+        getKey: () => Promise<Uint8Array>,
+    ): Promise<Aes256> {
+        if (!authData) {
+            throw new Error("auth_data missing");
+        }
+        const key = await getKey();
+        if (authData.mac) {
+            const { mac } = await calculateKeyCheck(key, authData.iv);
+            if (authData.mac.replace(/=+$/g, '') !== mac.replace(/=+/g, '')) {
+                throw new Error("Key does not match");
+            }
+        }
+        return new Aes256(authData, key);
+    }
+
+    public static async prepare(
+        key: string | Uint8Array | null,
+    ): Promise<[Uint8Array, AuthData]> {
+        let outKey: Uint8Array;
+        const authData: Partial<IAes256AuthData> = {};
+        if (!key) {
+            outKey = randomBytes(32);
+        } else if (key instanceof Uint8Array) {
+            outKey = new Uint8Array(key);
+        } else {
+            const derivation = await keyFromPassphrase(key);
+            authData.private_key_salt = derivation.salt;
+            authData.private_key_iterations = derivation.iterations;
+            outKey = derivation.key;
+        }
+
+        const { iv, mac } = await calculateKeyCheck(outKey);
+        authData.iv = iv;
+        authData.mac = mac;
+
+        return [outKey, authData as AuthData];
+    }
+
+    public static checkBackupVersion(info: IKeyBackupInfo): void {
+        if (!("iv" in info.auth_data && "mac" in info.auth_data)) {
+            throw new Error("Invalid backup data returned");
+        }
+    }
+
+    public get untrusted() { return false; }
+
+    async encryptSession(data: Record<string, any>): Promise<any> {
+        const plainText: Record<string, any> = Object.assign({}, data);
+        delete plainText.session_id;
+        delete plainText.room_id;
+        delete plainText.first_known_index;
+        return await encryptAES(JSON.stringify(plainText), this.key, data.session_id);
+    }
+
+    async decryptSessions(sessions: Record<string, IKeyBackupSession>): Promise<Record<string, any>[]> {
+        const keys = [];
+
+        for (const [sessionId, sessionData] of Object.entries(sessions)) {
+            try {
+                const decrypted = JSON.parse(await decryptAES(sessionData.session_data, this.key, sessionId));
+                decrypted.session_id = sessionId;
+                keys.push(decrypted);
+            } catch (e) {
+                logger.log("Failed to decrypt megolm session from backup", e, sessionData);
+            }
+        }
+        return keys;
+    }
+
+    async keyMatches(key: Uint8Array): Promise<boolean> {
+        if (this.authData.mac) {
+            const { mac } = await calculateKeyCheck(key, this.authData.iv);
+            return this.authData.mac.replace(/=+$/g, '') === mac.replace(/=+/g, '');
+        } else {
+            // if we have no information, we have to assume the key is right
+            return true;
+        }
+    }
+
+    public free(): void {
+        this.key.fill(0);
+    }
+}
+
 export const algorithmsByName: Record<string, BackupAlgorithmClass> = {
     [Curve25519.algorithmName]: Curve25519,
+    [Aes256.algorithmName]: Aes256,
 };
 
 export const DefaultAlgorithm: BackupAlgorithmClass = Curve25519;

src/crypto/dehydration.ts

@@ -19,7 +19,7 @@ import { IndexedDBCryptoStore } from '../crypto/store/indexeddb-crypto-store';
 import { decryptAES, encryptAES } from './aes';
 import anotherjson from "another-json";
 import { logger } from '../logger';
-import { ISecretStorageKeyInfo } from "../matrix";
+import { ISecretStorageKeyInfo } from "./api";
 
 // FIXME: these types should eventually go in a different file
 type Signatures = Record<string, Record<string, string>>;
@@ -36,7 +36,7 @@ export interface IDehydratedDeviceKeyInfo {
     passphrase?: string;
 }
 
-interface DeviceKeys {
+export interface IDeviceKeys {
     algorithms: Array<string>;
     device_id: string; // eslint-disable-line camelcase
     user_id: string; // eslint-disable-line camelcase
@@ -44,7 +44,7 @@ interface DeviceKeys {
     signatures?: Signatures;
 }
 
-interface OneTimeKey {
+export interface IOneTimeKey {
     key: string;
     fallback?: boolean;
     signatures?: Signatures;
@@ -64,16 +64,16 @@ export class DehydrationManager {
         this.getDehydrationKeyFromCache();
     }
     async getDehydrationKeyFromCache(): Promise<void> {
-        return await this.crypto._cryptoStore.doTxn(
+        return await this.crypto.cryptoStore.doTxn(
             'readonly',
             [IndexedDBCryptoStore.STORE_ACCOUNT],
             (txn) => {
-                this.crypto._cryptoStore.getSecretStorePrivateKey(
+                this.crypto.cryptoStore.getSecretStorePrivateKey(
                     txn,
                     async (result) => {
                         if (result) {
                             const { key, keyInfo, deviceDisplayName, time } = result;
-                            const pickleKey = Buffer.from(this.crypto._olmDevice._pickleKey);
+                            const pickleKey = Buffer.from(this.crypto.olmDevice._pickleKey);
                             const decrypted = await decryptAES(key, pickleKey, DEHYDRATION_ALGORITHM);
                             this.key = decodeBase64(decrypted);
                             this.keyInfo = keyInfo;
@@ -114,11 +114,11 @@ export class DehydrationManager {
                 this.timeoutId = undefined;
             }
             // clear storage
-            await this.crypto._cryptoStore.doTxn(
+            await this.crypto.cryptoStore.doTxn(
                 'readwrite',
                 [IndexedDBCryptoStore.STORE_ACCOUNT],
                 (txn) => {
-                    this.crypto._cryptoStore.storeSecretStorePrivateKey(
+                    this.crypto.cryptoStore.storeSecretStorePrivateKey(
                         txn, "dehydration", null,
                     );
                 },
@@ -158,15 +158,15 @@ export class DehydrationManager {
             this.timeoutId = undefined;
         }
         try {
-            const pickleKey = Buffer.from(this.crypto._olmDevice._pickleKey);
+            const pickleKey = Buffer.from(this.crypto.olmDevice._pickleKey);
 
             // update the crypto store with the timestamp
             const key = await encryptAES(encodeBase64(this.key), pickleKey, DEHYDRATION_ALGORITHM);
-            await this.crypto._cryptoStore.doTxn(
+            await this.crypto.cryptoStore.doTxn(
                 'readwrite',
                 [IndexedDBCryptoStore.STORE_ACCOUNT],
                 (txn) => {
-                    this.crypto._cryptoStore.storeSecretStorePrivateKey(
+                    this.crypto.cryptoStore.storeSecretStorePrivateKey(
                         txn, "dehydration",
                         {
                             keyInfo: this.keyInfo,
@@ -205,7 +205,7 @@ export class DehydrationManager {
             }
 
             logger.log("Uploading account to server");
-            const dehydrateResult = await this.crypto._baseApis.http.authedRequest(
+            const dehydrateResult = await this.crypto.baseApis.http.authedRequest(
                 undefined,
                 "PUT",
                 "/dehydrated_device",
@@ -222,10 +222,10 @@ export class DehydrationManager {
             // send the keys to the server
             const deviceId = dehydrateResult.device_id;
             logger.log("Preparing device keys", deviceId);
-            const deviceKeys: DeviceKeys = {
-                algorithms: this.crypto._supportedAlgorithms,
+            const deviceKeys: IDeviceKeys = {
+                algorithms: this.crypto.supportedAlgorithms,
                 device_id: deviceId,
-                user_id: this.crypto._userId,
+                user_id: this.crypto.userId,
                 keys: {
                     [`ed25519:${deviceId}`]: e2eKeys.ed25519,
                     [`curve25519:${deviceId}`]: e2eKeys.curve25519,
@@ -233,21 +233,21 @@ export class DehydrationManager {
             };
             const deviceSignature = account.sign(anotherjson.stringify(deviceKeys));
             deviceKeys.signatures = {
-                [this.crypto._userId]: {
+                [this.crypto.userId]: {
                     [`ed25519:${deviceId}`]: deviceSignature,
                 },
             };
-            if (this.crypto._crossSigningInfo.getId("self_signing")) {
-                await this.crypto._crossSigningInfo.signObject(deviceKeys, "self_signing");
+            if (this.crypto.crossSigningInfo.getId("self_signing")) {
+                await this.crypto.crossSigningInfo.signObject(deviceKeys, "self_signing");
             }
 
             logger.log("Preparing one-time keys");
             const oneTimeKeys = {};
             for (const [keyId, key] of Object.entries(otks.curve25519)) {
-                const k: OneTimeKey = { key };
+                const k: IOneTimeKey = { key };
                 const signature = account.sign(anotherjson.stringify(k));
                 k.signatures = {
-                    [this.crypto._userId]: {
+                    [this.crypto.userId]: {
                         [`ed25519:${deviceId}`]: signature,
                     },
                 };
@@ -257,10 +257,10 @@ export class DehydrationManager {
             logger.log("Preparing fallback keys");
             const fallbackKeys = {};
             for (const [keyId, key] of Object.entries(fallbacks.curve25519)) {
-                const k: OneTimeKey = { key, fallback: true };
+                const k: IOneTimeKey = { key, fallback: true };
                 const signature = account.sign(anotherjson.stringify(k));
                 k.signatures = {
-                    [this.crypto._userId]: {
+                    [this.crypto.userId]: {
                         [`ed25519:${deviceId}`]: signature,
                     },
                 };
@@ -268,7 +268,7 @@ export class DehydrationManager {
             }
 
             logger.log("Uploading keys to server");
-            await this.crypto._baseApis.http.authedRequest(
+            await this.crypto.baseApis.http.authedRequest(
                 undefined,
                 "POST",
                 "/keys/upload/" + encodeURI(deviceId),
@@ -292,7 +292,7 @@ export class DehydrationManager {
         }
     }
 
-    private stop() {
+    public stop() {
         if (this.timeoutId) {
             global.clearTimeout(this.timeoutId);
             this.timeoutId = undefined;

src/crypto/deviceinfo.js

@@ -1,168 +0,0 @@
-/*
-Copyright 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module crypto/deviceinfo
- */
-
-/**
-  * Information about a user's device
-  *
-  * @constructor
-  * @alias module:crypto/deviceinfo
-  *
-  * @property {string} deviceId the ID of this device
-  *
-  * @property {string[]} algorithms list of algorithms supported by this device
-  *
-  * @property {Object.<string,string>} keys a map from
-  *      &lt;key type&gt;:&lt;id&gt; -> &lt;base64-encoded key&gt;>
-  *
-  * @property {module:crypto/deviceinfo.DeviceVerification} verified
-  *     whether the device has been verified/blocked by the user
-  *
-  * @property {boolean} known
-  *     whether the user knows of this device's existence (useful when warning
-  *     the user that a user has added new devices)
-  *
-  * @property {Object} unsigned  additional data from the homeserver
-  *
-  * @param {string} deviceId id of the device
-  */
-export function DeviceInfo(deviceId) {
-    // you can't change the deviceId
-    Object.defineProperty(this, 'deviceId', {
-        enumerable: true,
-        value: deviceId,
-    });
-
-    this.algorithms = [];
-    this.keys = {};
-    this.verified = DeviceVerification.UNVERIFIED;
-    this.known = false;
-    this.unsigned = {};
-    this.signatures = {};
-}
-
-/**
- * rehydrate a DeviceInfo from the session store
- *
- * @param {object} obj  raw object from session store
- * @param {string} deviceId id of the device
- *
- * @return {module:crypto~DeviceInfo} new DeviceInfo
- */
-DeviceInfo.fromStorage = function(obj, deviceId) {
-    const res = new DeviceInfo(deviceId);
-    for (const prop in obj) {
-        if (obj.hasOwnProperty(prop)) {
-            res[prop] = obj[prop];
-        }
-    }
-    return res;
-};
-
-/**
- * Prepare a DeviceInfo for JSON serialisation in the session store
- *
- * @return {object} deviceinfo with non-serialised members removed
- */
-DeviceInfo.prototype.toStorage = function() {
-    return {
-        algorithms: this.algorithms,
-        keys: this.keys,
-        verified: this.verified,
-        known: this.known,
-        unsigned: this.unsigned,
-        signatures: this.signatures,
-    };
-};
-
-/**
- * Get the fingerprint for this device (ie, the Ed25519 key)
- *
- * @return {string} base64-encoded fingerprint of this device
- */
-DeviceInfo.prototype.getFingerprint = function() {
-    return this.keys["ed25519:" + this.deviceId];
-};
-
-/**
- * Get the identity key for this device (ie, the Curve25519 key)
- *
- * @return {string} base64-encoded identity key of this device
- */
-DeviceInfo.prototype.getIdentityKey = function() {
-    return this.keys["curve25519:" + this.deviceId];
-};
-
-/**
- * Get the configured display name for this device, if any
- *
- * @return {string?} displayname
- */
-DeviceInfo.prototype.getDisplayName = function() {
-    return this.unsigned.device_display_name || null;
-};
-
-/**
- * Returns true if this device is blocked
- *
- * @return {Boolean} true if blocked
- */
-DeviceInfo.prototype.isBlocked = function() {
-    return this.verified == DeviceVerification.BLOCKED;
-};
-
-/**
- * Returns true if this device is verified
- *
- * @return {Boolean} true if verified
- */
-DeviceInfo.prototype.isVerified = function() {
-    return this.verified == DeviceVerification.VERIFIED;
-};
-
-/**
- * Returns true if this device is unverified
- *
- * @return {Boolean} true if unverified
- */
-DeviceInfo.prototype.isUnverified = function() {
-    return this.verified == DeviceVerification.UNVERIFIED;
-};
-
-/**
- * Returns true if the user knows about this device's existence
- *
- * @return {Boolean} true if known
- */
-DeviceInfo.prototype.isKnown = function() {
-    return this.known == true;
-};
-
-/**
- * @enum
- */
-DeviceInfo.DeviceVerification = {
-    VERIFIED: 1,
-    UNVERIFIED: 0,
-    BLOCKED: -1,
-};
-
-const DeviceVerification = DeviceInfo.DeviceVerification;
-

src/crypto/deviceinfo.ts

@@ -0,0 +1,177 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { ISignatures } from "../@types/signed";
+
+/**
+ * @module crypto/deviceinfo
+ */
+
+export interface IDevice {
+    keys: Record<string, string>;
+    algorithms: string[];
+    verified: DeviceVerification;
+    known: boolean;
+    unsigned?: Record<string, any>;
+    signatures?: ISignatures;
+}
+
+enum DeviceVerification {
+    Blocked = -1,
+    Unverified = 0,
+    Verified = 1,
+}
+
+/**
+  * Information about a user's device
+  *
+  * @constructor
+  * @alias module:crypto/deviceinfo
+  *
+  * @property {string} deviceId the ID of this device
+  *
+  * @property {string[]} algorithms list of algorithms supported by this device
+  *
+  * @property {Object.<string,string>} keys a map from
+  *      &lt;key type&gt;:&lt;id&gt; -> &lt;base64-encoded key&gt;>
+  *
+  * @property {module:crypto/deviceinfo.DeviceVerification} verified
+  *     whether the device has been verified/blocked by the user
+  *
+  * @property {boolean} known
+  *     whether the user knows of this device's existence (useful when warning
+  *     the user that a user has added new devices)
+  *
+  * @property {Object} unsigned  additional data from the homeserver
+  *
+  * @param {string} deviceId id of the device
+  */
+export class DeviceInfo {
+    /**
+     * rehydrate a DeviceInfo from the session store
+     *
+     * @param {object} obj  raw object from session store
+     * @param {string} deviceId id of the device
+     *
+     * @return {module:crypto~DeviceInfo} new DeviceInfo
+     */
+    public static fromStorage(obj: IDevice, deviceId: string): DeviceInfo {
+        const res = new DeviceInfo(deviceId);
+        for (const prop in obj) {
+            if (obj.hasOwnProperty(prop)) {
+                res[prop] = obj[prop];
+            }
+        }
+        return res;
+    }
+
+    /**
+     * @enum
+     */
+    public static DeviceVerification = {
+        VERIFIED: DeviceVerification.Verified,
+        UNVERIFIED: DeviceVerification.Unverified,
+        BLOCKED: DeviceVerification.Blocked,
+    };
+
+    public algorithms: string[];
+    public keys: Record<string, string> = {};
+    public verified = DeviceVerification.Unverified;
+    public known = false;
+    public unsigned: Record<string, any> = {};
+    public signatures: ISignatures = {};
+
+    constructor(public readonly deviceId: string) {}
+
+    /**
+     * Prepare a DeviceInfo for JSON serialisation in the session store
+     *
+     * @return {object} deviceinfo with non-serialised members removed
+     */
+    public toStorage(): IDevice {
+        return {
+            algorithms: this.algorithms,
+            keys: this.keys,
+            verified: this.verified,
+            known: this.known,
+            unsigned: this.unsigned,
+            signatures: this.signatures,
+        };
+    }
+
+    /**
+     * Get the fingerprint for this device (ie, the Ed25519 key)
+     *
+     * @return {string} base64-encoded fingerprint of this device
+     */
+    public getFingerprint(): string {
+        return this.keys["ed25519:" + this.deviceId];
+    }
+
+    /**
+     * Get the identity key for this device (ie, the Curve25519 key)
+     *
+     * @return {string} base64-encoded identity key of this device
+     */
+    public getIdentityKey(): string {
+        return this.keys["curve25519:" + this.deviceId];
+    }
+
+    /**
+     * Get the configured display name for this device, if any
+     *
+     * @return {string?} displayname
+     */
+    public getDisplayName(): string | null {
+        return this.unsigned.device_display_name || null;
+    }
+
+    /**
+     * Returns true if this device is blocked
+     *
+     * @return {Boolean} true if blocked
+     */
+    public isBlocked(): boolean {
+        return this.verified == DeviceVerification.Blocked;
+    }
+
+    /**
+     * Returns true if this device is verified
+     *
+     * @return {Boolean} true if verified
+     */
+    public isVerified(): boolean {
+        return this.verified == DeviceVerification.Verified;
+    }
+
+    /**
+     * Returns true if this device is unverified
+     *
+     * @return {Boolean} true if unverified
+     */
+    public isUnverified(): boolean {
+        return this.verified == DeviceVerification.Unverified;
+    }
+
+    /**
+     * Returns true if the user knows about this device's existence
+     *
+     * @return {Boolean} true if known
+     */
+    public isKnown(): boolean {
+        return this.known === true;
+    }
+}

src/crypto/key_passphrase.ts

@@ -1,6 +1,5 @@
 /*
-Copyright 2018 New Vector Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2018 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -21,7 +20,21 @@ const DEFAULT_ITERATIONS = 500000;
 
 const DEFAULT_BITSIZE = 256;
 
-export async function keyFromAuthData(authData, password) {
+/* eslint-disable camelcase */
+interface IAuthData {
+    private_key_salt?: string;
+    private_key_iterations?: number;
+    private_key_bits?: number;
+}
+/* eslint-enable camelcase */
+
+interface IKey {
+    key: Uint8Array;
+    salt: string;
+    iterations: number;
+}
+
+export async function keyFromAuthData(authData: IAuthData, password: string): Promise<Uint8Array> {
     if (!global.Olm) {
         throw new Error("Olm is not available");
     }
@@ -40,7 +53,7 @@ export async function keyFromAuthData(authData, password) {
     );
 }
 
-export async function keyFromPassphrase(password) {
+export async function keyFromPassphrase(password: string): Promise<IKey> {
     if (!global.Olm) {
         throw new Error("Olm is not available");
     }
@@ -52,7 +65,12 @@ export async function keyFromPassphrase(password) {
     return { key, salt, iterations: DEFAULT_ITERATIONS };
 }
 
-export async function deriveKey(password, salt, iterations, numBits = DEFAULT_BITSIZE) {
+export async function deriveKey(
+    password: string,
+    salt: string,
+    iterations: number,
+    numBits = DEFAULT_BITSIZE,
+): Promise<Uint8Array> {
     const subtleCrypto = global.crypto.subtle;
     const TextEncoder = global.TextEncoder;
     if (!subtleCrypto || !TextEncoder) {

src/crypto/keybackup.ts

@@ -14,8 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { ISignatures } from "../@types/signed";
-import { DeviceInfo } from "./deviceinfo";
+import { ISigned } from "../@types/signed";
 
 export interface IKeyBackupSession {
     first_message_index: number; // eslint-disable-line camelcase
@@ -25,6 +24,7 @@ export interface IKeyBackupSession {
         ciphertext: string;
         ephemeral: string;
         mac: string;
+        iv: string;
     };
 }
 
@@ -32,29 +32,30 @@ export interface IKeyBackupRoomSessions {
     [sessionId: string]: IKeyBackupSession;
 }
 
-export interface IKeyBackupVersion {
-    algorithm: string;
-    auth_data: { // eslint-disable-line camelcase
-        public_key: string; // eslint-disable-line camelcase
-        signatures: ISignatures;
-    };
-    count: number;
-    etag: string;
-    version: string; // number contained within
+/* eslint-disable camelcase */
+export interface ICurve25519AuthData {
+    public_key: string;
+    private_key_salt?: string;
+    private_key_iterations?: number;
+    private_key_bits?: number;
 }
 
-// TODO: Verify types
-export interface IKeyBackupTrustInfo {
-    /**
-     * is the backup trusted, true if there is a sig that is valid & from a trusted device
-     */
-    usable: boolean[];
-    sigs: {
-        valid: boolean[];
-        device: DeviceInfo[];
-    }[];
+export interface IAes256AuthData {
+    iv: string;
+    mac: string;
+    private_key_salt?: string;
+    private_key_iterations?: number;
 }
 
+export interface IKeyBackupInfo {
+    algorithm: string;
+    auth_data: ISigned & (ICurve25519AuthData | IAes256AuthData);
+    count?: number;
+    etag?: string;
+    version?: string; // number contained within
+}
+/* eslint-enable camelcase */
+
 export interface IKeyBackupPrepareOpts {
     secureSecretStorage: boolean;
 }

src/crypto/olmlib.ts

@@ -1,7 +1,5 @@
 /*
-Copyright 2016 OpenMarket Ltd
-Copyright 2019 New Vector Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -22,24 +20,42 @@ limitations under the License.
  * Utilities common to olm encryption algorithms
  */
 
+import anotherjson from "another-json";
+import type { PkSigning } from "@matrix-org/olm";
+import { Logger } from "loglevel";
+
+import OlmDevice from "./OlmDevice";
+import { DeviceInfo } from "./deviceinfo";
 import { logger } from '../logger';
 import * as utils from "../utils";
-import anotherjson from "another-json";
+import { IOneTimeKey } from "./dehydration";
+import { MatrixClient } from "../client";
+
+enum Algorithm {
+    Olm = "m.olm.v1.curve25519-aes-sha2",
+    Megolm = "m.megolm.v1.aes-sha2",
+    MegolmBackup = "m.megolm_backup.v1.curve25519-aes-sha2",
+}
 
 /**
  * matrix algorithm tag for olm
  */
-export const OLM_ALGORITHM = "m.olm.v1.curve25519-aes-sha2";
+export const OLM_ALGORITHM = Algorithm.Olm;
 
 /**
  * matrix algorithm tag for megolm
  */
-export const MEGOLM_ALGORITHM = "m.megolm.v1.aes-sha2";
+export const MEGOLM_ALGORITHM = Algorithm.Megolm;
 
 /**
  * matrix algorithm tag for megolm backups
  */
-export const MEGOLM_BACKUP_ALGORITHM = "m.megolm_backup.v1.curve25519-aes-sha2";
+export const MEGOLM_BACKUP_ALGORITHM = Algorithm.MegolmBackup;
+
+export interface IOlmSessionResult {
+    device: DeviceInfo;
+    sessionId?: string;
+}
 
 /**
  * Encrypt an event payload for an Olm device
@@ -58,9 +74,13 @@ export const MEGOLM_BACKUP_ALGORITHM = "m.megolm_backup.v1.curve25519-aes-sha2";
  *    has been encrypted into `resultsObject`
  */
 export async function encryptMessageForDevice(
-    resultsObject,
-    ourUserId, ourDeviceId, olmDevice, recipientUserId, recipientDevice,
-    payloadFields,
+    resultsObject: Record<string, string>,
+    ourUserId: string,
+    ourDeviceId: string,
+    olmDevice: OlmDevice,
+    recipientUserId: string,
+    recipientDevice: DeviceInfo,
+    payloadFields: Record<string, any>,
 ) {
     const deviceKey = recipientDevice.getIdentityKey();
     const sessionId = await olmDevice.getSessionIdForDevice(deviceKey);
@@ -77,6 +97,7 @@ export async function encryptMessageForDevice(
 
     const payload = {
         sender: ourUserId,
+        // TODO this appears to no longer be used whatsoever
         sender_device: ourDeviceId,
 
         // Include the Ed25519 key so that the recipient knows what
@@ -129,7 +150,9 @@ export async function encryptMessageForDevice(
  *    a map from userId to deviceId to {@link module:crypto~OlmSessionResult}
  */
 export async function getExistingOlmSessions(
-    olmDevice, baseApis, devicesByUser,
+    olmDevice: OlmDevice,
+    baseApis: MatrixClient,
+    devicesByUser: Record<string, DeviceInfo[]>,
 ) {
     const devicesWithoutSession = {};
     const sessions = {};
@@ -189,23 +212,30 @@ export async function getExistingOlmSessions(
  *    {@link module:crypto~OlmSessionResult}
  */
 export async function ensureOlmSessionsForDevices(
-    olmDevice, baseApis, devicesByUser, force, otkTimeout, failedServers, log,
-) {
+    olmDevice: OlmDevice,
+    baseApis: MatrixClient,
+    devicesByUser: Record<string, DeviceInfo[]>,
+    force = false,
+    otkTimeout?: number,
+    failedServers?: string[],
+    log: Logger = logger,
+): Promise<Record<string, Record<string, IOlmSessionResult>>> {
     if (typeof force === "number") {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore - backwards compatibility
         log = failedServers;
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore - backwards compatibility
         failedServers = otkTimeout;
         otkTimeout = force;
         force = false;
     }
-    if (!log) {
-        log = logger;
-    }
 
     const devicesWithoutSession = [
         // [userId, deviceId], ...
     ];
     const result = {};
-    const resolveSession = {};
+    const resolveSession: Record<string, (sessionId?: string) => void> = {};
 
     // Mark all sessions this task intends to update as in progress. It is
     // important to do this for all devices this task cares about in a single
@@ -227,9 +257,9 @@ export async function ensureOlmSessionsForDevices(
                 // conditions.  If we find that we already have a session, then
                 // we'll resolve
                 olmDevice._sessionsInProgress[key] = new Promise(resolve => {
-                    resolveSession[key] = (...args) => {
+                    resolveSession[key] = (v: any) => {
                         delete olmDevice._sessionsInProgress[key];
-                        resolve(...args);
+                        resolve(v);
                     };
                 });
             }
@@ -375,7 +405,12 @@ export async function ensureOlmSessionsForDevices(
     return result;
 }
 
-async function _verifyKeyAndStartSession(olmDevice, oneTimeKey, userId, deviceInfo) {
+async function _verifyKeyAndStartSession(
+    olmDevice: OlmDevice,
+    oneTimeKey: IOneTimeKey,
+    userId: string,
+    deviceInfo: DeviceInfo,
+): Promise<string> {
     const deviceId = deviceInfo.deviceId;
     try {
         await verifySignature(
@@ -407,6 +442,11 @@ async function _verifyKeyAndStartSession(olmDevice, oneTimeKey, userId, deviceIn
     return sid;
 }
 
+export interface IObject {
+    unsigned?: object;
+    signatures?: object;
+}
+
 /**
  * Verify the signature on an object
  *
@@ -424,7 +464,11 @@ async function _verifyKeyAndStartSession(olmDevice, oneTimeKey, userId, deviceIn
  * or rejects with an Error if it is bad.
  */
 export async function verifySignature(
-    olmDevice, obj, signingUserId, signingDeviceId, signingKey,
+    olmDevice: OlmDevice,
+    obj: IOneTimeKey | IObject,
+    signingUserId: string,
+    signingDeviceId: string,
+    signingKey: string,
 ) {
     const signKeyId = "ed25519:" + signingDeviceId;
     const signatures = obj.signatures || {};
@@ -434,10 +478,11 @@ export async function verifySignature(
         throw Error("No signature");
     }
 
-    // prepare the canonical json: remove unsigned and signatures, and stringify with
-    // anotherjson
+    // prepare the canonical json: remove unsigned and signatures, and stringify with anotherjson
     const mangledObj = Object.assign({}, obj);
-    delete mangledObj.unsigned;
+    if ("unsigned" in mangledObj) {
+        delete mangledObj.unsigned;
+    }
     delete mangledObj.signatures;
     const json = anotherjson.stringify(mangledObj);
 
@@ -453,14 +498,14 @@ export async function verifySignature(
  * @param {Olm.PkSigning|Uint8Array} key the signing object or the private key
  * seed
  * @param {string} userId The user ID who owns the signing key
- * @param {string} pubkey The public key (ignored if key is a seed)
+ * @param {string} pubKey The public key (ignored if key is a seed)
  * @returns {string} the signature for the object
  */
-export function pkSign(obj, key, userId, pubkey) {
+export function pkSign(obj: IObject, key: PkSigning, userId: string, pubKey: string): string {
     let createdKey = false;
     if (key instanceof Uint8Array) {
         const keyObj = new global.Olm.PkSigning();
-        pubkey = keyObj.init_with_seed(key);
+        pubKey = keyObj.init_with_seed(key);
         key = keyObj;
         createdKey = true;
     }
@@ -472,7 +517,7 @@ export function pkSign(obj, key, userId, pubkey) {
         const mysigs = sigs[userId] || {};
         sigs[userId] = mysigs;
 
-        return mysigs['ed25519:' + pubkey] = key.sign(anotherjson.stringify(obj));
+        return mysigs['ed25519:' + pubKey] = key.sign(anotherjson.stringify(obj));
     } finally {
         obj.signatures = sigs;
         if (unsigned) obj.unsigned = unsigned;
@@ -485,11 +530,11 @@ export function pkSign(obj, key, userId, pubkey) {
 /**
  * Verify a signed JSON object
  * @param {Object} obj Object to verify
- * @param {string} pubkey The public key to use to verify
+ * @param {string} pubKey The public key to use to verify
  * @param {string} userId The user ID who signed the object
  */
-export function pkVerify(obj, pubkey, userId) {
-    const keyId = "ed25519:" + pubkey;
+export function pkVerify(obj: IObject, pubKey: string, userId: string) {
+    const keyId = "ed25519:" + pubKey;
     if (!(obj.signatures && obj.signatures[userId] && obj.signatures[userId][keyId])) {
         throw new Error("No signature");
     }
@@ -500,7 +545,7 @@ export function pkVerify(obj, pubkey, userId) {
     const unsigned = obj.unsigned;
     if (obj.unsigned) delete obj.unsigned;
     try {
-        util.ed25519_verify(pubkey, anotherjson.stringify(obj), signature);
+        util.ed25519_verify(pubKey, anotherjson.stringify(obj), signature);
     } finally {
         obj.signatures = sigs;
         if (unsigned) obj.unsigned = unsigned;
@@ -513,7 +558,7 @@ export function pkVerify(obj, pubkey, userId) {
  * @param {Uint8Array} uint8Array The data to encode.
  * @return {string} The base64.
  */
-export function encodeBase64(uint8Array) {
+export function encodeBase64(uint8Array: ArrayBuffer | Uint8Array): string {
     return Buffer.from(uint8Array).toString("base64");
 }
 
@@ -522,7 +567,7 @@ export function encodeBase64(uint8Array) {
  * @param {Uint8Array} uint8Array The data to encode.
  * @return {string} The unpadded base64.
  */
-export function encodeUnpaddedBase64(uint8Array) {
+export function encodeUnpaddedBase64(uint8Array: ArrayBuffer | Uint8Array): string {
     return encodeBase64(uint8Array).replace(/=+$/g, '');
 }
 
@@ -531,6 +576,6 @@ export function encodeUnpaddedBase64(uint8Array) {
  * @param {string} base64 The base64 to decode.
  * @return {Uint8Array} The decoded data.
  */
-export function decodeBase64(base64) {
+export function decodeBase64(base64: string): Uint8Array {
     return Buffer.from(base64, "base64");
 }

src/crypto/recoverykey.ts

@@ -20,7 +20,7 @@ import bs58 from 'bs58';
 // (which are also base58 encoded, but bitcoin's involve a lot more hashing)
 const OLM_RECOVERY_KEY_PREFIX = [0x8B, 0x01];
 
-export function encodeRecoveryKey(key) {
+export function encodeRecoveryKey(key: ArrayLike<number>): string {
     const buf = new Buffer(OLM_RECOVERY_KEY_PREFIX.length + key.length + 1);
     buf.set(OLM_RECOVERY_KEY_PREFIX, 0);
     buf.set(key, OLM_RECOVERY_KEY_PREFIX.length);
@@ -35,8 +35,8 @@ export function encodeRecoveryKey(key) {
     return base58key.match(/.{1,4}/g).join(" ");
 }
 
-export function decodeRecoveryKey(recoverykey) {
-    const result = bs58.decode(recoverykey.replace(/ /g, ''));
+export function decodeRecoveryKey(recoveryKey: string): Uint8Array {
+    const result = bs58.decode(recoveryKey.replace(/ /g, ''));
 
     let parity = 0;
     for (const b of result) {

src/crypto/store/base.ts

@@ -10,6 +10,9 @@
  * @interface CryptoStore
  */
 
+import { IRoomKeyRequestBody, IRoomKeyRequestRecipient } from "../index";
+import { RoomKeyRequestState } from "../OutgoingRoomKeyRequestManager";
+
 /**
  * Represents an outgoing room key request
  *
@@ -32,3 +35,11 @@
  * @property {Number} state   current state of this request (states are defined
  *    in {@link module:crypto/OutgoingRoomKeyRequestManager~ROOM_KEY_REQUEST_STATES})
  */
+export interface OutgoingRoomKeyRequest {
+    requestId: string;
+    requestTxnId?: string;
+    cancellationTxnId?: string;
+    recipients: IRoomKeyRequestRecipient[];
+    requestBody: IRoomKeyRequestBody;
+    state: RoomKeyRequestState;
+}

src/crypto/verification/Base.js

@@ -292,7 +292,7 @@ export class VerificationBase extends EventEmitter {
                 await verifier(keyId, device, keyInfo);
                 verifiedDevices.push(deviceId);
             } else {
-                const crossSigningInfo = this._baseApis.crypto._deviceList
+                const crossSigningInfo = this._baseApis.crypto.deviceList
                       .getStoredCrossSigningForUser(userId);
                 if (crossSigningInfo && crossSigningInfo.getId() === deviceId) {
                     await verifier(keyId, DeviceInfo.fromStorage({

src/event-mapper.ts

@@ -15,9 +15,9 @@ limitations under the License.
 */
 
 import { MatrixClient } from "./client";
-import { MatrixEvent } from "./models/event";
+import { IEvent, MatrixEvent } from "./models/event";
 
-export type EventMapper = (obj: any) => MatrixEvent;
+export type EventMapper = (obj: Partial<IEvent>) => MatrixEvent;
 
 export interface MapperOpts {
     preventReEmit?: boolean;
@@ -28,7 +28,7 @@ export function eventMapperFor(client: MatrixClient, options: MapperOpts): Event
     const preventReEmit = Boolean(options.preventReEmit);
     const decrypt = options.decrypt !== false;
 
-    function mapper(plainOldJsObject) {
+    function mapper(plainOldJsObject: Partial<IEvent>) {
         const event = new MatrixEvent(plainOldJsObject);
         if (event.isEncrypted()) {
             if (!preventReEmit) {

src/filter-component.js

@@ -1,145 +0,0 @@
-/*
-Copyright 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module filter-component
- */
-
-/**
- * Checks if a value matches a given field value, which may be a * terminated
- * wildcard pattern.
- * @param {String} actual_value  The value to be compared
- * @param {String} filter_value  The filter pattern to be compared
- * @return {bool} true if the actual_value matches the filter_value
- */
-function _matches_wildcard(actual_value, filter_value) {
-    if (filter_value.endsWith("*")) {
-        const type_prefix = filter_value.slice(0, -1);
-        return actual_value.substr(0, type_prefix.length) === type_prefix;
-    } else {
-        return actual_value === filter_value;
-    }
-}
-
-/**
- * FilterComponent is a section of a Filter definition which defines the
- * types, rooms, senders filters etc to be applied to a particular type of resource.
- * This is all ported over from synapse's Filter object.
- *
- * N.B. that synapse refers to these as 'Filters', and what js-sdk refers to as
- * 'Filters' are referred to as 'FilterCollections'.
- *
- * @constructor
- * @param {Object} filter_json the definition of this filter JSON, e.g. { 'contains_url': true }
- */
-export function FilterComponent(filter_json) {
-    this.filter_json = filter_json;
-
-    this.types = filter_json.types || null;
-    this.not_types = filter_json.not_types || [];
-
-    this.rooms = filter_json.rooms || null;
-    this.not_rooms = filter_json.not_rooms || [];
-
-    this.senders = filter_json.senders || null;
-    this.not_senders = filter_json.not_senders || [];
-
-    this.contains_url = filter_json.contains_url || null;
-}
-
-/**
- * Checks with the filter component matches the given event
- * @param {MatrixEvent} event event to be checked against the filter
- * @return {bool} true if the event matches the filter
- */
-FilterComponent.prototype.check = function(event) {
-    return this._checkFields(
-        event.getRoomId(),
-        event.getSender(),
-        event.getType(),
-        event.getContent() ? event.getContent().url !== undefined : false,
-    );
-};
-
-/**
- * Checks whether the filter component matches the given event fields.
- * @param {String} room_id       the room_id for the event being checked
- * @param {String} sender        the sender of the event being checked
- * @param {String} event_type    the type of the event being checked
- * @param {String} contains_url  whether the event contains a content.url field
- * @return {bool} true if the event fields match the filter
- */
-FilterComponent.prototype._checkFields =
-    function(room_id, sender, event_type, contains_url) {
-    const literal_keys = {
-        "rooms": function(v) {
-            return room_id === v;
-        },
-        "senders": function(v) {
-            return sender === v;
-        },
-        "types": function(v) {
-            return _matches_wildcard(event_type, v);
-        },
-    };
-
-    const self = this;
-    for (let n=0; n < Object.keys(literal_keys).length; n++) {
-        const name = Object.keys(literal_keys)[n];
-        const match_func = literal_keys[name];
-        const not_name = "not_" + name;
-        const disallowed_values = self[not_name];
-        if (disallowed_values.filter(match_func).length > 0) {
-            return false;
-        }
-
-        const allowed_values = self[name];
-        if (allowed_values && allowed_values.length > 0) {
-            const anyMatch = allowed_values.some(match_func);
-            if (!anyMatch) {
-                return false;
-            }
-        }
-    }
-
-    const contains_url_filter = this.filter_json.contains_url;
-    if (contains_url_filter !== undefined) {
-        if (contains_url_filter !== contains_url) {
-            return false;
-        }
-    }
-
-    return true;
-};
-
-/**
- * Filters a list of events down to those which match this filter component
- * @param {MatrixEvent[]} events  Events to be checked againt the filter component
- * @return {MatrixEvent[]} events which matched the filter component
- */
-FilterComponent.prototype.filter = function(events) {
-    return events.filter(this.check, this);
-};
-
-/**
- * Returns the limit field for a given filter component, providing a default of
- * 10 if none is otherwise specified.  Cargo-culted from Synapse.
- * @return {Number} the limit for this filter component.
- */
-FilterComponent.prototype.limit = function() {
-    return this.filter_json.limit !== undefined ? this.filter_json.limit : 10;
-};

src/filter-component.ts

@@ -0,0 +1,156 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { MatrixEvent } from "./models/event";
+
+/**
+ * @module filter-component
+ */
+
+/**
+ * Checks if a value matches a given field value, which may be a * terminated
+ * wildcard pattern.
+ * @param {String} actualValue  The value to be compared
+ * @param {String} filterValue  The filter pattern to be compared
+ * @return {boolean} true if the actualValue matches the filterValue
+ */
+function matchesWildcard(actualValue: string, filterValue: string): boolean {
+    if (filterValue.endsWith("*")) {
+        const typePrefix = filterValue.slice(0, -1);
+        return actualValue.substr(0, typePrefix.length) === typePrefix;
+    } else {
+        return actualValue === filterValue;
+    }
+}
+
+/* eslint-disable camelcase */
+export interface IFilterComponent {
+    types?: string[];
+    not_types?: string[];
+    rooms?: string[];
+    not_rooms?: string[];
+    senders?: string[];
+    not_senders?: string[];
+    contains_url?: boolean;
+    limit?: number;
+}
+/* eslint-enable camelcase */
+
+/**
+ * FilterComponent is a section of a Filter definition which defines the
+ * types, rooms, senders filters etc to be applied to a particular type of resource.
+ * This is all ported over from synapse's Filter object.
+ *
+ * N.B. that synapse refers to these as 'Filters', and what js-sdk refers to as
+ * 'Filters' are referred to as 'FilterCollections'.
+ *
+ * @constructor
+ * @param {Object} filterJson the definition of this filter JSON, e.g. { 'contains_url': true }
+ */
+export class FilterComponent {
+    constructor(private filterJson: IFilterComponent) {}
+
+    /**
+     * Checks with the filter component matches the given event
+     * @param {MatrixEvent} event event to be checked against the filter
+     * @return {boolean} true if the event matches the filter
+     */
+    public check(event: MatrixEvent): boolean {
+        return this.checkFields(
+            event.getRoomId(),
+            event.getSender(),
+            event.getType(),
+            event.getContent() ? event.getContent().url !== undefined : false,
+        );
+    }
+
+    /**
+     * Converts the filter component into the form expected over the wire
+     */
+    public toJSON(): object {
+        return {
+            types: this.filterJson.types || null,
+            not_types: this.filterJson.not_types || [],
+            rooms: this.filterJson.rooms || null,
+            not_rooms: this.filterJson.not_rooms || [],
+            senders: this.filterJson.senders || null,
+            not_senders: this.filterJson.not_senders || [],
+            contains_url: this.filterJson.contains_url || null,
+        };
+    }
+
+    /**
+     * Checks whether the filter component matches the given event fields.
+     * @param {String} roomId        the roomId for the event being checked
+     * @param {String} sender        the sender of the event being checked
+     * @param {String} eventType     the type of the event being checked
+     * @param {boolean} containsUrl  whether the event contains a content.url field
+     * @return {boolean} true if the event fields match the filter
+     */
+    private checkFields(roomId: string, sender: string, eventType: string, containsUrl: boolean): boolean {
+        const literalKeys = {
+            "rooms": function(v: string): boolean {
+                return roomId === v;
+            },
+            "senders": function(v: string): boolean {
+                return sender === v;
+            },
+            "types": function(v: string): boolean {
+                return matchesWildcard(eventType, v);
+            },
+        };
+
+        for (let n = 0; n < Object.keys(literalKeys).length; n++) {
+            const name = Object.keys(literalKeys)[n];
+            const matchFunc = literalKeys[name];
+            const notName = "not_" + name;
+            const disallowedValues: string[] = this.filterJson[notName];
+            if (disallowedValues?.some(matchFunc)) {
+                return false;
+            }
+
+            const allowedValues: string[] = this.filterJson[name];
+            if (allowedValues && !allowedValues.some(matchFunc)) {
+                return false;
+            }
+        }
+
+        const containsUrlFilter = this.filterJson.contains_url;
+        if (containsUrlFilter !== undefined && containsUrlFilter !== containsUrl) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Filters a list of events down to those which match this filter component
+     * @param {MatrixEvent[]} events  Events to be checked against the filter component
+     * @return {MatrixEvent[]} events which matched the filter component
+     */
+    filter(events: MatrixEvent[]): MatrixEvent[] {
+        return events.filter(this.check, this);
+    }
+
+    /**
+     * Returns the limit field for a given filter component, providing a default of
+     * 10 if none is otherwise specified. Cargo-culted from Synapse.
+     * @return {Number} the limit for this filter component.
+     */
+    limit(): number {
+        return this.filterJson.limit !== undefined ? this.filterJson.limit : 10;
+    }
+}

src/filter.js

@@ -1,199 +0,0 @@
-/*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module filter
- */
-
-import { FilterComponent } from "./filter-component";
-
-/**
- * @param {Object} obj
- * @param {string} keyNesting
- * @param {*} val
- */
-function setProp(obj, keyNesting, val) {
-    const nestedKeys = keyNesting.split(".");
-    let currentObj = obj;
-    for (let i = 0; i < (nestedKeys.length - 1); i++) {
-        if (!currentObj[nestedKeys[i]]) {
-            currentObj[nestedKeys[i]] = {};
-        }
-        currentObj = currentObj[nestedKeys[i]];
-    }
-    currentObj[nestedKeys[nestedKeys.length - 1]] = val;
-}
-
-/**
- * Construct a new Filter.
- * @constructor
- * @param {string} userId The user ID for this filter.
- * @param {string=} filterId The filter ID if known.
- * @prop {string} userId The user ID of the filter
- * @prop {?string} filterId The filter ID
- */
-export function Filter(userId, filterId) {
-    this.userId = userId;
-    this.filterId = filterId;
-    this.definition = {};
-}
-
-Filter.LAZY_LOADING_MESSAGES_FILTER = {
-    lazy_load_members: true,
-};
-
-/**
- * Get the ID of this filter on your homeserver (if known)
- * @return {?Number} The filter ID
- */
-Filter.prototype.getFilterId = function() {
-    return this.filterId;
-};
-
-/**
- * Get the JSON body of the filter.
- * @return {Object} The filter definition
- */
-Filter.prototype.getDefinition = function() {
-    return this.definition;
-};
-
-/**
- * Set the JSON body of the filter
- * @param {Object} definition The filter definition
- */
-Filter.prototype.setDefinition = function(definition) {
-    this.definition = definition;
-
-    // This is all ported from synapse's FilterCollection()
-
-    // definitions look something like:
-    // {
-    //   "room": {
-    //     "rooms": ["!abcde:example.com"],
-    //     "not_rooms": ["!123456:example.com"],
-    //     "state": {
-    //       "types": ["m.room.*"],
-    //       "not_rooms": ["!726s6s6q:example.com"],
-    //       "lazy_load_members": true,
-    //     },
-    //     "timeline": {
-    //       "limit": 10,
-    //       "types": ["m.room.message"],
-    //       "not_rooms": ["!726s6s6q:example.com"],
-    //       "not_senders": ["@spam:example.com"]
-    //       "contains_url": true
-    //     },
-    //     "ephemeral": {
-    //       "types": ["m.receipt", "m.typing"],
-    //       "not_rooms": ["!726s6s6q:example.com"],
-    //       "not_senders": ["@spam:example.com"]
-    //     }
-    //   },
-    //   "presence": {
-    //     "types": ["m.presence"],
-    //     "not_senders": ["@alice:example.com"]
-    //   },
-    //   "event_format": "client",
-    //   "event_fields": ["type", "content", "sender"]
-    // }
-
-    const room_filter_json = definition.room;
-
-    // consider the top level rooms/not_rooms filter
-    const room_filter_fields = {};
-    if (room_filter_json) {
-        if (room_filter_json.rooms) {
-            room_filter_fields.rooms = room_filter_json.rooms;
-        }
-        if (room_filter_json.rooms) {
-            room_filter_fields.not_rooms = room_filter_json.not_rooms;
-        }
-
-        this._include_leave = room_filter_json.include_leave || false;
-    }
-
-    this._room_filter = new FilterComponent(room_filter_fields);
-    this._room_timeline_filter = new FilterComponent(
-        room_filter_json ? (room_filter_json.timeline || {}) : {},
-    );
-
-    // don't bother porting this from synapse yet:
-    // this._room_state_filter =
-    //     new FilterComponent(room_filter_json.state || {});
-    // this._room_ephemeral_filter =
-    //     new FilterComponent(room_filter_json.ephemeral || {});
-    // this._room_account_data_filter =
-    //     new FilterComponent(room_filter_json.account_data || {});
-    // this._presence_filter =
-    //     new FilterComponent(definition.presence || {});
-    // this._account_data_filter =
-    //     new FilterComponent(definition.account_data || {});
-};
-
-/**
- * Get the room.timeline filter component of the filter
- * @return {FilterComponent} room timeline filter component
- */
-Filter.prototype.getRoomTimelineFilterComponent = function() {
-    return this._room_timeline_filter;
-};
-
-/**
- * Filter the list of events based on whether they are allowed in a timeline
- * based on this filter
- * @param {MatrixEvent[]} events  the list of events being filtered
- * @return {MatrixEvent[]} the list of events which match the filter
- */
-Filter.prototype.filterRoomTimeline = function(events) {
-    return this._room_timeline_filter.filter(this._room_filter.filter(events));
-};
-
-/**
- * Set the max number of events to return for each room's timeline.
- * @param {Number} limit The max number of events to return for each room.
- */
-Filter.prototype.setTimelineLimit = function(limit) {
-    setProp(this.definition, "room.timeline.limit", limit);
-};
-
-Filter.prototype.setLazyLoadMembers = function(enabled) {
-    setProp(this.definition, "room.state.lazy_load_members", !!enabled);
-};
-
-/**
- * Control whether left rooms should be included in responses.
- * @param {boolean} includeLeave True to make rooms the user has left appear
- * in responses.
- */
-Filter.prototype.setIncludeLeaveRooms = function(includeLeave) {
-    setProp(this.definition, "room.include_leave", includeLeave);
-};
-
-/**
- * Create a filter from existing data.
- * @static
- * @param {string} userId
- * @param {string} filterId
- * @param {Object} jsonObj
- * @return {Filter}
- */
-Filter.fromJson = function(userId, filterId, jsonObj) {
-    const filter = new Filter(userId, filterId);
-    filter.setDefinition(jsonObj);
-    return filter;
-};

src/filter.ts

@@ -0,0 +1,224 @@
+/*
+Copyright 2015 - 2021 Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module filter
+ */
+
+import { FilterComponent, IFilterComponent } from "./filter-component";
+import { MatrixEvent } from "./models/event";
+
+/**
+ * @param {Object} obj
+ * @param {string} keyNesting
+ * @param {*} val
+ */
+function setProp(obj: object, keyNesting: string, val: any) {
+    const nestedKeys = keyNesting.split(".");
+    let currentObj = obj;
+    for (let i = 0; i < (nestedKeys.length - 1); i++) {
+        if (!currentObj[nestedKeys[i]]) {
+            currentObj[nestedKeys[i]] = {};
+        }
+        currentObj = currentObj[nestedKeys[i]];
+    }
+    currentObj[nestedKeys[nestedKeys.length - 1]] = val;
+}
+
+/* eslint-disable camelcase */
+export interface IFilterDefinition {
+    event_fields?: string[];
+    event_format?: "client" | "federation";
+    presence?: IFilterComponent;
+    account_data?: IFilterComponent;
+    room?: IRoomFilter;
+}
+
+export interface IRoomEventFilter extends IFilterComponent {
+    lazy_load_members?: boolean;
+    include_redundant_members?: boolean;
+}
+
+interface IStateFilter extends IRoomEventFilter {}
+
+interface IRoomFilter {
+    not_rooms?: string[];
+    rooms?: string[];
+    ephemeral?: IRoomEventFilter;
+    include_leave?: boolean;
+    state?: IStateFilter;
+    timeline?: IRoomEventFilter;
+    account_data?: IRoomEventFilter;
+}
+/* eslint-enable camelcase */
+
+/**
+ * Construct a new Filter.
+ * @constructor
+ * @param {string} userId The user ID for this filter.
+ * @param {string=} filterId The filter ID if known.
+ * @prop {string} userId The user ID of the filter
+ * @prop {?string} filterId The filter ID
+ */
+export class Filter {
+    static LAZY_LOADING_MESSAGES_FILTER = {
+        lazy_load_members: true,
+    };
+
+    /**
+     * Create a filter from existing data.
+     * @static
+     * @param {string} userId
+     * @param {string} filterId
+     * @param {Object} jsonObj
+     * @return {Filter}
+     */
+    public static fromJson(userId: string, filterId: string, jsonObj: IFilterDefinition): Filter {
+        const filter = new Filter(userId, filterId);
+        filter.setDefinition(jsonObj);
+        return filter;
+    }
+
+    private definition: IFilterDefinition = {};
+    private roomFilter: FilterComponent;
+    private roomTimelineFilter: FilterComponent;
+
+    constructor(public readonly userId: string, public filterId?: string) {}
+
+    /**
+     * Get the ID of this filter on your homeserver (if known)
+     * @return {?string} The filter ID
+     */
+    getFilterId(): string | null {
+        return this.filterId;
+    }
+
+    /**
+     * Get the JSON body of the filter.
+     * @return {Object} The filter definition
+     */
+    getDefinition(): IFilterDefinition {
+        return this.definition;
+    }
+
+    /**
+     * Set the JSON body of the filter
+     * @param {Object} definition The filter definition
+     */
+    setDefinition(definition: IFilterDefinition) {
+        this.definition = definition;
+
+        // This is all ported from synapse's FilterCollection()
+
+        // definitions look something like:
+        // {
+        //   "room": {
+        //     "rooms": ["!abcde:example.com"],
+        //     "not_rooms": ["!123456:example.com"],
+        //     "state": {
+        //       "types": ["m.room.*"],
+        //       "not_rooms": ["!726s6s6q:example.com"],
+        //       "lazy_load_members": true,
+        //     },
+        //     "timeline": {
+        //       "limit": 10,
+        //       "types": ["m.room.message"],
+        //       "not_rooms": ["!726s6s6q:example.com"],
+        //       "not_senders": ["@spam:example.com"]
+        //       "contains_url": true
+        //     },
+        //     "ephemeral": {
+        //       "types": ["m.receipt", "m.typing"],
+        //       "not_rooms": ["!726s6s6q:example.com"],
+        //       "not_senders": ["@spam:example.com"]
+        //     }
+        //   },
+        //   "presence": {
+        //     "types": ["m.presence"],
+        //     "not_senders": ["@alice:example.com"]
+        //   },
+        //   "event_format": "client",
+        //   "event_fields": ["type", "content", "sender"]
+        // }
+
+        const roomFilterJson = definition.room;
+
+        // consider the top level rooms/not_rooms filter
+        const roomFilterFields: IRoomFilter = {};
+        if (roomFilterJson) {
+            if (roomFilterJson.rooms) {
+                roomFilterFields.rooms = roomFilterJson.rooms;
+            }
+            if (roomFilterJson.rooms) {
+                roomFilterFields.not_rooms = roomFilterJson.not_rooms;
+            }
+        }
+
+        this.roomFilter = new FilterComponent(roomFilterFields);
+        this.roomTimelineFilter = new FilterComponent(roomFilterJson?.timeline || {});
+
+        // don't bother porting this from synapse yet:
+        // this._room_state_filter =
+        //     new FilterComponent(roomFilterJson.state || {});
+        // this._room_ephemeral_filter =
+        //     new FilterComponent(roomFilterJson.ephemeral || {});
+        // this._room_account_data_filter =
+        //     new FilterComponent(roomFilterJson.account_data || {});
+        // this._presence_filter =
+        //     new FilterComponent(definition.presence || {});
+        // this._account_data_filter =
+        //     new FilterComponent(definition.account_data || {});
+    }
+
+    /**
+     * Get the room.timeline filter component of the filter
+     * @return {FilterComponent} room timeline filter component
+     */
+    getRoomTimelineFilterComponent(): FilterComponent {
+        return this.roomTimelineFilter;
+    }
+
+    /**
+     * Filter the list of events based on whether they are allowed in a timeline
+     * based on this filter
+     * @param {MatrixEvent[]} events  the list of events being filtered
+     * @return {MatrixEvent[]} the list of events which match the filter
+     */
+    filterRoomTimeline(events: MatrixEvent[]): MatrixEvent[] {
+        return this.roomTimelineFilter.filter(this.roomFilter.filter(events));
+    }
+
+    /**
+     * Set the max number of events to return for each room's timeline.
+     * @param {Number} limit The max number of events to return for each room.
+     */
+    setTimelineLimit(limit: number) {
+        setProp(this.definition, "room.timeline.limit", limit);
+    }
+
+    setLazyLoadMembers(enabled: boolean) {
+        setProp(this.definition, "room.state.lazy_load_members", !!enabled);
+    }
+
+    /**
+     * Control whether left rooms should be included in responses.
+     * @param {boolean} includeLeave True to make rooms the user has left appear
+     * in responses.
+     */
+    setIncludeLeaveRooms(includeLeave: boolean) {
+        setProp(this.definition, "room.include_leave", includeLeave);
+    }
+}

src/http-api.js

@@ -121,7 +121,7 @@ MatrixHttpApi.prototype = {
     },
 
     /**
-     * Upload content to the Home Server
+     * Upload content to the homeserver
      *
      * @param {object} file The object to upload. On a browser, something that
      *   can be sent to XMLHttpRequest.send (typically a File).  Under node.js,
@@ -393,7 +393,7 @@ MatrixHttpApi.prototype = {
         accessToken,
     ) {
         if (!this.opts.idBaseUrl) {
-            throw new Error("No Identity Server base URL set");
+            throw new Error("No identity server base URL set");
         }
 
         const fullUri = this.opts.idBaseUrl + prefix + path;

src/interactive-auth.js

@@ -18,7 +18,6 @@ limitations under the License.
 
 /** @module interactive-auth */
 
-import url from "url";
 import * as utils from "./utils";
 import { logger } from './logger';
 
@@ -187,9 +186,7 @@ InteractiveAuth.prototype = {
                     client_secret: this._clientSecret,
                 };
                 if (await this._matrixClient.doesServerRequireIdServerParam()) {
-                    const idServerParsedUrl = url.parse(
-                        this._matrixClient.getIdentityServerUrl(),
-                    );
+                    const idServerParsedUrl = new URL(this._matrixClient.getIdentityServerUrl());
                     creds.id_server = idServerParsedUrl.host;
                 }
                 authDict = {
@@ -217,7 +214,7 @@ InteractiveAuth.prototype = {
 
     /**
      * get the client secret used for validation sessions
-     * with the ID server.
+     * with the identity server.
      *
      * @return {string} client secret
      */

src/matrix.ts

@@ -19,6 +19,8 @@ import { MemoryStore } from "./store/memory";
 import { MatrixScheduler } from "./scheduler";
 import { MatrixClient } from "./client";
 import { ICreateClientOpts } from "./client";
+import { DeviceTrustLevel } from "./crypto/CrossSigning";
+import { ISecretStorageKeyInfo } from "./crypto/api";
 
 export * from "./client";
 export * from "./http-api";
@@ -99,7 +101,7 @@ export function setCryptoStoreFactory(fac) {
 }
 
 export interface ICryptoCallbacks {
-    getCrossSigningKey?: (keyType: string, pubKey: Uint8Array) => Promise<Uint8Array>;
+    getCrossSigningKey?: (keyType: string, pubKey: string) => Promise<Uint8Array>;
     saveCrossSigningKeys?: (keys: Record<string, Uint8Array>) => void;
     shouldUpgradeDeviceVerifications?: (
         users: Record<string, any>
@@ -112,7 +114,7 @@ export interface ICryptoCallbacks {
     ) => void;
     onSecretRequested?: (
         userId: string, deviceId: string,
-        requestId: string, secretName: string, deviceTrust: IDeviceTrustLevel
+        requestId: string, secretName: string, deviceTrust: DeviceTrustLevel
     ) => Promise<string>;
     getDehydrationKey?: (
         keyInfo: ISecretStorageKeyInfo,
@@ -121,25 +123,6 @@ export interface ICryptoCallbacks {
     getBackupKey?: () => Promise<Uint8Array>;
 }
 
-// TODO: Move this to `SecretStorage` once converted
-export interface ISecretStorageKeyInfo {
-    passphrase?: {
-        algorithm: "m.pbkdf2";
-        iterations: number;
-        salt: string;
-    };
-    iv?: string;
-    mac?: string;
-}
-
-// TODO: Move this to `CrossSigning` once converted
-export interface IDeviceTrustLevel {
-    isVerified(): boolean;
-    isCrossSigningVerified(): boolean;
-    isLocallyVerified(): boolean;
-    isTofu(): boolean;
-}
-
 /**
  * Construct a Matrix Client. Similar to {@link module:client.MatrixClient}
  * except that the 'request', 'store' and 'scheduler' dependencies are satisfied.

src/models/MSC3089Branch.ts

@@ -70,8 +70,8 @@ export class MSC3089Branch {
      * @param {string} name The new name for this file.
      * @returns {Promise<void>} Resolves when complete.
      */
-    public setName(name: string): Promise<void> {
-        return this.client.sendStateEvent(this.roomId, UNSTABLE_MSC3089_BRANCH.name, {
+    public async setName(name: string): Promise<void> {
+        await this.client.sendStateEvent(this.roomId, UNSTABLE_MSC3089_BRANCH.name, {
             ...this.indexEvent.getContent(),
             name: name,
         }, this.id);

src/models/MSC3089TreeSpace.ts

@@ -19,8 +19,17 @@ import { EventType, IEncryptedFile, MsgType, UNSTABLE_MSC3089_BRANCH, UNSTABLE_M
 import { Room } from "./room";
 import { logger } from "../logger";
 import { MatrixEvent } from "./event";
-import { averageBetweenStrings, DEFAULT_ALPHABET, lexicographicCompare, nextString, prevString } from "../utils";
+import {
+    averageBetweenStrings,
+    DEFAULT_ALPHABET,
+    lexicographicCompare,
+    nextString,
+    prevString,
+    simpleRetryOperation,
+} from "../utils";
 import { MSC3089Branch } from "./MSC3089Branch";
+import promiseRetry from "p-retry";
+import { isRoomSharedHistory } from "../crypto/algorithms/megolm";
 
 /**
  * The recommended defaults for a tree space's power levels. Note that this
@@ -102,20 +111,50 @@ export class MSC3089TreeSpace {
      * @param {string} name The new name for the space.
      * @returns {Promise<void>} Resolves when complete.
      */
-    public setName(name: string): Promise<void> {
-        return this.client.sendStateEvent(this.roomId, EventType.RoomName, { name }, "");
+    public async setName(name: string): Promise<void> {
+        await this.client.sendStateEvent(this.roomId, EventType.RoomName, { name }, "");
     }
 
     /**
      * Invites a user to the tree space. They will be given the default Viewer
      * permission level unless specified elsewhere.
      * @param {string} userId The user ID to invite.
+     * @param {boolean} andSubspaces True (default) to invite the user to all
+     * directories/subspaces too, recursively.
+     * @param {boolean} shareHistoryKeys True (default) to share encryption keys
+     * with the invited user. This will allow them to decrypt the events (files)
+     * in the tree. Keys will not be shared if the room is lacking appropriate
+     * history visibility (by default, history visibility is "shared" in trees,
+     * which is an appropriate visibility for these purposes).
      * @returns {Promise<void>} Resolves when complete.
      */
-    public invite(userId: string): Promise<void> {
-        // TODO: [@@TR] Reliable invites
-        // TODO: [@@TR] Share keys
-        return this.client.invite(this.roomId, userId);
+    public async invite(userId: string, andSubspaces = true, shareHistoryKeys = true): Promise<void> {
+        const promises: Promise<void>[] = [this.retryInvite(userId)];
+        if (andSubspaces) {
+            promises.push(...this.getDirectories().map(d => d.invite(userId, andSubspaces, shareHistoryKeys)));
+        }
+        return Promise.all(promises).then(() => {
+            // Note: key sharing is default on because for file trees it is relatively important that the invite
+            // target can actually decrypt the files. The implied use case is that by inviting a user to the tree
+            // it means the sender would like the receiver to view/download the files contained within, much like
+            // sharing a folder in other circles.
+            if (shareHistoryKeys && isRoomSharedHistory(this.room)) {
+                // noinspection JSIgnoredPromiseFromCall - we aren't concerned as much if this fails.
+                this.client.sendSharedHistoryKeys(this.roomId, [userId]);
+            }
+        });
+    }
+
+    private retryInvite(userId: string): Promise<void> {
+        return simpleRetryOperation(async () => {
+            await this.client.invite(this.roomId, userId).catch(e => {
+                // We don't want to retry permission errors forever...
+                if (e?.errcode === "M_FORBIDDEN") {
+                    throw new promiseRetry.AbortError(e);
+                }
+                throw e;
+            });
+        });
     }
 
     /**
@@ -151,7 +190,7 @@ export class MSC3089TreeSpace {
         }
         pls['users'] = users;
 
-        return this.client.sendStateEvent(this.roomId, EventType.RoomPowerLevels, pls, "");
+        await this.client.sendStateEvent(this.roomId, EventType.RoomPowerLevels, pls, "");
     }
 
     /**

src/models/event-context.js

@@ -1,115 +0,0 @@
-/*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/event-context
- */
-
-/**
- * Construct a new EventContext
- *
- * An eventcontext is used for circumstances such as search results, when we
- * have a particular event of interest, and a bunch of events before and after
- * it.
- *
- * It also stores pagination tokens for going backwards and forwards in the
- * timeline.
- *
- * @param {MatrixEvent} ourEvent  the event at the centre of this context
- *
- * @constructor
- */
-export function EventContext(ourEvent) {
-    this._timeline = [ourEvent];
-    this._ourEventIndex = 0;
-    this._paginateTokens = { b: null, f: null };
-
-    // this is used by MatrixClient to keep track of active requests
-    this._paginateRequests = { b: null, f: null };
-}
-
-/**
- * Get the main event of interest
- *
- * This is a convenience function for getTimeline()[getOurEventIndex()].
- *
- * @return {MatrixEvent} The event at the centre of this context.
- */
-EventContext.prototype.getEvent = function() {
-    return this._timeline[this._ourEventIndex];
-};
-
-/**
- * Get the list of events in this context
- *
- * @return {Array} An array of MatrixEvents
- */
-EventContext.prototype.getTimeline = function() {
-    return this._timeline;
-};
-
-/**
- * Get the index in the timeline of our event
- *
- * @return {Number}
- */
-EventContext.prototype.getOurEventIndex = function() {
-    return this._ourEventIndex;
-};
-
-/**
- * Get a pagination token.
- *
- * @param {boolean} backwards   true to get the pagination token for going
- *                                  backwards in time
- * @return {string}
- */
-EventContext.prototype.getPaginateToken = function(backwards) {
-    return this._paginateTokens[backwards ? 'b' : 'f'];
-};
-
-/**
- * Set a pagination token.
- *
- * Generally this will be used only by the matrix js sdk.
- *
- * @param {string} token        pagination token
- * @param {boolean} backwards   true to set the pagination token for going
- *                                   backwards in time
- */
-EventContext.prototype.setPaginateToken = function(token, backwards) {
-    this._paginateTokens[backwards ? 'b' : 'f'] = token;
-};
-
-/**
- * Add more events to the timeline
- *
- * @param {Array} events      new events, in timeline order
- * @param {boolean} atStart   true to insert new events at the start
- */
-EventContext.prototype.addEvents = function(events, atStart) {
-    // TODO: should we share logic with Room.addEventsToTimeline?
-    // Should Room even use EventContext?
-
-    if (atStart) {
-        this._timeline = events.concat(this._timeline);
-        this._ourEventIndex += events.length;
-    } else {
-        this._timeline = this._timeline.concat(events);
-    }
-};
-

src/models/event-context.ts

@@ -0,0 +1,119 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { MatrixEvent } from "./event";
+import { Direction } from "./event-timeline";
+
+/**
+ * @module models/event-context
+ */
+export class EventContext {
+    private timeline: MatrixEvent[];
+    private ourEventIndex = 0;
+    private paginateTokens: Record<Direction, string | null> = {
+        [Direction.Backward]: null,
+        [Direction.Forward]: null,
+    };
+
+    /**
+     * Construct a new EventContext
+     *
+     * An eventcontext is used for circumstances such as search results, when we
+     * have a particular event of interest, and a bunch of events before and after
+     * it.
+     *
+     * It also stores pagination tokens for going backwards and forwards in the
+     * timeline.
+     *
+     * @param {MatrixEvent} ourEvent  the event at the centre of this context
+     *
+     * @constructor
+     */
+    constructor(ourEvent: MatrixEvent) {
+        this.timeline = [ourEvent];
+    }
+
+    /**
+     * Get the main event of interest
+     *
+     * This is a convenience function for getTimeline()[getOurEventIndex()].
+     *
+     * @return {MatrixEvent} The event at the centre of this context.
+     */
+    public getEvent(): MatrixEvent {
+        return this.timeline[this.ourEventIndex];
+    }
+
+    /**
+     * Get the list of events in this context
+     *
+     * @return {Array} An array of MatrixEvents
+     */
+    public getTimeline(): MatrixEvent[] {
+        return this.timeline;
+    }
+
+    /**
+     * Get the index in the timeline of our event
+     *
+     * @return {Number}
+     */
+    public getOurEventIndex(): number {
+        return this.ourEventIndex;
+    }
+
+    /**
+     * Get a pagination token.
+     *
+     * @param {boolean} backwards   true to get the pagination token for going
+     *                                  backwards in time
+     * @return {string}
+     */
+    public getPaginateToken(backwards = false): string {
+        return this.paginateTokens[backwards ? Direction.Backward : Direction.Forward];
+    }
+
+    /**
+     * Set a pagination token.
+     *
+     * Generally this will be used only by the matrix js sdk.
+     *
+     * @param {string} token        pagination token
+     * @param {boolean} backwards   true to set the pagination token for going
+     *                                   backwards in time
+     */
+    public setPaginateToken(token: string, backwards = false): void {
+        this.paginateTokens[backwards ? Direction.Backward : Direction.Forward] = token;
+    }
+
+    /**
+     * Add more events to the timeline
+     *
+     * @param {Array} events      new events, in timeline order
+     * @param {boolean} atStart   true to insert new events at the start
+     */
+    public addEvents(events: MatrixEvent[], atStart = false): void {
+        // TODO: should we share logic with Room.addEventsToTimeline?
+        // Should Room even use EventContext?
+
+        if (atStart) {
+            this.timeline = events.concat(this.timeline);
+            this.ourEventIndex += events.length;
+        } else {
+            this.timeline = this.timeline.concat(events);
+        }
+    }
+}

src/models/event-timeline-set.js

@@ -1,848 +0,0 @@
-/*
-Copyright 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/event-timeline-set
- */
-
-import { EventEmitter } from "events";
-import { EventTimeline } from "./event-timeline";
-import { EventStatus } from "./event";
-import * as utils from "../utils";
-import { logger } from '../logger';
-import { Relations } from './relations';
-
-// var DEBUG = false;
-const DEBUG = true;
-
-let debuglog;
-if (DEBUG) {
-    // using bind means that we get to keep useful line numbers in the console
-    debuglog = logger.log.bind(logger);
-} else {
-    debuglog = function() {};
-}
-
-/**
- * Construct a set of EventTimeline objects, typically on behalf of a given
- * room.  A room may have multiple EventTimelineSets for different levels
- * of filtering.  The global notification list is also an EventTimelineSet, but
- * lacks a room.
- *
- * <p>This is an ordered sequence of timelines, which may or may not
- * be continuous. Each timeline lists a series of events, as well as tracking
- * the room state at the start and the end of the timeline (if appropriate).
- * It also tracks forward and backward pagination tokens, as well as containing
- * links to the next timeline in the sequence.
- *
- * <p>There is one special timeline - the 'live' timeline, which represents the
- * timeline to which events are being added in real-time as they are received
- * from the /sync API. Note that you should not retain references to this
- * timeline - even if it is the current timeline right now, it may not remain
- * so if the server gives us a timeline gap in /sync.
- *
- * <p>In order that we can find events from their ids later, we also maintain a
- * map from event_id to timeline and index.
- *
- * @constructor
- * @param {?Room} room
- * Room for this timelineSet. May be null for non-room cases, such as the
- * notification timeline.
- * @param {Object} opts Options inherited from Room.
- *
- * @param {boolean} [opts.timelineSupport = false]
- * Set to true to enable improved timeline support.
- * @param {Object} [opts.filter = null]
- * The filter object, if any, for this timelineSet.
- * @param {boolean} [opts.unstableClientRelationAggregation = false]
- * Optional. Set to true to enable client-side aggregation of event relations
- * via `getRelationsForEvent`.
- * This feature is currently unstable and the API may change without notice.
- */
-export function EventTimelineSet(room, opts) {
-    this.room = room;
-
-    this._timelineSupport = Boolean(opts.timelineSupport);
-    this._liveTimeline = new EventTimeline(this);
-    this._unstableClientRelationAggregation = !!opts.unstableClientRelationAggregation;
-
-    // just a list - *not* ordered.
-    this._timelines = [this._liveTimeline];
-    this._eventIdToTimeline = {};
-
-    this._filter = opts.filter || null;
-
-    if (this._unstableClientRelationAggregation) {
-        // A tree of objects to access a set of relations for an event, as in:
-        // this._relations[relatesToEventId][relationType][relationEventType]
-        this._relations = {};
-    }
-}
-utils.inherits(EventTimelineSet, EventEmitter);
-
-/**
- * Get all the timelines in this set
- * @return {module:models/event-timeline~EventTimeline[]} the timelines in this set
- */
-EventTimelineSet.prototype.getTimelines = function() {
-    return this._timelines;
-};
-/**
- * Get the filter object this timeline set is filtered on, if any
- * @return {?Filter} the optional filter for this timelineSet
- */
-EventTimelineSet.prototype.getFilter = function() {
-    return this._filter;
-};
-
-/**
- * Set the filter object this timeline set is filtered on
- * (passed to the server when paginating via /messages).
- * @param {Filter} filter the filter for this timelineSet
- */
-EventTimelineSet.prototype.setFilter = function(filter) {
-    this._filter = filter;
-};
-
-/**
- * Get the list of pending sent events for this timelineSet's room, filtered
- * by the timelineSet's filter if appropriate.
- *
- * @return {module:models/event.MatrixEvent[]} A list of the sent events
- * waiting for remote echo.
- *
- * @throws If <code>opts.pendingEventOrdering</code> was not 'detached'
- */
-EventTimelineSet.prototype.getPendingEvents = function() {
-    if (!this.room) {
-        return [];
-    }
-
-    if (this._filter) {
-        return this._filter.filterRoomTimeline(this.room.getPendingEvents());
-    } else {
-        return this.room.getPendingEvents();
-    }
-};
-
-/**
- * Get the live timeline for this room.
- *
- * @return {module:models/event-timeline~EventTimeline} live timeline
- */
-EventTimelineSet.prototype.getLiveTimeline = function() {
-    return this._liveTimeline;
-};
-
-/**
- * Return the timeline (if any) this event is in.
- * @param {String} eventId the eventId being sought
- * @return {module:models/event-timeline~EventTimeline} timeline
- */
-EventTimelineSet.prototype.eventIdToTimeline = function(eventId) {
-    return this._eventIdToTimeline[eventId];
-};
-
-/**
- * Track a new event as if it were in the same timeline as an old event,
- * replacing it.
- * @param {String} oldEventId  event ID of the original event
- * @param {String} newEventId  event ID of the replacement event
- */
-EventTimelineSet.prototype.replaceEventId = function(oldEventId, newEventId) {
-    const existingTimeline = this._eventIdToTimeline[oldEventId];
-    if (existingTimeline) {
-        delete this._eventIdToTimeline[oldEventId];
-        this._eventIdToTimeline[newEventId] = existingTimeline;
-    }
-};
-
-/**
- * Reset the live timeline, and start a new one.
- *
- * <p>This is used when /sync returns a 'limited' timeline.
- *
- * @param {string=} backPaginationToken   token for back-paginating the new timeline
- * @param {string=} forwardPaginationToken token for forward-paginating the old live timeline,
- * if absent or null, all timelines are reset.
- *
- * @fires module:client~MatrixClient#event:"Room.timelineReset"
- */
-EventTimelineSet.prototype.resetLiveTimeline = function(
-    backPaginationToken, forwardPaginationToken,
-) {
-    // Each EventTimeline has RoomState objects tracking the state at the start
-    // and end of that timeline. The copies at the end of the live timeline are
-    // special because they will have listeners attached to monitor changes to
-    // the current room state, so we move this RoomState from the end of the
-    // current live timeline to the end of the new one and, if necessary,
-    // replace it with a newly created one. We also make a copy for the start
-    // of the new timeline.
-
-    // if timeline support is disabled, forget about the old timelines
-    const resetAllTimelines = !this._timelineSupport || !forwardPaginationToken;
-
-    const oldTimeline = this._liveTimeline;
-    const newTimeline = resetAllTimelines ?
-        oldTimeline.forkLive(EventTimeline.FORWARDS) :
-        oldTimeline.fork(EventTimeline.FORWARDS);
-
-    if (resetAllTimelines) {
-        this._timelines = [newTimeline];
-        this._eventIdToTimeline = {};
-    } else {
-        this._timelines.push(newTimeline);
-    }
-
-    if (forwardPaginationToken) {
-        // Now set the forward pagination token on the old live timeline
-        // so it can be forward-paginated.
-        oldTimeline.setPaginationToken(
-            forwardPaginationToken, EventTimeline.FORWARDS,
-        );
-    }
-
-    // make sure we set the pagination token before firing timelineReset,
-    // otherwise clients which start back-paginating will fail, and then get
-    // stuck without realising that they *can* back-paginate.
-    newTimeline.setPaginationToken(backPaginationToken, EventTimeline.BACKWARDS);
-
-    // Now we can swap the live timeline to the new one.
-    this._liveTimeline = newTimeline;
-    this.emit("Room.timelineReset", this.room, this, resetAllTimelines);
-};
-
-/**
- * Get the timeline which contains the given event, if any
- *
- * @param {string} eventId  event ID to look for
- * @return {?module:models/event-timeline~EventTimeline} timeline containing
- * the given event, or null if unknown
- */
-EventTimelineSet.prototype.getTimelineForEvent = function(eventId) {
-    const res = this._eventIdToTimeline[eventId];
-    return (res === undefined) ? null : res;
-};
-
-/**
- * Get an event which is stored in our timelines
- *
- * @param {string} eventId  event ID to look for
- * @return {?module:models/event~MatrixEvent} the given event, or undefined if unknown
- */
-EventTimelineSet.prototype.findEventById = function(eventId) {
-    const tl = this.getTimelineForEvent(eventId);
-    if (!tl) {
-        return undefined;
-    }
-    return tl.getEvents().find(function(ev) {
-        return ev.getId() == eventId;
-    });
-};
-
-/**
- * Add a new timeline to this timeline list
- *
- * @return {module:models/event-timeline~EventTimeline} newly-created timeline
- */
-EventTimelineSet.prototype.addTimeline = function() {
-    if (!this._timelineSupport) {
-        throw new Error("timeline support is disabled. Set the 'timelineSupport'" +
-                        " parameter to true when creating MatrixClient to enable" +
-                        " it.");
-    }
-
-    const timeline = new EventTimeline(this);
-    this._timelines.push(timeline);
-    return timeline;
-};
-
-/**
- * Add events to a timeline
- *
- * <p>Will fire "Room.timeline" for each event added.
- *
- * @param {MatrixEvent[]} events A list of events to add.
- *
- * @param {boolean} toStartOfTimeline   True to add these events to the start
- * (oldest) instead of the end (newest) of the timeline. If true, the oldest
- * event will be the <b>last</b> element of 'events'.
- *
- * @param {module:models/event-timeline~EventTimeline} timeline   timeline to
- *    add events to.
- *
- * @param {string=} paginationToken   token for the next batch of events
- *
- * @fires module:client~MatrixClient#event:"Room.timeline"
- *
- */
-EventTimelineSet.prototype.addEventsToTimeline = function(events, toStartOfTimeline,
-                                              timeline, paginationToken) {
-    if (!timeline) {
-        throw new Error(
-            "'timeline' not specified for EventTimelineSet.addEventsToTimeline",
-        );
-    }
-
-    if (!toStartOfTimeline && timeline == this._liveTimeline) {
-        throw new Error(
-            "EventTimelineSet.addEventsToTimeline cannot be used for adding events to " +
-            "the live timeline - use Room.addLiveEvents instead",
-        );
-    }
-
-    if (this._filter) {
-        events = this._filter.filterRoomTimeline(events);
-        if (!events.length) {
-            return;
-        }
-    }
-
-    const direction = toStartOfTimeline ? EventTimeline.BACKWARDS :
-        EventTimeline.FORWARDS;
-    const inverseDirection = toStartOfTimeline ? EventTimeline.FORWARDS :
-        EventTimeline.BACKWARDS;
-
-    // Adding events to timelines can be quite complicated. The following
-    // illustrates some of the corner-cases.
-    //
-    // Let's say we start by knowing about four timelines. timeline3 and
-    // timeline4 are neighbours:
-    //
-    //    timeline1    timeline2    timeline3    timeline4
-    //      [M]          [P]          [S] <------> [T]
-    //
-    // Now we paginate timeline1, and get the following events from the server:
-    // [M, N, P, R, S, T, U].
-    //
-    // 1. First, we ignore event M, since we already know about it.
-    //
-    // 2. Next, we append N to timeline 1.
-    //
-    // 3. Next, we don't add event P, since we already know about it,
-    //    but we do link together the timelines. We now have:
-    //
-    //    timeline1    timeline2    timeline3    timeline4
-    //      [M, N] <---> [P]          [S] <------> [T]
-    //
-    // 4. Now we add event R to timeline2:
-    //
-    //    timeline1    timeline2    timeline3    timeline4
-    //      [M, N] <---> [P, R]       [S] <------> [T]
-    //
-    //    Note that we have switched the timeline we are working on from
-    //    timeline1 to timeline2.
-    //
-    // 5. We ignore event S, but again join the timelines:
-    //
-    //    timeline1    timeline2    timeline3    timeline4
-    //      [M, N] <---> [P, R] <---> [S] <------> [T]
-    //
-    // 6. We ignore event T, and the timelines are already joined, so there
-    //    is nothing to do.
-    //
-    // 7. Finally, we add event U to timeline4:
-    //
-    //    timeline1    timeline2    timeline3    timeline4
-    //      [M, N] <---> [P, R] <---> [S] <------> [T, U]
-    //
-    // The important thing to note in the above is what happened when we
-    // already knew about a given event:
-    //
-    //   - if it was appropriate, we joined up the timelines (steps 3, 5).
-    //   - in any case, we started adding further events to the timeline which
-    //       contained the event we knew about (steps 3, 5, 6).
-    //
-    //
-    // So much for adding events to the timeline. But what do we want to do
-    // with the pagination token?
-    //
-    // In the case above, we will be given a pagination token which tells us how to
-    // get events beyond 'U' - in this case, it makes sense to store this
-    // against timeline4. But what if timeline4 already had 'U' and beyond? in
-    // that case, our best bet is to throw away the pagination token we were
-    // given and stick with whatever token timeline4 had previously. In short,
-    // we want to only store the pagination token if the last event we receive
-    // is one we didn't previously know about.
-    //
-    // We make an exception for this if it turns out that we already knew about
-    // *all* of the events, and we weren't able to join up any timelines. When
-    // that happens, it means our existing pagination token is faulty, since it
-    // is only telling us what we already know. Rather than repeatedly
-    // paginating with the same token, we might as well use the new pagination
-    // token in the hope that we eventually work our way out of the mess.
-
-    let didUpdate = false;
-    let lastEventWasNew = false;
-    for (let i = 0; i < events.length; i++) {
-        const event = events[i];
-        const eventId = event.getId();
-
-        const existingTimeline = this._eventIdToTimeline[eventId];
-
-        if (!existingTimeline) {
-            // we don't know about this event yet. Just add it to the timeline.
-            this.addEventToTimeline(event, timeline, toStartOfTimeline);
-            lastEventWasNew = true;
-            didUpdate = true;
-            continue;
-        }
-
-        lastEventWasNew = false;
-
-        if (existingTimeline == timeline) {
-            debuglog("Event " + eventId + " already in timeline " + timeline);
-            continue;
-        }
-
-        const neighbour = timeline.getNeighbouringTimeline(direction);
-        if (neighbour) {
-            // this timeline already has a neighbour in the relevant direction;
-            // let's assume the timelines are already correctly linked up, and
-            // skip over to it.
-            //
-            // there's probably some edge-case here where we end up with an
-            // event which is in a timeline a way down the chain, and there is
-            // a break in the chain somewhere. But I can't really imagine how
-            // that would happen, so I'm going to ignore it for now.
-            //
-            if (existingTimeline == neighbour) {
-                debuglog("Event " + eventId + " in neighbouring timeline - " +
-                            "switching to " + existingTimeline);
-            } else {
-                debuglog("Event " + eventId + " already in a different " +
-                            "timeline " + existingTimeline);
-            }
-            timeline = existingTimeline;
-            continue;
-        }
-
-        // time to join the timelines.
-        logger.info("Already have timeline for " + eventId +
-                     " - joining timeline " + timeline + " to " +
-                     existingTimeline);
-
-        // Variables to keep the line length limited below.
-        const existingIsLive = existingTimeline === this._liveTimeline;
-        const timelineIsLive = timeline === this._liveTimeline;
-
-        const backwardsIsLive = direction === EventTimeline.BACKWARDS && existingIsLive;
-        const forwardsIsLive = direction === EventTimeline.FORWARDS && timelineIsLive;
-
-        if (backwardsIsLive || forwardsIsLive) {
-            // The live timeline should never be spliced into a non-live position.
-            // We use independent logging to better discover the problem at a glance.
-            if (backwardsIsLive) {
-                logger.warn(
-                    "Refusing to set a preceding existingTimeLine on our " +
-                    "timeline as the existingTimeLine is live (" + existingTimeline + ")",
-                );
-            }
-            if (forwardsIsLive) {
-                logger.warn(
-                    "Refusing to set our preceding timeline on a existingTimeLine " +
-                    "as our timeline is live (" + timeline + ")",
-                );
-            }
-            continue; // abort splicing - try next event
-        }
-
-        timeline.setNeighbouringTimeline(existingTimeline, direction);
-        existingTimeline.setNeighbouringTimeline(timeline, inverseDirection);
-
-        timeline = existingTimeline;
-        didUpdate = true;
-    }
-
-    // see above - if the last event was new to us, or if we didn't find any
-    // new information, we update the pagination token for whatever
-    // timeline we ended up on.
-    if (lastEventWasNew || !didUpdate) {
-        if (direction === EventTimeline.FORWARDS && timeline === this._liveTimeline) {
-            logger.warn({ lastEventWasNew, didUpdate }); // for debugging
-            logger.warn(
-                `Refusing to set forwards pagination token of live timeline ` +
-                `${timeline} to ${paginationToken}`,
-            );
-            return;
-        }
-        timeline.setPaginationToken(paginationToken, direction);
-    }
-};
-
-/**
- * Add an event to the end of this live timeline.
- *
- * @param {MatrixEvent} event Event to be added
- * @param {string?} duplicateStrategy 'ignore' or 'replace'
- * @param {boolean} fromCache whether the sync response came from cache
- */
-EventTimelineSet.prototype.addLiveEvent = function(event, duplicateStrategy, fromCache) {
-    if (this._filter) {
-        const events = this._filter.filterRoomTimeline([event]);
-        if (!events.length) {
-            return;
-        }
-    }
-
-    const timeline = this._eventIdToTimeline[event.getId()];
-    if (timeline) {
-        if (duplicateStrategy === "replace") {
-            debuglog("EventTimelineSet.addLiveEvent: replacing duplicate event " +
-                     event.getId());
-            const tlEvents = timeline.getEvents();
-            for (let j = 0; j < tlEvents.length; j++) {
-                if (tlEvents[j].getId() === event.getId()) {
-                    // still need to set the right metadata on this event
-                    EventTimeline.setEventMetadata(
-                        event,
-                        timeline.getState(EventTimeline.FORWARDS),
-                        false,
-                    );
-
-                    if (!tlEvents[j].encryptedType) {
-                        tlEvents[j] = event;
-                    }
-
-                    // XXX: we need to fire an event when this happens.
-                    break;
-                }
-            }
-        } else {
-            debuglog("EventTimelineSet.addLiveEvent: ignoring duplicate event " +
-                     event.getId());
-        }
-        return;
-    }
-
-    this.addEventToTimeline(event, this._liveTimeline, false, fromCache);
-};
-
-/**
- * Add event to the given timeline, and emit Room.timeline. Assumes
- * we have already checked we don't know about this event.
- *
- * Will fire "Room.timeline" for each event added.
- *
- * @param {MatrixEvent} event
- * @param {EventTimeline} timeline
- * @param {boolean} toStartOfTimeline
- * @param {boolean} fromCache whether the sync response came from cache
- *
- * @fires module:client~MatrixClient#event:"Room.timeline"
- */
-EventTimelineSet.prototype.addEventToTimeline = function(event, timeline,
-                                                         toStartOfTimeline, fromCache) {
-    const eventId = event.getId();
-    timeline.addEvent(event, toStartOfTimeline);
-    this._eventIdToTimeline[eventId] = timeline;
-
-    this.setRelationsTarget(event);
-    this.aggregateRelations(event);
-
-    const data = {
-        timeline: timeline,
-        liveEvent: !toStartOfTimeline && timeline == this._liveTimeline && !fromCache,
-    };
-    this.emit("Room.timeline", event, this.room,
-              Boolean(toStartOfTimeline), false, data);
-};
-
-/**
- * Replaces event with ID oldEventId with one with newEventId, if oldEventId is
- * recognised.  Otherwise, add to the live timeline.  Used to handle remote echos.
- *
- * @param {MatrixEvent} localEvent     the new event to be added to the timeline
- * @param {String} oldEventId          the ID of the original event
- * @param {boolean} newEventId         the ID of the replacement event
- *
- * @fires module:client~MatrixClient#event:"Room.timeline"
- */
-EventTimelineSet.prototype.handleRemoteEcho = function(localEvent, oldEventId,
-                                                        newEventId) {
-    // XXX: why don't we infer newEventId from localEvent?
-    const existingTimeline = this._eventIdToTimeline[oldEventId];
-    if (existingTimeline) {
-        delete this._eventIdToTimeline[oldEventId];
-        this._eventIdToTimeline[newEventId] = existingTimeline;
-    } else {
-        if (this._filter) {
-            if (this._filter.filterRoomTimeline([localEvent]).length) {
-                this.addEventToTimeline(localEvent, this._liveTimeline, false);
-            }
-        } else {
-            this.addEventToTimeline(localEvent, this._liveTimeline, false);
-        }
-    }
-};
-
-/**
- * Removes a single event from this room.
- *
- * @param {String} eventId  The id of the event to remove
- *
- * @return {?MatrixEvent} the removed event, or null if the event was not found
- * in this room.
- */
-EventTimelineSet.prototype.removeEvent = function(eventId) {
-    const timeline = this._eventIdToTimeline[eventId];
-    if (!timeline) {
-        return null;
-    }
-
-    const removed = timeline.removeEvent(eventId);
-    if (removed) {
-        delete this._eventIdToTimeline[eventId];
-        const data = {
-            timeline: timeline,
-        };
-        this.emit("Room.timeline", removed, this.room, undefined, true, data);
-    }
-    return removed;
-};
-
-/**
- * Determine where two events appear in the timeline relative to one another
- *
- * @param {string} eventId1   The id of the first event
- * @param {string} eventId2   The id of the second event
-
- * @return {?number} a number less than zero if eventId1 precedes eventId2, and
- *    greater than zero if eventId1 succeeds eventId2. zero if they are the
- *    same event; null if we can't tell (either because we don't know about one
- *    of the events, or because they are in separate timelines which don't join
- *    up).
- */
-EventTimelineSet.prototype.compareEventOrdering = function(eventId1, eventId2) {
-    if (eventId1 == eventId2) {
-        // optimise this case
-        return 0;
-    }
-
-    const timeline1 = this._eventIdToTimeline[eventId1];
-    const timeline2 = this._eventIdToTimeline[eventId2];
-
-    if (timeline1 === undefined) {
-        return null;
-    }
-    if (timeline2 === undefined) {
-        return null;
-    }
-
-    if (timeline1 === timeline2) {
-        // both events are in the same timeline - figure out their
-        // relative indices
-        let idx1;
-        let idx2;
-        const events = timeline1.getEvents();
-        for (let idx = 0; idx < events.length &&
-             (idx1 === undefined || idx2 === undefined); idx++) {
-            const evId = events[idx].getId();
-            if (evId == eventId1) {
-                idx1 = idx;
-            }
-            if (evId == eventId2) {
-                idx2 = idx;
-            }
-        }
-        return idx1 - idx2;
-    }
-
-    // the events are in different timelines. Iterate through the
-    // linkedlist to see which comes first.
-
-    // first work forwards from timeline1
-    let tl = timeline1;
-    while (tl) {
-        if (tl === timeline2) {
-            // timeline1 is before timeline2
-            return -1;
-        }
-        tl = tl.getNeighbouringTimeline(EventTimeline.FORWARDS);
-    }
-
-    // now try backwards from timeline1
-    tl = timeline1;
-    while (tl) {
-        if (tl === timeline2) {
-            // timeline2 is before timeline1
-            return 1;
-        }
-        tl = tl.getNeighbouringTimeline(EventTimeline.BACKWARDS);
-    }
-
-    // the timelines are not contiguous.
-    return null;
-};
-
-/**
- * Get a collection of relations to a given event in this timeline set.
- *
- * @param {String} eventId
- * The ID of the event that you'd like to access relation events for.
- * For example, with annotations, this would be the ID of the event being annotated.
- * @param {String} relationType
- * The type of relation involved, such as "m.annotation", "m.reference", "m.replace", etc.
- * @param {String} eventType
- * The relation event's type, such as "m.reaction", etc.
- * @throws If <code>eventId</code>, <code>relationType</code> or <code>eventType</code>
- * are not valid.
- *
- * @returns {?Relations}
- * A container for relation events or undefined if there are no relation events for
- * the relationType.
- */
-EventTimelineSet.prototype.getRelationsForEvent = function(
-    eventId, relationType, eventType,
-) {
-    if (!this._unstableClientRelationAggregation) {
-        throw new Error("Client-side relation aggregation is disabled");
-    }
-
-    if (!eventId || !relationType || !eventType) {
-        throw new Error("Invalid arguments for `getRelationsForEvent`");
-    }
-
-    // debuglog("Getting relations for: ", eventId, relationType, eventType);
-
-    const relationsForEvent = this._relations[eventId] || {};
-    const relationsWithRelType = relationsForEvent[relationType] || {};
-    return relationsWithRelType[eventType];
-};
-
-/**
- * Set an event as the target event if any Relations exist for it already
- *
- * @param {MatrixEvent} event
- * The event to check as relation target.
- */
-EventTimelineSet.prototype.setRelationsTarget = function(event) {
-    if (!this._unstableClientRelationAggregation) {
-        return;
-    }
-
-    const relationsForEvent = this._relations[event.getId()];
-    if (!relationsForEvent) {
-        return;
-    }
-
-    for (const relationsWithRelType of Object.values(relationsForEvent)) {
-        for (const relationsWithEventType of Object.values(relationsWithRelType)) {
-            relationsWithEventType.setTargetEvent(event);
-        }
-    }
-};
-
-/**
- * Add relation events to the relevant relation collection.
- *
- * @param {MatrixEvent} event
- * The new relation event to be aggregated.
- */
-EventTimelineSet.prototype.aggregateRelations = function(event) {
-    if (!this._unstableClientRelationAggregation) {
-        return;
-    }
-
-    if (event.isRedacted() || event.status === EventStatus.CANCELLED) {
-        return;
-    }
-
-    // If the event is currently encrypted, wait until it has been decrypted.
-    if (event.isBeingDecrypted() || event.shouldAttemptDecryption()) {
-        event.once("Event.decrypted", () => {
-            this.aggregateRelations(event);
-        });
-        return;
-    }
-
-    const relation = event.getRelation();
-    if (!relation) {
-        return;
-    }
-
-    const relatesToEventId = relation.event_id;
-    const relationType = relation.rel_type;
-    const eventType = event.getType();
-
-    // debuglog("Aggregating relation: ", event.getId(), eventType, relation);
-
-    let relationsForEvent = this._relations[relatesToEventId];
-    if (!relationsForEvent) {
-        relationsForEvent = this._relations[relatesToEventId] = {};
-    }
-    let relationsWithRelType = relationsForEvent[relationType];
-    if (!relationsWithRelType) {
-        relationsWithRelType = relationsForEvent[relationType] = {};
-    }
-    let relationsWithEventType = relationsWithRelType[eventType];
-
-    let relatesToEvent;
-    if (!relationsWithEventType) {
-        relationsWithEventType = relationsWithRelType[eventType] = new Relations(
-            relationType,
-            eventType,
-            this.room,
-        );
-        relatesToEvent = this.findEventById(relatesToEventId) || this.room.getPendingEvent(relatesToEventId);
-        if (relatesToEvent) {
-            relationsWithEventType.setTargetEvent(relatesToEvent);
-        }
-    }
-
-    relationsWithEventType.addEvent(event);
-};
-
-/**
- * Fires whenever the timeline in a room is updated.
- * @event module:client~MatrixClient#"Room.timeline"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {?Room} room The room, if any, whose timeline was updated.
- * @param {boolean} toStartOfTimeline True if this event was added to the start
- * @param {boolean} removed True if this event has just been removed from the timeline
- * (beginning; oldest) of the timeline e.g. due to pagination.
- *
- * @param {object} data  more data about the event
- *
- * @param {module:models/event-timeline.EventTimeline} data.timeline the timeline the
- * event was added to/removed from
- *
- * @param {boolean} data.liveEvent true if the event was a real-time event
- * added to the end of the live timeline
- *
- * @example
- * matrixClient.on("Room.timeline",
- *                 function(event, room, toStartOfTimeline, removed, data) {
- *   if (!toStartOfTimeline && data.liveEvent) {
- *     var messageToAppend = room.timeline.[room.timeline.length - 1];
- *   }
- * });
- */
-
-/**
- * Fires whenever the live timeline in a room is reset.
- *
- * When we get a 'limited' sync (for example, after a network outage), we reset
- * the live timeline to be empty before adding the recent events to the new
- * timeline. This event is fired after the timeline is reset, and before the
- * new events are added.
- *
- * @event module:client~MatrixClient#"Room.timelineReset"
- * @param {Room} room The room whose live timeline was reset, if any
- * @param {EventTimelineSet} timelineSet timelineSet room whose live timeline was reset
- * @param {boolean} resetAllTimelines True if all timelines were reset.
- */

src/models/event-timeline-set.ts

@@ -0,0 +1,874 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module models/event-timeline-set
+ */
+
+import { EventEmitter } from "events";
+
+import { EventTimeline } from "./event-timeline";
+import { EventStatus, MatrixEvent } from "./event";
+import { logger } from '../logger';
+import { Relations } from './relations';
+import { Room } from "./room";
+import { Filter } from "../filter";
+import { EventType, RelationType } from "../@types/event";
+
+// var DEBUG = false;
+const DEBUG = true;
+
+let debuglog;
+if (DEBUG) {
+    // using bind means that we get to keep useful line numbers in the console
+    debuglog = logger.log.bind(logger);
+} else {
+    debuglog = function() {};
+}
+
+interface IOpts {
+    timelineSupport?: boolean;
+    filter?: Filter;
+    unstableClientRelationAggregation?: boolean;
+}
+
+export class EventTimelineSet extends EventEmitter {
+    private readonly timelineSupport: boolean;
+    private unstableClientRelationAggregation: boolean;
+    private liveTimeline: EventTimeline;
+    private timelines: EventTimeline[];
+    private _eventIdToTimeline: Record<string, EventTimeline>;
+    private filter?: Filter;
+    private relations: Record<string, Record<string, Record<RelationType, Relations>>>;
+
+    /**
+     * Construct a set of EventTimeline objects, typically on behalf of a given
+     * room.  A room may have multiple EventTimelineSets for different levels
+     * of filtering.  The global notification list is also an EventTimelineSet, but
+     * lacks a room.
+     *
+     * <p>This is an ordered sequence of timelines, which may or may not
+     * be continuous. Each timeline lists a series of events, as well as tracking
+     * the room state at the start and the end of the timeline (if appropriate).
+     * It also tracks forward and backward pagination tokens, as well as containing
+     * links to the next timeline in the sequence.
+     *
+     * <p>There is one special timeline - the 'live' timeline, which represents the
+     * timeline to which events are being added in real-time as they are received
+     * from the /sync API. Note that you should not retain references to this
+     * timeline - even if it is the current timeline right now, it may not remain
+     * so if the server gives us a timeline gap in /sync.
+     *
+     * <p>In order that we can find events from their ids later, we also maintain a
+     * map from event_id to timeline and index.
+     *
+     * @constructor
+     * @param {?Room} room
+     * Room for this timelineSet. May be null for non-room cases, such as the
+     * notification timeline.
+     * @param {Object} opts Options inherited from Room.
+     *
+     * @param {boolean} [opts.timelineSupport = false]
+     * Set to true to enable improved timeline support.
+     * @param {Object} [opts.filter = null]
+     * The filter object, if any, for this timelineSet.
+     * @param {boolean} [opts.unstableClientRelationAggregation = false]
+     * Optional. Set to true to enable client-side aggregation of event relations
+     * via `getRelationsForEvent`.
+     * This feature is currently unstable and the API may change without notice.
+     */
+    constructor(public readonly room: Room, opts: IOpts) {
+        super();
+
+        this.timelineSupport = Boolean(opts.timelineSupport);
+        this.liveTimeline = new EventTimeline(this);
+        this.unstableClientRelationAggregation = !!opts.unstableClientRelationAggregation;
+
+        // just a list - *not* ordered.
+        this.timelines = [this.liveTimeline];
+        this._eventIdToTimeline = {};
+
+        this.filter = opts.filter;
+
+        if (this.unstableClientRelationAggregation) {
+            // A tree of objects to access a set of relations for an event, as in:
+            // this.relations[relatesToEventId][relationType][relationEventType]
+            this.relations = {};
+        }
+    }
+
+    /**
+     * Get all the timelines in this set
+     * @return {module:models/event-timeline~EventTimeline[]} the timelines in this set
+     */
+    public getTimelines(): EventTimeline[] {
+        return this.timelines;
+    }
+
+    /**
+     * Get the filter object this timeline set is filtered on, if any
+     * @return {?Filter} the optional filter for this timelineSet
+     */
+    public getFilter(): Filter | undefined {
+        return this.filter;
+    }
+
+    /**
+     * Set the filter object this timeline set is filtered on
+     * (passed to the server when paginating via /messages).
+     * @param {Filter} filter the filter for this timelineSet
+     */
+    public setFilter(filter?: Filter): void {
+        this.filter = filter;
+    }
+
+    /**
+     * Get the list of pending sent events for this timelineSet's room, filtered
+     * by the timelineSet's filter if appropriate.
+     *
+     * @return {module:models/event.MatrixEvent[]} A list of the sent events
+     * waiting for remote echo.
+     *
+     * @throws If <code>opts.pendingEventOrdering</code> was not 'detached'
+     */
+    public getPendingEvents(): MatrixEvent[] {
+        if (!this.room) {
+            return [];
+        }
+
+        if (this.filter) {
+            return this.filter.filterRoomTimeline(this.room.getPendingEvents());
+        } else {
+            return this.room.getPendingEvents();
+        }
+    }
+
+    /**
+     * Get the live timeline for this room.
+     *
+     * @return {module:models/event-timeline~EventTimeline} live timeline
+     */
+    public getLiveTimeline(): EventTimeline {
+        return this.liveTimeline;
+    }
+
+    /**
+     * Return the timeline (if any) this event is in.
+     * @param {String} eventId the eventId being sought
+     * @return {module:models/event-timeline~EventTimeline} timeline
+     */
+    public eventIdToTimeline(eventId: string): EventTimeline {
+        return this._eventIdToTimeline[eventId];
+    }
+
+    /**
+     * Track a new event as if it were in the same timeline as an old event,
+     * replacing it.
+     * @param {String} oldEventId  event ID of the original event
+     * @param {String} newEventId  event ID of the replacement event
+     */
+    public replaceEventId(oldEventId: string, newEventId: string): void {
+        const existingTimeline = this._eventIdToTimeline[oldEventId];
+        if (existingTimeline) {
+            delete this._eventIdToTimeline[oldEventId];
+            this._eventIdToTimeline[newEventId] = existingTimeline;
+        }
+    }
+
+    /**
+     * Reset the live timeline, and start a new one.
+     *
+     * <p>This is used when /sync returns a 'limited' timeline.
+     *
+     * @param {string=} backPaginationToken   token for back-paginating the new timeline
+     * @param {string=} forwardPaginationToken token for forward-paginating the old live timeline,
+     * if absent or null, all timelines are reset.
+     *
+     * @fires module:client~MatrixClient#event:"Room.timelineReset"
+     */
+    public resetLiveTimeline(backPaginationToken: string, forwardPaginationToken?: string): void {
+        // Each EventTimeline has RoomState objects tracking the state at the start
+        // and end of that timeline. The copies at the end of the live timeline are
+        // special because they will have listeners attached to monitor changes to
+        // the current room state, so we move this RoomState from the end of the
+        // current live timeline to the end of the new one and, if necessary,
+        // replace it with a newly created one. We also make a copy for the start
+        // of the new timeline.
+
+        // if timeline support is disabled, forget about the old timelines
+        const resetAllTimelines = !this.timelineSupport || !forwardPaginationToken;
+
+        const oldTimeline = this.liveTimeline;
+        const newTimeline = resetAllTimelines ?
+            oldTimeline.forkLive(EventTimeline.FORWARDS) :
+            oldTimeline.fork(EventTimeline.FORWARDS);
+
+        if (resetAllTimelines) {
+            this.timelines = [newTimeline];
+            this._eventIdToTimeline = {};
+        } else {
+            this.timelines.push(newTimeline);
+        }
+
+        if (forwardPaginationToken) {
+            // Now set the forward pagination token on the old live timeline
+            // so it can be forward-paginated.
+            oldTimeline.setPaginationToken(
+                forwardPaginationToken, EventTimeline.FORWARDS,
+            );
+        }
+
+        // make sure we set the pagination token before firing timelineReset,
+        // otherwise clients which start back-paginating will fail, and then get
+        // stuck without realising that they *can* back-paginate.
+        newTimeline.setPaginationToken(backPaginationToken, EventTimeline.BACKWARDS);
+
+        // Now we can swap the live timeline to the new one.
+        this.liveTimeline = newTimeline;
+        this.emit("Room.timelineReset", this.room, this, resetAllTimelines);
+    }
+
+    /**
+     * Get the timeline which contains the given event, if any
+     *
+     * @param {string} eventId  event ID to look for
+     * @return {?module:models/event-timeline~EventTimeline} timeline containing
+     * the given event, or null if unknown
+     */
+    public getTimelineForEvent(eventId: string): EventTimeline | null {
+        const res = this._eventIdToTimeline[eventId];
+        return (res === undefined) ? null : res;
+    }
+
+    /**
+     * Get an event which is stored in our timelines
+     *
+     * @param {string} eventId  event ID to look for
+     * @return {?module:models/event~MatrixEvent} the given event, or undefined if unknown
+     */
+    public findEventById(eventId: string): MatrixEvent | undefined {
+        const tl = this.getTimelineForEvent(eventId);
+        if (!tl) {
+            return undefined;
+        }
+        return tl.getEvents().find(function(ev) {
+            return ev.getId() == eventId;
+        });
+    }
+
+    /**
+     * Add a new timeline to this timeline list
+     *
+     * @return {module:models/event-timeline~EventTimeline} newly-created timeline
+     */
+    public addTimeline(): EventTimeline {
+        if (!this.timelineSupport) {
+            throw new Error("timeline support is disabled. Set the 'timelineSupport'" +
+                " parameter to true when creating MatrixClient to enable" +
+                " it.");
+        }
+
+        const timeline = new EventTimeline(this);
+        this.timelines.push(timeline);
+        return timeline;
+    }
+
+    /**
+     * Add events to a timeline
+     *
+     * <p>Will fire "Room.timeline" for each event added.
+     *
+     * @param {MatrixEvent[]} events A list of events to add.
+     *
+     * @param {boolean} toStartOfTimeline   True to add these events to the start
+     * (oldest) instead of the end (newest) of the timeline. If true, the oldest
+     * event will be the <b>last</b> element of 'events'.
+     *
+     * @param {module:models/event-timeline~EventTimeline} timeline   timeline to
+     *    add events to.
+     *
+     * @param {string=} paginationToken   token for the next batch of events
+     *
+     * @fires module:client~MatrixClient#event:"Room.timeline"
+     *
+     */
+    public addEventsToTimeline(
+        events: MatrixEvent[],
+        toStartOfTimeline: boolean,
+        timeline: EventTimeline,
+        paginationToken: string,
+    ): void {
+        if (!timeline) {
+            throw new Error(
+                "'timeline' not specified for EventTimelineSet.addEventsToTimeline",
+            );
+        }
+
+        if (!toStartOfTimeline && timeline == this.liveTimeline) {
+            throw new Error(
+                "EventTimelineSet.addEventsToTimeline cannot be used for adding events to " +
+                "the live timeline - use Room.addLiveEvents instead",
+            );
+        }
+
+        if (this.filter) {
+            events = this.filter.filterRoomTimeline(events);
+            if (!events.length) {
+                return;
+            }
+        }
+
+        const direction = toStartOfTimeline ? EventTimeline.BACKWARDS :
+            EventTimeline.FORWARDS;
+        const inverseDirection = toStartOfTimeline ? EventTimeline.FORWARDS :
+            EventTimeline.BACKWARDS;
+
+        // Adding events to timelines can be quite complicated. The following
+        // illustrates some of the corner-cases.
+        //
+        // Let's say we start by knowing about four timelines. timeline3 and
+        // timeline4 are neighbours:
+        //
+        //    timeline1    timeline2    timeline3    timeline4
+        //      [M]          [P]          [S] <------> [T]
+        //
+        // Now we paginate timeline1, and get the following events from the server:
+        // [M, N, P, R, S, T, U].
+        //
+        // 1. First, we ignore event M, since we already know about it.
+        //
+        // 2. Next, we append N to timeline 1.
+        //
+        // 3. Next, we don't add event P, since we already know about it,
+        //    but we do link together the timelines. We now have:
+        //
+        //    timeline1    timeline2    timeline3    timeline4
+        //      [M, N] <---> [P]          [S] <------> [T]
+        //
+        // 4. Now we add event R to timeline2:
+        //
+        //    timeline1    timeline2    timeline3    timeline4
+        //      [M, N] <---> [P, R]       [S] <------> [T]
+        //
+        //    Note that we have switched the timeline we are working on from
+        //    timeline1 to timeline2.
+        //
+        // 5. We ignore event S, but again join the timelines:
+        //
+        //    timeline1    timeline2    timeline3    timeline4
+        //      [M, N] <---> [P, R] <---> [S] <------> [T]
+        //
+        // 6. We ignore event T, and the timelines are already joined, so there
+        //    is nothing to do.
+        //
+        // 7. Finally, we add event U to timeline4:
+        //
+        //    timeline1    timeline2    timeline3    timeline4
+        //      [M, N] <---> [P, R] <---> [S] <------> [T, U]
+        //
+        // The important thing to note in the above is what happened when we
+        // already knew about a given event:
+        //
+        //   - if it was appropriate, we joined up the timelines (steps 3, 5).
+        //   - in any case, we started adding further events to the timeline which
+        //       contained the event we knew about (steps 3, 5, 6).
+        //
+        //
+        // So much for adding events to the timeline. But what do we want to do
+        // with the pagination token?
+        //
+        // In the case above, we will be given a pagination token which tells us how to
+        // get events beyond 'U' - in this case, it makes sense to store this
+        // against timeline4. But what if timeline4 already had 'U' and beyond? in
+        // that case, our best bet is to throw away the pagination token we were
+        // given and stick with whatever token timeline4 had previously. In short,
+        // we want to only store the pagination token if the last event we receive
+        // is one we didn't previously know about.
+        //
+        // We make an exception for this if it turns out that we already knew about
+        // *all* of the events, and we weren't able to join up any timelines. When
+        // that happens, it means our existing pagination token is faulty, since it
+        // is only telling us what we already know. Rather than repeatedly
+        // paginating with the same token, we might as well use the new pagination
+        // token in the hope that we eventually work our way out of the mess.
+
+        let didUpdate = false;
+        let lastEventWasNew = false;
+        for (let i = 0; i < events.length; i++) {
+            const event = events[i];
+            const eventId = event.getId();
+
+            const existingTimeline = this._eventIdToTimeline[eventId];
+
+            if (!existingTimeline) {
+                // we don't know about this event yet. Just add it to the timeline.
+                this.addEventToTimeline(event, timeline, toStartOfTimeline);
+                lastEventWasNew = true;
+                didUpdate = true;
+                continue;
+            }
+
+            lastEventWasNew = false;
+
+            if (existingTimeline == timeline) {
+                debuglog("Event " + eventId + " already in timeline " + timeline);
+                continue;
+            }
+
+            const neighbour = timeline.getNeighbouringTimeline(direction);
+            if (neighbour) {
+                // this timeline already has a neighbour in the relevant direction;
+                // let's assume the timelines are already correctly linked up, and
+                // skip over to it.
+                //
+                // there's probably some edge-case here where we end up with an
+                // event which is in a timeline a way down the chain, and there is
+                // a break in the chain somewhere. But I can't really imagine how
+                // that would happen, so I'm going to ignore it for now.
+                //
+                if (existingTimeline == neighbour) {
+                    debuglog("Event " + eventId + " in neighbouring timeline - " +
+                        "switching to " + existingTimeline);
+                } else {
+                    debuglog("Event " + eventId + " already in a different " +
+                        "timeline " + existingTimeline);
+                }
+                timeline = existingTimeline;
+                continue;
+            }
+
+            // time to join the timelines.
+            logger.info("Already have timeline for " + eventId +
+                " - joining timeline " + timeline + " to " +
+                existingTimeline);
+
+            // Variables to keep the line length limited below.
+            const existingIsLive = existingTimeline === this.liveTimeline;
+            const timelineIsLive = timeline === this.liveTimeline;
+
+            const backwardsIsLive = direction === EventTimeline.BACKWARDS && existingIsLive;
+            const forwardsIsLive = direction === EventTimeline.FORWARDS && timelineIsLive;
+
+            if (backwardsIsLive || forwardsIsLive) {
+                // The live timeline should never be spliced into a non-live position.
+                // We use independent logging to better discover the problem at a glance.
+                if (backwardsIsLive) {
+                    logger.warn(
+                        "Refusing to set a preceding existingTimeLine on our " +
+                        "timeline as the existingTimeLine is live (" + existingTimeline + ")",
+                    );
+                }
+                if (forwardsIsLive) {
+                    logger.warn(
+                        "Refusing to set our preceding timeline on a existingTimeLine " +
+                        "as our timeline is live (" + timeline + ")",
+                    );
+                }
+                continue; // abort splicing - try next event
+            }
+
+            timeline.setNeighbouringTimeline(existingTimeline, direction);
+            existingTimeline.setNeighbouringTimeline(timeline, inverseDirection);
+
+            timeline = existingTimeline;
+            didUpdate = true;
+        }
+
+        // see above - if the last event was new to us, or if we didn't find any
+        // new information, we update the pagination token for whatever
+        // timeline we ended up on.
+        if (lastEventWasNew || !didUpdate) {
+            if (direction === EventTimeline.FORWARDS && timeline === this.liveTimeline) {
+                logger.warn({ lastEventWasNew, didUpdate }); // for debugging
+                logger.warn(
+                    `Refusing to set forwards pagination token of live timeline ` +
+                    `${timeline} to ${paginationToken}`,
+                );
+                return;
+            }
+            timeline.setPaginationToken(paginationToken, direction);
+        }
+    }
+
+    /**
+     * Add an event to the end of this live timeline.
+     *
+     * @param {MatrixEvent} event Event to be added
+     * @param {string?} duplicateStrategy 'ignore' or 'replace'
+     * @param {boolean} fromCache whether the sync response came from cache
+     */
+    public addLiveEvent(event: MatrixEvent, duplicateStrategy?: "ignore" | "replace", fromCache = false): void {
+        if (this.filter) {
+            const events = this.filter.filterRoomTimeline([event]);
+            if (!events.length) {
+                return;
+            }
+        }
+
+        const timeline = this._eventIdToTimeline[event.getId()];
+        if (timeline) {
+            if (duplicateStrategy === "replace") {
+                debuglog("EventTimelineSet.addLiveEvent: replacing duplicate event " +
+                    event.getId());
+                const tlEvents = timeline.getEvents();
+                for (let j = 0; j < tlEvents.length; j++) {
+                    if (tlEvents[j].getId() === event.getId()) {
+                        // still need to set the right metadata on this event
+                        EventTimeline.setEventMetadata(
+                            event,
+                            timeline.getState(EventTimeline.FORWARDS),
+                            false,
+                        );
+                        tlEvents[j] = event;
+
+                        // XXX: we need to fire an event when this happens.
+                        break;
+                    }
+                }
+            } else {
+                debuglog("EventTimelineSet.addLiveEvent: ignoring duplicate event " +
+                    event.getId());
+            }
+            return;
+        }
+
+        this.addEventToTimeline(event, this.liveTimeline, false, fromCache);
+    }
+
+    /**
+     * Add event to the given timeline, and emit Room.timeline. Assumes
+     * we have already checked we don't know about this event.
+     *
+     * Will fire "Room.timeline" for each event added.
+     *
+     * @param {MatrixEvent} event
+     * @param {EventTimeline} timeline
+     * @param {boolean} toStartOfTimeline
+     * @param {boolean} fromCache whether the sync response came from cache
+     *
+     * @fires module:client~MatrixClient#event:"Room.timeline"
+     */
+    public addEventToTimeline(
+        event: MatrixEvent,
+        timeline: EventTimeline,
+        toStartOfTimeline: boolean,
+        fromCache = false,
+    ) {
+        const eventId = event.getId();
+        timeline.addEvent(event, toStartOfTimeline);
+        this._eventIdToTimeline[eventId] = timeline;
+
+        this.setRelationsTarget(event);
+        this.aggregateRelations(event);
+
+        const data = {
+            timeline: timeline,
+            liveEvent: !toStartOfTimeline && timeline == this.liveTimeline && !fromCache,
+        };
+        this.emit("Room.timeline", event, this.room,
+            Boolean(toStartOfTimeline), false, data);
+    }
+
+    /**
+     * Replaces event with ID oldEventId with one with newEventId, if oldEventId is
+     * recognised.  Otherwise, add to the live timeline.  Used to handle remote echos.
+     *
+     * @param {MatrixEvent} localEvent     the new event to be added to the timeline
+     * @param {String} oldEventId          the ID of the original event
+     * @param {boolean} newEventId         the ID of the replacement event
+     *
+     * @fires module:client~MatrixClient#event:"Room.timeline"
+     */
+    public handleRemoteEcho(
+        localEvent: MatrixEvent,
+        oldEventId: string,
+        newEventId: string,
+    ): void {
+        // XXX: why don't we infer newEventId from localEvent?
+        const existingTimeline = this._eventIdToTimeline[oldEventId];
+        if (existingTimeline) {
+            delete this._eventIdToTimeline[oldEventId];
+            this._eventIdToTimeline[newEventId] = existingTimeline;
+        } else {
+            if (this.filter) {
+                if (this.filter.filterRoomTimeline([localEvent]).length) {
+                    this.addEventToTimeline(localEvent, this.liveTimeline, false);
+                }
+            } else {
+                this.addEventToTimeline(localEvent, this.liveTimeline, false);
+            }
+        }
+    }
+
+    /**
+     * Removes a single event from this room.
+     *
+     * @param {String} eventId  The id of the event to remove
+     *
+     * @return {?MatrixEvent} the removed event, or null if the event was not found
+     * in this room.
+     */
+    public removeEvent(eventId: string): MatrixEvent | null {
+        const timeline = this._eventIdToTimeline[eventId];
+        if (!timeline) {
+            return null;
+        }
+
+        const removed = timeline.removeEvent(eventId);
+        if (removed) {
+            delete this._eventIdToTimeline[eventId];
+            const data = {
+                timeline: timeline,
+            };
+            this.emit("Room.timeline", removed, this.room, undefined, true, data);
+        }
+        return removed;
+    }
+
+    /**
+     * Determine where two events appear in the timeline relative to one another
+     *
+     * @param {string} eventId1   The id of the first event
+     * @param {string} eventId2   The id of the second event
+
+     * @return {?number} a number less than zero if eventId1 precedes eventId2, and
+     *    greater than zero if eventId1 succeeds eventId2. zero if they are the
+     *    same event; null if we can't tell (either because we don't know about one
+     *    of the events, or because they are in separate timelines which don't join
+     *    up).
+     */
+    public compareEventOrdering(eventId1: string, eventId2: string): number | null {
+        if (eventId1 == eventId2) {
+            // optimise this case
+            return 0;
+        }
+
+        const timeline1 = this._eventIdToTimeline[eventId1];
+        const timeline2 = this._eventIdToTimeline[eventId2];
+
+        if (timeline1 === undefined) {
+            return null;
+        }
+        if (timeline2 === undefined) {
+            return null;
+        }
+
+        if (timeline1 === timeline2) {
+            // both events are in the same timeline - figure out their
+            // relative indices
+            let idx1;
+            let idx2;
+            const events = timeline1.getEvents();
+            for (let idx = 0; idx < events.length &&
+            (idx1 === undefined || idx2 === undefined); idx++) {
+                const evId = events[idx].getId();
+                if (evId == eventId1) {
+                    idx1 = idx;
+                }
+                if (evId == eventId2) {
+                    idx2 = idx;
+                }
+            }
+            return idx1 - idx2;
+        }
+
+        // the events are in different timelines. Iterate through the
+        // linkedlist to see which comes first.
+
+        // first work forwards from timeline1
+        let tl = timeline1;
+        while (tl) {
+            if (tl === timeline2) {
+                // timeline1 is before timeline2
+                return -1;
+            }
+            tl = tl.getNeighbouringTimeline(EventTimeline.FORWARDS);
+        }
+
+        // now try backwards from timeline1
+        tl = timeline1;
+        while (tl) {
+            if (tl === timeline2) {
+                // timeline2 is before timeline1
+                return 1;
+            }
+            tl = tl.getNeighbouringTimeline(EventTimeline.BACKWARDS);
+        }
+
+        // the timelines are not contiguous.
+        return null;
+    }
+
+    /**
+     * Get a collection of relations to a given event in this timeline set.
+     *
+     * @param {String} eventId
+     * The ID of the event that you'd like to access relation events for.
+     * For example, with annotations, this would be the ID of the event being annotated.
+     * @param {String} relationType
+     * The type of relation involved, such as "m.annotation", "m.reference", "m.replace", etc.
+     * @param {String} eventType
+     * The relation event's type, such as "m.reaction", etc.
+     * @throws If <code>eventId</code>, <code>relationType</code> or <code>eventType</code>
+     * are not valid.
+     *
+     * @returns {?Relations}
+     * A container for relation events or undefined if there are no relation events for
+     * the relationType.
+     */
+    public getRelationsForEvent(
+        eventId: string,
+        relationType: RelationType,
+        eventType: EventType | string,
+    ): Relations | undefined {
+        if (!this.unstableClientRelationAggregation) {
+            throw new Error("Client-side relation aggregation is disabled");
+        }
+
+        if (!eventId || !relationType || !eventType) {
+            throw new Error("Invalid arguments for `getRelationsForEvent`");
+        }
+
+        // debuglog("Getting relations for: ", eventId, relationType, eventType);
+
+        const relationsForEvent = this.relations[eventId] || {};
+        const relationsWithRelType = relationsForEvent[relationType] || {};
+        return relationsWithRelType[eventType];
+    }
+
+    /**
+     * Set an event as the target event if any Relations exist for it already
+     *
+     * @param {MatrixEvent} event
+     * The event to check as relation target.
+     */
+    public setRelationsTarget(event: MatrixEvent): void {
+        if (!this.unstableClientRelationAggregation) {
+            return;
+        }
+
+        const relationsForEvent = this.relations[event.getId()];
+        if (!relationsForEvent) {
+            return;
+        }
+
+        for (const relationsWithRelType of Object.values(relationsForEvent)) {
+            for (const relationsWithEventType of Object.values(relationsWithRelType)) {
+                relationsWithEventType.setTargetEvent(event);
+            }
+        }
+    }
+
+    /**
+     * Add relation events to the relevant relation collection.
+     *
+     * @param {MatrixEvent} event
+     * The new relation event to be aggregated.
+     */
+    public aggregateRelations(event: MatrixEvent): void {
+        if (!this.unstableClientRelationAggregation) {
+            return;
+        }
+
+        if (event.isRedacted() || event.status === EventStatus.CANCELLED) {
+            return;
+        }
+
+        // If the event is currently encrypted, wait until it has been decrypted.
+        if (event.isBeingDecrypted() || event.shouldAttemptDecryption()) {
+            event.once("Event.decrypted", () => {
+                this.aggregateRelations(event);
+            });
+            return;
+        }
+
+        const relation = event.getRelation();
+        if (!relation) {
+            return;
+        }
+
+        const relatesToEventId = relation.event_id;
+        const relationType = relation.rel_type;
+        const eventType = event.getType();
+
+        // debuglog("Aggregating relation: ", event.getId(), eventType, relation);
+
+        let relationsForEvent: Record<string, Partial<Record<string, Relations>>> = this.relations[relatesToEventId];
+        if (!relationsForEvent) {
+            relationsForEvent = this.relations[relatesToEventId] = {};
+        }
+        let relationsWithRelType = relationsForEvent[relationType];
+        if (!relationsWithRelType) {
+            relationsWithRelType = relationsForEvent[relationType] = {};
+        }
+        let relationsWithEventType = relationsWithRelType[eventType];
+
+        let relatesToEvent;
+        if (!relationsWithEventType) {
+            relationsWithEventType = relationsWithRelType[eventType] = new Relations(
+                relationType,
+                eventType,
+                this.room,
+            );
+            relatesToEvent = this.findEventById(relatesToEventId) || this.room.getPendingEvent(relatesToEventId);
+            if (relatesToEvent) {
+                relationsWithEventType.setTargetEvent(relatesToEvent);
+            }
+        }
+
+        relationsWithEventType.addEvent(event);
+    }
+}
+
+/**
+ * Fires whenever the timeline in a room is updated.
+ * @event module:client~MatrixClient#"Room.timeline"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {?Room} room The room, if any, whose timeline was updated.
+ * @param {boolean} toStartOfTimeline True if this event was added to the start
+ * @param {boolean} removed True if this event has just been removed from the timeline
+ * (beginning; oldest) of the timeline e.g. due to pagination.
+ *
+ * @param {object} data  more data about the event
+ *
+ * @param {module:models/event-timeline.EventTimeline} data.timeline the timeline the
+ * event was added to/removed from
+ *
+ * @param {boolean} data.liveEvent true if the event was a real-time event
+ * added to the end of the live timeline
+ *
+ * @example
+ * matrixClient.on("Room.timeline",
+ *                 function(event, room, toStartOfTimeline, removed, data) {
+ *   if (!toStartOfTimeline && data.liveEvent) {
+ *     var messageToAppend = room.timeline.[room.timeline.length - 1];
+ *   }
+ * });
+ */
+
+/**
+ * Fires whenever the live timeline in a room is reset.
+ *
+ * When we get a 'limited' sync (for example, after a network outage), we reset
+ * the live timeline to be empty before adding the recent events to the new
+ * timeline. This event is fired after the timeline is reset, and before the
+ * new events are added.
+ *
+ * @event module:client~MatrixClient#"Room.timelineReset"
+ * @param {Room} room The room whose live timeline was reset, if any
+ * @param {EventTimelineSet} timelineSet timelineSet room whose live timeline was reset
+ * @param {boolean} resetAllTimelines True if all timelines were reset.
+ */

src/models/event-timeline.js

@@ -1,398 +0,0 @@
-/*
-Copyright 2016, 2017 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/event-timeline
- */
-
-import { RoomState } from "./room-state";
-
-/**
- * Construct a new EventTimeline
- *
- * <p>An EventTimeline represents a contiguous sequence of events in a room.
- *
- * <p>As well as keeping track of the events themselves, it stores the state of
- * the room at the beginning and end of the timeline, and pagination tokens for
- * going backwards and forwards in the timeline.
- *
- * <p>In order that clients can meaningfully maintain an index into a timeline,
- * the EventTimeline object tracks a 'baseIndex'. This starts at zero, but is
- * incremented when events are prepended to the timeline. The index of an event
- * relative to baseIndex therefore remains constant.
- *
- * <p>Once a timeline joins up with its neighbour, they are linked together into a
- * doubly-linked list.
- *
- * @param {EventTimelineSet} eventTimelineSet the set of timelines this is part of
- * @constructor
- */
-export function EventTimeline(eventTimelineSet) {
-    this._eventTimelineSet = eventTimelineSet;
-    this._roomId = eventTimelineSet.room ? eventTimelineSet.room.roomId : null;
-    this._events = [];
-    this._baseIndex = 0;
-    this._startState = new RoomState(this._roomId);
-    this._startState.paginationToken = null;
-    this._endState = new RoomState(this._roomId);
-    this._endState.paginationToken = null;
-
-    this._prevTimeline = null;
-    this._nextTimeline = null;
-
-    // this is used by client.js
-    this._paginationRequests = { 'b': null, 'f': null };
-
-    this._name = this._roomId + ":" + new Date().toISOString();
-}
-
-/**
- * Symbolic constant for methods which take a 'direction' argument:
- * refers to the start of the timeline, or backwards in time.
- */
-EventTimeline.BACKWARDS = "b";
-
-/**
- * Symbolic constant for methods which take a 'direction' argument:
- * refers to the end of the timeline, or forwards in time.
- */
-EventTimeline.FORWARDS = "f";
-
-/**
- * Initialise the start and end state with the given events
- *
- * <p>This can only be called before any events are added.
- *
- * @param {MatrixEvent[]} stateEvents list of state events to initialise the
- * state with.
- * @throws {Error} if an attempt is made to call this after addEvent is called.
- */
-EventTimeline.prototype.initialiseState = function(stateEvents) {
-    if (this._events.length > 0) {
-        throw new Error("Cannot initialise state after events are added");
-    }
-
-    // We previously deep copied events here and used different copies in
-    // the oldState and state events: this decision seems to date back
-    // quite a way and was apparently made to fix a bug where modifications
-    // made to the start state leaked through to the end state.
-    // This really shouldn't be possible though: the events themselves should
-    // not change. Duplicating the events uses a lot of extra memory,
-    // so we now no longer do it. To assert that they really do never change,
-    // freeze them! Note that we can't do this for events in general:
-    // although it looks like the only things preventing us are the
-    // 'status' flag, forwardLooking (which is only set once when adding to the
-    // timeline) and possibly the sender (which seems like it should never be
-    // reset but in practice causes a lot of the tests to break).
-    for (const e of stateEvents) {
-        Object.freeze(e);
-    }
-
-    this._startState.setStateEvents(stateEvents);
-    this._endState.setStateEvents(stateEvents);
-};
-
-/**
- * Forks the (live) timeline, taking ownership of the existing directional state of this timeline.
- * All attached listeners will keep receiving state updates from the new live timeline state.
- * The end state of this timeline gets replaced with an independent copy of the current RoomState,
- * and will need a new pagination token if it ever needs to paginate forwards.
-
- * @param {string} direction   EventTimeline.BACKWARDS to get the state at the
- *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
- *   of the timeline.
- *
- * @return {EventTimeline} the new timeline
- */
-EventTimeline.prototype.forkLive = function(direction) {
-    const forkState = this.getState(direction);
-    const timeline = new EventTimeline(this._eventTimelineSet);
-    timeline._startState = forkState.clone();
-    // Now clobber the end state of the new live timeline with that from the
-    // previous live timeline. It will be identical except that we'll keep
-    // using the same RoomMember objects for the 'live' set of members with any
-    // listeners still attached
-    timeline._endState = forkState;
-    // Firstly, we just stole the current timeline's end state, so it needs a new one.
-    // Make an immutable copy of the state so back pagination will get the correct sentinels.
-    this._endState = forkState.clone();
-    return timeline;
-};
-
-/**
- * Creates an independent timeline, inheriting the directional state from this timeline.
- *
- * @param {string} direction   EventTimeline.BACKWARDS to get the state at the
- *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
- *   of the timeline.
- *
- * @return {EventTimeline} the new timeline
- */
-EventTimeline.prototype.fork = function(direction) {
-    const forkState = this.getState(direction);
-    const timeline = new EventTimeline(this._eventTimelineSet);
-    timeline._startState = forkState.clone();
-    timeline._endState = forkState.clone();
-    return timeline;
-};
-
-/**
- * Get the ID of the room for this timeline
- * @return {string} room ID
- */
-EventTimeline.prototype.getRoomId = function() {
-    return this._roomId;
-};
-
-/**
- * Get the filter for this timeline's timelineSet (if any)
- * @return {Filter} filter
- */
-EventTimeline.prototype.getFilter = function() {
-    return this._eventTimelineSet.getFilter();
-};
-
-/**
- * Get the timelineSet for this timeline
- * @return {EventTimelineSet} timelineSet
- */
-EventTimeline.prototype.getTimelineSet = function() {
-    return this._eventTimelineSet;
-};
-
-/**
- * Get the base index.
- *
- * <p>This is an index which is incremented when events are prepended to the
- * timeline. An individual event therefore stays at the same index in the array
- * relative to the base index (although note that a given event's index may
- * well be less than the base index, thus giving that event a negative relative
- * index).
- *
- * @return {number}
- */
-EventTimeline.prototype.getBaseIndex = function() {
-    return this._baseIndex;
-};
-
-/**
- * Get the list of events in this context
- *
- * @return {MatrixEvent[]} An array of MatrixEvents
- */
-EventTimeline.prototype.getEvents = function() {
-    return this._events;
-};
-
-/**
- * Get the room state at the start/end of the timeline
- *
- * @param {string} direction   EventTimeline.BACKWARDS to get the state at the
- *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
- *   of the timeline.
- *
- * @return {RoomState} state at the start/end of the timeline
- */
-EventTimeline.prototype.getState = function(direction) {
-    if (direction == EventTimeline.BACKWARDS) {
-        return this._startState;
-    } else if (direction == EventTimeline.FORWARDS) {
-        return this._endState;
-    } else {
-        throw new Error("Invalid direction '" + direction + "'");
-    }
-};
-
-/**
- * Get a pagination token
- *
- * @param {string} direction   EventTimeline.BACKWARDS to get the pagination
- *   token for going backwards in time; EventTimeline.FORWARDS to get the
- *   pagination token for going forwards in time.
- *
- * @return {?string} pagination token
- */
-EventTimeline.prototype.getPaginationToken = function(direction) {
-    return this.getState(direction).paginationToken;
-};
-
-/**
- * Set a pagination token
- *
- * @param {?string} token       pagination token
- *
- * @param {string} direction    EventTimeline.BACKWARDS to set the pagination
- *   token for going backwards in time; EventTimeline.FORWARDS to set the
- *   pagination token for going forwards in time.
- */
-EventTimeline.prototype.setPaginationToken = function(token, direction) {
-    this.getState(direction).paginationToken = token;
-};
-
-/**
- * Get the next timeline in the series
- *
- * @param {string} direction EventTimeline.BACKWARDS to get the previous
- *   timeline; EventTimeline.FORWARDS to get the next timeline.
- *
- * @return {?EventTimeline} previous or following timeline, if they have been
- * joined up.
- */
-EventTimeline.prototype.getNeighbouringTimeline = function(direction) {
-    if (direction == EventTimeline.BACKWARDS) {
-        return this._prevTimeline;
-    } else if (direction == EventTimeline.FORWARDS) {
-        return this._nextTimeline;
-    } else {
-        throw new Error("Invalid direction '" + direction + "'");
-    }
-};
-
-/**
- * Set the next timeline in the series
- *
- * @param {EventTimeline} neighbour previous/following timeline
- *
- * @param {string} direction EventTimeline.BACKWARDS to set the previous
- *   timeline; EventTimeline.FORWARDS to set the next timeline.
- *
- * @throws {Error} if an attempt is made to set the neighbouring timeline when
- * it is already set.
- */
-EventTimeline.prototype.setNeighbouringTimeline = function(neighbour, direction) {
-    if (this.getNeighbouringTimeline(direction)) {
-        throw new Error("timeline already has a neighbouring timeline - " +
-                        "cannot reset neighbour (direction: " + direction + ")");
-    }
-
-    if (direction == EventTimeline.BACKWARDS) {
-        this._prevTimeline = neighbour;
-    } else if (direction == EventTimeline.FORWARDS) {
-        this._nextTimeline = neighbour;
-    } else {
-        throw new Error("Invalid direction '" + direction + "'");
-    }
-
-    // make sure we don't try to paginate this timeline
-    this.setPaginationToken(null, direction);
-};
-
-/**
- * Add a new event to the timeline, and update the state
- *
- * @param {MatrixEvent} event   new event
- * @param {boolean}  atStart     true to insert new event at the start
- */
-EventTimeline.prototype.addEvent = function(event, atStart) {
-    const stateContext = atStart ? this._startState : this._endState;
-
-    // only call setEventMetadata on the unfiltered timelineSets
-    const timelineSet = this.getTimelineSet();
-    if (timelineSet.room &&
-        timelineSet.room.getUnfilteredTimelineSet() === timelineSet) {
-        EventTimeline.setEventMetadata(event, stateContext, atStart);
-
-        // modify state
-        if (event.isState()) {
-            stateContext.setStateEvents([event]);
-            // it is possible that the act of setting the state event means we
-            // can set more metadata (specifically sender/target props), so try
-            // it again if the prop wasn't previously set. It may also mean that
-            // the sender/target is updated (if the event set was a room member event)
-            // so we want to use the *updated* member (new avatar/name) instead.
-            //
-            // However, we do NOT want to do this on member events if we're going
-            // back in time, else we'll set the .sender value for BEFORE the given
-            // member event, whereas we want to set the .sender value for the ACTUAL
-            // member event itself.
-            if (!event.sender || (event.getType() === "m.room.member" && !atStart)) {
-                EventTimeline.setEventMetadata(event, stateContext, atStart);
-            }
-        }
-    }
-
-    let insertIndex;
-
-    if (atStart) {
-        insertIndex = 0;
-    } else {
-        insertIndex = this._events.length;
-    }
-
-    this._events.splice(insertIndex, 0, event); // insert element
-    if (atStart) {
-        this._baseIndex++;
-    }
-};
-
-/**
- * Static helper method to set sender and target properties
- *
- * @param {MatrixEvent} event   the event whose metadata is to be set
- * @param {RoomState} stateContext  the room state to be queried
- * @param {bool} toStartOfTimeline  if true the event's forwardLooking flag is set false
- */
-EventTimeline.setEventMetadata = function(event, stateContext, toStartOfTimeline) {
-    // set sender and target properties
-    event.sender = stateContext.getSentinelMember(
-        event.getSender(),
-    );
-    if (event.getType() === "m.room.member") {
-        event.target = stateContext.getSentinelMember(
-            event.getStateKey(),
-        );
-    }
-    if (event.isState()) {
-        // room state has no concept of 'old' or 'current', but we want the
-        // room state to regress back to previous values if toStartOfTimeline
-        // is set, which means inspecting prev_content if it exists. This
-        // is done by toggling the forwardLooking flag.
-        if (toStartOfTimeline) {
-            event.forwardLooking = false;
-        }
-    }
-};
-
-/**
- * Remove an event from the timeline
- *
- * @param {string} eventId  ID of event to be removed
- * @return {?MatrixEvent} removed event, or null if not found
- */
-EventTimeline.prototype.removeEvent = function(eventId) {
-    for (let i = this._events.length - 1; i >= 0; i--) {
-        const ev = this._events[i];
-        if (ev.getId() == eventId) {
-            this._events.splice(i, 1);
-            if (i < this._baseIndex) {
-                this._baseIndex--;
-            }
-            return ev;
-        }
-    }
-    return null;
-};
-
-/**
- * Return a string to identify this timeline, for debugging
- *
- * @return {string} name for this timeline
- */
-EventTimeline.prototype.toString = function() {
-    return this._name;
-};
-

src/models/event-timeline.ts

@@ -0,0 +1,419 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module models/event-timeline
+ */
+
+import { RoomState } from "./room-state";
+import { EventTimelineSet } from "./event-timeline-set";
+import { MatrixEvent } from "./event";
+import { Filter } from "../filter";
+import { EventType } from "../@types/event";
+
+export enum Direction {
+    Backward = "b",
+    Forward = "f",
+}
+
+export class EventTimeline {
+    /**
+     * Symbolic constant for methods which take a 'direction' argument:
+     * refers to the start of the timeline, or backwards in time.
+     */
+    static BACKWARDS = Direction.Backward;
+
+    /**
+     * Symbolic constant for methods which take a 'direction' argument:
+     * refers to the end of the timeline, or forwards in time.
+     */
+    static FORWARDS = Direction.Forward;
+
+    /**
+     * Static helper method to set sender and target properties
+     *
+     * @param {MatrixEvent} event   the event whose metadata is to be set
+     * @param {RoomState} stateContext  the room state to be queried
+     * @param {boolean} toStartOfTimeline  if true the event's forwardLooking flag is set false
+     */
+    static setEventMetadata(event: MatrixEvent, stateContext: RoomState, toStartOfTimeline: boolean): void {
+        // We always check if the event doesn't already have the property. We do
+        // this to avoid overriding non-sentinel members by sentinel ones when
+        // adding the event to a filtered timeline
+        if (!event.sender) {
+            event.sender = stateContext.getSentinelMember(event.getSender());
+        }
+        if (!event.target && event.getType() === EventType.RoomMember) {
+            event.target = stateContext.getSentinelMember(event.getStateKey());
+        }
+
+        if (event.isState()) {
+            // room state has no concept of 'old' or 'current', but we want the
+            // room state to regress back to previous values if toStartOfTimeline
+            // is set, which means inspecting prev_content if it exists. This
+            // is done by toggling the forwardLooking flag.
+            if (toStartOfTimeline) {
+                event.forwardLooking = false;
+            }
+        }
+    }
+
+    private readonly roomId: string | null;
+    private readonly name: string;
+    private events: MatrixEvent[] = [];
+    private baseIndex = 0;
+    private startState: RoomState;
+    private endState: RoomState;
+    private prevTimeline?: EventTimeline;
+    private nextTimeline?: EventTimeline;
+    public paginationRequests: Record<Direction, Promise<boolean>> = {
+        [Direction.Backward]: null,
+        [Direction.Forward]: null,
+    };
+
+    /**
+     * Construct a new EventTimeline
+     *
+     * <p>An EventTimeline represents a contiguous sequence of events in a room.
+     *
+     * <p>As well as keeping track of the events themselves, it stores the state of
+     * the room at the beginning and end of the timeline, and pagination tokens for
+     * going backwards and forwards in the timeline.
+     *
+     * <p>In order that clients can meaningfully maintain an index into a timeline,
+     * the EventTimeline object tracks a 'baseIndex'. This starts at zero, but is
+     * incremented when events are prepended to the timeline. The index of an event
+     * relative to baseIndex therefore remains constant.
+     *
+     * <p>Once a timeline joins up with its neighbour, they are linked together into a
+     * doubly-linked list.
+     *
+     * @param {EventTimelineSet} eventTimelineSet the set of timelines this is part of
+     * @constructor
+     */
+    constructor(private readonly eventTimelineSet: EventTimelineSet) {
+        this.roomId = eventTimelineSet.room?.roomId ?? null;
+        this.startState = new RoomState(this.roomId);
+        this.startState.paginationToken = null;
+        this.endState = new RoomState(this.roomId);
+        this.endState.paginationToken = null;
+
+        this.prevTimeline = null;
+        this.nextTimeline = null;
+
+        // this is used by client.js
+        this.paginationRequests = { 'b': null, 'f': null };
+
+        this.name = this.roomId + ":" + new Date().toISOString();
+    }
+
+    /**
+     * Initialise the start and end state with the given events
+     *
+     * <p>This can only be called before any events are added.
+     *
+     * @param {MatrixEvent[]} stateEvents list of state events to initialise the
+     * state with.
+     * @throws {Error} if an attempt is made to call this after addEvent is called.
+     */
+    public initialiseState(stateEvents: MatrixEvent[]): void {
+        if (this.events.length > 0) {
+            throw new Error("Cannot initialise state after events are added");
+        }
+
+        // We previously deep copied events here and used different copies in
+        // the oldState and state events: this decision seems to date back
+        // quite a way and was apparently made to fix a bug where modifications
+        // made to the start state leaked through to the end state.
+        // This really shouldn't be possible though: the events themselves should
+        // not change. Duplicating the events uses a lot of extra memory,
+        // so we now no longer do it. To assert that they really do never change,
+        // freeze them! Note that we can't do this for events in general:
+        // although it looks like the only things preventing us are the
+        // 'status' flag, forwardLooking (which is only set once when adding to the
+        // timeline) and possibly the sender (which seems like it should never be
+        // reset but in practice causes a lot of the tests to break).
+        for (const e of stateEvents) {
+            Object.freeze(e);
+        }
+
+        this.startState.setStateEvents(stateEvents);
+        this.endState.setStateEvents(stateEvents);
+    }
+
+    /**
+     * Forks the (live) timeline, taking ownership of the existing directional state of this timeline.
+     * All attached listeners will keep receiving state updates from the new live timeline state.
+     * The end state of this timeline gets replaced with an independent copy of the current RoomState,
+     * and will need a new pagination token if it ever needs to paginate forwards.
+
+     * @param {string} direction   EventTimeline.BACKWARDS to get the state at the
+     *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
+     *   of the timeline.
+     *
+     * @return {EventTimeline} the new timeline
+     */
+    public forkLive(direction: Direction): EventTimeline {
+        const forkState = this.getState(direction);
+        const timeline = new EventTimeline(this.eventTimelineSet);
+        timeline.startState = forkState.clone();
+        // Now clobber the end state of the new live timeline with that from the
+        // previous live timeline. It will be identical except that we'll keep
+        // using the same RoomMember objects for the 'live' set of members with any
+        // listeners still attached
+        timeline.endState = forkState;
+        // Firstly, we just stole the current timeline's end state, so it needs a new one.
+        // Make an immutable copy of the state so back pagination will get the correct sentinels.
+        this.endState = forkState.clone();
+        return timeline;
+    }
+
+    /**
+     * Creates an independent timeline, inheriting the directional state from this timeline.
+     *
+     * @param {string} direction   EventTimeline.BACKWARDS to get the state at the
+     *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
+     *   of the timeline.
+     *
+     * @return {EventTimeline} the new timeline
+     */
+    public fork(direction: Direction): EventTimeline {
+        const forkState = this.getState(direction);
+        const timeline = new EventTimeline(this.eventTimelineSet);
+        timeline.startState = forkState.clone();
+        timeline.endState = forkState.clone();
+        return timeline;
+    }
+
+    /**
+     * Get the ID of the room for this timeline
+     * @return {string} room ID
+     */
+    public getRoomId(): string {
+        return this.roomId;
+    }
+
+    /**
+     * Get the filter for this timeline's timelineSet (if any)
+     * @return {Filter} filter
+     */
+    public getFilter(): Filter {
+        return this.eventTimelineSet.getFilter();
+    }
+
+    /**
+     * Get the timelineSet for this timeline
+     * @return {EventTimelineSet} timelineSet
+     */
+    public getTimelineSet(): EventTimelineSet {
+        return this.eventTimelineSet;
+    }
+
+    /**
+     * Get the base index.
+     *
+     * <p>This is an index which is incremented when events are prepended to the
+     * timeline. An individual event therefore stays at the same index in the array
+     * relative to the base index (although note that a given event's index may
+     * well be less than the base index, thus giving that event a negative relative
+     * index).
+     *
+     * @return {number}
+     */
+    public getBaseIndex(): number {
+        return this.baseIndex;
+    }
+
+    /**
+     * Get the list of events in this context
+     *
+     * @return {MatrixEvent[]} An array of MatrixEvents
+     */
+    public getEvents(): MatrixEvent[] {
+        return this.events;
+    }
+
+    /**
+     * Get the room state at the start/end of the timeline
+     *
+     * @param {string} direction   EventTimeline.BACKWARDS to get the state at the
+     *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
+     *   of the timeline.
+     *
+     * @return {RoomState} state at the start/end of the timeline
+     */
+    public getState(direction: Direction): RoomState {
+        if (direction == EventTimeline.BACKWARDS) {
+            return this.startState;
+        } else if (direction == EventTimeline.FORWARDS) {
+            return this.endState;
+        } else {
+            throw new Error("Invalid direction '" + direction + "'");
+        }
+    }
+
+    /**
+     * Get a pagination token
+     *
+     * @param {string} direction   EventTimeline.BACKWARDS to get the pagination
+     *   token for going backwards in time; EventTimeline.FORWARDS to get the
+     *   pagination token for going forwards in time.
+     *
+     * @return {?string} pagination token
+     */
+    public getPaginationToken(direction: Direction): string | null {
+        return this.getState(direction).paginationToken;
+    }
+
+    /**
+     * Set a pagination token
+     *
+     * @param {?string} token       pagination token
+     *
+     * @param {string} direction    EventTimeline.BACKWARDS to set the pagination
+     *   token for going backwards in time; EventTimeline.FORWARDS to set the
+     *   pagination token for going forwards in time.
+     */
+    public setPaginationToken(token: string, direction: Direction): void {
+        this.getState(direction).paginationToken = token;
+    }
+
+    /**
+     * Get the next timeline in the series
+     *
+     * @param {string} direction EventTimeline.BACKWARDS to get the previous
+     *   timeline; EventTimeline.FORWARDS to get the next timeline.
+     *
+     * @return {?EventTimeline} previous or following timeline, if they have been
+     * joined up.
+     */
+    public getNeighbouringTimeline(direction: Direction): EventTimeline {
+        if (direction == EventTimeline.BACKWARDS) {
+            return this.prevTimeline;
+        } else if (direction == EventTimeline.FORWARDS) {
+            return this.nextTimeline;
+        } else {
+            throw new Error("Invalid direction '" + direction + "'");
+        }
+    }
+
+    /**
+     * Set the next timeline in the series
+     *
+     * @param {EventTimeline} neighbour previous/following timeline
+     *
+     * @param {string} direction EventTimeline.BACKWARDS to set the previous
+     *   timeline; EventTimeline.FORWARDS to set the next timeline.
+     *
+     * @throws {Error} if an attempt is made to set the neighbouring timeline when
+     * it is already set.
+     */
+    public setNeighbouringTimeline(neighbour: EventTimeline, direction: Direction): void {
+        if (this.getNeighbouringTimeline(direction)) {
+            throw new Error("timeline already has a neighbouring timeline - " +
+                "cannot reset neighbour (direction: " + direction + ")");
+        }
+
+        if (direction == EventTimeline.BACKWARDS) {
+            this.prevTimeline = neighbour;
+        } else if (direction == EventTimeline.FORWARDS) {
+            this.nextTimeline = neighbour;
+        } else {
+            throw new Error("Invalid direction '" + direction + "'");
+        }
+
+        // make sure we don't try to paginate this timeline
+        this.setPaginationToken(null, direction);
+    }
+
+    /**
+     * Add a new event to the timeline, and update the state
+     *
+     * @param {MatrixEvent} event   new event
+     * @param {boolean}  atStart     true to insert new event at the start
+     */
+    public addEvent(event: MatrixEvent, atStart: boolean): void {
+        const stateContext = atStart ? this.startState : this.endState;
+        const timelineSet = this.getTimelineSet();
+
+        if (timelineSet.room) {
+            EventTimeline.setEventMetadata(event, stateContext, atStart);
+
+            // modify state but only on unfiltered timelineSets
+            if (
+                event.isState() &&
+                timelineSet.room.getUnfilteredTimelineSet() === timelineSet
+            ) {
+                stateContext.setStateEvents([event]);
+                // it is possible that the act of setting the state event means we
+                // can set more metadata (specifically sender/target props), so try
+                // it again if the prop wasn't previously set. It may also mean that
+                // the sender/target is updated (if the event set was a room member event)
+                // so we want to use the *updated* member (new avatar/name) instead.
+                //
+                // However, we do NOT want to do this on member events if we're going
+                // back in time, else we'll set the .sender value for BEFORE the given
+                // member event, whereas we want to set the .sender value for the ACTUAL
+                // member event itself.
+                if (!event.sender || (event.getType() === "m.room.member" && !atStart)) {
+                    EventTimeline.setEventMetadata(event, stateContext, atStart);
+                }
+            }
+        }
+
+        let insertIndex;
+
+        if (atStart) {
+            insertIndex = 0;
+        } else {
+            insertIndex = this.events.length;
+        }
+
+        this.events.splice(insertIndex, 0, event); // insert element
+        if (atStart) {
+            this.baseIndex++;
+        }
+    }
+
+    /**
+     * Remove an event from the timeline
+     *
+     * @param {string} eventId  ID of event to be removed
+     * @return {?MatrixEvent} removed event, or null if not found
+     */
+    public removeEvent(eventId: string): MatrixEvent | null {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            if (ev.getId() == eventId) {
+                this.events.splice(i, 1);
+                if (i < this.baseIndex) {
+                    this.baseIndex--;
+                }
+                return ev;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Return a string to identify this timeline, for debugging
+     *
+     * @return {string} name for this timeline
+     */
+    public toString(): string {
+        return this.name;
+    }
+}

src/models/relations.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2019 New Vector Ltd
+Copyright 2019, 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -15,8 +15,11 @@ limitations under the License.
 */
 
 import { EventEmitter } from 'events';
-import { EventStatus } from '../models/event';
+
+import { EventStatus, MatrixEvent } from './event';
+import { Room } from './room';
 import { logger } from '../logger';
+import { RelationType } from "../@types/event";
 
 /**
  * A container for relation events that supports easy access to common ways of
@@ -27,8 +30,16 @@ import { logger } from '../logger';
  * EventTimelineSet#getRelationsForEvent.
  */
 export class Relations extends EventEmitter {
+    private relationEventIds = new Set<string>();
+    private relations = new Set<MatrixEvent>();
+    private annotationsByKey: Record<string, Set<MatrixEvent>> = {};
+    private annotationsBySender: Record<string, Set<MatrixEvent>> = {};
+    private sortedAnnotationsByKey: [string, Set<MatrixEvent>][] = [];
+    private targetEvent: MatrixEvent = null;
+    private creationEmitted = false;
+
     /**
-     * @param {String} relationType
+     * @param {RelationType} relationType
      * The type of relation involved, such as "m.annotation", "m.reference",
      * "m.replace", etc.
      * @param {String} eventType
@@ -37,18 +48,12 @@ export class Relations extends EventEmitter {
      * Room for this container. May be null for non-room cases, such as the
      * notification timeline.
      */
-    constructor(relationType, eventType, room) {
+    constructor(
+        public readonly relationType: RelationType | string,
+        public readonly eventType: string,
+        private readonly room: Room,
+    ) {
         super();
-        this.relationType = relationType;
-        this.eventType = eventType;
-        this._relationEventIds = new Set();
-        this._relations = new Set();
-        this._annotationsByKey = {};
-        this._annotationsBySender = {};
-        this._sortedAnnotationsByKey = [];
-        this._targetEvent = null;
-        this._room = room;
-        this._creationEmitted = false;
     }
 
     /**
@@ -57,8 +62,8 @@ export class Relations extends EventEmitter {
      * @param {MatrixEvent} event
      * The new relation event to be added.
      */
-    async addEvent(event) {
-        if (this._relationEventIds.has(event.getId())) {
+    public async addEvent(event: MatrixEvent) {
+        if (this.relationEventIds.has(event.getId())) {
             return;
         }
 
@@ -79,24 +84,24 @@ export class Relations extends EventEmitter {
         // If the event is in the process of being sent, listen for cancellation
         // so we can remove the event from the collection.
         if (event.isSending()) {
-            event.on("Event.status", this._onEventStatus);
+            event.on("Event.status", this.onEventStatus);
         }
 
-        this._relations.add(event);
-        this._relationEventIds.add(event.getId());
+        this.relations.add(event);
+        this.relationEventIds.add(event.getId());
 
-        if (this.relationType === "m.annotation") {
-            this._addAnnotationToAggregation(event);
-        } else if (this.relationType === "m.replace" && this._targetEvent) {
+        if (this.relationType === RelationType.Annotation) {
+            this.addAnnotationToAggregation(event);
+        } else if (this.relationType === RelationType.Replace && this.targetEvent) {
             const lastReplacement = await this.getLastReplacement();
-            this._targetEvent.makeReplaced(lastReplacement);
+            this.targetEvent.makeReplaced(lastReplacement);
         }
 
-        event.on("Event.beforeRedaction", this._onBeforeRedaction);
+        event.on("Event.beforeRedaction", this.onBeforeRedaction);
 
         this.emit("Relations.add", event);
 
-        this._maybeEmitCreated();
+        this.maybeEmitCreated();
     }
 
     /**
@@ -105,8 +110,8 @@ export class Relations extends EventEmitter {
      * @param {MatrixEvent} event
      * The relation event to remove.
      */
-    async _removeEvent(event) {
-        if (!this._relations.has(event)) {
+    private async removeEvent(event: MatrixEvent) {
+        if (!this.relations.has(event)) {
             return;
         }
 
@@ -124,13 +129,13 @@ export class Relations extends EventEmitter {
             return;
         }
 
-        this._relations.delete(event);
+        this.relations.delete(event);
 
-        if (this.relationType === "m.annotation") {
-            this._removeAnnotationFromAggregation(event);
-        } else if (this.relationType === "m.replace" && this._targetEvent) {
+        if (this.relationType === RelationType.Annotation) {
+            this.removeAnnotationFromAggregation(event);
+        } else if (this.relationType === RelationType.Replace && this.targetEvent) {
             const lastReplacement = await this.getLastReplacement();
-            this._targetEvent.makeReplaced(lastReplacement);
+            this.targetEvent.makeReplaced(lastReplacement);
         }
 
         this.emit("Relations.remove", event);
@@ -142,19 +147,19 @@ export class Relations extends EventEmitter {
      * @param {MatrixEvent} event The event whose status has changed
      * @param {EventStatus} status The new status
      */
-    _onEventStatus = (event, status) => {
+    private onEventStatus = (event: MatrixEvent, status: EventStatus) => {
         if (!event.isSending()) {
             // Sending is done, so we don't need to listen anymore
-            event.removeListener("Event.status", this._onEventStatus);
+            event.removeListener("Event.status", this.onEventStatus);
             return;
         }
         if (status !== EventStatus.CANCELLED) {
             return;
         }
         // Event was cancelled, remove from the collection
-        event.removeListener("Event.status", this._onEventStatus);
-        this._removeEvent(event);
-    }
+        event.removeListener("Event.status", this.onEventStatus);
+        this.removeEvent(event);
+    };
 
     /**
      * Get all relation events in this collection.
@@ -166,51 +171,51 @@ export class Relations extends EventEmitter {
      * @return {Array}
      * Relation events in insertion order.
      */
-    getRelations() {
-        return [...this._relations];
+    public getRelations() {
+        return [...this.relations];
     }
 
-    _addAnnotationToAggregation(event) {
+    private addAnnotationToAggregation(event: MatrixEvent) {
         const { key } = event.getRelation();
         if (!key) {
             return;
         }
 
-        let eventsForKey = this._annotationsByKey[key];
+        let eventsForKey = this.annotationsByKey[key];
         if (!eventsForKey) {
-            eventsForKey = this._annotationsByKey[key] = new Set();
-            this._sortedAnnotationsByKey.push([key, eventsForKey]);
+            eventsForKey = this.annotationsByKey[key] = new Set();
+            this.sortedAnnotationsByKey.push([key, eventsForKey]);
         }
         // Add the new event to the set for this key
         eventsForKey.add(event);
         // Re-sort the [key, events] pairs in descending order of event count
-        this._sortedAnnotationsByKey.sort((a, b) => {
+        this.sortedAnnotationsByKey.sort((a, b) => {
             const aEvents = a[1];
             const bEvents = b[1];
             return bEvents.size - aEvents.size;
         });
 
         const sender = event.getSender();
-        let eventsFromSender = this._annotationsBySender[sender];
+        let eventsFromSender = this.annotationsBySender[sender];
         if (!eventsFromSender) {
-            eventsFromSender = this._annotationsBySender[sender] = new Set();
+            eventsFromSender = this.annotationsBySender[sender] = new Set();
         }
         // Add the new event to the set for this sender
         eventsFromSender.add(event);
     }
 
-    _removeAnnotationFromAggregation(event) {
+    private removeAnnotationFromAggregation(event: MatrixEvent) {
         const { key } = event.getRelation();
         if (!key) {
             return;
         }
 
-        const eventsForKey = this._annotationsByKey[key];
+        const eventsForKey = this.annotationsByKey[key];
         if (eventsForKey) {
             eventsForKey.delete(event);
 
             // Re-sort the [key, events] pairs in descending order of event count
-            this._sortedAnnotationsByKey.sort((a, b) => {
+            this.sortedAnnotationsByKey.sort((a, b) => {
                 const aEvents = a[1];
                 const bEvents = b[1];
                 return bEvents.size - aEvents.size;
@@ -218,7 +223,7 @@ export class Relations extends EventEmitter {
         }
 
         const sender = event.getSender();
-        const eventsFromSender = this._annotationsBySender[sender];
+        const eventsFromSender = this.annotationsBySender[sender];
         if (eventsFromSender) {
             eventsFromSender.delete(event);
         }
@@ -235,25 +240,25 @@ export class Relations extends EventEmitter {
      * @param {MatrixEvent} redactedEvent
      * The original relation event that is about to be redacted.
      */
-    _onBeforeRedaction = async (redactedEvent) => {
-        if (!this._relations.has(redactedEvent)) {
+    private onBeforeRedaction = async (redactedEvent: MatrixEvent) => {
+        if (!this.relations.has(redactedEvent)) {
             return;
         }
 
-        this._relations.delete(redactedEvent);
+        this.relations.delete(redactedEvent);
 
-        if (this.relationType === "m.annotation") {
+        if (this.relationType === RelationType.Annotation) {
             // Remove the redacted annotation from aggregation by key
-            this._removeAnnotationFromAggregation(redactedEvent);
-        } else if (this.relationType === "m.replace" && this._targetEvent) {
+            this.removeAnnotationFromAggregation(redactedEvent);
+        } else if (this.relationType === RelationType.Replace && this.targetEvent) {
             const lastReplacement = await this.getLastReplacement();
-            this._targetEvent.makeReplaced(lastReplacement);
+            this.targetEvent.makeReplaced(lastReplacement);
         }
 
-        redactedEvent.removeListener("Event.beforeRedaction", this._onBeforeRedaction);
+        redactedEvent.removeListener("Event.beforeRedaction", this.onBeforeRedaction);
 
         this.emit("Relations.redaction", redactedEvent);
-    }
+    };
 
     /**
      * Get all events in this collection grouped by key and sorted by descending
@@ -265,13 +270,13 @@ export class Relations extends EventEmitter {
      * An array of [key, events] pairs sorted by descending event count.
      * The events are stored in a Set (which preserves insertion order).
      */
-    getSortedAnnotationsByKey() {
-        if (this.relationType !== "m.annotation") {
+    public getSortedAnnotationsByKey() {
+        if (this.relationType !== RelationType.Annotation) {
             // Other relation types are not grouped currently.
             return null;
         }
 
-        return this._sortedAnnotationsByKey;
+        return this.sortedAnnotationsByKey;
     }
 
     /**
@@ -283,13 +288,13 @@ export class Relations extends EventEmitter {
      * An object with each relation sender as a key and the matching Set of
      * events for that sender as a value.
      */
-    getAnnotationsBySender() {
-        if (this.relationType !== "m.annotation") {
+    public getAnnotationsBySender() {
+        if (this.relationType !== RelationType.Annotation) {
             // Other relation types are not grouped currently.
             return null;
         }
 
-        return this._annotationsBySender;
+        return this.annotationsBySender;
     }
 
     /**
@@ -300,12 +305,12 @@ export class Relations extends EventEmitter {
      *
      * @return {MatrixEvent?}
      */
-    async getLastReplacement() {
-        if (this.relationType !== "m.replace") {
+    public async getLastReplacement(): Promise<MatrixEvent | null> {
+        if (this.relationType !== RelationType.Replace) {
             // Aggregating on last only makes sense for this relation type
             return null;
         }
-        if (!this._targetEvent) {
+        if (!this.targetEvent) {
             // Don't know which replacements to accept yet.
             // This method shouldn't be called before the original
             // event is known anyway.
@@ -314,12 +319,11 @@ export class Relations extends EventEmitter {
 
         // the all-knowning server tells us that the event at some point had
         // this timestamp for its replacement, so any following replacement should definitely not be less
-        const replaceRelation =
-            this._targetEvent.getServerAggregatedRelation("m.replace");
+        const replaceRelation = this.targetEvent.getServerAggregatedRelation(RelationType.Replace);
         const minTs = replaceRelation && replaceRelation.origin_server_ts;
 
         const lastReplacement = this.getRelations().reduce((last, event) => {
-            if (event.getSender() !== this._targetEvent.getSender()) {
+            if (event.getSender() !== this.targetEvent.getSender()) {
                 return last;
             }
             if (minTs && minTs > event.getTs()) {
@@ -332,9 +336,9 @@ export class Relations extends EventEmitter {
         }, null);
 
         if (lastReplacement?.shouldAttemptDecryption()) {
-            await lastReplacement.attemptDecryption(this._room._client.crypto);
+            await lastReplacement.attemptDecryption(this.room.client.crypto);
         } else if (lastReplacement?.isBeingDecrypted()) {
-            await lastReplacement._decryptionPromise;
+            await lastReplacement.getDecryptionPromise();
         }
 
         return lastReplacement;
@@ -343,38 +347,34 @@ export class Relations extends EventEmitter {
     /*
      * @param {MatrixEvent} targetEvent the event the relations are related to.
      */
-    async setTargetEvent(event) {
-        if (this._targetEvent) {
+    public async setTargetEvent(event: MatrixEvent) {
+        if (this.targetEvent) {
             return;
         }
-        this._targetEvent = event;
+        this.targetEvent = event;
 
-        if (this.relationType === "m.replace") {
+        if (this.relationType === RelationType.Replace) {
             const replacement = await this.getLastReplacement();
             // this is the initial update, so only call it if we already have something
             // to not emit Event.replaced needlessly
             if (replacement) {
-                this._targetEvent.makeReplaced(replacement);
+                this.targetEvent.makeReplaced(replacement);
             }
         }
 
-        this._maybeEmitCreated();
+        this.maybeEmitCreated();
     }
 
-    _maybeEmitCreated() {
-        if (this._creationEmitted) {
+    private maybeEmitCreated() {
+        if (this.creationEmitted) {
             return;
         }
         // Only emit we're "created" once we have a target event instance _and_
         // at least one related event.
-        if (!this._targetEvent || !this._relations.size) {
+        if (!this.targetEvent || !this.relations.size) {
             return;
         }
-        this._creationEmitted = true;
-        this._targetEvent.emit(
-            "Event.relationsCreated",
-            this.relationType,
-            this.eventType,
-        );
+        this.creationEmitted = true;
+        this.targetEvent.emit("Event.relationsCreated", this.relationType, this.eventType);
     }
 }

src/models/room-member.js

@@ -1,393 +0,0 @@
-/*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/room-member
- */
-
-import { EventEmitter } from "events";
-import { getHttpUriForMxc } from "../content-repo";
-import * as utils from "../utils";
-
-/**
- * Construct a new room member.
- *
- * @constructor
- * @alias module:models/room-member
- *
- * @param {string} roomId The room ID of the member.
- * @param {string} userId The user ID of the member.
- * @prop {string} roomId The room ID for this member.
- * @prop {string} userId The user ID of this member.
- * @prop {boolean} typing True if the room member is currently typing.
- * @prop {string} name The human-readable name for this room member. This will be
- * disambiguated with a suffix of " (@user_id:matrix.org)" if another member shares the
- * same displayname.
- * @prop {string} rawDisplayName The ambiguous displayname of this room member.
- * @prop {Number} powerLevel The power level for this room member.
- * @prop {Number} powerLevelNorm The normalised power level (0-100) for this
- * room member.
- * @prop {User} user The User object for this room member, if one exists.
- * @prop {string} membership The membership state for this room member e.g. 'join'.
- * @prop {Object} events The events describing this RoomMember.
- * @prop {MatrixEvent} events.member The m.room.member event for this RoomMember.
- * @prop {boolean} disambiguate True if the member's name is disambiguated.
- */
-export function RoomMember(roomId, userId) {
-    this.roomId = roomId;
-    this.userId = userId;
-    this.typing = false;
-    this.name = userId;
-    this.rawDisplayName = userId;
-    this.powerLevel = 0;
-    this.powerLevelNorm = 0;
-    this.user = null;
-    this.membership = null;
-    this.events = {
-        member: null,
-    };
-    this._isOutOfBand = false;
-    this._updateModifiedTime();
-    this.disambiguate = false;
-}
-utils.inherits(RoomMember, EventEmitter);
-
-/**
- * Mark the member as coming from a channel that is not sync
- */
-RoomMember.prototype.markOutOfBand = function() {
-    this._isOutOfBand = true;
-};
-
-/**
- * @return {bool} does the member come from a channel that is not sync?
- * This is used to store the member seperately
- * from the sync state so it available across browser sessions.
- */
-RoomMember.prototype.isOutOfBand = function() {
-    return this._isOutOfBand;
-};
-
-/**
- * Update this room member's membership event. May fire "RoomMember.name" if
- * this event updates this member's name.
- * @param {MatrixEvent} event The <code>m.room.member</code> event
- * @param {RoomState} roomState Optional. The room state to take into account
- * when calculating (e.g. for disambiguating users with the same name).
- * @fires module:client~MatrixClient#event:"RoomMember.name"
- * @fires module:client~MatrixClient#event:"RoomMember.membership"
- */
-RoomMember.prototype.setMembershipEvent = function(event, roomState) {
-    const displayName = event.getDirectionalContent().displayname;
-
-    if (event.getType() !== "m.room.member") {
-        return;
-    }
-
-    this._isOutOfBand = false;
-
-    this.events.member = event;
-
-    const oldMembership = this.membership;
-    this.membership = event.getDirectionalContent().membership;
-
-    this.disambiguate = shouldDisambiguate(
-        this.userId,
-        displayName,
-        roomState,
-    );
-
-    const oldName = this.name;
-    this.name = calculateDisplayName(
-        this.userId,
-        displayName,
-        roomState,
-        this.disambiguate,
-    );
-
-    this.rawDisplayName = event.getDirectionalContent().displayname || this.userId;
-    if (oldMembership !== this.membership) {
-        this._updateModifiedTime();
-        this.emit("RoomMember.membership", event, this, oldMembership);
-    }
-    if (oldName !== this.name) {
-        this._updateModifiedTime();
-        this.emit("RoomMember.name", event, this, oldName);
-    }
-};
-
-/**
- * Update this room member's power level event. May fire
- * "RoomMember.powerLevel" if this event updates this member's power levels.
- * @param {MatrixEvent} powerLevelEvent The <code>m.room.power_levels</code>
- * event
- * @fires module:client~MatrixClient#event:"RoomMember.powerLevel"
- */
-RoomMember.prototype.setPowerLevelEvent = function(powerLevelEvent) {
-    if (powerLevelEvent.getType() !== "m.room.power_levels") {
-        return;
-    }
-
-    const evContent = powerLevelEvent.getDirectionalContent();
-
-    let maxLevel = evContent.users_default || 0;
-    const users = evContent.users || {};
-    Object.values(users).forEach(function(lvl) {
-        maxLevel = Math.max(maxLevel, lvl);
-    });
-    const oldPowerLevel = this.powerLevel;
-    const oldPowerLevelNorm = this.powerLevelNorm;
-
-    if (users[this.userId] !== undefined) {
-        this.powerLevel = users[this.userId];
-    } else if (evContent.users_default !== undefined) {
-        this.powerLevel = evContent.users_default;
-    } else {
-        this.powerLevel = 0;
-    }
-    this.powerLevelNorm = 0;
-    if (maxLevel > 0) {
-        this.powerLevelNorm = (this.powerLevel * 100) / maxLevel;
-    }
-
-    // emit for changes in powerLevelNorm as well (since the app will need to
-    // redraw everyone's level if the max has changed)
-    if (oldPowerLevel !== this.powerLevel || oldPowerLevelNorm !== this.powerLevelNorm) {
-        this._updateModifiedTime();
-        this.emit("RoomMember.powerLevel", powerLevelEvent, this);
-    }
-};
-
-/**
- * Update this room member's typing event. May fire "RoomMember.typing" if
- * this event changes this member's typing state.
- * @param {MatrixEvent} event The typing event
- * @fires module:client~MatrixClient#event:"RoomMember.typing"
- */
-RoomMember.prototype.setTypingEvent = function(event) {
-    if (event.getType() !== "m.typing") {
-        return;
-    }
-    const oldTyping = this.typing;
-    this.typing = false;
-    const typingList = event.getContent().user_ids;
-    if (!Array.isArray(typingList)) {
-        // malformed event :/ bail early. TODO: whine?
-        return;
-    }
-    if (typingList.indexOf(this.userId) !== -1) {
-        this.typing = true;
-    }
-    if (oldTyping !== this.typing) {
-        this._updateModifiedTime();
-        this.emit("RoomMember.typing", event, this);
-    }
-};
-
-/**
- * Update the last modified time to the current time.
- */
-RoomMember.prototype._updateModifiedTime = function() {
-    this._modified = Date.now();
-};
-
-/**
- * Get the timestamp when this RoomMember was last updated. This timestamp is
- * updated when properties on this RoomMember are updated.
- * It is updated <i>before</i> firing events.
- * @return {number} The timestamp
- */
-RoomMember.prototype.getLastModifiedTime = function() {
-    return this._modified;
-};
-
-RoomMember.prototype.isKicked = function() {
-    return this.membership === "leave" &&
-        this.events.member.getSender() !== this.events.member.getStateKey();
-};
-
-/**
- * If this member was invited with the is_direct flag set, return
- * the user that invited this member
- * @return {string} user id of the inviter
- */
-RoomMember.prototype.getDMInviter = function() {
-    // when not available because that room state hasn't been loaded in,
-    // we don't really know, but more likely to not be a direct chat
-    if (this.events.member) {
-        // TODO: persist the is_direct flag on the member as more member events
-        //       come in caused by displayName changes.
-
-        // the is_direct flag is set on the invite member event.
-        // This is copied on the prev_content section of the join member event
-        // when the invite is accepted.
-
-        const memberEvent = this.events.member;
-        let memberContent = memberEvent.getContent();
-        let inviteSender = memberEvent.getSender();
-
-        if (memberContent.membership === "join") {
-            memberContent = memberEvent.getPrevContent();
-            inviteSender = memberEvent.getUnsigned().prev_sender;
-        }
-
-        if (memberContent.membership === "invite" && memberContent.is_direct) {
-            return inviteSender;
-        }
-    }
-};
-
-/**
- * Get the avatar URL for a room member.
- * @param {string} baseUrl The base homeserver URL See
- * {@link module:client~MatrixClient#getHomeserverUrl}.
- * @param {Number} width The desired width of the thumbnail.
- * @param {Number} height The desired height of the thumbnail.
- * @param {string} resizeMethod The thumbnail resize method to use, either
- * "crop" or "scale".
- * @param {Boolean} allowDefault (optional) Passing false causes this method to
- * return null if the user has no avatar image. Otherwise, a default image URL
- * will be returned. Default: true. (Deprecated)
- * @param {Boolean} allowDirectLinks (optional) If true, the avatar URL will be
- * returned even if it is a direct hyperlink rather than a matrix content URL.
- * If false, any non-matrix content URLs will be ignored. Setting this option to
- * true will expose URLs that, if fetched, will leak information about the user
- * to anyone who they share a room with.
- * @return {?string} the avatar URL or null.
- */
-RoomMember.prototype.getAvatarUrl =
-        function(baseUrl, width, height, resizeMethod, allowDefault, allowDirectLinks) {
-    if (allowDefault === undefined) {
-        allowDefault = true;
-    }
-
-    const rawUrl = this.getMxcAvatarUrl();
-
-    if (!rawUrl && !allowDefault) {
-        return null;
-    }
-    const httpUrl = getHttpUriForMxc(
-        baseUrl, rawUrl, width, height, resizeMethod, allowDirectLinks,
-    );
-    if (httpUrl) {
-        return httpUrl;
-    }
-    return null;
-};
-/**
- * get the mxc avatar url, either from a state event, or from a lazily loaded member
- * @return {string} the mxc avatar url
- */
-RoomMember.prototype.getMxcAvatarUrl = function() {
-    if (this.events.member) {
-        return this.events.member.getDirectionalContent().avatar_url;
-    } else if (this.user) {
-        return this.user.avatarUrl;
-    }
-    return null;
-};
-
-const MXID_PATTERN = /@.+:.+/;
-const LTR_RTL_PATTERN = /[\u200E\u200F\u202A-\u202F]/;
-
-function shouldDisambiguate(selfUserId, displayName, roomState) {
-    if (!displayName || displayName === selfUserId) return false;
-
-    // First check if the displayname is something we consider truthy
-    // after stripping it of zero width characters and padding spaces
-    if (!utils.removeHiddenChars(displayName)) return false;
-
-    if (!roomState) return false;
-
-    // Next check if the name contains something that look like a mxid
-    // If it does, it may be someone trying to impersonate someone else
-    // Show full mxid in this case
-    if (MXID_PATTERN.test(displayName)) return true;
-
-    // Also show mxid if the display name contains any LTR/RTL characters as these
-    // make it very difficult for us to find similar *looking* display names
-    // E.g "Mark" could be cloned by writing "kraM" but in RTL.
-    if (LTR_RTL_PATTERN.test(displayName)) return true;
-
-    // Also show mxid if there are other people with the same or similar
-    // displayname, after hidden character removal.
-    const userIds = roomState.getUserIdsWithDisplayName(displayName);
-    if (userIds.some((u) => u !== selfUserId)) return true;
-
-    return false;
-}
-
-function calculateDisplayName(selfUserId, displayName, roomState, disambiguate) {
-    if (disambiguate) return displayName + " (" + selfUserId + ")";
-
-    if (!displayName || displayName === selfUserId) return selfUserId;
-
-    // First check if the displayname is something we consider truthy
-    // after stripping it of zero width characters and padding spaces
-    if (!utils.removeHiddenChars(displayName)) return selfUserId;
-
-    return displayName;
-}
-
-/**
- * Fires whenever any room member's name changes.
- * @event module:client~MatrixClient#"RoomMember.name"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomMember} member The member whose RoomMember.name changed.
- * @param {string?} oldName The previous name. Null if the member didn't have a
- *    name previously.
- * @example
- * matrixClient.on("RoomMember.name", function(event, member){
- *   var newName = member.name;
- * });
- */
-
-/**
- * Fires whenever any room member's membership state changes.
- * @event module:client~MatrixClient#"RoomMember.membership"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomMember} member The member whose RoomMember.membership changed.
- * @param {string?} oldMembership The previous membership state. Null if it's a
- *    new member.
- * @example
- * matrixClient.on("RoomMember.membership", function(event, member, oldMembership){
- *   var newState = member.membership;
- * });
- */
-
-/**
- * Fires whenever any room member's typing state changes.
- * @event module:client~MatrixClient#"RoomMember.typing"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomMember} member The member whose RoomMember.typing changed.
- * @example
- * matrixClient.on("RoomMember.typing", function(event, member){
- *   var isTyping = member.typing;
- * });
- */
-
-/**
- * Fires whenever any room member's power level changes.
- * @event module:client~MatrixClient#"RoomMember.powerLevel"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomMember} member The member whose RoomMember.powerLevel changed.
- * @example
- * matrixClient.on("RoomMember.powerLevel", function(event, member){
- *   var newPowerLevel = member.powerLevel;
- *   var newNormPowerLevel = member.powerLevelNorm;
- * });
- */

src/models/room-member.ts

@@ -0,0 +1,412 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module models/room-member
+ */
+
+import { EventEmitter } from "events";
+
+import { getHttpUriForMxc } from "../content-repo";
+import * as utils from "../utils";
+import { User } from "./user";
+import { MatrixEvent } from "./event";
+import { RoomState } from "./room-state";
+
+export class RoomMember extends EventEmitter {
+    private _isOutOfBand = false;
+    private _modified: number;
+    public _requestedProfileInfo: boolean; // used by sync.ts
+
+    // XXX these should be read-only
+    public typing = false;
+    public name: string;
+    public rawDisplayName: string;
+    public powerLevel = 0;
+    public powerLevelNorm = 0;
+    public user?: User = null;
+    public membership: string = null;
+    public disambiguate = false;
+    public events: {
+        member?: MatrixEvent;
+    } = {
+        member: null,
+    };
+
+    /**
+     * Construct a new room member.
+     *
+     * @constructor
+     * @alias module:models/room-member
+     *
+     * @param {string} roomId The room ID of the member.
+     * @param {string} userId The user ID of the member.
+     * @prop {string} roomId The room ID for this member.
+     * @prop {string} userId The user ID of this member.
+     * @prop {boolean} typing True if the room member is currently typing.
+     * @prop {string} name The human-readable name for this room member. This will be
+     * disambiguated with a suffix of " (@user_id:matrix.org)" if another member shares the
+     * same displayname.
+     * @prop {string} rawDisplayName The ambiguous displayname of this room member.
+     * @prop {Number} powerLevel The power level for this room member.
+     * @prop {Number} powerLevelNorm The normalised power level (0-100) for this
+     * room member.
+     * @prop {User} user The User object for this room member, if one exists.
+     * @prop {string} membership The membership state for this room member e.g. 'join'.
+     * @prop {Object} events The events describing this RoomMember.
+     * @prop {MatrixEvent} events.member The m.room.member event for this RoomMember.
+     * @prop {boolean} disambiguate True if the member's name is disambiguated.
+     */
+    constructor(public readonly roomId: string, public readonly userId: string) {
+        super();
+
+        this.name = userId;
+        this.rawDisplayName = userId;
+        this.updateModifiedTime();
+    }
+
+    /**
+     * Mark the member as coming from a channel that is not sync
+     */
+    public markOutOfBand(): void {
+        this._isOutOfBand = true;
+    }
+
+    /**
+     * @return {boolean} does the member come from a channel that is not sync?
+     * This is used to store the member seperately
+     * from the sync state so it available across browser sessions.
+     */
+    public isOutOfBand(): boolean {
+        return this._isOutOfBand;
+    }
+
+    /**
+     * Update this room member's membership event. May fire "RoomMember.name" if
+     * this event updates this member's name.
+     * @param {MatrixEvent} event The <code>m.room.member</code> event
+     * @param {RoomState} roomState Optional. The room state to take into account
+     * when calculating (e.g. for disambiguating users with the same name).
+     * @fires module:client~MatrixClient#event:"RoomMember.name"
+     * @fires module:client~MatrixClient#event:"RoomMember.membership"
+     */
+    public setMembershipEvent(event: MatrixEvent, roomState: RoomState): void {
+        const displayName = event.getDirectionalContent().displayname;
+
+        if (event.getType() !== "m.room.member") {
+            return;
+        }
+
+        this._isOutOfBand = false;
+
+        this.events.member = event;
+
+        const oldMembership = this.membership;
+        this.membership = event.getDirectionalContent().membership;
+
+        this.disambiguate = shouldDisambiguate(
+            this.userId,
+            displayName,
+            roomState,
+        );
+
+        const oldName = this.name;
+        this.name = calculateDisplayName(
+            this.userId,
+            displayName,
+            roomState,
+            this.disambiguate,
+        );
+
+        this.rawDisplayName = event.getDirectionalContent().displayname || this.userId;
+        if (oldMembership !== this.membership) {
+            this.updateModifiedTime();
+            this.emit("RoomMember.membership", event, this, oldMembership);
+        }
+        if (oldName !== this.name) {
+            this.updateModifiedTime();
+            this.emit("RoomMember.name", event, this, oldName);
+        }
+    }
+
+    /**
+     * Update this room member's power level event. May fire
+     * "RoomMember.powerLevel" if this event updates this member's power levels.
+     * @param {MatrixEvent} powerLevelEvent The <code>m.room.power_levels</code>
+     * event
+     * @fires module:client~MatrixClient#event:"RoomMember.powerLevel"
+     */
+    public setPowerLevelEvent(powerLevelEvent: MatrixEvent): void {
+        if (powerLevelEvent.getType() !== "m.room.power_levels") {
+            return;
+        }
+
+        const evContent = powerLevelEvent.getDirectionalContent();
+
+        let maxLevel = evContent.users_default || 0;
+        const users = evContent.users || {};
+        Object.values(users).forEach(function(lvl: number) {
+            maxLevel = Math.max(maxLevel, lvl);
+        });
+        const oldPowerLevel = this.powerLevel;
+        const oldPowerLevelNorm = this.powerLevelNorm;
+
+        if (users[this.userId] !== undefined && Number.isInteger(users[this.userId])) {
+            this.powerLevel = users[this.userId];
+        } else if (evContent.users_default !== undefined) {
+            this.powerLevel = evContent.users_default;
+        } else {
+            this.powerLevel = 0;
+        }
+        this.powerLevelNorm = 0;
+        if (maxLevel > 0) {
+            this.powerLevelNorm = (this.powerLevel * 100) / maxLevel;
+        }
+
+        // emit for changes in powerLevelNorm as well (since the app will need to
+        // redraw everyone's level if the max has changed)
+        if (oldPowerLevel !== this.powerLevel || oldPowerLevelNorm !== this.powerLevelNorm) {
+            this.updateModifiedTime();
+            this.emit("RoomMember.powerLevel", powerLevelEvent, this);
+        }
+    }
+
+    /**
+     * Update this room member's typing event. May fire "RoomMember.typing" if
+     * this event changes this member's typing state.
+     * @param {MatrixEvent} event The typing event
+     * @fires module:client~MatrixClient#event:"RoomMember.typing"
+     */
+    public setTypingEvent(event: MatrixEvent): void {
+        if (event.getType() !== "m.typing") {
+            return;
+        }
+        const oldTyping = this.typing;
+        this.typing = false;
+        const typingList = event.getContent().user_ids;
+        if (!Array.isArray(typingList)) {
+            // malformed event :/ bail early. TODO: whine?
+            return;
+        }
+        if (typingList.indexOf(this.userId) !== -1) {
+            this.typing = true;
+        }
+        if (oldTyping !== this.typing) {
+            this.updateModifiedTime();
+            this.emit("RoomMember.typing", event, this);
+        }
+    }
+
+    /**
+     * Update the last modified time to the current time.
+     */
+    private updateModifiedTime() {
+        this._modified = Date.now();
+    }
+
+    /**
+     * Get the timestamp when this RoomMember was last updated. This timestamp is
+     * updated when properties on this RoomMember are updated.
+     * It is updated <i>before</i> firing events.
+     * @return {number} The timestamp
+     */
+    public getLastModifiedTime(): number {
+        return this._modified;
+    }
+
+    public isKicked(): boolean {
+        return this.membership === "leave" &&
+            this.events.member.getSender() !== this.events.member.getStateKey();
+    }
+
+    /**
+     * If this member was invited with the is_direct flag set, return
+     * the user that invited this member
+     * @return {string} user id of the inviter
+     */
+    public getDMInviter(): string {
+        // when not available because that room state hasn't been loaded in,
+        // we don't really know, but more likely to not be a direct chat
+        if (this.events.member) {
+            // TODO: persist the is_direct flag on the member as more member events
+            //       come in caused by displayName changes.
+
+            // the is_direct flag is set on the invite member event.
+            // This is copied on the prev_content section of the join member event
+            // when the invite is accepted.
+
+            const memberEvent = this.events.member;
+            let memberContent = memberEvent.getContent();
+            let inviteSender = memberEvent.getSender();
+
+            if (memberContent.membership === "join") {
+                memberContent = memberEvent.getPrevContent();
+                inviteSender = memberEvent.getUnsigned().prev_sender;
+            }
+
+            if (memberContent.membership === "invite" && memberContent.is_direct) {
+                return inviteSender;
+            }
+        }
+    }
+
+    /**
+     * Get the avatar URL for a room member.
+     * @param {string} baseUrl The base homeserver URL See
+     * {@link module:client~MatrixClient#getHomeserverUrl}.
+     * @param {Number} width The desired width of the thumbnail.
+     * @param {Number} height The desired height of the thumbnail.
+     * @param {string} resizeMethod The thumbnail resize method to use, either
+     * "crop" or "scale".
+     * @param {Boolean} allowDefault (optional) Passing false causes this method to
+     * return null if the user has no avatar image. Otherwise, a default image URL
+     * will be returned. Default: true. (Deprecated)
+     * @param {Boolean} allowDirectLinks (optional) If true, the avatar URL will be
+     * returned even if it is a direct hyperlink rather than a matrix content URL.
+     * If false, any non-matrix content URLs will be ignored. Setting this option to
+     * true will expose URLs that, if fetched, will leak information about the user
+     * to anyone who they share a room with.
+     * @return {?string} the avatar URL or null.
+     */
+    public getAvatarUrl(
+        baseUrl: string,
+        width: number,
+        height: number,
+        resizeMethod: string,
+        allowDefault = true,
+        allowDirectLinks: boolean,
+    ): string | null {
+        const rawUrl = this.getMxcAvatarUrl();
+
+        if (!rawUrl && !allowDefault) {
+            return null;
+        }
+        const httpUrl = getHttpUriForMxc(baseUrl, rawUrl, width, height, resizeMethod, allowDirectLinks);
+        if (httpUrl) {
+            return httpUrl;
+        }
+        return null;
+    }
+
+    /**
+     * get the mxc avatar url, either from a state event, or from a lazily loaded member
+     * @return {string} the mxc avatar url
+     */
+    public getMxcAvatarUrl(): string | null {
+        if (this.events.member) {
+            return this.events.member.getDirectionalContent().avatar_url;
+        } else if (this.user) {
+            return this.user.avatarUrl;
+        }
+        return null;
+    }
+}
+
+const MXID_PATTERN = /@.+:.+/;
+const LTR_RTL_PATTERN = /[\u200E\u200F\u202A-\u202F]/;
+
+function shouldDisambiguate(selfUserId: string, displayName: string, roomState: RoomState): boolean {
+    if (!displayName || displayName === selfUserId) return false;
+
+    // First check if the displayname is something we consider truthy
+    // after stripping it of zero width characters and padding spaces
+    if (!utils.removeHiddenChars(displayName)) return false;
+
+    if (!roomState) return false;
+
+    // Next check if the name contains something that look like a mxid
+    // If it does, it may be someone trying to impersonate someone else
+    // Show full mxid in this case
+    if (MXID_PATTERN.test(displayName)) return true;
+
+    // Also show mxid if the display name contains any LTR/RTL characters as these
+    // make it very difficult for us to find similar *looking* display names
+    // E.g "Mark" could be cloned by writing "kraM" but in RTL.
+    if (LTR_RTL_PATTERN.test(displayName)) return true;
+
+    // Also show mxid if there are other people with the same or similar
+    // displayname, after hidden character removal.
+    const userIds = roomState.getUserIdsWithDisplayName(displayName);
+    if (userIds.some((u) => u !== selfUserId)) return true;
+
+    return false;
+}
+
+function calculateDisplayName(
+    selfUserId: string,
+    displayName: string,
+    roomState: RoomState,
+    disambiguate: boolean,
+): string {
+    if (disambiguate) return displayName + " (" + selfUserId + ")";
+
+    if (!displayName || displayName === selfUserId) return selfUserId;
+
+    // First check if the displayname is something we consider truthy
+    // after stripping it of zero width characters and padding spaces
+    if (!utils.removeHiddenChars(displayName)) return selfUserId;
+
+    return displayName;
+}
+
+/**
+ * Fires whenever any room member's name changes.
+ * @event module:client~MatrixClient#"RoomMember.name"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomMember} member The member whose RoomMember.name changed.
+ * @param {string?} oldName The previous name. Null if the member didn't have a
+ *    name previously.
+ * @example
+ * matrixClient.on("RoomMember.name", function(event, member){
+ *   var newName = member.name;
+ * });
+ */
+
+/**
+ * Fires whenever any room member's membership state changes.
+ * @event module:client~MatrixClient#"RoomMember.membership"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomMember} member The member whose RoomMember.membership changed.
+ * @param {string?} oldMembership The previous membership state. Null if it's a
+ *    new member.
+ * @example
+ * matrixClient.on("RoomMember.membership", function(event, member, oldMembership){
+ *   var newState = member.membership;
+ * });
+ */
+
+/**
+ * Fires whenever any room member's typing state changes.
+ * @event module:client~MatrixClient#"RoomMember.typing"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomMember} member The member whose RoomMember.typing changed.
+ * @example
+ * matrixClient.on("RoomMember.typing", function(event, member){
+ *   var isTyping = member.typing;
+ * });
+ */
+
+/**
+ * Fires whenever any room member's power level changes.
+ * @event module:client~MatrixClient#"RoomMember.powerLevel"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomMember} member The member whose RoomMember.powerLevel changed.
+ * @example
+ * matrixClient.on("RoomMember.powerLevel", function(event, member){
+ *   var newPowerLevel = member.powerLevel;
+ *   var newNormPowerLevel = member.powerLevelNorm;
+ * });
+ */

src/models/room-state.js

@@ -1,832 +0,0 @@
-/*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/room-state
- */
-
-import { EventEmitter } from "events";
-import { RoomMember } from "./room-member";
-import { logger } from '../logger';
-import * as utils from "../utils";
-import { EventType } from "../@types/event";
-
-// possible statuses for out-of-band member loading
-const OOB_STATUS_NOTSTARTED = 1;
-const OOB_STATUS_INPROGRESS = 2;
-const OOB_STATUS_FINISHED = 3;
-
-/**
- * Construct room state.
- *
- * Room State represents the state of the room at a given point.
- * It can be mutated by adding state events to it.
- * There are two types of room member associated with a state event:
- * normal member objects (accessed via getMember/getMembers) which mutate
- * with the state to represent the current state of that room/user, eg.
- * the object returned by getMember('@bob:example.com') will mutate to
- * get a different display name if Bob later changes his display name
- * in the room.
- * There are also 'sentinel' members (accessed via getSentinelMember).
- * These also represent the state of room members at the point in time
- * represented by the RoomState object, but unlike objects from getMember,
- * sentinel objects will always represent the room state as at the time
- * getSentinelMember was called, so if Bob subsequently changes his display
- * name, a room member object previously acquired with getSentinelMember
- * will still have his old display name. Calling getSentinelMember again
- * after the display name change will return a new RoomMember object
- * with Bob's new display name.
- *
- * @constructor
- * @param {?string} roomId Optional. The ID of the room which has this state.
- * If none is specified it just tracks paginationTokens, useful for notifTimelineSet
- * @param {?object} oobMemberFlags Optional. The state of loading out of bound members.
- * As the timeline might get reset while they are loading, this state needs to be inherited
- * and shared when the room state is cloned for the new timeline.
- * This should only be passed from clone.
- * @prop {Object.<string, RoomMember>} members The room member dictionary, keyed
- * on the user's ID.
- * @prop {Object.<string, Object.<string, MatrixEvent>>} events The state
- * events dictionary, keyed on the event type and then the state_key value.
- * @prop {string} paginationToken The pagination token for this state.
- */
-export function RoomState(roomId, oobMemberFlags = undefined) {
-    this.roomId = roomId;
-    this.members = {
-        // userId: RoomMember
-    };
-    this.events = new Map(); // Map<eventType, Map<stateKey, MatrixEvent>>
-    this.paginationToken = null;
-
-    this._sentinels = {
-        // userId: RoomMember
-    };
-    this._updateModifiedTime();
-
-    // stores fuzzy matches to a list of userIDs (applies utils.removeHiddenChars to keys)
-    this._displayNameToUserIds = {};
-    this._userIdsToDisplayNames = {};
-    this._tokenToInvite = {}; // 3pid invite state_key to m.room.member invite
-    this._joinedMemberCount = null; // cache of the number of joined members
-    // joined members count from summary api
-    // once set, we know the server supports the summary api
-    // and we should only trust that
-    // we could also only trust that before OOB members
-    // are loaded but doesn't seem worth the hassle atm
-    this._summaryJoinedMemberCount = null;
-    // same for invited member count
-    this._invitedMemberCount = null;
-    this._summaryInvitedMemberCount = null;
-
-    if (!oobMemberFlags) {
-        oobMemberFlags = {
-            status: OOB_STATUS_NOTSTARTED,
-        };
-    }
-    this._oobMemberFlags = oobMemberFlags;
-}
-utils.inherits(RoomState, EventEmitter);
-
-/**
- * Returns the number of joined members in this room
- * This method caches the result.
- * @return {integer} The number of members in this room whose membership is 'join'
- */
-RoomState.prototype.getJoinedMemberCount = function() {
-    if (this._summaryJoinedMemberCount !== null) {
-        return this._summaryJoinedMemberCount;
-    }
-    if (this._joinedMemberCount === null) {
-        this._joinedMemberCount = this.getMembers().reduce((count, m) => {
-            return m.membership === 'join' ? count + 1 : count;
-        }, 0);
-    }
-    return this._joinedMemberCount;
-};
-
-/**
- * Set the joined member count explicitly (like from summary part of the sync response)
- * @param {number} count the amount of joined members
- */
-RoomState.prototype.setJoinedMemberCount = function(count) {
-    this._summaryJoinedMemberCount = count;
-};
-/**
- * Returns the number of invited members in this room
- * @return {integer} The number of members in this room whose membership is 'invite'
- */
-RoomState.prototype.getInvitedMemberCount = function() {
-    if (this._summaryInvitedMemberCount !== null) {
-        return this._summaryInvitedMemberCount;
-    }
-    if (this._invitedMemberCount === null) {
-        this._invitedMemberCount = this.getMembers().reduce((count, m) => {
-            return m.membership === 'invite' ? count + 1 : count;
-        }, 0);
-    }
-    return this._invitedMemberCount;
-};
-
-/**
- * Set the amount of invited members in this room
- * @param {number} count the amount of invited members
- */
-RoomState.prototype.setInvitedMemberCount = function(count) {
-    this._summaryInvitedMemberCount = count;
-};
-
-/**
- * Get all RoomMembers in this room.
- * @return {Array<RoomMember>} A list of RoomMembers.
- */
-RoomState.prototype.getMembers = function() {
-    return Object.values(this.members);
-};
-
-/**
- * Get all RoomMembers in this room, excluding the user IDs provided.
- * @param {Array<string>} excludedIds The user IDs to exclude.
- * @return {Array<RoomMember>} A list of RoomMembers.
- */
-RoomState.prototype.getMembersExcept = function(excludedIds) {
-    return Object.values(this.members)
-        .filter((m) => !excludedIds.includes(m.userId));
-};
-
-/**
- * Get a room member by their user ID.
- * @param {string} userId The room member's user ID.
- * @return {RoomMember} The member or null if they do not exist.
- */
-RoomState.prototype.getMember = function(userId) {
-    return this.members[userId] || null;
-};
-
-/**
- * Get a room member whose properties will not change with this room state. You
- * typically want this if you want to attach a RoomMember to a MatrixEvent which
- * may no longer be represented correctly by Room.currentState or Room.oldState.
- * The term 'sentinel' refers to the fact that this RoomMember is an unchanging
- * guardian for state at this particular point in time.
- * @param {string} userId The room member's user ID.
- * @return {RoomMember} The member or null if they do not exist.
- */
-RoomState.prototype.getSentinelMember = function(userId) {
-    if (!userId) return null;
-    let sentinel = this._sentinels[userId];
-
-    if (sentinel === undefined) {
-        sentinel = new RoomMember(this.roomId, userId);
-        const member = this.members[userId];
-        if (member) {
-            sentinel.setMembershipEvent(member.events.member, this);
-        }
-        this._sentinels[userId] = sentinel;
-    }
-    return sentinel;
-};
-
-/**
- * Get state events from the state of the room.
- * @param {string} eventType The event type of the state event.
- * @param {string} stateKey Optional. The state_key of the state event. If
- * this is <code>undefined</code> then all matching state events will be
- * returned.
- * @return {MatrixEvent[]|MatrixEvent} A list of events if state_key was
- * <code>undefined</code>, else a single event (or null if no match found).
- */
-RoomState.prototype.getStateEvents = function(eventType, stateKey) {
-    if (!this.events.has(eventType)) {
-        // no match
-        return stateKey === undefined ? [] : null;
-    }
-    if (stateKey === undefined) { // return all values
-        return Array.from(this.events.get(eventType).values());
-    }
-    const event = this.events.get(eventType).get(stateKey);
-    return event ? event : null;
-};
-
-/**
- * Creates a copy of this room state so that mutations to either won't affect the other.
- * @return {RoomState} the copy of the room state
- */
-RoomState.prototype.clone = function() {
-    const copy = new RoomState(this.roomId, this._oobMemberFlags);
-
-    // Ugly hack: because setStateEvents will mark
-    // members as susperseding future out of bound members
-    // if loading is in progress (through _oobMemberFlags)
-    // since these are not new members, we're merely copying them
-    // set the status to not started
-    // after copying, we set back the status
-    const status = this._oobMemberFlags.status;
-    this._oobMemberFlags.status = OOB_STATUS_NOTSTARTED;
-
-    Array.from(this.events.values()).forEach((eventsByStateKey) => {
-        copy.setStateEvents(Array.from(eventsByStateKey.values()));
-    });
-
-    // Ugly hack: see above
-    this._oobMemberFlags.status = status;
-
-    if (this._summaryInvitedMemberCount !== null) {
-        copy.setInvitedMemberCount(this.getInvitedMemberCount());
-    }
-    if (this._summaryJoinedMemberCount !== null) {
-        copy.setJoinedMemberCount(this.getJoinedMemberCount());
-    }
-
-    // copy out of band flags if needed
-    if (this._oobMemberFlags.status == OOB_STATUS_FINISHED) {
-        // copy markOutOfBand flags
-        this.getMembers().forEach((member) => {
-            if (member.isOutOfBand()) {
-                const copyMember = copy.getMember(member.userId);
-                copyMember.markOutOfBand();
-            }
-        });
-    }
-
-    return copy;
-};
-
-/**
- * Add previously unknown state events.
- * When lazy loading members while back-paginating,
- * the relevant room state for the timeline chunk at the end
- * of the chunk can be set with this method.
- * @param {MatrixEvent[]} events state events to prepend
- */
-RoomState.prototype.setUnknownStateEvents = function(events) {
-    const unknownStateEvents = events.filter((event) => {
-        return !this.events.has(event.getType()) ||
-            !this.events.get(event.getType()).has(event.getStateKey());
-    });
-
-    this.setStateEvents(unknownStateEvents);
-};
-
-/**
- * Add an array of one or more state MatrixEvents, overwriting
- * any existing state with the same {type, stateKey} tuple. Will fire
- * "RoomState.events" for every event added. May fire "RoomState.members"
- * if there are <code>m.room.member</code> events.
- * @param {MatrixEvent[]} stateEvents a list of state events for this room.
- * @fires module:client~MatrixClient#event:"RoomState.members"
- * @fires module:client~MatrixClient#event:"RoomState.newMember"
- * @fires module:client~MatrixClient#event:"RoomState.events"
- */
-RoomState.prototype.setStateEvents = function(stateEvents) {
-    const self = this;
-    this._updateModifiedTime();
-
-    // update the core event dict
-    stateEvents.forEach(function(event) {
-        if (event.getRoomId() !== self.roomId) {
-            return;
-        }
-        if (!event.isState()) {
-            return;
-        }
-
-        const lastStateEvent = self._getStateEventMatching(event);
-        self._setStateEvent(event);
-        if (event.getType() === "m.room.member") {
-            _updateDisplayNameCache(
-                self, event.getStateKey(), event.getContent().displayname,
-            );
-            _updateThirdPartyTokenCache(self, event);
-        }
-        self.emit("RoomState.events", event, self, lastStateEvent);
-    });
-
-    // update higher level data structures. This needs to be done AFTER the
-    // core event dict as these structures may depend on other state events in
-    // the given array (e.g. disambiguating display names in one go to do both
-    // clashing names rather than progressively which only catches 1 of them).
-    stateEvents.forEach(function(event) {
-        if (event.getRoomId() !== self.roomId) {
-            return;
-        }
-        if (!event.isState()) {
-            return;
-        }
-
-        if (event.getType() === "m.room.member") {
-            const userId = event.getStateKey();
-
-            // leave events apparently elide the displayname or avatar_url,
-            // so let's fake one up so that we don't leak user ids
-            // into the timeline
-            if (event.getContent().membership === "leave" ||
-                event.getContent().membership === "ban") {
-                event.getContent().avatar_url =
-                    event.getContent().avatar_url ||
-                    event.getPrevContent().avatar_url;
-                event.getContent().displayname =
-                    event.getContent().displayname ||
-                    event.getPrevContent().displayname;
-            }
-
-            const member = self._getOrCreateMember(userId, event);
-            member.setMembershipEvent(event, self);
-
-            self._updateMember(member);
-            self.emit("RoomState.members", event, self, member);
-        } else if (event.getType() === "m.room.power_levels") {
-            // events with unknown state keys should be ignored
-            // and should not aggregate onto members power levels
-            if (event.getStateKey() !== "") {
-                return;
-            }
-            const members = Object.values(self.members);
-            members.forEach(function(member) {
-                // We only propagate `RoomState.members` event if the
-                // power levels has been changed
-                // large room suffer from large re-rendering especially when not needed
-                const oldLastModified = member.getLastModifiedTime();
-                member.setPowerLevelEvent(event);
-                if (oldLastModified !== member.getLastModifiedTime()) {
-                    self.emit("RoomState.members", event, self, member);
-                }
-            });
-
-            // assume all our sentinels are now out-of-date
-            self._sentinels = {};
-        }
-    });
-};
-
-/**
- * Looks up a member by the given userId, and if it doesn't exist,
- * create it and emit the `RoomState.newMember` event.
- * This method makes sure the member is added to the members dictionary
- * before emitting, as this is done from setStateEvents and _setOutOfBandMember.
- * @param {string} userId the id of the user to look up
- * @param {MatrixEvent} event the membership event for the (new) member. Used to emit.
- * @fires module:client~MatrixClient#event:"RoomState.newMember"
- * @returns {RoomMember} the member, existing or newly created.
- */
-RoomState.prototype._getOrCreateMember = function(userId, event) {
-    let member = this.members[userId];
-    if (!member) {
-        member = new RoomMember(this.roomId, userId);
-        // add member to members before emitting any events,
-        // as event handlers often lookup the member
-        this.members[userId] = member;
-        this.emit("RoomState.newMember", event, this, member);
-    }
-    return member;
-};
-
-RoomState.prototype._setStateEvent = function(event) {
-    if (!this.events.has(event.getType())) {
-        this.events.set(event.getType(), new Map());
-    }
-    this.events.get(event.getType()).set(event.getStateKey(), event);
-};
-
-RoomState.prototype._getStateEventMatching = function(event) {
-    if (!this.events.has(event.getType())) return null;
-    return this.events.get(event.getType()).get(event.getStateKey());
-};
-
-RoomState.prototype._updateMember = function(member) {
-    // this member may have a power level already, so set it.
-    const pwrLvlEvent = this.getStateEvents("m.room.power_levels", "");
-    if (pwrLvlEvent) {
-        member.setPowerLevelEvent(pwrLvlEvent);
-    }
-
-    // blow away the sentinel which is now outdated
-    delete this._sentinels[member.userId];
-
-    this.members[member.userId] = member;
-    this._joinedMemberCount = null;
-    this._invitedMemberCount = null;
-};
-
-/**
- * Get the out-of-band members loading state, whether loading is needed or not.
- * Note that loading might be in progress and hence isn't needed.
- * @return {bool} whether or not the members of this room need to be loaded
- */
-RoomState.prototype.needsOutOfBandMembers = function() {
-    return this._oobMemberFlags.status === OOB_STATUS_NOTSTARTED;
-};
-
-/**
- * Mark this room state as waiting for out-of-band members,
- * ensuring it doesn't ask for them to be requested again
- * through needsOutOfBandMembers
- */
-RoomState.prototype.markOutOfBandMembersStarted = function() {
-    if (this._oobMemberFlags.status !== OOB_STATUS_NOTSTARTED) {
-        return;
-    }
-    this._oobMemberFlags.status = OOB_STATUS_INPROGRESS;
-};
-
-/**
- * Mark this room state as having failed to fetch out-of-band members
- */
-RoomState.prototype.markOutOfBandMembersFailed = function() {
-    if (this._oobMemberFlags.status !== OOB_STATUS_INPROGRESS) {
-        return;
-    }
-    this._oobMemberFlags.status = OOB_STATUS_NOTSTARTED;
-};
-
-/**
- * Clears the loaded out-of-band members
- */
-RoomState.prototype.clearOutOfBandMembers = function() {
-    let count = 0;
-    Object.keys(this.members).forEach((userId) => {
-        const member = this.members[userId];
-        if (member.isOutOfBand()) {
-            ++count;
-            delete this.members[userId];
-        }
-    });
-    logger.log(`LL: RoomState removed ${count} members...`);
-    this._oobMemberFlags.status = OOB_STATUS_NOTSTARTED;
-};
-
-/**
- * Sets the loaded out-of-band members.
- * @param {MatrixEvent[]} stateEvents array of membership state events
- */
-RoomState.prototype.setOutOfBandMembers = function(stateEvents) {
-    logger.log(`LL: RoomState about to set ${stateEvents.length} OOB members ...`);
-    if (this._oobMemberFlags.status !== OOB_STATUS_INPROGRESS) {
-        return;
-    }
-    logger.log(`LL: RoomState put in OOB_STATUS_FINISHED state ...`);
-    this._oobMemberFlags.status = OOB_STATUS_FINISHED;
-    stateEvents.forEach((e) => this._setOutOfBandMember(e));
-};
-
-/**
- * Sets a single out of band member, used by both setOutOfBandMembers and clone
- * @param {MatrixEvent} stateEvent membership state event
- */
-RoomState.prototype._setOutOfBandMember = function(stateEvent) {
-    if (stateEvent.getType() !== 'm.room.member') {
-        return;
-    }
-    const userId = stateEvent.getStateKey();
-    const existingMember = this.getMember(userId);
-    // never replace members received as part of the sync
-    if (existingMember && !existingMember.isOutOfBand()) {
-        return;
-    }
-
-    const member = this._getOrCreateMember(userId, stateEvent);
-    member.setMembershipEvent(stateEvent, this);
-    // needed to know which members need to be stored seperately
-    // as they are not part of the sync accumulator
-    // this is cleared by setMembershipEvent so when it's updated through /sync
-    member.markOutOfBand();
-
-    _updateDisplayNameCache(this, member.userId, member.name);
-
-    this._setStateEvent(stateEvent);
-    this._updateMember(member);
-    this.emit("RoomState.members", stateEvent, this, member);
-};
-
-/**
- * Set the current typing event for this room.
- * @param {MatrixEvent} event The typing event
- */
-RoomState.prototype.setTypingEvent = function(event) {
-    Object.values(this.members).forEach(function(member) {
-        member.setTypingEvent(event);
-    });
-};
-
-/**
- * Get the m.room.member event which has the given third party invite token.
- *
- * @param {string} token The token
- * @return {?MatrixEvent} The m.room.member event or null
- */
-RoomState.prototype.getInviteForThreePidToken = function(token) {
-    return this._tokenToInvite[token] || null;
-};
-
-/**
- * Update the last modified time to the current time.
- */
-RoomState.prototype._updateModifiedTime = function() {
-    this._modified = Date.now();
-};
-
-/**
- * Get the timestamp when this room state was last updated. This timestamp is
- * updated when this object has received new state events.
- * @return {number} The timestamp
- */
-RoomState.prototype.getLastModifiedTime = function() {
-    return this._modified;
-};
-
-/**
- * Get user IDs with the specified or similar display names.
- * @param {string} displayName The display name to get user IDs from.
- * @return {string[]} An array of user IDs or an empty array.
- */
-RoomState.prototype.getUserIdsWithDisplayName = function(displayName) {
-    return this._displayNameToUserIds[utils.removeHiddenChars(displayName)] || [];
-};
-
-/**
- * Returns true if userId is in room, event is not redacted and either sender of
- * mxEvent or has power level sufficient to redact events other than their own.
- * @param {MatrixEvent} mxEvent The event to test permission for
- * @param {string} userId The user ID of the user to test permission for
- * @return {boolean} true if the given used ID can redact given event
- */
-RoomState.prototype.maySendRedactionForEvent = function(mxEvent, userId) {
-    const member = this.getMember(userId);
-    if (!member || member.membership === 'leave') return false;
-
-    if (mxEvent.status || mxEvent.isRedacted()) return false;
-
-    // The user may have been the sender, but they can't redact their own message
-    // if redactions are blocked.
-    const canRedact = this.maySendEvent("m.room.redaction", userId);
-    if (mxEvent.getSender() === userId) return canRedact;
-
-    return this._hasSufficientPowerLevelFor('redact', member.powerLevel);
-};
-
-/**
- * Returns true if the given power level is sufficient for action
- * @param {string} action The type of power level to check
- * @param {number} powerLevel The power level of the member
- * @return {boolean} true if the given power level is sufficient
- */
-RoomState.prototype._hasSufficientPowerLevelFor = function(action, powerLevel) {
-    const powerLevelsEvent = this.getStateEvents('m.room.power_levels', '');
-
-    let powerLevels = {};
-    if (powerLevelsEvent) {
-        powerLevels = powerLevelsEvent.getContent();
-    }
-
-    let requiredLevel = 50;
-    if (utils.isNumber(powerLevels[action])) {
-        requiredLevel = powerLevels[action];
-    }
-
-    return powerLevel >= requiredLevel;
-};
-
-/**
- * Short-form for maySendEvent('m.room.message', userId)
- * @param {string} userId The user ID of the user to test permission for
- * @return {boolean} true if the given user ID should be permitted to send
- *                   message events into the given room.
- */
-RoomState.prototype.maySendMessage = function(userId) {
-    return this._maySendEventOfType('m.room.message', userId, false);
-};
-
-/**
- * Returns true if the given user ID has permission to send a normal
- * event of type `eventType` into this room.
- * @param {string} eventType The type of event to test
- * @param {string} userId The user ID of the user to test permission for
- * @return {boolean} true if the given user ID should be permitted to send
- *                        the given type of event into this room,
- *                        according to the room's state.
- */
-RoomState.prototype.maySendEvent = function(eventType, userId) {
-    return this._maySendEventOfType(eventType, userId, false);
-};
-
-/**
- * Returns true if the given MatrixClient has permission to send a state
- * event of type `stateEventType` into this room.
- * @param {string} stateEventType The type of state events to test
- * @param {MatrixClient} cli The client to test permission for
- * @return {boolean} true if the given client should be permitted to send
- *                        the given type of state event into this room,
- *                        according to the room's state.
- */
-RoomState.prototype.mayClientSendStateEvent = function(stateEventType, cli) {
-    if (cli.isGuest()) {
-        return false;
-    }
-    return this.maySendStateEvent(stateEventType, cli.credentials.userId);
-};
-
-/**
- * Returns true if the given user ID has permission to send a state
- * event of type `stateEventType` into this room.
- * @param {string} stateEventType The type of state events to test
- * @param {string} userId The user ID of the user to test permission for
- * @return {boolean} true if the given user ID should be permitted to send
- *                        the given type of state event into this room,
- *                        according to the room's state.
- */
-RoomState.prototype.maySendStateEvent = function(stateEventType, userId) {
-    return this._maySendEventOfType(stateEventType, userId, true);
-};
-
-/**
- * Returns true if the given user ID has permission to send a normal or state
- * event of type `eventType` into this room.
- * @param {string} eventType The type of event to test
- * @param {string} userId The user ID of the user to test permission for
- * @param {boolean} state If true, tests if the user may send a state
-                          event of this type. Otherwise tests whether
-                          they may send a regular event.
- * @return {boolean} true if the given user ID should be permitted to send
- *                        the given type of event into this room,
- *                        according to the room's state.
- */
-RoomState.prototype._maySendEventOfType = function(eventType, userId, state) {
-    const power_levels_event = this.getStateEvents('m.room.power_levels', '');
-
-    let power_levels;
-    let events_levels = {};
-
-    let state_default = 0;
-    let events_default = 0;
-    let powerLevel = 0;
-    if (power_levels_event) {
-        power_levels = power_levels_event.getContent();
-        events_levels = power_levels.events || {};
-
-        if (Number.isFinite(power_levels.state_default)) {
-            state_default = power_levels.state_default;
-        } else {
-            state_default = 50;
-        }
-
-        const userPowerLevel = power_levels.users && power_levels.users[userId];
-        if (Number.isFinite(userPowerLevel)) {
-            powerLevel = userPowerLevel;
-        } else if (Number.isFinite(power_levels.users_default)) {
-            powerLevel = power_levels.users_default;
-        }
-
-        if (Number.isFinite(power_levels.events_default)) {
-            events_default = power_levels.events_default;
-        }
-    }
-
-    let required_level = state ? state_default : events_default;
-    if (Number.isFinite(events_levels[eventType])) {
-        required_level = events_levels[eventType];
-    }
-    return powerLevel >= required_level;
-};
-
-/**
- * Returns true if the given user ID has permission to trigger notification
- * of type `notifLevelKey`
- * @param {string} notifLevelKey The level of notification to test (eg. 'room')
- * @param {string} userId The user ID of the user to test permission for
- * @return {boolean} true if the given user ID has permission to trigger a
- *                        notification of this type.
- */
-RoomState.prototype.mayTriggerNotifOfType = function(notifLevelKey, userId) {
-    const member = this.getMember(userId);
-    if (!member) {
-        return false;
-    }
-
-    const powerLevelsEvent = this.getStateEvents('m.room.power_levels', '');
-
-    let notifLevel = 50;
-    if (
-        powerLevelsEvent &&
-        powerLevelsEvent.getContent() &&
-        powerLevelsEvent.getContent().notifications &&
-        utils.isNumber(powerLevelsEvent.getContent().notifications[notifLevelKey])
-    ) {
-        notifLevel = powerLevelsEvent.getContent().notifications[notifLevelKey];
-    }
-
-    return member.powerLevel >= notifLevel;
-};
-
-/**
- * Returns the join rule based on the m.room.join_rule state event, defaulting to `invite`.
- * @returns {string} the join_rule applied to this room
- */
-RoomState.prototype.getJoinRule = function() {
-    const joinRuleEvent = this.getStateEvents(EventType.RoomJoinRules, "");
-    const joinRuleContent = joinRuleEvent ? joinRuleEvent.getContent() : {};
-    return joinRuleContent["join_rule"] || "invite";
-};
-
-function _updateThirdPartyTokenCache(roomState, memberEvent) {
-    if (!memberEvent.getContent().third_party_invite) {
-        return;
-    }
-    const token = (memberEvent.getContent().third_party_invite.signed || {}).token;
-    if (!token) {
-        return;
-    }
-    const threePidInvite = roomState.getStateEvents(
-        "m.room.third_party_invite", token,
-    );
-    if (!threePidInvite) {
-        return;
-    }
-    roomState._tokenToInvite[token] = memberEvent;
-}
-
-function _updateDisplayNameCache(roomState, userId, displayName) {
-    const oldName = roomState._userIdsToDisplayNames[userId];
-    delete roomState._userIdsToDisplayNames[userId];
-    if (oldName) {
-        // Remove the old name from the cache.
-        // We clobber the user_id > name lookup but the name -> [user_id] lookup
-        // means we need to remove that user ID from that array rather than nuking
-        // the lot.
-        const strippedOldName = utils.removeHiddenChars(oldName);
-
-        const existingUserIds = roomState._displayNameToUserIds[strippedOldName];
-        if (existingUserIds) {
-            // remove this user ID from this array
-            const filteredUserIDs = existingUserIds.filter((id) => id !== userId);
-            roomState._displayNameToUserIds[strippedOldName] = filteredUserIDs;
-        }
-    }
-
-    roomState._userIdsToDisplayNames[userId] = displayName;
-
-    const strippedDisplayname = displayName && utils.removeHiddenChars(displayName);
-    // an empty stripped displayname (undefined/'') will be set to MXID in room-member.js
-    if (strippedDisplayname) {
-        if (!roomState._displayNameToUserIds[strippedDisplayname]) {
-            roomState._displayNameToUserIds[strippedDisplayname] = [];
-        }
-        roomState._displayNameToUserIds[strippedDisplayname].push(userId);
-    }
-}
-
-/**
- * Fires whenever the event dictionary in room state is updated.
- * @event module:client~MatrixClient#"RoomState.events"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomState} state The room state whose RoomState.events dictionary
- * was updated.
- * @param {MatrixEvent} prevEvent The event being replaced by the new state, if
- * known. Note that this can differ from `getPrevContent()` on the new state event
- * as this is the store's view of the last state, not the previous state provided
- * by the server.
- * @example
- * matrixClient.on("RoomState.events", function(event, state, prevEvent){
- *   var newStateEvent = event;
- * });
- */
-
-/**
- * Fires whenever a member in the members dictionary is updated in any way.
- * @event module:client~MatrixClient#"RoomState.members"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomState} state The room state whose RoomState.members dictionary
- * was updated.
- * @param {RoomMember} member The room member that was updated.
- * @example
- * matrixClient.on("RoomState.members", function(event, state, member){
- *   var newMembershipState = member.membership;
- * });
- */
-
- /**
- * Fires whenever a member is added to the members dictionary. The RoomMember
- * will not be fully populated yet (e.g. no membership state) but will already
- * be available in the members dictionary.
- * @event module:client~MatrixClient#"RoomState.newMember"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomState} state The room state whose RoomState.members dictionary
- * was updated with a new entry.
- * @param {RoomMember} member The room member that was added.
- * @example
- * matrixClient.on("RoomState.newMember", function(event, state, member){
- *   // add event listeners on 'member'
- * });
- */

src/models/room-state.ts

@@ -0,0 +1,825 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module models/room-state
+ */
+
+import { EventEmitter } from "events";
+
+import { RoomMember } from "./room-member";
+import { logger } from '../logger';
+import * as utils from "../utils";
+import { EventType } from "../@types/event";
+import { MatrixEvent } from "./event";
+import { MatrixClient } from "../client";
+
+// possible statuses for out-of-band member loading
+enum OobStatus {
+    NotStarted,
+    InProgress,
+    Finished,
+}
+
+export class RoomState extends EventEmitter {
+    private sentinels: Record<string, RoomMember> = {}; // userId: RoomMember
+    // stores fuzzy matches to a list of userIDs (applies utils.removeHiddenChars to keys)
+    private displayNameToUserIds: Record<string, string[]> = {};
+    private userIdsToDisplayNames: Record<string, string> = {};
+    private tokenToInvite: Record<string, MatrixEvent> = {}; // 3pid invite state_key to m.room.member invite
+    private joinedMemberCount: number = null; // cache of the number of joined members
+    // joined members count from summary api
+    // once set, we know the server supports the summary api
+    // and we should only trust that
+    // we could also only trust that before OOB members
+    // are loaded but doesn't seem worth the hassle atm
+    private summaryJoinedMemberCount: number = null;
+    // same for invited member count
+    private invitedMemberCount: number = null;
+    private summaryInvitedMemberCount: number = null;
+    private modified: number;
+
+    // XXX: Should be read-only
+    public members: Record<string, RoomMember> = {}; // userId: RoomMember
+    public events = new Map<string, Map<string, MatrixEvent>>(); // Map<eventType, Map<stateKey, MatrixEvent>>
+    public paginationToken: string = null;
+
+    /**
+     * Construct room state.
+     *
+     * Room State represents the state of the room at a given point.
+     * It can be mutated by adding state events to it.
+     * There are two types of room member associated with a state event:
+     * normal member objects (accessed via getMember/getMembers) which mutate
+     * with the state to represent the current state of that room/user, eg.
+     * the object returned by getMember('@bob:example.com') will mutate to
+     * get a different display name if Bob later changes his display name
+     * in the room.
+     * There are also 'sentinel' members (accessed via getSentinelMember).
+     * These also represent the state of room members at the point in time
+     * represented by the RoomState object, but unlike objects from getMember,
+     * sentinel objects will always represent the room state as at the time
+     * getSentinelMember was called, so if Bob subsequently changes his display
+     * name, a room member object previously acquired with getSentinelMember
+     * will still have his old display name. Calling getSentinelMember again
+     * after the display name change will return a new RoomMember object
+     * with Bob's new display name.
+     *
+     * @constructor
+     * @param {?string} roomId Optional. The ID of the room which has this state.
+     * If none is specified it just tracks paginationTokens, useful for notifTimelineSet
+     * @param {?object} oobMemberFlags Optional. The state of loading out of bound members.
+     * As the timeline might get reset while they are loading, this state needs to be inherited
+     * and shared when the room state is cloned for the new timeline.
+     * This should only be passed from clone.
+     * @prop {Object.<string, RoomMember>} members The room member dictionary, keyed
+     * on the user's ID.
+     * @prop {Object.<string, Object.<string, MatrixEvent>>} events The state
+     * events dictionary, keyed on the event type and then the state_key value.
+     * @prop {string} paginationToken The pagination token for this state.
+     */
+    constructor(public readonly roomId: string, private oobMemberFlags = { status: OobStatus.NotStarted }) {
+        super();
+        this.updateModifiedTime();
+    }
+
+    /**
+     * Returns the number of joined members in this room
+     * This method caches the result.
+     * @return {number} The number of members in this room whose membership is 'join'
+     */
+    public getJoinedMemberCount(): number {
+        if (this.summaryJoinedMemberCount !== null) {
+            return this.summaryJoinedMemberCount;
+        }
+        if (this.joinedMemberCount === null) {
+            this.joinedMemberCount = this.getMembers().reduce((count, m) => {
+                return m.membership === 'join' ? count + 1 : count;
+            }, 0);
+        }
+        return this.joinedMemberCount;
+    }
+
+    /**
+     * Set the joined member count explicitly (like from summary part of the sync response)
+     * @param {number} count the amount of joined members
+     */
+    public setJoinedMemberCount(count: number): void {
+        this.summaryJoinedMemberCount = count;
+    }
+
+    /**
+     * Returns the number of invited members in this room
+     * @return {number} The number of members in this room whose membership is 'invite'
+     */
+    public getInvitedMemberCount(): number {
+        if (this.summaryInvitedMemberCount !== null) {
+            return this.summaryInvitedMemberCount;
+        }
+        if (this.invitedMemberCount === null) {
+            this.invitedMemberCount = this.getMembers().reduce((count, m) => {
+                return m.membership === 'invite' ? count + 1 : count;
+            }, 0);
+        }
+        return this.invitedMemberCount;
+    }
+
+    /**
+     * Set the amount of invited members in this room
+     * @param {number} count the amount of invited members
+     */
+    public setInvitedMemberCount(count: number): void {
+        this.summaryInvitedMemberCount = count;
+    }
+
+    /**
+     * Get all RoomMembers in this room.
+     * @return {Array<RoomMember>} A list of RoomMembers.
+     */
+    public getMembers(): RoomMember[] {
+        return Object.values(this.members);
+    }
+
+    /**
+     * Get all RoomMembers in this room, excluding the user IDs provided.
+     * @param {Array<string>} excludedIds The user IDs to exclude.
+     * @return {Array<RoomMember>} A list of RoomMembers.
+     */
+    public getMembersExcept(excludedIds: string[]): RoomMember[] {
+        return this.getMembers().filter((m) => !excludedIds.includes(m.userId));
+    }
+
+    /**
+     * Get a room member by their user ID.
+     * @param {string} userId The room member's user ID.
+     * @return {RoomMember} The member or null if they do not exist.
+     */
+    public getMember(userId: string): RoomMember | null {
+        return this.members[userId] || null;
+    }
+
+    /**
+     * Get a room member whose properties will not change with this room state. You
+     * typically want this if you want to attach a RoomMember to a MatrixEvent which
+     * may no longer be represented correctly by Room.currentState or Room.oldState.
+     * The term 'sentinel' refers to the fact that this RoomMember is an unchanging
+     * guardian for state at this particular point in time.
+     * @param {string} userId The room member's user ID.
+     * @return {RoomMember} The member or null if they do not exist.
+     */
+    public getSentinelMember(userId: string): RoomMember | null {
+        if (!userId) return null;
+        let sentinel = this.sentinels[userId];
+
+        if (sentinel === undefined) {
+            sentinel = new RoomMember(this.roomId, userId);
+            const member = this.members[userId];
+            if (member) {
+                sentinel.setMembershipEvent(member.events.member, this);
+            }
+            this.sentinels[userId] = sentinel;
+        }
+        return sentinel;
+    }
+
+    /**
+     * Get state events from the state of the room.
+     * @param {string} eventType The event type of the state event.
+     * @param {string} stateKey Optional. The state_key of the state event. If
+     * this is <code>undefined</code> then all matching state events will be
+     * returned.
+     * @return {MatrixEvent[]|MatrixEvent} A list of events if state_key was
+     * <code>undefined</code>, else a single event (or null if no match found).
+     */
+    public getStateEvents(eventType: string): MatrixEvent[];
+    public getStateEvents(eventType: string, stateKey: string): MatrixEvent;
+    public getStateEvents(eventType: string, stateKey?: string) {
+        if (!this.events.has(eventType)) {
+            // no match
+            return stateKey === undefined ? [] : null;
+        }
+        if (stateKey === undefined) { // return all values
+            return Array.from(this.events.get(eventType).values());
+        }
+        const event = this.events.get(eventType).get(stateKey);
+        return event ? event : null;
+    }
+
+    /**
+     * Creates a copy of this room state so that mutations to either won't affect the other.
+     * @return {RoomState} the copy of the room state
+     */
+    public clone(): RoomState {
+        const copy = new RoomState(this.roomId, this.oobMemberFlags);
+
+        // Ugly hack: because setStateEvents will mark
+        // members as susperseding future out of bound members
+        // if loading is in progress (through oobMemberFlags)
+        // since these are not new members, we're merely copying them
+        // set the status to not started
+        // after copying, we set back the status
+        const status = this.oobMemberFlags.status;
+        this.oobMemberFlags.status = OobStatus.NotStarted;
+
+        Array.from(this.events.values()).forEach((eventsByStateKey) => {
+            copy.setStateEvents(Array.from(eventsByStateKey.values()));
+        });
+
+        // Ugly hack: see above
+        this.oobMemberFlags.status = status;
+
+        if (this.summaryInvitedMemberCount !== null) {
+            copy.setInvitedMemberCount(this.getInvitedMemberCount());
+        }
+        if (this.summaryJoinedMemberCount !== null) {
+            copy.setJoinedMemberCount(this.getJoinedMemberCount());
+        }
+
+        // copy out of band flags if needed
+        if (this.oobMemberFlags.status == OobStatus.Finished) {
+            // copy markOutOfBand flags
+            this.getMembers().forEach((member) => {
+                if (member.isOutOfBand()) {
+                    const copyMember = copy.getMember(member.userId);
+                    copyMember.markOutOfBand();
+                }
+            });
+        }
+
+        return copy;
+    }
+
+    /**
+     * Add previously unknown state events.
+     * When lazy loading members while back-paginating,
+     * the relevant room state for the timeline chunk at the end
+     * of the chunk can be set with this method.
+     * @param {MatrixEvent[]} events state events to prepend
+     */
+    public setUnknownStateEvents(events: MatrixEvent[]): void {
+        const unknownStateEvents = events.filter((event) => {
+            return !this.events.has(event.getType()) ||
+                !this.events.get(event.getType()).has(event.getStateKey());
+        });
+
+        this.setStateEvents(unknownStateEvents);
+    }
+
+    /**
+     * Add an array of one or more state MatrixEvents, overwriting
+     * any existing state with the same {type, stateKey} tuple. Will fire
+     * "RoomState.events" for every event added. May fire "RoomState.members"
+     * if there are <code>m.room.member</code> events.
+     * @param {MatrixEvent[]} stateEvents a list of state events for this room.
+     * @fires module:client~MatrixClient#event:"RoomState.members"
+     * @fires module:client~MatrixClient#event:"RoomState.newMember"
+     * @fires module:client~MatrixClient#event:"RoomState.events"
+     */
+    public setStateEvents(stateEvents: MatrixEvent[]) {
+        this.updateModifiedTime();
+
+        // update the core event dict
+        stateEvents.forEach((event) => {
+            if (event.getRoomId() !== this.roomId) {
+                return;
+            }
+            if (!event.isState()) {
+                return;
+            }
+
+            const lastStateEvent = this.getStateEventMatching(event);
+            this.setStateEvent(event);
+            if (event.getType() === EventType.RoomMember) {
+                this.updateDisplayNameCache(event.getStateKey(), event.getContent().displayname);
+                this.updateThirdPartyTokenCache(event);
+            }
+            this.emit("RoomState.events", event, this, lastStateEvent);
+        });
+
+        // update higher level data structures. This needs to be done AFTER the
+        // core event dict as these structures may depend on other state events in
+        // the given array (e.g. disambiguating display names in one go to do both
+        // clashing names rather than progressively which only catches 1 of them).
+        stateEvents.forEach((event) => {
+            if (event.getRoomId() !== this.roomId) {
+                return;
+            }
+            if (!event.isState()) {
+                return;
+            }
+
+            if (event.getType() === EventType.RoomMember) {
+                const userId = event.getStateKey();
+
+                // leave events apparently elide the displayname or avatar_url,
+                // so let's fake one up so that we don't leak user ids
+                // into the timeline
+                if (event.getContent().membership === "leave" ||
+                    event.getContent().membership === "ban") {
+                    event.getContent().avatar_url =
+                        event.getContent().avatar_url ||
+                        event.getPrevContent().avatar_url;
+                    event.getContent().displayname =
+                        event.getContent().displayname ||
+                        event.getPrevContent().displayname;
+                }
+
+                const member = this.getOrCreateMember(userId, event);
+                member.setMembershipEvent(event, this);
+
+                this.updateMember(member);
+                this.emit("RoomState.members", event, this, member);
+            } else if (event.getType() === EventType.RoomPowerLevels) {
+                // events with unknown state keys should be ignored
+                // and should not aggregate onto members power levels
+                if (event.getStateKey() !== "") {
+                    return;
+                }
+                const members = Object.values(this.members);
+                members.forEach((member) => {
+                    // We only propagate `RoomState.members` event if the
+                    // power levels has been changed
+                    // large room suffer from large re-rendering especially when not needed
+                    const oldLastModified = member.getLastModifiedTime();
+                    member.setPowerLevelEvent(event);
+                    if (oldLastModified !== member.getLastModifiedTime()) {
+                        this.emit("RoomState.members", event, this, member);
+                    }
+                });
+
+                // assume all our sentinels are now out-of-date
+                this.sentinels = {};
+            }
+        });
+    }
+
+    /**
+     * Looks up a member by the given userId, and if it doesn't exist,
+     * create it and emit the `RoomState.newMember` event.
+     * This method makes sure the member is added to the members dictionary
+     * before emitting, as this is done from setStateEvents and setOutOfBandMember.
+     * @param {string} userId the id of the user to look up
+     * @param {MatrixEvent} event the membership event for the (new) member. Used to emit.
+     * @fires module:client~MatrixClient#event:"RoomState.newMember"
+     * @returns {RoomMember} the member, existing or newly created.
+     */
+    private getOrCreateMember(userId: string, event: MatrixEvent): RoomMember {
+        let member = this.members[userId];
+        if (!member) {
+            member = new RoomMember(this.roomId, userId);
+            // add member to members before emitting any events,
+            // as event handlers often lookup the member
+            this.members[userId] = member;
+            this.emit("RoomState.newMember", event, this, member);
+        }
+        return member;
+    }
+
+    private setStateEvent(event: MatrixEvent): void {
+        if (!this.events.has(event.getType())) {
+            this.events.set(event.getType(), new Map());
+        }
+        this.events.get(event.getType()).set(event.getStateKey(), event);
+    }
+
+    private getStateEventMatching(event: MatrixEvent): MatrixEvent | null {
+        if (!this.events.has(event.getType())) return null;
+        return this.events.get(event.getType()).get(event.getStateKey());
+    }
+
+    private updateMember(member: RoomMember): void {
+        // this member may have a power level already, so set it.
+        const pwrLvlEvent = this.getStateEvents(EventType.RoomPowerLevels, "");
+        if (pwrLvlEvent) {
+            member.setPowerLevelEvent(pwrLvlEvent);
+        }
+
+        // blow away the sentinel which is now outdated
+        delete this.sentinels[member.userId];
+
+        this.members[member.userId] = member;
+        this.joinedMemberCount = null;
+        this.invitedMemberCount = null;
+    }
+
+    /**
+     * Get the out-of-band members loading state, whether loading is needed or not.
+     * Note that loading might be in progress and hence isn't needed.
+     * @return {boolean} whether or not the members of this room need to be loaded
+     */
+    public needsOutOfBandMembers(): boolean {
+        return this.oobMemberFlags.status === OobStatus.NotStarted;
+    }
+
+    /**
+     * Mark this room state as waiting for out-of-band members,
+     * ensuring it doesn't ask for them to be requested again
+     * through needsOutOfBandMembers
+     */
+    public markOutOfBandMembersStarted(): void {
+        if (this.oobMemberFlags.status !== OobStatus.NotStarted) {
+            return;
+        }
+        this.oobMemberFlags.status = OobStatus.InProgress;
+    }
+
+    /**
+     * Mark this room state as having failed to fetch out-of-band members
+     */
+    public markOutOfBandMembersFailed(): void {
+        if (this.oobMemberFlags.status !== OobStatus.InProgress) {
+            return;
+        }
+        this.oobMemberFlags.status = OobStatus.NotStarted;
+    }
+
+    /**
+     * Clears the loaded out-of-band members
+     */
+    public clearOutOfBandMembers(): void {
+        let count = 0;
+        Object.keys(this.members).forEach((userId) => {
+            const member = this.members[userId];
+            if (member.isOutOfBand()) {
+                ++count;
+                delete this.members[userId];
+            }
+        });
+        logger.log(`LL: RoomState removed ${count} members...`);
+        this.oobMemberFlags.status = OobStatus.NotStarted;
+    }
+
+    /**
+     * Sets the loaded out-of-band members.
+     * @param {MatrixEvent[]} stateEvents array of membership state events
+     */
+    public setOutOfBandMembers(stateEvents: MatrixEvent[]): void {
+        logger.log(`LL: RoomState about to set ${stateEvents.length} OOB members ...`);
+        if (this.oobMemberFlags.status !== OobStatus.InProgress) {
+            return;
+        }
+        logger.log(`LL: RoomState put in finished state ...`);
+        this.oobMemberFlags.status = OobStatus.Finished;
+        stateEvents.forEach((e) => this.setOutOfBandMember(e));
+    }
+
+    /**
+     * Sets a single out of band member, used by both setOutOfBandMembers and clone
+     * @param {MatrixEvent} stateEvent membership state event
+     */
+    private setOutOfBandMember(stateEvent: MatrixEvent): void {
+        if (stateEvent.getType() !== EventType.RoomMember) {
+            return;
+        }
+        const userId = stateEvent.getStateKey();
+        const existingMember = this.getMember(userId);
+        // never replace members received as part of the sync
+        if (existingMember && !existingMember.isOutOfBand()) {
+            return;
+        }
+
+        const member = this.getOrCreateMember(userId, stateEvent);
+        member.setMembershipEvent(stateEvent, this);
+        // needed to know which members need to be stored seperately
+        // as they are not part of the sync accumulator
+        // this is cleared by setMembershipEvent so when it's updated through /sync
+        member.markOutOfBand();
+
+        this.updateDisplayNameCache(member.userId, member.name);
+
+        this.setStateEvent(stateEvent);
+        this.updateMember(member);
+        this.emit("RoomState.members", stateEvent, this, member);
+    }
+
+    /**
+     * Set the current typing event for this room.
+     * @param {MatrixEvent} event The typing event
+     */
+    public setTypingEvent(event: MatrixEvent): void {
+        Object.values(this.members).forEach(function(member) {
+            member.setTypingEvent(event);
+        });
+    }
+
+    /**
+     * Get the m.room.member event which has the given third party invite token.
+     *
+     * @param {string} token The token
+     * @return {?MatrixEvent} The m.room.member event or null
+     */
+    public getInviteForThreePidToken(token: string): MatrixEvent | null {
+        return this.tokenToInvite[token] || null;
+    }
+
+    /**
+     * Update the last modified time to the current time.
+     */
+    private updateModifiedTime(): void {
+        this.modified = Date.now();
+    }
+
+    /**
+     * Get the timestamp when this room state was last updated. This timestamp is
+     * updated when this object has received new state events.
+     * @return {number} The timestamp
+     */
+    public getLastModifiedTime(): number {
+        return this.modified;
+    }
+
+    /**
+     * Get user IDs with the specified or similar display names.
+     * @param {string} displayName The display name to get user IDs from.
+     * @return {string[]} An array of user IDs or an empty array.
+     */
+    public getUserIdsWithDisplayName(displayName: string): string[] {
+        return this.displayNameToUserIds[utils.removeHiddenChars(displayName)] || [];
+    }
+
+    /**
+     * Returns true if userId is in room, event is not redacted and either sender of
+     * mxEvent or has power level sufficient to redact events other than their own.
+     * @param {MatrixEvent} mxEvent The event to test permission for
+     * @param {string} userId The user ID of the user to test permission for
+     * @return {boolean} true if the given used ID can redact given event
+     */
+    public maySendRedactionForEvent(mxEvent: MatrixEvent, userId: string): boolean {
+        const member = this.getMember(userId);
+        if (!member || member.membership === 'leave') return false;
+
+        if (mxEvent.status || mxEvent.isRedacted()) return false;
+
+        // The user may have been the sender, but they can't redact their own message
+        // if redactions are blocked.
+        const canRedact = this.maySendEvent(EventType.RoomRedaction, userId);
+        if (mxEvent.getSender() === userId) return canRedact;
+
+        return this.hasSufficientPowerLevelFor('redact', member.powerLevel);
+    }
+
+    /**
+     * Returns true if the given power level is sufficient for action
+     * @param {string} action The type of power level to check
+     * @param {number} powerLevel The power level of the member
+     * @return {boolean} true if the given power level is sufficient
+     */
+    private hasSufficientPowerLevelFor(action: string, powerLevel: number): boolean {
+        const powerLevelsEvent = this.getStateEvents(EventType.RoomPowerLevels, "");
+
+        let powerLevels = {};
+        if (powerLevelsEvent) {
+            powerLevels = powerLevelsEvent.getContent();
+        }
+
+        let requiredLevel = 50;
+        if (utils.isNumber(powerLevels[action])) {
+            requiredLevel = powerLevels[action];
+        }
+
+        return powerLevel >= requiredLevel;
+    }
+
+    /**
+     * Short-form for maySendEvent('m.room.message', userId)
+     * @param {string} userId The user ID of the user to test permission for
+     * @return {boolean} true if the given user ID should be permitted to send
+     *                   message events into the given room.
+     */
+    public maySendMessage(userId: string): boolean {
+        return this.maySendEventOfType(EventType.RoomMessage, userId, false);
+    }
+
+    /**
+     * Returns true if the given user ID has permission to send a normal
+     * event of type `eventType` into this room.
+     * @param {string} eventType The type of event to test
+     * @param {string} userId The user ID of the user to test permission for
+     * @return {boolean} true if the given user ID should be permitted to send
+     *                        the given type of event into this room,
+     *                        according to the room's state.
+     */
+    public maySendEvent(eventType: EventType | string, userId: string): boolean {
+        return this.maySendEventOfType(eventType, userId, false);
+    }
+
+    /**
+     * Returns true if the given MatrixClient has permission to send a state
+     * event of type `stateEventType` into this room.
+     * @param {string} stateEventType The type of state events to test
+     * @param {MatrixClient} cli The client to test permission for
+     * @return {boolean} true if the given client should be permitted to send
+     *                        the given type of state event into this room,
+     *                        according to the room's state.
+     */
+    public mayClientSendStateEvent(stateEventType: EventType | string, cli: MatrixClient): boolean {
+        if (cli.isGuest()) {
+            return false;
+        }
+        return this.maySendStateEvent(stateEventType, cli.credentials.userId);
+    }
+
+    /**
+     * Returns true if the given user ID has permission to send a state
+     * event of type `stateEventType` into this room.
+     * @param {string} stateEventType The type of state events to test
+     * @param {string} userId The user ID of the user to test permission for
+     * @return {boolean} true if the given user ID should be permitted to send
+     *                        the given type of state event into this room,
+     *                        according to the room's state.
+     */
+    public maySendStateEvent(stateEventType: EventType | string, userId: string): boolean {
+        return this.maySendEventOfType(stateEventType, userId, true);
+    }
+
+    /**
+     * Returns true if the given user ID has permission to send a normal or state
+     * event of type `eventType` into this room.
+     * @param {string} eventType The type of event to test
+     * @param {string} userId The user ID of the user to test permission for
+     * @param {boolean} state If true, tests if the user may send a state
+     event of this type. Otherwise tests whether
+     they may send a regular event.
+     * @return {boolean} true if the given user ID should be permitted to send
+     *                        the given type of event into this room,
+     *                        according to the room's state.
+     */
+    private maySendEventOfType(eventType: EventType | string, userId: string, state: boolean): boolean {
+        const powerLevelsEvent = this.getStateEvents(EventType.RoomPowerLevels, '');
+
+        let powerLevels;
+        let eventsLevels = {};
+
+        let stateDefault = 0;
+        let eventsDefault = 0;
+        let powerLevel = 0;
+        if (powerLevelsEvent) {
+            powerLevels = powerLevelsEvent.getContent();
+            eventsLevels = powerLevels.events || {};
+
+            if (Number.isSafeInteger(powerLevels.state_default)) {
+                stateDefault = powerLevels.state_default;
+            } else {
+                stateDefault = 50;
+            }
+
+            const userPowerLevel = powerLevels.users && powerLevels.users[userId];
+            if (Number.isSafeInteger(userPowerLevel)) {
+                powerLevel = userPowerLevel;
+            } else if (Number.isSafeInteger(powerLevels.users_default)) {
+                powerLevel = powerLevels.users_default;
+            }
+
+            if (Number.isSafeInteger(powerLevels.events_default)) {
+                eventsDefault = powerLevels.events_default;
+            }
+        }
+
+        let requiredLevel = state ? stateDefault : eventsDefault;
+        if (Number.isSafeInteger(eventsLevels[eventType])) {
+            requiredLevel = eventsLevels[eventType];
+        }
+        return powerLevel >= requiredLevel;
+    }
+
+    /**
+     * Returns true if the given user ID has permission to trigger notification
+     * of type `notifLevelKey`
+     * @param {string} notifLevelKey The level of notification to test (eg. 'room')
+     * @param {string} userId The user ID of the user to test permission for
+     * @return {boolean} true if the given user ID has permission to trigger a
+     *                        notification of this type.
+     */
+    public mayTriggerNotifOfType(notifLevelKey: string, userId: string): boolean {
+        const member = this.getMember(userId);
+        if (!member) {
+            return false;
+        }
+
+        const powerLevelsEvent = this.getStateEvents(EventType.RoomPowerLevels, '');
+
+        let notifLevel = 50;
+        if (
+            powerLevelsEvent &&
+            powerLevelsEvent.getContent() &&
+            powerLevelsEvent.getContent().notifications &&
+            utils.isNumber(powerLevelsEvent.getContent().notifications[notifLevelKey])
+        ) {
+            notifLevel = powerLevelsEvent.getContent().notifications[notifLevelKey];
+        }
+
+        return member.powerLevel >= notifLevel;
+    }
+
+    /**
+     * Returns the join rule based on the m.room.join_rule state event, defaulting to `invite`.
+     * @returns {string} the join_rule applied to this room
+     */
+    public getJoinRule(): string {
+        const joinRuleEvent = this.getStateEvents(EventType.RoomJoinRules, "");
+        const joinRuleContent = joinRuleEvent ? joinRuleEvent.getContent() : {};
+        return joinRuleContent["join_rule"] || "invite";
+    }
+
+    private updateThirdPartyTokenCache(memberEvent: MatrixEvent): void {
+        if (!memberEvent.getContent().third_party_invite) {
+            return;
+        }
+        const token = (memberEvent.getContent().third_party_invite.signed || {}).token;
+        if (!token) {
+            return;
+        }
+        const threePidInvite = this.getStateEvents(EventType.RoomThirdPartyInvite, token);
+        if (!threePidInvite) {
+            return;
+        }
+        this.tokenToInvite[token] = memberEvent;
+    }
+
+    private updateDisplayNameCache(userId: string, displayName: string): void {
+        const oldName = this.userIdsToDisplayNames[userId];
+        delete this.userIdsToDisplayNames[userId];
+        if (oldName) {
+            // Remove the old name from the cache.
+            // We clobber the user_id > name lookup but the name -> [user_id] lookup
+            // means we need to remove that user ID from that array rather than nuking
+            // the lot.
+            const strippedOldName = utils.removeHiddenChars(oldName);
+
+            const existingUserIds = this.displayNameToUserIds[strippedOldName];
+            if (existingUserIds) {
+                // remove this user ID from this array
+                const filteredUserIDs = existingUserIds.filter((id) => id !== userId);
+                this.displayNameToUserIds[strippedOldName] = filteredUserIDs;
+            }
+        }
+
+        this.userIdsToDisplayNames[userId] = displayName;
+
+        const strippedDisplayname = displayName && utils.removeHiddenChars(displayName);
+        // an empty stripped displayname (undefined/'') will be set to MXID in room-member.js
+        if (strippedDisplayname) {
+            if (!this.displayNameToUserIds[strippedDisplayname]) {
+                this.displayNameToUserIds[strippedDisplayname] = [];
+            }
+            this.displayNameToUserIds[strippedDisplayname].push(userId);
+        }
+    }
+}
+
+/**
+ * Fires whenever the event dictionary in room state is updated.
+ * @event module:client~MatrixClient#"RoomState.events"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomState} state The room state whose RoomState.events dictionary
+ * was updated.
+ * @param {MatrixEvent} prevEvent The event being replaced by the new state, if
+ * known. Note that this can differ from `getPrevContent()` on the new state event
+ * as this is the store's view of the last state, not the previous state provided
+ * by the server.
+ * @example
+ * matrixClient.on("RoomState.events", function(event, state, prevEvent){
+ *   var newStateEvent = event;
+ * });
+ */
+
+/**
+ * Fires whenever a member in the members dictionary is updated in any way.
+ * @event module:client~MatrixClient#"RoomState.members"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomState} state The room state whose RoomState.members dictionary
+ * was updated.
+ * @param {RoomMember} member The room member that was updated.
+ * @example
+ * matrixClient.on("RoomState.members", function(event, state, member){
+ *   var newMembershipState = member.membership;
+ * });
+ */
+
+/**
+ * Fires whenever a member is added to the members dictionary. The RoomMember
+ * will not be fully populated yet (e.g. no membership state) but will already
+ * be available in the members dictionary.
+ * @event module:client~MatrixClient#"RoomState.newMember"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomState} state The room state whose RoomState.members dictionary
+ * was updated with a new entry.
+ * @param {RoomMember} member The room member that was added.
+ * @example
+ * matrixClient.on("RoomState.newMember", function(event, state, member){
+ *   // add event listeners on 'member'
+ * });
+ */

src/models/room-summary.ts

@@ -1,6 +1,5 @@
 /*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -19,6 +18,20 @@ limitations under the License.
  * @module models/room-summary
  */
 
+export interface IRoomSummary {
+    "m.heroes": string[];
+    "m.joined_member_count": number;
+    "m.invited_member_count": number;
+}
+
+interface IInfo {
+    title: string;
+    desc?: string;
+    numMembers?: number;
+    aliases?: string[];
+    timestamp?: number;
+}
+
 /**
  * Construct a new Room Summary. A summary can be used for display on a recent
  * list, without having to load the entire room list into memory.
@@ -32,8 +45,7 @@ limitations under the License.
  * @param {string[]} info.aliases The list of aliases for this room.
  * @param {Number} info.timestamp The timestamp for this room.
  */
-export function RoomSummary(roomId, info) {
-    this.roomId = roomId;
-    this.info = info;
+export class RoomSummary {
+    constructor(public readonly roomId: string, info?: IInfo) {}
 }
 

src/models/search-result.js

@@ -1,60 +0,0 @@
-/*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/search-result
- */
-
-import { EventContext } from "./event-context";
-
-/**
- * Construct a new SearchResult
- *
- * @param {number} rank   where this SearchResult ranks in the results
- * @param {event-context.EventContext} eventContext  the matching event and its
- *    context
- *
- * @constructor
- */
-export function SearchResult(rank, eventContext) {
-    this.rank = rank;
-    this.context = eventContext;
-}
-
-/**
- * Create a SearchResponse from the response to /search
- * @static
- * @param {Object} jsonObj
- * @param {function} eventMapper
- * @return {SearchResult}
- */
-
-SearchResult.fromJson = function(jsonObj, eventMapper) {
-    const jsonContext = jsonObj.context || {};
-    const events_before = jsonContext.events_before || [];
-    const events_after = jsonContext.events_after || [];
-
-    const context = new EventContext(eventMapper(jsonObj.result));
-
-    context.setPaginateToken(jsonContext.start, true);
-    context.addEvents(events_before.map(eventMapper), true);
-    context.addEvents(events_after.map(eventMapper), false);
-    context.setPaginateToken(jsonContext.end, false);
-
-    return new SearchResult(jsonObj.rank, context);
-};
-

src/models/search-result.ts

@@ -0,0 +1,60 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module models/search-result
+ */
+
+import { EventContext } from "./event-context";
+import { EventMapper } from "../event-mapper";
+import { IResultContext, ISearchResult } from "../@types/search";
+
+export class SearchResult {
+    /**
+     * Create a SearchResponse from the response to /search
+     * @static
+     * @param {Object} jsonObj
+     * @param {function} eventMapper
+     * @return {SearchResult}
+     */
+
+    static fromJson(jsonObj: ISearchResult, eventMapper: EventMapper): SearchResult {
+        const jsonContext = jsonObj.context || {} as IResultContext;
+        const eventsBefore = jsonContext.events_before || [];
+        const eventsAfter = jsonContext.events_after || [];
+
+        const context = new EventContext(eventMapper(jsonObj.result));
+
+        context.setPaginateToken(jsonContext.start, true);
+        context.addEvents(eventsBefore.map(eventMapper), true);
+        context.addEvents(eventsAfter.map(eventMapper), false);
+        context.setPaginateToken(jsonContext.end, false);
+
+        return new SearchResult(jsonObj.rank, context);
+    }
+
+    /**
+     * Construct a new SearchResult
+     *
+     * @param {number} rank   where this SearchResult ranks in the results
+     * @param {event-context.EventContext} context  the matching event and its
+     *    context
+     *
+     * @constructor
+     */
+    constructor(public readonly rank: number, public readonly context: EventContext) {}
+}
+

src/models/user.js

@@ -1,260 +0,0 @@
-/*
-Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2019 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-/**
- * @module models/user
- */
-
-import * as utils from "../utils";
-import { EventEmitter } from "events";
-
-/**
- * Construct a new User. A User must have an ID and can optionally have extra
- * information associated with it.
- * @constructor
- * @param {string} userId Required. The ID of this user.
- * @prop {string} userId The ID of the user.
- * @prop {Object} info The info object supplied in the constructor.
- * @prop {string} displayName The 'displayname' of the user if known.
- * @prop {string} avatarUrl The 'avatar_url' of the user if known.
- * @prop {string} presence The presence enum if known.
- * @prop {string} presenceStatusMsg The presence status message if known.
- * @prop {Number} lastActiveAgo The time elapsed in ms since the user interacted
- *                proactively with the server, or we saw a message from the user
- * @prop {Number} lastPresenceTs Timestamp (ms since the epoch) for when we last
- *                received presence data for this user.  We can subtract
- *                lastActiveAgo from this to approximate an absolute value for
- *                when a user was last active.
- * @prop {Boolean} currentlyActive Whether we should consider lastActiveAgo to be
- *               an approximation and that the user should be seen as active 'now'
- * @prop {string} _unstable_statusMessage The status message for the user, if known. This is
- *                different from the presenceStatusMsg in that this is not tied to
- *                the user's presence, and should be represented differently.
- * @prop {Object} events The events describing this user.
- * @prop {MatrixEvent} events.presence The m.presence event for this user.
- */
-export function User(userId) {
-    this.userId = userId;
-    this.presence = "offline";
-    this.presenceStatusMsg = null;
-    this._unstable_statusMessage = "";
-    this.displayName = userId;
-    this.rawDisplayName = userId;
-    this.avatarUrl = null;
-    this.lastActiveAgo = 0;
-    this.lastPresenceTs = 0;
-    this.currentlyActive = false;
-    this.events = {
-        presence: null,
-        profile: null,
-    };
-    this._updateModifiedTime();
-}
-utils.inherits(User, EventEmitter);
-
-/**
- * Update this User with the given presence event. May fire "User.presence",
- * "User.avatarUrl" and/or "User.displayName" if this event updates this user's
- * properties.
- * @param {MatrixEvent} event The <code>m.presence</code> event.
- * @fires module:client~MatrixClient#event:"User.presence"
- * @fires module:client~MatrixClient#event:"User.displayName"
- * @fires module:client~MatrixClient#event:"User.avatarUrl"
- */
-User.prototype.setPresenceEvent = function(event) {
-    if (event.getType() !== "m.presence") {
-        return;
-    }
-    const firstFire = this.events.presence === null;
-    this.events.presence = event;
-
-    const eventsToFire = [];
-    if (event.getContent().presence !== this.presence || firstFire) {
-        eventsToFire.push("User.presence");
-    }
-    if (event.getContent().avatar_url &&
-        event.getContent().avatar_url !== this.avatarUrl) {
-        eventsToFire.push("User.avatarUrl");
-    }
-    if (event.getContent().displayname &&
-        event.getContent().displayname !== this.displayName) {
-        eventsToFire.push("User.displayName");
-    }
-    if (event.getContent().currently_active !== undefined &&
-        event.getContent().currently_active !== this.currentlyActive) {
-        eventsToFire.push("User.currentlyActive");
-    }
-
-    this.presence = event.getContent().presence;
-    eventsToFire.push("User.lastPresenceTs");
-
-    if (event.getContent().status_msg) {
-      this.presenceStatusMsg = event.getContent().status_msg;
-    }
-    if (event.getContent().displayname) {
-        this.displayName = event.getContent().displayname;
-    }
-    if (event.getContent().avatar_url) {
-        this.avatarUrl = event.getContent().avatar_url;
-    }
-    this.lastActiveAgo = event.getContent().last_active_ago;
-    this.lastPresenceTs = Date.now();
-    this.currentlyActive = event.getContent().currently_active;
-
-    this._updateModifiedTime();
-
-    for (let i = 0; i < eventsToFire.length; i++) {
-        this.emit(eventsToFire[i], event, this);
-    }
-};
-
-/**
- * Manually set this user's display name. No event is emitted in response to this
- * as there is no underlying MatrixEvent to emit with.
- * @param {string} name The new display name.
- */
-User.prototype.setDisplayName = function(name) {
-    const oldName = this.displayName;
-    if (typeof name === "string") {
-        this.displayName = name;
-    } else {
-        this.displayName = undefined;
-    }
-    if (name !== oldName) {
-        this._updateModifiedTime();
-    }
-};
-
-/**
- * Manually set this user's non-disambiguated display name. No event is emitted
- * in response to this as there is no underlying MatrixEvent to emit with.
- * @param {string} name The new display name.
- */
-User.prototype.setRawDisplayName = function(name) {
-    if (typeof name === "string") {
-        this.rawDisplayName = name;
-    } else {
-        this.rawDisplayName = undefined;
-    }
-};
-
-/**
- * Manually set this user's avatar URL. No event is emitted in response to this
- * as there is no underlying MatrixEvent to emit with.
- * @param {string} url The new avatar URL.
- */
-User.prototype.setAvatarUrl = function(url) {
-    const oldUrl = this.avatarUrl;
-    this.avatarUrl = url;
-    if (url !== oldUrl) {
-        this._updateModifiedTime();
-    }
-};
-
-/**
- * Update the last modified time to the current time.
- */
-User.prototype._updateModifiedTime = function() {
-    this._modified = Date.now();
-};
-
-/**
- * Get the timestamp when this User was last updated. This timestamp is
- * updated when this User receives a new Presence event which has updated a
- * property on this object. It is updated <i>before</i> firing events.
- * @return {number} The timestamp
- */
-User.prototype.getLastModifiedTime = function() {
-    return this._modified;
-};
-
-/**
- * Get the absolute timestamp when this User was last known active on the server.
- * It is *NOT* accurate if this.currentlyActive is true.
- * @return {number} The timestamp
- */
-User.prototype.getLastActiveTs = function() {
-    return this.lastPresenceTs - this.lastActiveAgo;
-};
-
-/**
- * Manually set the user's status message.
- * @param {MatrixEvent} event The <code>im.vector.user_status</code> event.
- * @fires module:client~MatrixClient#event:"User._unstable_statusMessage"
- */
-User.prototype._unstable_updateStatusMessage = function(event) {
-    if (!event.getContent()) this._unstable_statusMessage = "";
-    else this._unstable_statusMessage = event.getContent()["status"];
-    this._updateModifiedTime();
-    this.emit("User._unstable_statusMessage", this);
-};
-
-/**
- * Fires whenever any user's lastPresenceTs changes,
- * ie. whenever any presence event is received for a user.
- * @event module:client~MatrixClient#"User.lastPresenceTs"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.lastPresenceTs changed.
- * @example
- * matrixClient.on("User.lastPresenceTs", function(event, user){
- *   var newlastPresenceTs = user.lastPresenceTs;
- * });
- */
-
-/**
- * Fires whenever any user's presence changes.
- * @event module:client~MatrixClient#"User.presence"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.presence changed.
- * @example
- * matrixClient.on("User.presence", function(event, user){
- *   var newPresence = user.presence;
- * });
- */
-
-/**
- * Fires whenever any user's currentlyActive changes.
- * @event module:client~MatrixClient#"User.currentlyActive"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.currentlyActive changed.
- * @example
- * matrixClient.on("User.currentlyActive", function(event, user){
- *   var newCurrentlyActive = user.currentlyActive;
- * });
- */
-
-/**
- * Fires whenever any user's display name changes.
- * @event module:client~MatrixClient#"User.displayName"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.displayName changed.
- * @example
- * matrixClient.on("User.displayName", function(event, user){
- *   var newName = user.displayName;
- * });
- */
-
-/**
- * Fires whenever any user's avatar URL changes.
- * @event module:client~MatrixClient#"User.avatarUrl"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.avatarUrl changed.
- * @example
- * matrixClient.on("User.avatarUrl", function(event, user){
- *   var newUrl = user.avatarUrl;
- * });
- */

src/models/user.ts

@@ -0,0 +1,274 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * @module models/user
+ */
+
+import { EventEmitter } from "events";
+
+import { MatrixEvent } from "./event";
+
+export class User extends EventEmitter {
+    // eslint-disable-next-line camelcase
+    private modified: number;
+
+    // XXX these should be read-only
+    public displayName: string;
+    public rawDisplayName: string;
+    public avatarUrl: string;
+    public presenceStatusMsg: string = null;
+    public presence = "offline";
+    public lastActiveAgo = 0;
+    public lastPresenceTs = 0;
+    public currentlyActive = false;
+    public events: {
+        presence?: MatrixEvent;
+        profile?: MatrixEvent;
+    } = {
+        presence: null,
+        profile: null,
+    };
+    // eslint-disable-next-line camelcase
+    public unstable_statusMessage = "";
+
+    /**
+     * Construct a new User. A User must have an ID and can optionally have extra
+     * information associated with it.
+     * @constructor
+     * @param {string} userId Required. The ID of this user.
+     * @prop {string} userId The ID of the user.
+     * @prop {Object} info The info object supplied in the constructor.
+     * @prop {string} displayName The 'displayname' of the user if known.
+     * @prop {string} avatarUrl The 'avatar_url' of the user if known.
+     * @prop {string} presence The presence enum if known.
+     * @prop {string} presenceStatusMsg The presence status message if known.
+     * @prop {Number} lastActiveAgo The time elapsed in ms since the user interacted
+     *                proactively with the server, or we saw a message from the user
+     * @prop {Number} lastPresenceTs Timestamp (ms since the epoch) for when we last
+     *                received presence data for this user.  We can subtract
+     *                lastActiveAgo from this to approximate an absolute value for
+     *                when a user was last active.
+     * @prop {Boolean} currentlyActive Whether we should consider lastActiveAgo to be
+     *               an approximation and that the user should be seen as active 'now'
+     * @prop {string} unstable_statusMessage The status message for the user, if known. This is
+     *                different from the presenceStatusMsg in that this is not tied to
+     *                the user's presence, and should be represented differently.
+     * @prop {Object} events The events describing this user.
+     * @prop {MatrixEvent} events.presence The m.presence event for this user.
+     */
+    constructor(public readonly userId: string) {
+        super();
+        this.displayName = userId;
+        this.rawDisplayName = userId;
+        this.avatarUrl = null;
+        this.updateModifiedTime();
+    }
+
+    /**
+     * Update this User with the given presence event. May fire "User.presence",
+     * "User.avatarUrl" and/or "User.displayName" if this event updates this user's
+     * properties.
+     * @param {MatrixEvent} event The <code>m.presence</code> event.
+     * @fires module:client~MatrixClient#event:"User.presence"
+     * @fires module:client~MatrixClient#event:"User.displayName"
+     * @fires module:client~MatrixClient#event:"User.avatarUrl"
+     */
+    public setPresenceEvent(event: MatrixEvent): void {
+        if (event.getType() !== "m.presence") {
+            return;
+        }
+        const firstFire = this.events.presence === null;
+        this.events.presence = event;
+
+        const eventsToFire = [];
+        if (event.getContent().presence !== this.presence || firstFire) {
+            eventsToFire.push("User.presence");
+        }
+        if (event.getContent().avatar_url &&
+            event.getContent().avatar_url !== this.avatarUrl) {
+            eventsToFire.push("User.avatarUrl");
+        }
+        if (event.getContent().displayname &&
+            event.getContent().displayname !== this.displayName) {
+            eventsToFire.push("User.displayName");
+        }
+        if (event.getContent().currently_active !== undefined &&
+            event.getContent().currently_active !== this.currentlyActive) {
+            eventsToFire.push("User.currentlyActive");
+        }
+
+        this.presence = event.getContent().presence;
+        eventsToFire.push("User.lastPresenceTs");
+
+        if (event.getContent().status_msg) {
+            this.presenceStatusMsg = event.getContent().status_msg;
+        }
+        if (event.getContent().displayname) {
+            this.displayName = event.getContent().displayname;
+        }
+        if (event.getContent().avatar_url) {
+            this.avatarUrl = event.getContent().avatar_url;
+        }
+        this.lastActiveAgo = event.getContent().last_active_ago;
+        this.lastPresenceTs = Date.now();
+        this.currentlyActive = event.getContent().currently_active;
+
+        this.updateModifiedTime();
+
+        for (let i = 0; i < eventsToFire.length; i++) {
+            this.emit(eventsToFire[i], event, this);
+        }
+    }
+
+    /**
+     * Manually set this user's display name. No event is emitted in response to this
+     * as there is no underlying MatrixEvent to emit with.
+     * @param {string} name The new display name.
+     */
+    public setDisplayName(name: string): void {
+        const oldName = this.displayName;
+        if (typeof name === "string") {
+            this.displayName = name;
+        } else {
+            this.displayName = undefined;
+        }
+        if (name !== oldName) {
+            this.updateModifiedTime();
+        }
+    }
+
+    /**
+     * Manually set this user's non-disambiguated display name. No event is emitted
+     * in response to this as there is no underlying MatrixEvent to emit with.
+     * @param {string} name The new display name.
+     */
+    public setRawDisplayName(name: string): void {
+        if (typeof name === "string") {
+            this.rawDisplayName = name;
+        } else {
+            this.rawDisplayName = undefined;
+        }
+    }
+
+    /**
+     * Manually set this user's avatar URL. No event is emitted in response to this
+     * as there is no underlying MatrixEvent to emit with.
+     * @param {string} url The new avatar URL.
+     */
+    public setAvatarUrl(url: string): void {
+        const oldUrl = this.avatarUrl;
+        this.avatarUrl = url;
+        if (url !== oldUrl) {
+            this.updateModifiedTime();
+        }
+    }
+
+    /**
+     * Update the last modified time to the current time.
+     */
+    private updateModifiedTime(): void {
+        this.modified = Date.now();
+    }
+
+    /**
+     * Get the timestamp when this User was last updated. This timestamp is
+     * updated when this User receives a new Presence event which has updated a
+     * property on this object. It is updated <i>before</i> firing events.
+     * @return {number} The timestamp
+     */
+    public getLastModifiedTime(): number {
+        return this.modified;
+    }
+
+    /**
+     * Get the absolute timestamp when this User was last known active on the server.
+     * It is *NOT* accurate if this.currentlyActive is true.
+     * @return {number} The timestamp
+     */
+    public getLastActiveTs(): number {
+        return this.lastPresenceTs - this.lastActiveAgo;
+    }
+
+    /**
+     * Manually set the user's status message.
+     * @param {MatrixEvent} event The <code>im.vector.user_status</code> event.
+     * @fires module:client~MatrixClient#event:"User.unstable_statusMessage"
+     */
+    // eslint-disable-next-line
+    public unstable_updateStatusMessage(event: MatrixEvent): void {
+        if (!event.getContent()) this.unstable_statusMessage = "";
+        else this.unstable_statusMessage = event.getContent()["status"];
+        this.updateModifiedTime();
+        this.emit("User.unstable_statusMessage", this);
+    }
+}
+
+/**
+ * Fires whenever any user's lastPresenceTs changes,
+ * ie. whenever any presence event is received for a user.
+ * @event module:client~MatrixClient#"User.lastPresenceTs"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.lastPresenceTs changed.
+ * @example
+ * matrixClient.on("User.lastPresenceTs", function(event, user){
+ *   var newlastPresenceTs = user.lastPresenceTs;
+ * });
+ */
+
+/**
+ * Fires whenever any user's presence changes.
+ * @event module:client~MatrixClient#"User.presence"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.presence changed.
+ * @example
+ * matrixClient.on("User.presence", function(event, user){
+ *   var newPresence = user.presence;
+ * });
+ */
+
+/**
+ * Fires whenever any user's currentlyActive changes.
+ * @event module:client~MatrixClient#"User.currentlyActive"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.currentlyActive changed.
+ * @example
+ * matrixClient.on("User.currentlyActive", function(event, user){
+ *   var newCurrentlyActive = user.currentlyActive;
+ * });
+ */
+
+/**
+ * Fires whenever any user's display name changes.
+ * @event module:client~MatrixClient#"User.displayName"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.displayName changed.
+ * @example
+ * matrixClient.on("User.displayName", function(event, user){
+ *   var newName = user.displayName;
+ * });
+ */
+
+/**
+ * Fires whenever any user's avatar URL changes.
+ * @event module:client~MatrixClient#"User.avatarUrl"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.avatarUrl changed.
+ * @example
+ * matrixClient.on("User.avatarUrl", function(event, user){
+ *   var newUrl = user.avatarUrl;
+ * });
+ */

src/service-types.ts

@@ -0,0 +1,20 @@
+/*
+Copyright 2019 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export enum SERVICE_TYPES {
+    IS = 'SERVICE_TYPE_IS', // An identity server
+    IM = 'SERVICE_TYPE_IM', // An integration manager
+}