v2.3.2

[Release] Fix addPendingEvent with pending event order == chronological

.babelrc

@@ -0,0 +1,15 @@
+{
+    "presets": ["es2015"],
+    "plugins": [
+        "transform-class-properties",
+
+        // this transforms async functions into generator functions, which
+        // are then made to use the regenerator module by babel's
+        // transform-regnerator plugin (which is enabled by es2015).
+        "transform-async-to-bluebird",
+
+        // This makes sure that the regenerator runtime is available to
+        // the transpiled code.
+        "transform-runtime",
+    ],
+}

.buildkite/pipeline.yaml

@@ -0,0 +1,34 @@
+steps:
+  - label: ":eslint: Lint"
+    command:
+      - "yarn install"
+      - "yarn lint"
+    plugins:
+      - docker#v3.0.1:
+          image: "node:10"
+
+  - label: ":karma: Tests"
+    command:
+      - "yarn install"
+      - "yarn test"
+    plugins:
+      - docker#v3.0.1:
+          image: "node:10"
+
+  - label: "📃 Docs"
+    command:
+      - "yarn install"
+      - "yarn gendoc"
+    plugins:
+      - docker#v3.0.1:
+          image: "node:10"
+
+  - wait
+
+  - label: "🐴 Trigger matrix-react-sdk"
+    trigger: "matrix-react-sdk"
+    branches: "develop"
+    build:
+        branch: "develop"
+        message: "[js-sdk] ${BUILDKITE_MESSAGE}"
+    async: true

.editorconfig

@@ -0,0 +1,23 @@
+#   Copyright 2017 Aviral Dasgupta
+#
+#   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.
+
+root = true
+
+[*]
+charset=utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true

.eslintrc.js

@@ -0,0 +1,86 @@
+module.exports = {
+    parser: "babel-eslint", // now needed for class properties
+    parserOptions: {
+        sourceType: "module",
+        ecmaFeatures: {
+        }
+    },
+    env: {
+        browser: true,
+        node: true,
+
+        // babel's transform-runtime converts references to ES6 globals such as
+        // Promise and Map to core-js polyfills, so we can use ES6 globals.
+        es6: true,
+    },
+    extends: ["eslint:recommended", "google"],
+    plugins: [
+        "babel",
+    ],
+    rules: {
+        // rules we've always adhered to or now do
+        "max-len": ["error", {
+            code: 90,
+            ignoreComments: true,
+        }],
+        curly: ["error", "multi-line"],
+        "prefer-const": ["error"],
+        "comma-dangle": ["error", {
+            arrays: "always-multiline",
+            objects: "always-multiline",
+            imports: "always-multiline",
+            exports: "always-multiline",
+            functions: "always-multiline",
+        }],
+
+        // loosen jsdoc requirements a little
+        "require-jsdoc": ["error", {
+            require: {
+                FunctionDeclaration: false,
+            }
+        }],
+        "valid-jsdoc": ["error", {
+            requireParamDescription: false,
+            requireReturn: false,
+            requireReturnDescription: false,
+        }],
+
+        // rules we do not want from eslint-recommended
+        "no-console": ["off"],
+        "no-constant-condition": ["off"],
+        "no-empty": ["error", { "allowEmptyCatch": true }],
+
+        // rules we do not want from the google styleguide
+        "object-curly-spacing": ["off"],
+        "spaced-comment": ["off"],
+        "guard-for-in": ["off"],
+
+        // in principle we prefer single quotes, but life is too short
+        quotes: ["off"],
+
+        // rules we'd ideally like to adhere to, but the current
+        // code does not (in most cases because it's still ES5)
+        // we set these to warnings, and assert that the number
+        // of warnings doesn't exceed a given threshold
+        "no-var": ["warn"],
+        "brace-style": ["warn", "1tbs", {"allowSingleLine": true}],
+        "prefer-rest-params": ["warn"],
+        "prefer-spread": ["warn"],
+        "one-var": ["warn"],
+        "padded-blocks": ["warn"],
+        "no-extend-native": ["warn"],
+        "camelcase": ["warn"],
+        "no-multi-spaces": ["error", { "ignoreEOLComments": true }],
+        "space-before-function-paren": ["error", {
+            "anonymous": "never",
+            "named": "never",
+            "asyncArrow": "always",
+        }],
+        "arrow-parens": "off",
+
+        // eslint's built in no-invalid-this rule breaks with class properties
+        "no-invalid-this": "off",
+        // so we replace it with a version that is class property aware
+        "babel/no-invalid-this": "error",
+    }
+}

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+patreon: matrixdotorg
+liberapay: matrixdotorg

.gitignore

@@ -1,8 +1,20 @@
+/.jsdocbuild
+/.jsdoc
+
 node_modules
+/.npmrc
+/*.log
+package-lock.json
 .lock-wscript
 build/Release
 coverage
 lib-cov
 out
 reports
-dist/browser-matrix-dev.js
+/dist
+/lib
+/specbuild
+
+# version file and tarball created by `npm pack` / `yarn pack`
+/git-revision.txt
+/matrix-js-sdk-*.tgz

.istanbul.yml

@@ -0,0 +1,2 @@
+instrumentation:
+  compact: false

.jshint

@@ -1,11 +0,0 @@
-{
-    "node": true,
-    "jasmine": true,
-
-    "nonew": true,
-    "curly": true,
-    "forin": true,
-    "freeze": true,
-    "undef": true,
-    "unused": "vars"
-}

CONTRIBUTING.rst

@@ -0,0 +1,124 @@
+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 Travis for continuous integration, and all pull requests get
+automatically tested by Travis: 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 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

README.md

@@ -1,25 +1,30 @@
 Matrix Javascript SDK
 =====================
-[![Build Status](http://matrix.org/jenkins/buildStatus/icon?job=JavascriptSDK)](http://matrix.org/jenkins/job/JavascriptSDK/)
 
-This is the [Matrix](https://matrix.org) Client-Server v1/v2 alpha SDK for JavaScript. This SDK can be run
-in a browser or in Node.js.
+This is the [Matrix](https://matrix.org) Client-Server r0 SDK for
+JavaScript. This SDK can be run in a browser or in Node.js.
 
 Quickstart
 ==========
 
 In a browser
 ------------
-Copy ``dist/browser-matrix-$VERSION.js`` and add that as a ``<script>`` to
-your page. There will be a global variable ``matrixcs`` attached to
-``window`` through which you can access the SDK.
+Download either the full or minified version from
+https://github.com/matrix-org/matrix-js-sdk/releases/latest and add that as a
+``<script>`` to your page. There will be a global variable ``matrixcs``
+attached to ``window`` through which you can access the SDK. See below for how to
+include libolm to enable end-to-end-encryption.
 
-Please check [the working browser example](examples/browser) for more information. 
+Please check [the working browser example](examples/browser) for more information.
 
 In Node.js
 ----------
 
-``npm install matrix-js-sdk``
+Ensure you have the latest LTS version of Node.js installed.
+
+Using `yarn` instead of `npm` is recommended. Please see the Yarn [install guide](https://yarnpkg.com/docs/install/) if you do not have it already.
+
+``yarn add matrix-js-sdk``
 
 ```javascript
   var sdk = require("matrix-js-sdk");
@@ -29,7 +34,60 @@ In Node.js
   });
 ```
 
-Please check [the Node.js terminal app](examples/node) for a more complex example.
+See below for how to include libolm to enable end-to-end-encryption. Please check
+[the Node.js terminal app](examples/node) for a more complex example.
+
+To start the client:
+
+```javascript
+await client.startClient({initialSyncLimit: 10});
+```
+
+You can perform a call to `/sync` to get the current state of the client:
+
+```javascript
+client.once('sync', function(state, prevState, res) {
+    if(state === 'PREPARED') {
+        console.log("prepared");
+    } else {
+        console.log(state);
+        process.exit(1);
+    }
+});
+```
+
+To send a message:
+
+```javascript
+var content = {
+    "body": "message text",
+    "msgtype": "m.text"
+};
+client.sendEvent("roomId", "m.room.message", content, "", (err, res) => {
+    console.log(err);
+});
+```
+
+To listen for message events:
+
+```javascript
+client.on("Room.timeline", function(event, room, toStartOfTimeline) {
+  if (event.getType() !== "m.room.message") {
+    return; // only use messages
+  }
+  console.log(event.event.content.body);
+});
+```
+
+By default, the `matrix-js-sdk` client uses the `MemoryStore` to store events as they are received. For example to iterate through the currently stored timeline for a room:
+
+```javascript
+Object.keys(client.store.rooms).forEach((roomId) => {
+  client.getRoom(roomId).timeline.forEach(t => {
+      console.log(t.event);
+  });
+});
+```
 
 What does this SDK do?
 ----------------------
@@ -44,20 +102,27 @@ events for incoming data and state changes. Aside from wrapping the HTTP API, it
  - Exposes high-level objects like `Rooms`, `RoomState`, `RoomMembers` and `Users`
    which can be listened to for things like name changes, new messages, membership
    changes, presence changes, and more.
-
-Later versions of the SDK will:
+ - Handle "local echo" of messages sent using the SDK. This means that messages
+   that have just been sent will appear in the timeline as 'sending', until it
+   completes. This is beneficial because it prevents there being a gap between
+   hitting the send button and having the "remote echo" arrive.
+ - Mark messages which failed to send as not sent.
  - Automatically retry requests to send messages due to network errors.
  - Automatically retry requests to send messages due to rate limiting errors.
- - Mark events' sent status (e.g. 'not sent').
- - Handle "local echo" of messages sent.
  - Handle queueing of messages.
- - Handle pagination.
+ - Handles pagination.
+ - Handle assigning push actions for events.
+ - Handles room initial sync on accepting invites.
+ - Handles WebRTC calling.
+
+Later versions of the SDK will:
  - Expose a `RoomSummary` which would be suitable for a recents page.
  - Provide different pluggable storage layers (e.g. local storage, database-backed)
 
 Usage
 =====
 
+
 Conventions
 -----------
 
@@ -72,7 +137,7 @@ are updated.
   client.on("event", function(event) {
     console.log(event.getType());
   });
-  
+
   // Listen for typing changes
   client.on("RoomMember.typing", function(event, member) {
     if (member.typing) {
@@ -82,35 +147,43 @@ are updated.
       console.log(member.name + " stopped typing.");
     }
   });
+
+  // start the client to setup the connection to the server
+  client.startClient();
 ```
 
-### Promises or Callbacks
+### Promises and Callbacks
 
-The SDK supports *both* callbacks and Promises (Q). The convention
-you'll see used is:
+Most of the methods in the SDK are asynchronous: they do not directly return a
+result, but instead return a [Promise](http://documentup.com/kriskowal/q/)
+which will be fulfilled in the future.
+
+The typical usage is something like:
 
 ```javascript
-  var promise = matrixClient.someMethod(arg1, arg2, callback);
-```
-  
-The ``callback`` parameter is optional, so you could do:
-
-```javascript
-  matrixClient.someMethod(arg1, arg2).then(function(result) {
+  matrixClient.someMethod(arg1, arg2).done(function(result) {
     ...
   });
 ```
 
-Alternatively, you could do:
+Alternatively, if you have a Node.js-style ``callback(err, result)`` function,
+you can pass the result of the promise into it with something like:
 
 ```javascript
-  matrixClient.someMethod(arg1, arg2, function(result) {
-    ...
-  });
+  matrixClient.someMethod(arg1, arg2).nodeify(callback);
 ```
-  
-Methods which support this will be clearly marked as returning
-``Promises``.
+
+The main thing to note is that it is an error to discard the result of a
+promise-returning function, as that will cause exceptions to go unobserved. If
+you have nothing better to do with the result, just call ``.done()`` on it. See
+http://documentup.com/kriskowal/q/#the-end for more information.
+
+Methods which return a promise show this in their documentation.
+
+Many methods in the SDK support *both* Node.js-style callbacks *and* Promises,
+via an optional ``callback`` argument. The callback support is now deprecated:
+new methods do not include a ``callback`` argument, and in the future it may be
+removed from existing methods.
 
 Examples
 --------
@@ -138,10 +211,10 @@ core functionality of the SDK. These examples assume the SDK is setup like this:
            });
        }
    });
-   
+
    matrixClient.startClient();
 ```
-   
+
 ### Print out messages for all rooms
 
 ```javascript
@@ -157,7 +230,7 @@ core functionality of the SDK. These examples assume the SDK is setup like this:
            "(%s) %s :: %s", room.name, event.getSender(), event.getContent().body
        );
    });
-   
+
    matrixClient.startClient();
 ```
 
@@ -189,10 +262,10 @@ Output:
            );
        }
    });
-   
+
    matrixClient.startClient();
 ```
-   
+
 Output:
 ```
   My Room
@@ -202,25 +275,63 @@ Output:
   (join) Bob
   (invite) @charlie:localhost
 ```
-  
+
 API Reference
 =============
 
 A hosted reference can be found at
-http://matrix-org.github.io/matrix-js-sdk/global.html
+http://matrix-org.github.io/matrix-js-sdk/index.html
 
 This SDK uses JSDoc3 style comments. You can manually build and
 host the API reference from the source files like this:
 
 ```
-  $ npm install -g jsdoc
-  $ jsdoc -r lib/
-  $ cd out
+  $ yarn gendoc
+  $ cd .jsdoc
   $ python -m SimpleHTTPServer 8005
 ```
-  
-Then visit ``http://localhost:8005`` to see the API docs. By
-default, ``jsdoc`` produces HTML in the ``out`` folder.
+
+Then visit ``http://localhost:8005`` to see the API docs.
+
+End-to-end encryption support
+=============================
+
+The SDK supports end-to-end encryption via the Olm and Megolm protocols, using
+[libolm](https://gitlab.matrix.org/matrix-org/olm). It is left up to the 
+application to make libolm available, via the ``Olm`` global.
+
+It is also necessry to call ``matrixClient.initCrypto()`` after creating a new
+``MatrixClient`` (but **before** calling ``matrixClient.startClient()``) to
+initialise the crypto layer.
+
+If the ``Olm`` global is not available, the SDK will show a warning, as shown
+below; ``initCrypto()`` will also fail.
+
+```
+Unable to load crypto module: crypto will be disabled: Error: global.Olm is not defined
+```
+
+If the crypto layer is not (successfully) initialised, the SDK will continue to
+work for unencrypted rooms, but it will not support the E2E parts of the Matrix
+specification.
+
+To provide the Olm library in a browser application:
+
+ * download the transpiled libolm (from https://packages.matrix.org/npm/olm/).
+ * load ``olm.js`` as a ``<script>`` *before* ``browser-matrix.js``.
+ 
+To provide the Olm library in a node.js application:
+
+ * ``yarn add https://packages.matrix.org/npm/olm/olm-3.0.0.tgz``
+   (replace the URL with the latest version you want to use from
+    https://packages.matrix.org/npm/olm/)
+ * ``global.Olm = require('olm');`` *before* loading ``matrix-js-sdk``.
+
+If you want to package Olm as dependency for your node.js application, you can
+use ``yarn add https://packages.matrix.org/npm/olm/olm-3.0.0.tgz``. If your
+application also works without e2e crypto enabled, add ``--optional`` to mark it
+as an optional dependency.
+
 
 Contributing
 ============
@@ -229,7 +340,7 @@ want to use this SDK, skip this section.*
 
 First, you need to pull in the right build tools:
 ```
- $ npm install
+ $ yarn install
 ```
 
 Building
@@ -237,20 +348,20 @@ Building
 
 To build a browser version from scratch when developing::
 ```
- $ npm run build
+ $ yarn build
 ```
 
 To constantly do builds when files are modified (using ``watchify``)::
 ```
- $ npm run watch
+ $ yarn watch
 ```
 
 To run tests (Jasmine)::
 ```
- $ npm test
+ $ yarn test
 ```
- 
-To run linters (Google Closure Linter and JSHint):
+
+To run linting:
 ```
- $ npm run lint
+ $ yarn lint
 ```

browser-index.js

@@ -1,4 +1,35 @@
 var matrixcs = require("./lib/matrix");
-matrixcs.request(require("browser-request"));
+const request = require('browser-request');
+const queryString = require('qs');
+
+matrixcs.request(function(opts, fn) {
+    // We manually fix the query string for browser-request because
+    // it doesn't correctly handle cases like ?via=one&via=two. Instead
+    // we mimic `request`'s query string interface to make it all work
+    // as expected.
+    // browser-request will happily take the constructed string as the
+    // query string without trying to modify it further.
+    opts.qs = queryString.stringify(opts.qs || {}, opts.qsStringifyOptions);
+    return request(opts, fn);
+});
+
+// just *accessing* indexedDB throws an exception in firefox with
+// indexeddb disabled.
+var indexedDB;
+try {
+    indexedDB = global.indexedDB;
+} catch(e) {}
+
+// if our browser (appears to) support indexeddb, use an indexeddb crypto store.
+if (indexedDB) {
+    matrixcs.setCryptoStoreFactory(
+        function() {
+            return new matrixcs.IndexedDBCryptoStore(
+                indexedDB, "matrix-js-sdk:crypto"
+            );
+        }
+    );
+}
+
 module.exports = matrixcs; // keep export for browserify package deps
 global.matrixcs = matrixcs;

dist/README

@@ -1 +0,0 @@
-Release builds and development builds will reside here.

docs/storage-notes.md

@@ -0,0 +1,70 @@
+# Browser Storage Notes
+
+## Overview
+
+Browsers examined: Firefox 67, Chrome 75
+
+The examination below applies to the default, non-persistent storage policy.
+
+## Quota Measurement
+
+Browsers appear to enforce and measure the quota in terms of space on disk, not
+data stored, so you may be able to store more data than the simple sum of all
+input data depending on how compressible your data is.
+
+## Quota Limit
+
+Specs and documentation suggest we should consistently receive
+`QuotaExceededError` when we're near space limits, but the reality is a bit
+blurrier.
+
+When we are low on disk space overall or near the group limit / origin quota:
+
+* Chrome
+    * Log database may fail to start with AbortError
+    * IndexedDB fails to start for crypto: AbortError in connect from
+      indexeddb-store-worker
+    * When near the quota, QuotaExceededError is used more consistently
+* Firefox
+    * The first error will be QuotaExceededError
+    * Future write attempts will fail with various errors when space is low,
+      including nonsense like "InvalidStateError: A mutation operation was
+      attempted on a database that did not allow mutations."
+    * Once you start getting errors, the DB is effectively wedged in read-only
+      mode
+    * Can revive access if you reopen the DB
+
+## Cache Eviction
+
+While the Storage Standard says all storage for an origin group should be
+limited by a single quota, in practice, browsers appear to handle `localStorage`
+separately from the others, so it has a separate quota limit and isn't evicted
+when low on space.
+
+* Chrome, Firefox
+    * IndexedDB for origin deleted
+    * Local Storage remains in place
+
+## Persistent Storage
+
+Storage Standard offers a `navigator.storage.persist` API that can be used to
+request persistent storage that won't be deleted by the browser because of low
+space.
+
+* Chrome
+    * Chrome 75 seems to grant this without any prompt based on [interaction
+      criteria](https://developers.google.com/web/updates/2016/06/persistent-storage)
+* Firefox
+    * Firefox 67 shows a prompt to grant
+    * Reverting persistent seems to require revoking permission _and_ clearing
+      site data
+
+## Storage Estimation
+
+Storage Standard offers a `navigator.storage.estimate` API to get some clue of
+how much space remains.
+
+* Chrome, Firefox
+    * Can run this at any time to request an estimate of space remaining
+* Firefox
+    * Returns `0` for `usage` if a site is persisted

docs/warning-on-unverified-devices.txt

@@ -0,0 +1,31 @@
+Random notes from Matthew on the two possible approaches for warning users about unexpected
+unverified devices popping up in their rooms....
+
+Original idea...
+================
+
+Warn when an existing user adds an unknown device to a room.
+
+Warn when a user joins the room with unverified or unknown devices.
+
+Warn when you initial sync if the room has any unverified devices in it.
+ ^ this is good enough if we're doing local storage.
+ OR, better:
+Warn when you initial sync if the room has any new undefined devices since you were last there.
+ => This means persisting the rooms that devices are in, across initial syncs.
+
+
+Updated idea...
+===============
+
+Warn when the user tries to send a message:
+  - If the room has unverified devices which the user has not yet been told about in the context of this room
+    ...or in the context of this user?  currently all verification is per-user, not per-room.
+    ...this should be good enough.
+
+  - so track whether we have warned the user or not about unverified devices - blocked, unverified, verified, unverified_warned.
+    throw an error when trying to encrypt if there are pure unverified devices there
+    app will have to search for the devices which are pure unverified to warn about them - have to do this from MembersList anyway?
+      - or megolm could warn which devices are causing the problems.
+
+Why do we wait to establish outbound sessions?  It just makes a horrible pause when we first try to send a message... but could otherwise unnecessarily consume resources?

examples/browser/lib/matrix.js

@@ -1 +1 @@
-../../../dist/browser-matrix-dev.js
+../../../dist/browser-matrix.js

examples/node/app.js

@@ -3,6 +3,7 @@
 var myUserId = "@example:localhost";
 var myAccessToken = "QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP";
 var sdk = require("matrix-js-sdk");
+var clc = require("cli-color");
 var matrixClient = sdk.createClient({
     baseUrl: "http://localhost:8008",
     accessToken: myAccessToken,
@@ -15,54 +16,142 @@ var viewingRoom = null;
 var numMessagesToShow = 20;
 
 // Reading from stdin
+var CLEAR_CONSOLE = '\x1B[2J';
 var readline = require("readline");
 var rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
-    terminal: false
+    completer: completer
 });
+rl.setPrompt("$ ");
 rl.on('line', function(line) {
-    if (line.indexOf("/enter ") === 0 && !viewingRoom) {
-        var roomIndex = line.split(" ")[1];
-        viewingRoom = roomList[roomIndex];
-        if (viewingRoom.getMember(myUserId).membership === "invite") {
-            // join the room first
-            matrixClient.joinRoom(viewingRoom.roomId).done(function() {
+    if (line.trim().length === 0) {
+        rl.prompt();
+        return;
+    }
+    if (line === "/help") {
+        printHelp();
+        rl.prompt();
+        return;
+    }
+
+    if (viewingRoom) {
+        if (line === "/exit") {
+            viewingRoom = null;
+            printRoomList();
+        }
+        else if (line === "/members") {
+            printMemberList(viewingRoom);
+        }
+        else if (line === "/roominfo") {
+            printRoomInfo(viewingRoom);
+        }
+        else if (line === "/resend") {
+            // get the oldest not sent event.
+            var notSentEvent;
+            for (var i = 0; i < viewingRoom.timeline.length; i++) {
+                if (viewingRoom.timeline[i].status == sdk.EventStatus.NOT_SENT) {
+                    notSentEvent = viewingRoom.timeline[i];
+                    break;
+                }
+            }
+            if (notSentEvent) {
+                matrixClient.resendEvent(notSentEvent, viewingRoom).done(function() {
+                    printMessages();
+                    rl.prompt();
+                }, function(err) {
+                    printMessages();
+                    print("/resend Error: %s", err);
+                    rl.prompt();
+                });
                 printMessages();
+                rl.prompt();
+            }
+        }
+        else if (line.indexOf("/more ") === 0) {
+            var amount = parseInt(line.split(" ")[1]) || 20;
+            matrixClient.scrollback(viewingRoom, amount).done(function(room) {
+                printMessages();
+                rl.prompt();
             }, function(err) {
-                console.log("Error: %s", err);
+                print("/more Error: %s", err);
+            });
+        }
+        else if (line.indexOf("/invite ") === 0) {
+            var userId = line.split(" ")[1].trim();
+            matrixClient.invite(viewingRoom.roomId, userId).done(function() {
+                printMessages();
+                rl.prompt();
+            }, function(err) {
+                print("/invite Error: %s", err);
+            });
+        }
+        else if (line.indexOf("/file ") === 0) {
+            var filename = line.split(" ")[1].trim();
+            var stream = fs.createReadStream(filename);
+            matrixClient.uploadContent({
+                stream: stream,
+                name: filename
+            }).done(function(url) {
+                var content = {
+                    msgtype: "m.file",
+                    body: filename,
+                    url: JSON.parse(url).content_uri
+                };
+                matrixClient.sendMessage(viewingRoom.roomId, content);
             });
         }
         else {
+            matrixClient.sendTextMessage(viewingRoom.roomId, line).finally(function() {
+                printMessages();
+                rl.prompt();
+            });
+            // print local echo immediately
             printMessages();
         }
     }
-    else if (line === "/exit" && viewingRoom) {
-        viewingRoom = null;
-        printRoomList();
-    }
-    else if (line === "/members" && viewingRoom) {
-        printMemberList();
-    }
-    else if (line === "/help") {
-        printHelp();
-    }
-    else if (viewingRoom) {
-        matrixClient.sendTextMessage(viewingRoom.roomId, line).done(function() {
-            console.log('\x1B[2J'); // clear console
-            printMessages();
-        }, function(err) {
-            console.log("Error: %s", err);
-        });
+    else {
+        if (line.indexOf("/join ") === 0) {
+            var roomIndex = line.split(" ")[1];
+            viewingRoom = roomList[roomIndex];
+            if (viewingRoom.getMember(myUserId).membership === "invite") {
+                // join the room first
+                matrixClient.joinRoom(viewingRoom.roomId).done(function(room) {
+                    setRoomList();
+                    viewingRoom = room;
+                    printMessages();
+                    rl.prompt();
+                }, function(err) {
+                    print("/join Error: %s", err);
+                });
+            }
+            else {
+                printMessages();
+            }
+        } 
     }
+    rl.prompt();
 });
 // ==== END User input
 
 // show the room list after syncing.
-matrixClient.on("syncComplete", function() {
-    roomList = matrixClient.getRooms();
-    printRoomList();
-    printHelp();
+matrixClient.on("sync", function(state, prevState, data) {
+    switch (state) {
+        case "PREPARED":
+          setRoomList();
+          printRoomList();
+          printHelp();
+          rl.prompt();
+        break;
+   }
+});
+
+matrixClient.on("Room", function() {
+    setRoomList();
+    if (!viewingRoom) {
+        printRoomList();
+        rl.prompt();
+    }
 });
 
 // print incoming messages.
@@ -76,24 +165,79 @@ matrixClient.on("Room.timeline", function(event, room, toStartOfTimeline) {
     printLine(event);
 });
 
+function setRoomList() {
+    roomList = matrixClient.getRooms();
+    roomList.sort(function(a,b) {
+        // < 0 = a comes first (lower index) - we want high indexes = newer
+        var aMsg = a.timeline[a.timeline.length-1];
+        if (!aMsg) {
+            return -1;
+        }
+        var bMsg = b.timeline[b.timeline.length-1];
+        if (!bMsg) {
+            return 1;
+        }
+        if (aMsg.getTs() > bMsg.getTs()) {
+            return 1;
+        }
+        else if (aMsg.getTs() < bMsg.getTs()) {
+            return -1;
+        }
+        return 0;
+    });
+}
+
 function printRoomList() {
-    console.log("Room List:");
+    print(CLEAR_CONSOLE);
+    print("Room List:");
+    var fmts = {
+        "invite": clc.cyanBright,
+        "leave": clc.blackBright
+    };
     for (var i = 0; i < roomList.length; i++) {
-        console.log(
-            "[%s] %s (%s members)",
-            i, roomList[i].name, roomList[i].getJoinedMembers().length
+        var msg = roomList[i].timeline[roomList[i].timeline.length-1];
+        var dateStr = "---";
+        var fmt;
+        if (msg) {
+            dateStr = new Date(msg.getTs()).toISOString().replace(
+                /T/, ' ').replace(/\..+/, '');
+        }
+        var myMembership = roomList[i].getMyMembership();
+        if (myMembership) {
+            fmt = fmts[myMembership];
+        }
+        var roomName = fixWidth(roomList[i].name, 25);
+        print(
+            "[%s] %s (%s members)  %s",
+            i, fmt ? fmt(roomName) : roomName,
+            roomList[i].getJoinedMembers().length,
+            dateStr
         );
     }
 }
 
 function printHelp() {
-    console.log("Global commands:");
-    console.log("  '/help' : Show this help.");
-    console.log("Room list index commands:");
-    console.log("  '/enter <index>' Enter a room, e.g. '/enter 5'");
-    console.log("Room commands:");
-    console.log("  '/exit' Return to the room list index.");
-    console.log("  '/members' Show the room member list.");
+    var hlp = clc.italic.white;
+    print("Global commands:", hlp);
+    print("  '/help' : Show this help.", clc.white);
+    print("Room list index commands:", hlp);
+    print("  '/join <index>' Join a room, e.g. '/join 5'", clc.white);
+    print("Room commands:", hlp);
+    print("  '/exit' Return to the room list index.", clc.white);
+    print("  '/members' Show the room member list.", clc.white);
+    print("  '/invite @foo:bar' Invite @foo:bar to the room.", clc.white);
+    print("  '/more 15' Scrollback 15 events", clc.white);
+    print("  '/resend' Resend the oldest event which failed to send.", clc.white);
+    print("  '/roominfo' Display room info e.g. name, topic.", clc.white);
+}
+
+function completer(line) {
+    var completions = [
+        "/help", "/join ", "/exit", "/members", "/more ", "/resend", "/invite"
+    ];
+    var hits = completions.filter(function(c) { return c.indexOf(line) == 0 });
+    // show all completions if none found
+    return [hits.length ? hits : completions, line]
 }
 
 function printMessages() {
@@ -101,19 +245,21 @@ function printMessages() {
         printRoomList();
         return;
     }
-    console.log('\x1B[2J'); // clear console
-    var mostRecentMessages = viewingRoom.timeline.slice(numMessagesToShow * -1);
+    print(CLEAR_CONSOLE);
+    var mostRecentMessages = viewingRoom.timeline;
     for (var i = 0; i < mostRecentMessages.length; i++) {
         printLine(mostRecentMessages[i]);
     }
 }
 
-function printMemberList() {
-    if (!viewingRoom) {
-        printRoomList();
-        return;
-    }
-    var members = viewingRoom.currentState.getMembers();
+function printMemberList(room) {
+    var fmts = {
+        "join": clc.green,
+        "ban": clc.red,
+        "invite": clc.blue,
+        "leave": clc.blackBright
+    };
+    var members = room.currentState.getMembers();
     // sorted based on name.
     members.sort(function(a, b) {
         if (a.name > b.name) {
@@ -124,23 +270,57 @@ function printMemberList() {
         }
         return 0;
     });
-    console.log("Membership list for room \"%s\"", viewingRoom.name);
-    console.log(new Array(viewingRoom.name.length + 28).join("-"));
-    viewingRoom.currentState.getMembers().forEach(function(member) {
+    print("Membership list for room \"%s\"", room.name);
+    print(new Array(room.name.length + 28).join("-"));
+    room.currentState.getMembers().forEach(function(member) {
         if (!member.membership) {
             return;
         }
+        var fmt = fmts[member.membership] || function(a){return a;};
         var membershipWithPadding = (
             member.membership + new Array(10 - member.membership.length).join(" ")
         );
-        console.log(
-            "%s :: %s (%s)", membershipWithPadding, member.name, 
-            (member.userId === myUserId ? "Me" : member.userId)
+        print(
+            "%s"+fmt(" :: ")+"%s"+fmt(" (")+"%s"+fmt(")"), 
+            membershipWithPadding, member.name, 
+            (member.userId === myUserId ? "Me" : member.userId),
+            fmt
         );
     });
 }
 
+function printRoomInfo(room) {
+    var eventDict = room.currentState.events;
+    var eTypeHeader = "    Event Type(state_key)    ";
+    var sendHeader = "        Sender        ";
+    // pad content to 100
+    var restCount = (
+        100 - "Content".length - " | ".length - " | ".length - 
+        eTypeHeader.length - sendHeader.length
+    );
+    var padSide = new Array(Math.floor(restCount/2)).join(" ");
+    var contentHeader = padSide + "Content" + padSide;
+    print(eTypeHeader+sendHeader+contentHeader);
+    print(new Array(100).join("-"));
+    Object.keys(eventDict).forEach(function(eventType) {
+        if (eventType === "m.room.member") { return; } // use /members instead.
+        Object.keys(eventDict[eventType]).forEach(function(stateKey) {
+            var typeAndKey = eventType + (
+                stateKey.length > 0 ? "("+stateKey+")" : ""
+            );
+            var typeStr = fixWidth(typeAndKey, eTypeHeader.length);
+            var event = eventDict[eventType][stateKey];
+            var sendStr = fixWidth(event.getSender(), sendHeader.length);
+            var contentStr = fixWidth(
+                JSON.stringify(event.getContent()), contentHeader.length
+            );
+            print(typeStr+" | "+sendStr+" | "+contentStr);
+        });
+    })
+}
+
 function printLine(event) {
+    var fmt;
     var name = event.sender ? event.sender.name : event.getSender();
     var time = new Date(
         event.getTs()
@@ -149,6 +329,14 @@ function printLine(event) {
     if (event.getSender() === myUserId) {
         name = "Me";
         separator = ">>>";
+        if (event.status === sdk.EventStatus.SENDING) {
+            separator = "...";
+            fmt = clc.xterm(8);
+        }
+        else if (event.status === sdk.EventStatus.NOT_SENT) {
+            separator = " x ";
+            fmt = clc.redBright;
+        }
     }
     var body = "";
 
@@ -169,6 +357,7 @@ function printLine(event) {
             "[State: "+stateName+" updated to: "+JSON.stringify(event.getContent())+"]"
         );
         separator = "---";
+        fmt = clc.xterm(249).italic;
     }
     else {
         // random message event
@@ -176,8 +365,46 @@ function printLine(event) {
             "[Message: "+event.getType()+" Content: "+JSON.stringify(event.getContent())+"]"
         );
         separator = "---";
+        fmt = clc.xterm(249).italic;
+    }
+    if (fmt) {
+        print(
+            "[%s] %s %s %s", time, name, separator, body, fmt
+        );
+    }
+    else {
+        print("[%s] %s %s %s", time, name, separator, body);
     }
-    console.log("[%s] %s %s %s", time, name, separator, body);
 }
-   
-matrixClient.startClient(numMessagesToShow);  // messages for each room.
+
+function print(str, formatter) {
+    if (typeof arguments[arguments.length-1] === "function") {
+        // last arg is the formatter so get rid of it and use it on each
+        // param passed in but not the template string.
+        var newArgs = [];
+        var i = 0;
+        for (i=0; i<arguments.length-1; i++) {
+            newArgs.push(arguments[i]);
+        }
+        var fmt = arguments[arguments.length-1];
+        for (i=0; i<newArgs.length; i++) {
+            newArgs[i] = fmt(newArgs[i]);
+        }
+        console.log.apply(console.log, newArgs);
+    }
+    else {
+        console.log.apply(console.log, arguments);
+    }
+}
+
+function fixWidth(str, len) {
+    if (str.length > len) {
+        return str.substr(0, len-2) + "\u2026";
+    }
+    else if (str.length < len) {
+        return str + new Array(len - str.length).join(" ");
+    }
+    return str;
+}
+
+matrixClient.startClient(numMessagesToShow);  // messages for each room.

examples/node/package.json

@@ -7,5 +7,8 @@
     "preinstall": "npm install ../.."
   },
   "author": "",
-  "license": "Apache 2.0"
+  "license": "Apache 2.0",
+  "dependencies": {
+    "cli-color": "^1.0.0"
+  }
 }

examples/voip/README.md

@@ -0,0 +1,9 @@
+To try it out, **you must build the SDK first** and then host this folder:
+
+```
+ $ npm run build
+ $ cd examples/voip
+ $ python -m SimpleHTTPServer 8003
+```
+
+Then visit ``http://localhost:8003``.

examples/voip/browserTest.js

@@ -0,0 +1,97 @@
+"use strict";
+console.log("Loading browser sdk");
+var BASE_URL = "https://matrix.org";
+var TOKEN = "accesstokengoeshere";
+var USER_ID = "@username:localhost";
+var ROOM_ID = "!room:id";
+
+
+var client = matrixcs.createClient({
+    baseUrl: BASE_URL,
+    accessToken: TOKEN,
+    userId: USER_ID
+});
+var call;
+
+function disableButtons(place, answer, hangup) {
+    document.getElementById("hangup").disabled = hangup;
+    document.getElementById("answer").disabled = answer;
+    document.getElementById("call").disabled = place;
+}
+
+function addListeners(call) {
+    var lastError = "";
+    call.on("hangup", function() {
+        disableButtons(false, true, true);
+        document.getElementById("result").innerHTML = (
+            "<p>Call ended. Last error: "+lastError+"</p>"
+        );
+    });
+    call.on("error", function(err) {
+        lastError = err.message;
+        call.hangup();
+        disableButtons(false, true, true);
+    });
+}
+
+window.onload = function() {
+    document.getElementById("result").innerHTML = "<p>Please wait. Syncing...</p>";
+    document.getElementById("config").innerHTML = "<p>" +
+        "Homeserver: <code>"+BASE_URL+"</code><br/>"+
+        "Room: <code>"+ROOM_ID+"</code><br/>"+
+        "User: <code>"+USER_ID+"</code><br/>"+
+        "</p>";
+    disableButtons(true, true, true);
+};
+
+client.on("sync", function(state, prevState, data) {
+    switch (state) {
+        case "PREPARED":
+          syncComplete();
+        break;
+   }
+});
+
+function syncComplete() {
+    document.getElementById("result").innerHTML = "<p>Ready for calls.</p>";
+    disableButtons(false, true, true);
+
+    document.getElementById("call").onclick = function() {
+        console.log("Placing call...");
+        call = matrixcs.createNewMatrixCall(
+            client, ROOM_ID
+        );
+        console.log("Call => %s", call);
+        addListeners(call);
+        call.placeVideoCall(
+            document.getElementById("remote"),
+            document.getElementById("local")
+        );
+        document.getElementById("result").innerHTML = "<p>Placed call.</p>";
+        disableButtons(true, true, false);
+    };
+
+    document.getElementById("hangup").onclick = function() {
+        console.log("Hanging up call...");
+        console.log("Call => %s", call);
+        call.hangup();
+        document.getElementById("result").innerHTML = "<p>Hungup call.</p>";
+    };
+
+    document.getElementById("answer").onclick = function() {
+        console.log("Answering call...");
+        console.log("Call => %s", call);
+        call.answer();
+        disableButtons(true, true, false);
+        document.getElementById("result").innerHTML = "<p>Answered call.</p>";
+    };
+
+    client.on("Call.incoming", function(c) {
+        console.log("Call ringing");
+        disableButtons(true, false, false);
+        document.getElementById("result").innerHTML = "<p>Incoming call...</p>";
+        call = c;
+        addListeners(call);
+    });
+}
+client.startClient();

examples/voip/index.html

@@ -0,0 +1,26 @@
+<html>
+<head>
+<title>VoIP Test</title>
+<script src="lib/matrix.js"></script>
+<script src="browserTest.js"></script>
+</head>
+<body>
+	You can place and receive calls with this example. Make sure to edit the
+    constants in <code>browserTest.js</code> first.
+    <div id="config"></div>
+    <div id="result"></div>
+    <button id="call">Place Call</button>
+    <button id="answer">Answer Call</button>
+    <button id="hangup">Hangup Call</button>
+    <div id="videoBackground">
+        <div id="videoContainer">
+            <video id="remote"></video>
+        </div>
+    </div>
+    <div id="videoBackground">
+        <div id="videoContainer">
+            <video id="local"></video>
+        </div>
+    </div>
+</body>
+</html>

examples/voip/lib/matrix.js

@@ -0,0 +1 @@
+../../../dist/browser-matrix.js

git-hooks/pre-commit

@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# pre-commit: script to run checks on a working copy before commit
+#
+# To use, symlink it into .git/hooks:
+#    ln -s ../../git-hooks/pre-commit .git/hooks
+#
+
+set -e
+
+# create a temp dir
+tmpdir=`mktemp -d`
+trap 'rm -rf "$tmpdir"' EXIT
+
+# get a copy of the index
+git checkout-index --prefix="$tmpdir/" -a
+
+# keep node_modules/.bin on the path
+rootdir=`git rev-parse --show-toplevel`
+export PATH="$rootdir/node_modules/.bin:$PATH"
+
+# now run our checks
+cd "$tmpdir"
+yarn lint

index.js

@@ -1,3 +1,6 @@
 var matrixcs = require("./lib/matrix");
 matrixcs.request(require("request"));
 module.exports = matrixcs;
+
+var utils = require("./lib/utils");
+utils.runPolyfills();

jenkins.sh

@@ -0,0 +1,36 @@
+#!/bin/bash -l
+
+set -x
+
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+nvm use 10 || exit $?
+yarn install || exit $?
+
+RC=0
+
+function fail {
+    echo $@ >&2
+    RC=1
+}
+
+# don't use last time's test reports
+rm -rf reports coverage || exit $?
+
+yarn test || fail "yarn test finished with return code $?"
+
+yarn -s lint -f checkstyle > eslint.xml ||
+    fail "eslint finished with return code $?"
+
+# delete the old tarball, if it exists
+rm -f matrix-js-sdk-*.tgz
+
+# `yarn pack` doesn't seem to run scripts, however that seems okay here as we
+# just built as part of `install` above.
+yarn pack ||
+    fail "yarn pack finished with return code $?"
+
+yarn gendoc || fail "JSDoc failed with code $?"
+
+exit $RC

lib/http-api.js

@@ -1,312 +0,0 @@
-"use strict";
-/**
- * This is an internal module. See {@link MatrixHttpApi} for the public class.
- * @module http-api
- */
-var q = require("q");
-var utils = require("./utils");
-
-/*
-TODO:
-- CS: complete register function (doing stages)
-- Identity server: linkEmail, authEmail, bindEmail, lookup3pid
-- uploadContent (?)
-*/
-
-/**
- * A constant representing the URI path for version 1 of the Client-Server HTTP API.
- */
-module.exports.PREFIX_V1 = "/_matrix/client/api/v1";
-
-/**
- * A constant representing the URI path for version 2 alpha of the Client-Server
- * HTTP API.
- */
-module.exports.PREFIX_V2_ALPHA_PREFIX = "/_matrix/client/v2_alpha";
-
-/**
- * Construct a MatrixHttpApi.
- * @constructor
- * @param {Object} opts The options to use for this HTTP API.
- * @param {string} opts.baseUrl Required. The base client-server URL e.g.
- * 'http://localhost:8008'.
- * @param {Function} opts.request Required. The function to call for HTTP
- * requests. This function must look like function(opts, callback){ ... }.
- * @param {string} opts.prefix Required. The matrix client prefix to use, e.g.
- * '/_matrix/client/api/v1'. See PREFIX_V1 and PREFIX_V2_ALPHA for constants.
- * @param {bool} opts.onlyData True to return only the 'data' component of the
- * response (e.g. the parsed HTTP body). If false, requests will return status
- * codes and headers in addition to data. Default: false.
- * @param {string} opts.accessToken The access_token to send with requests. Can be
- * null to not send an access token.
- */
-module.exports.MatrixHttpApi = function MatrixHttpApi(opts) {
-    utils.checkObjectHasKeys(opts, ["baseUrl", "request", "prefix"]);
-    opts.onlyData = opts.onlyData || false;
-    this.opts = opts;
-};
-
-module.exports.MatrixHttpApi.prototype = {
-
-    // URI functions
-    // =============
-
-    /**
-     * Get the HTTP URL for an MXC URI.
-     * @param {string} mxc The mxc:// URI.
-     * @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".
-     * @return {string} The complete URL to the content.
-     */
-    getHttpUriForMxc: function(mxc, width, height, resizeMethod) {
-        if (typeof mxc !== "string" || !mxc) {
-            return mxc;
-        }
-        if (mxc.indexOf("mxc://") !== 0) {
-            return mxc;
-        }
-        var serverAndMediaId = mxc.slice(6); // strips mxc://
-        var prefix = "/_matrix/media/v1/download/";
-        var params = {};
-
-        if (width) {
-            params.width = width;
-        }
-        if (height) {
-            params.height = height;
-        }
-        if (resizeMethod) {
-            params.method = resizeMethod;
-        }
-        if (utils.keys(params).length > 0) {
-            // these are thumbnailing params so they probably want the
-            // thumbnailing API...
-            prefix = "/_matrix/media/v1/thumbnail/";
-        }
-
-        var fragmentOffset = serverAndMediaId.indexOf("#"),
-            fragment = "";
-        if (fragmentOffset >= 0) {
-            fragment = serverAndMediaId.substr(fragmentOffset);
-            serverAndMediaId = serverAndMediaId.substr(0, fragmentOffset);
-        }
-        return this.credentials.baseUrl + prefix + serverAndMediaId +
-            (utils.keys(params).length === 0 ? "" :
-            ("?" + utils.encodeParams(params))) + fragment;
-    },
-
-    /**
-     * Get an identicon URL from an arbitrary string.
-     * @param {string} identiconString The string to create an identicon for.
-     * @param {Number} width The desired width of the image in pixels.
-     * @param {Number} height The desired height of the image in pixels.
-     * @return {string} The complete URL to the identicon.
-     */
-    getIdenticonUri: function(identiconString, width, height) {
-        if (!identiconString) {
-            return;
-        }
-        if (!width) { width = 96; }
-        if (!height) { height = 96; }
-        var params = {
-            width: width,
-            height: height
-        };
-
-        var path = utils.encodeUri("/_matrix/media/v1/identicon/$ident", {
-            $ident: identiconString
-        });
-        return this.credentials.baseUrl + path +
-            (utils.keys(params).length === 0 ? "" :
-                ("?" + utils.encodeParams(params)));
-    },
-
-    /**
-     * Get the content repository url with query parameters.
-     * @return {Object} An object with a 'base', 'path' and 'params' for base URL,
-     *          path and query parameters respectively.
-     */
-    getContentUri: function() {
-        var params = {
-            access_token: this.credentials.accessToken
-        };
-        return {
-            base: this.credentials.baseUrl,
-            path: "/_matrix/media/v1/upload",
-            params: params
-        };
-    },
-
-    /**
-     * Perform an authorised request to the homeserver.
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @param {string} method The HTTP method e.g. "GET".
-     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
-     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
-     * @param {Object} data The HTTP JSON body.
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
-     * headers: {Object}, code: {Number}}</code>.
-     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
-     * object only.
-     * @return {module:http-api.MatrixError} Rejects with an error if a problem
-     * occurred. This includes network problems and Matrix-specific error JSON.
-     */
-    authedRequest: function(callback, method, path, queryParams, data) {
-        if (!queryParams) { queryParams = {}; }
-        queryParams.access_token = this.opts.accessToken;
-        return this.request(callback, method, path, queryParams, data);
-    },
-
-    /**
-     * Perform a request to the homeserver without any credentials.
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @param {string} method The HTTP method e.g. "GET".
-     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
-     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
-     * @param {Object} data The HTTP JSON body.
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
-     * headers: {Object}, code: {Number}}</code>.
-     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
-     * object only.
-     * @return {module:http-api.MatrixError} Rejects with an error if a problem
-     * occurred. This includes network problems and Matrix-specific error JSON.
-     */
-    request: function(callback, method, path, queryParams, data) {
-        return this.requestWithPrefix(
-            callback, method, path, queryParams, data, this.opts.prefix
-        );
-    },
-
-    /**
-     * Perform an authorised request to the homeserver with a specific path
-     * prefix which overrides the default for this call only. Useful for hitting
-     * different Matrix Client-Server versions.
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @param {string} method The HTTP method e.g. "GET".
-     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
-     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
-     * @param {Object} data The HTTP JSON body.
-     * @param {string} prefix The full prefix to use e.g.
-     * "/_matrix/client/v2_alpha".
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
-     * headers: {Object}, code: {Number}}</code>.
-     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
-     * object only.
-     * @return {module:http-api.MatrixError} Rejects with an error if a problem
-     * occurred. This includes network problems and Matrix-specific error JSON.
-     */
-    authedRequestWithPrefix: function(callback, method, path, queryParams, data,
-                                      prefix) {
-        var fullUri = this.opts.baseUrl + prefix + path;
-        if (!queryParams) {
-            queryParams = {};
-        }
-        queryParams.access_token = this.opts.accessToken;
-        return this._request(callback, method, fullUri, queryParams, data);
-    },
-
-    /**
-     * Perform a request to the homeserver without any credentials but with a
-     * specific path prefix which overrides the default for this call only.
-     * Useful for hitting different Matrix Client-Server versions.
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @param {string} method The HTTP method e.g. "GET".
-     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
-     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
-     * @param {Object} data The HTTP JSON body.
-     * @param {string} prefix The full prefix to use e.g.
-     * "/_matrix/client/v2_alpha".
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
-     * headers: {Object}, code: {Number}}</code>.
-     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
-     * object only.
-     * @return {module:http-api.MatrixError} Rejects with an error if a problem
-     * occurred. This includes network problems and Matrix-specific error JSON.
-     */
-    requestWithPrefix: function(callback, method, path, queryParams, data, prefix) {
-        var fullUri = this.opts.baseUrl + prefix + path;
-        if (!queryParams) {
-            queryParams = {};
-        }
-        return this._request(callback, method, fullUri, queryParams, data);
-    },
-
-    _request: function(callback, method, uri, queryParams, data) {
-        if (callback !== undefined && !utils.isFunction(callback)) {
-            throw Error(
-                "Expected callback to be a function but got " + typeof callback
-            );
-        }
-        var defer = q.defer();
-        this.opts.request(
-            {
-                uri: uri,
-                method: method,
-                withCredentials: false,
-                qs: queryParams,
-                body: data,
-                json: true,
-                _matrix_opts: this.opts
-            },
-            requestCallback(defer, callback, this.opts.onlyData)
-        );
-        return defer.promise;
-    }
-};
-
-
-var requestCallback = function(defer, userDefinedCallback, onlyData) {
-    userDefinedCallback = userDefinedCallback || function() {};
-
-    return function(err, response, body) {
-        if (!err && response.statusCode >= 400) {
-            err = new module.exports.MatrixError(body);
-        }
-
-        if (err) {
-            defer.reject(err);
-            userDefinedCallback(err);
-        }
-        else {
-            var res = {
-                code: response.statusCode,
-                headers: response.headers,
-                data: body
-            };
-            defer.resolve(onlyData ? body : res);
-            userDefinedCallback(null, onlyData ? body : res);
-        }
-    };
-};
-
-/**
- * Construct a Matrix error. This is a JavaScript Error with additional
- * information specific to the standard Matrix error response.
- * @constructor
- * @param {Object} errorJson The Matrix error JSON returned from the homeserver.
- * @prop {string} name The Matrix 'errcode' value, e.g. "M_FORBIDDEN".
- * @prop {string} message The Matrix 'error' value, e.g. "Missing token."
- * @prop {Object} data The raw Matrix error JSON used to construct this object.
- */
-module.exports.MatrixError = function MatrixError(errorJson) {
-    this.name = errorJson.errcode || "Unknown error code";
-    this.message = errorJson.error || "Unknown message";
-    this.data = errorJson;
-};
-module.exports.MatrixError.prototype = Object.create(Error.prototype);
-/** */
-module.exports.MatrixError.prototype.constructor = module.exports.MatrixError;

lib/matrix.js

@@ -1,84 +0,0 @@
-"use strict";
-
-/** The {@link module:models/event.MatrixEvent|MatrixEvent} class. */
-module.exports.MatrixEvent = require("./models/event").MatrixEvent;
-/** The {@link module:store/memory.MatrixInMemoryStore|MatrixInMemoryStore} class. */
-module.exports.MatrixInMemoryStore = require("./store/memory").MatrixInMemoryStore;
-/** The {@link module:http-api.MatrixHttpApi|MatrixHttpApi} class. */
-module.exports.MatrixHttpApi = require("./http-api").MatrixHttpApi;
-/** The {@link module:http-api.MatrixError|MatrixError} class. */
-module.exports.MatrixError = require("./http-api").MatrixError;
-/** The {@link module:client.MatrixClient|MatrixClient} class. */
-module.exports.MatrixClient = require("./client").MatrixClient;
-/** The {@link module:models/room~Room|Room} class. */
-module.exports.Room = require("./models/room");
-/** The {@link module:models/room-member~RoomMember|RoomMember} class. */
-module.exports.RoomMember = require("./models/room-member");
-/** The {@link module:models/room-state~RoomState|RoomState} class. */
-module.exports.RoomState = require("./models/room-state");
-/** The {@link module:models/user~User|User} class. */
-module.exports.User = require("./models/user");
-
-// expose the underlying request object so different environments can use
-// different request libs (e.g. request or browser-request)
-var request;
-/**
- * The function used to perform HTTP requests. Only use this if you want to
- * use a different HTTP library, e.g. Angular's <code>$http</code>. This should
- * be set prior to calling {@link createClient}.
- * @param {requestFunction} r The request function to use.
- */
-module.exports.request = function(r) {
-    request = r;
-};
-
-/**
- * Construct a Matrix Client. Identical to {@link module:client.MatrixClient}
- * except the 'request' option is already specified.
- * @param {(Object|string)} opts The configuration options for this client. If
- * this is a string, it is assumed to be the base URL.
- * @param {string} opts.baseUrl The base URL to the client-server HTTP API.
- * @param {string} opts.accessToken Optional. The access_token for this user.
- * @param {string} opts.userId Optional. The user ID for this user.
- * @param {Object} opts.store Optional. The data store to use. Defaults to
- * {@link module:store/memory.MatrixInMemoryStore}.
- * @return {MatrixClient} A new matrix client.
- */
-module.exports.createClient = function(opts) {
-    if (typeof opts === "string") {
-        opts = {
-            "baseUrl": opts
-        };
-    }
-    opts.request = request;
-    return new module.exports.MatrixClient(opts);
-};
-
-/**
- * The request function interface for performing HTTP requests. This matches the
- * API for the {@link https://github.com/request/request#requestoptions-callback|
- * request NPM module}. The SDK will attempt to call this function in order to
- * perform an HTTP request.
- * @callback requestFunction
- * @param {Object} opts The options for this HTTP request.
- * @param {string} opts.uri The complete URI.
- * @param {string} opts.method The HTTP method.
- * @param {Object} opts.qs The query parameters to append to the URI.
- * @param {Object} opts.body The JSON-serializable object.
- * @param {boolean} opts.json True if this is a JSON request.
- * @param {Object} opts._matrix_opts The underlying options set for
- * {@link MatrixHttpApi}.
- * @param {requestCallback} callback The request callback.
- */
-
- /**
-  * The request callback interface for performing HTTP requests. This matches the
-  * API for the {@link https://github.com/request/request#requestoptions-callback|
-  * request NPM module}. The SDK will implement a callback which meets this
-  * interface in order to handle the HTTP response.
-  * @callback requestCallback
-  * @param {Error} err The error if one occurred, else falsey.
-  * @param {Object} response The HTTP response which consists of
-  * <code>{statusCode: {Number}, headers: {Object}}</code>
-  * @param {Object} body The parsed HTTP response body.
-  */

lib/models/event.js

@@ -1,144 +0,0 @@
-"use strict";
-/**
- * This is an internal module. See {@link MatrixEvent} and {@link RoomEvent} for
- * the public classes.
- * @module models/event
- */
-
-
-/**
- * Enum for event statuses.
- * @readonly
- * @enum {string}
- */
-module.exports.EventStatus = {
-    UNKNOWN: "unknown",
-    SENT: "sent",
-    NOT_SENT: "not_sent",
-    SENDING: "sending",
-    INCOMING: "incoming"
-};
-
-/**
- * Construct a Matrix Event object
- * @constructor
- * @param {Object} event The raw event to be wrapped in this DAO
- * @prop {Object} event The raw event. <b>Do not access this property</b>
- * directly unless you absolutely have to. Prefer the getter methods defined on
- * this class. Using the getter methods shields your app from
- * changes to event JSON between Matrix versions.
- * @prop {RoomMember} sender The room member who sent this event, or null e.g.
- * this is a presence event.
- * @prop {RoomMember} target The room member who is the target of this event, e.g.
- * the invitee, the person being banned, etc.
- * @prop {EventStatus} status The sending status of the event.
- * @prop {boolean} forwardLooking True if this event is 'forward looking', meaning
- * that getDirectionalContent() will return event.content and not event.prev_content.
- * Default: true. <strong>This property is experimental and may change.</strong>
- */
-module.exports.MatrixEvent = function MatrixEvent(event) {
-    this.event = event || {};
-    this.sender = null;
-    this.target = null;
-    this.status = null;
-    this.forwardLooking = true;
-};
-module.exports.MatrixEvent.prototype = {
-    /**
-     * Get the event_id for this event.
-     * @return {string} The event ID, e.g. <code>$143350589368169JsLZx:localhost
-     * </code>
-     */
-    getId: function() {
-        return this.event.event_id;
-    },
-
-    /**
-     * Get the user_id for this event.
-     * @return {string} The user ID, e.g. <code>@alice:matrix.org</code>
-     */
-    getSender: function() {
-        return this.event.user_id;
-    },
-
-    /**
-     * Get the type of event.
-     * @return {string} The event type, e.g. <code>m.room.message</code>
-     */
-    getType: function() {
-        return this.event.type;
-    },
-
-    /**
-     * Get the room_id for this event. This will return <code>undefined</code>
-     * for <code>m.presence</code> events.
-     * @return {string} The room ID, e.g. <code>!cURbafjkfsMDVwdRDQ:matrix.org
-     * </code>
-     */
-    getRoomId: function() {
-        return this.event.room_id;
-    },
-
-    /**
-     * Get the timestamp of this event.
-     * @return {Number} The event timestamp, e.g. <code>1433502692297</code>
-     */
-    getTs: function() {
-        return this.event.origin_server_ts;
-    },
-
-    /**
-     * Get the event content JSON.
-     * @return {Object} The event content JSON, or an empty object.
-     */
-    getContent: function() {
-        return this.event.content || {};
-    },
-
-    /**
-     * Get the previous event content JSON. This will only return something for
-     * state events which exist in the timeline.
-     * @return {Object} The previous event content JSON, or an empty object.
-     */
-    getPrevContent: function() {
-        return this.event.prev_content || {};
-    },
-
-    /**
-     * Get either 'content' or 'prev_content' depending on if this event is
-     * 'forward-looking' or not. This can be modified via event.forwardLooking.
-     * <strong>This method is experimental and may change.</strong>
-     * @return {Object} event.content if this event is forward-looking, else
-     * event.prev_content.
-     */
-    getDirectionalContent: function() {
-        return this.forwardLooking ? this.getContent() : this.getPrevContent();
-    },
-
-    /**
-     * Get the age of this event. This represents the age of the event when the
-     * event arrived at the device, and not the age of the event when this
-     * function was called.
-     * @return {Number} The age of this event in milliseconds.
-     */
-    getAge: function() {
-        return this.event.age;
-    },
-
-    /**
-     * Get the event state_key if it has one. This will return <code>undefined
-     * </code> for message events.
-     * @return {string} The event's <code>state_key</code>.
-     */
-    getStateKey: function() {
-        return this.event.state_key;
-    },
-
-    /**
-     * Check if this event is a state event.
-     * @return {boolean} True if this is a state event.
-     */
-    isState: function() {
-        return this.event.state_key !== undefined;
-    }
-};

lib/models/room-member.js

@@ -1,204 +0,0 @@
-"use strict";
-/**
- * @module models/room-member
- */
-var EventEmitter = require("events").EventEmitter;
-
-var utils = require("../utils");
-
-/**
- * Construct a new room member.
- * @constructor
- * @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.
- * @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'.
- * @throws If the event provided is not <code>m.room.member</code>
- */
-function RoomMember(roomId, userId) {
-    this.roomId = roomId;
-    this.userId = userId;
-    this.typing = false;
-    this.name = userId;
-    this.powerLevel = 0;
-    this.powerLevelNorm = 0;
-    this.user = null;
-    this.membership = null;
-}
-utils.inherits(RoomMember, EventEmitter);
-
-/**
- * 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) {
-    if (event.getType() !== "m.room.member") {
-        return;
-    }
-    var oldMembership = this.membership;
-    this.membership = event.getDirectionalContent().membership;
-
-    var oldName = this.name;
-    this.name = calculateDisplayName(this, event, roomState);
-    if (oldMembership !== this.membership) {
-        this.emit("RoomMember.membership", event, this);
-    }
-    if (oldName !== this.name) {
-        this.emit("RoomMember.name", event, this);
-    }
-};
-
-/**
- * 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;
-    }
-    var maxLevel = powerLevelEvent.getContent().users_default || 0;
-    utils.forEach(utils.values(powerLevelEvent.getContent().users), function(lvl) {
-        maxLevel = Math.max(maxLevel, lvl);
-    });
-    var oldPowerLevel = this.powerLevel;
-    var oldPowerLevelNorm = this.powerLevelNorm;
-    this.powerLevel = (
-        powerLevelEvent.getContent().users[this.userId] ||
-        powerLevelEvent.getContent().users_default ||
-        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.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;
-    }
-    var oldTyping = this.typing;
-    this.typing = false;
-    var typingList = event.getContent().user_ids;
-    if (!utils.isArray(typingList)) {
-        // malformed event :/ bail early. TODO: whine?
-        return;
-    }
-    if (typingList.indexOf(this.userId) !== -1) {
-        this.typing = true;
-    }
-    if (oldTyping !== this.typing) {
-        this.emit("RoomMember.typing", event, this);
-    }
-};
-
-/**
- * Get the membership state of this room member.
- * @return {string} The membership state e.g. 'join'.
- */
-RoomMember.prototype.getMembershipState = function() {
-    return this.event.getContent().membership;
-};
-
-
-function calculateDisplayName(member, event, roomState) {
-    var displayName = event.getDirectionalContent().displayname;
-    var selfUserId = member.userId;
-    if (!displayName) {
-        return selfUserId;
-    }
-    if (!roomState) {
-        return displayName;
-    }
-
-    var stateEvents = utils.filter(
-        roomState.getStateEvents("m.room.member"),
-        function(e) {
-            return e.getContent().displayname === displayName &&
-                e.getSender() !== selfUserId;
-        }
-    );
-    if (stateEvents.length > 1) {
-        // need to disambiguate
-        return displayName + " (" + selfUserId + ")";
-    }
-
-    return displayName;
-}
-
-/**
- * The RoomMember class.
- */
-module.exports = RoomMember;
-
-/**
- * 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.
- * @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.
- * @example
- * matrixClient.on("RoomMember.membership", function(event, member){
- *   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;
- * });
- */

lib/models/room-state.js

@@ -1,195 +0,0 @@
-"use strict";
-/**
- * @module models/room-state
- */
-var EventEmitter = require("events").EventEmitter;
-
-var utils = require("../utils");
-var RoomMember = require("./room-member");
-
-/**
- * Construct room state.
- * @constructor
- * @param {string} roomId Required. The ID of the room which has this state.
- * @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.
- */
-function RoomState(roomId) {
-    this.roomId = roomId;
-    this.members = {
-        // userId: RoomMember
-    };
-    this.events = {
-        // eventType: { stateKey: MatrixEvent }
-    };
-    this.paginationToken = null;
-
-    this._sentinels = {
-        // userId: RoomMember
-    };
-}
-utils.inherits(RoomState, EventEmitter);
-
-/**
- * Get all RoomMembers in this room.
- * @return {Array<RoomMember>} A list of RoomMembers.
- */
-RoomState.prototype.getMembers = function() {
-    return utils.values(this.members);
-};
-
-/**
- * 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) {
-    return this._sentinels[userId] || null;
-};
-
-/**
- * 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[eventType]) {
-        // no match
-        return stateKey === undefined ? [] : null;
-    }
-    if (stateKey === undefined) { // return all values
-        return utils.values(this.events[eventType]);
-    }
-    var event = this.events[eventType][stateKey];
-    return event ? event : null;
-};
-
-/**
- * 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.events"
- */
-RoomState.prototype.setStateEvents = function(stateEvents) {
-    var self = this;
-    utils.forEach(stateEvents, function(event) {
-        if (event.getRoomId() !== self.roomId) { return; }
-        if (!event.isState()) { return; }
-
-        if (self.events[event.getType()] === undefined) {
-            self.events[event.getType()] = {};
-        }
-        self.events[event.getType()][event.getStateKey()] = event;
-        self.emit("RoomState.events", event, self);
-
-        if (event.getType() === "m.room.member") {
-            var userId = event.getStateKey();
-            var member = self.members[userId];
-            if (!member) {
-                member = new RoomMember(event.getRoomId(), userId);
-                self.emit("RoomState.newMember", event, self, member);
-            }
-            // Add a new sentinel for this change. We apply the same
-            // operations to both sentinel and member rather than deep copying
-            // so we don't make assumptions about the properties of RoomMember
-            // (e.g. and manage to break it because deep copying doesn't do
-            // everything).
-            var sentinel = new RoomMember(event.getRoomId(), userId);
-            utils.forEach([member, sentinel], function(roomMember) {
-                roomMember.setMembershipEvent(event, self);
-                // this member may have a power level already, so set it.
-                var pwrLvlEvent = self.getStateEvents("m.room.power_levels", "");
-                if (pwrLvlEvent) {
-                    roomMember.setPowerLevelEvent(pwrLvlEvent);
-                }
-            });
-
-            self._sentinels[userId] = sentinel;
-            self.members[userId] = member;
-            self.emit("RoomState.members", event, self, member);
-        }
-        else if (event.getType() === "m.room.power_levels") {
-            var members = utils.values(self.members);
-            utils.forEach(members, function(member) {
-                member.setPowerLevelEvent(event);
-            });
-        }
-    });
-};
-
-/**
- * Set the current typing event for this room.
- * @param {MatrixEvent} event The typing event
- */
-RoomState.prototype.setTypingEvent = function(event) {
-    utils.forEach(utils.values(this.members), function(member) {
-        member.setTypingEvent(event);
-    });
-};
-
-/**
- * The RoomState class.
- */
-module.exports = RoomState;
-
-/**
- * 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.
- * @example
- * matrixClient.on("RoomState.events", function(event, state){
- *   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.getMembershipState();
- * });
- */
-
- /**
- * Fires whenever a member is added to the members dictionary. The RoomMember
- * will not be fully populated yet (e.g. no membership state).
- * @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'
- * });
- */

lib/models/room.js

@@ -1,228 +0,0 @@
-"use strict";
-/**
- * @module models/room
- */
-var EventEmitter = require("events").EventEmitter;
-
-var RoomState = require("./room-state");
-var RoomSummary = require("./room-summary");
-var utils = require("../utils");
-
-/**
- * Construct a new Room.
- * @constructor
- * @param {string} roomId Required. The ID of this room.
- * @prop {string} roomId The ID of this room.
- * @prop {string} name The human-readable display name for this room.
- * @prop {Array<MatrixEvent>} timeline The ordered list of message events for
- * this room.
- * @prop {RoomState} oldState The state of the room at the time of the oldest
- * event in the timeline.
- * @prop {RoomState} currentState The state of the room at the time of the
- * newest event in the timeline.
- * @prop {RoomSummary} summary The room summary.
- */
-function Room(roomId) {
-    this.roomId = roomId;
-    this.name = roomId;
-    this.timeline = [];
-    this.oldState = new RoomState(roomId);
-    this.currentState = new RoomState(roomId);
-    this.summary = null;
-}
-utils.inherits(Room, EventEmitter);
-
-/**
- * Get a member from the current room state.
- * @param {string} userId The user ID of the member.
- * @return {RoomMember} The member or <code>null</code>.
- */
- Room.prototype.getMember = function(userId) {
-    var member = this.currentState.members[userId];
-    if (!member) {
-        return null;
-    }
-    return member;
- };
-
-/**
- * Get a list of members whose membership state is "join".
- * @return {RoomMember[]} A list of currently joined members.
- */
- Room.prototype.getJoinedMembers = function() {
-    return utils.filter(this.currentState.getMembers(), function(m) {
-        return m.membership === "join";
-    });
- };
-
-/**
- * Add some events to this room's timeline. 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'.
- * @fires module:client~MatrixClient#event:"Room.timeline"
- */
-Room.prototype.addEventsToTimeline = function(events, toStartOfTimeline) {
-    var stateContext = toStartOfTimeline ? this.oldState : this.currentState;
-    for (var i = 0; i < events.length; i++) {
-        // set sender and target properties
-        events[i].sender = stateContext.getSentinelMember(
-            events[i].getSender()
-        );
-        if (events[i].getType() === "m.room.member") {
-            events[i].target = stateContext.getSentinelMember(
-                events[i].getStateKey()
-            );
-        }
-
-        // modify state
-        if (events[i].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) {
-                events[i].forwardLooking = false;
-            }
-            stateContext.setStateEvents([events[i]], toStartOfTimeline);
-        }
-        // TODO: pass through filter to see if this should be added to the timeline.
-        if (toStartOfTimeline) {
-            this.timeline.unshift(events[i]);
-        }
-        else {
-            this.timeline.push(events[i]);
-        }
-        this.emit("Room.timeline", events[i], this, toStartOfTimeline);
-    }
-};
-
-/**
- * Add some events to this room. This can include state events, message
- * events and typing notifications. These events are treated as "live" so
- * they will go to the end of the timeline.
- * @param {MatrixEvent[]} events A list of events to add.
- */
-Room.prototype.addEvents = function(events) {
-    for (var i = 0; i < events.length; i++) {
-        if (events[i].getType() === "m.typing") {
-            this.currentState.setTypingEvent(events[i]);
-        }
-        else {
-            // TODO: We should have a filter to say "only add state event
-            // types X Y Z to the timeline".
-            this.addEventsToTimeline([events[i]]);
-        }
-    }
-};
-
-/**
- * Recalculate various aspects of the room, including the room name and
- * room summary. Call this any time the room's current state is modified.
- * May fire "Room.name" if the room name is updated.
- * @param {string} userId The client's user ID.
- * @fires module:client~MatrixClient#event:"Room.name"
- */
-Room.prototype.recalculate = function(userId) {
-    var oldName = this.name;
-    this.name = this.calculateRoomName(userId);
-    this.summary = new RoomSummary(this.roomId, {
-        title: this.name
-    });
-
-    if (oldName !== this.name) {
-        this.emit("Room.name", this);
-    }
-};
-
-/**
- * Calculates the name of the room from the current room state.
- * @param {string} userId The client's user ID. Used to filter room members
- * correctly.
- * @return {string} The calculated room name.
- */
-Room.prototype.calculateRoomName = function(userId) {
-    // check for an alias, if any. for now, assume first alias is the
-    // official one.
-    var alias;
-    var mRoomAliases = this.currentState.getStateEvents("m.room.aliases")[0];
-    if (mRoomAliases && utils.isArray(mRoomAliases.getContent().aliases)) {
-        alias = mRoomAliases.getContent().aliases[0];
-    }
-
-    var mRoomName = this.currentState.getStateEvents('m.room.name', '');
-    if (mRoomName) {
-        return mRoomName.getContent().name + (alias ? " (" + alias + ")" : "");
-    }
-    else if (alias) {
-        return alias;
-    }
-    else {
-        // get members that are NOT ourselves.
-        var members = utils.filter(this.currentState.getMembers(), function(m) {
-            return m.userId !== userId;
-        });
-        // TODO: Localisation
-        if (members.length === 0) {
-            var memberList = this.currentState.getMembers();
-            if (memberList.length === 1) {
-                // we exist, but no one else... self-chat or invite.
-                if (memberList[0].membership === "invite") {
-                    return "Room Invite";
-                }
-                else {
-                    return userId;
-                }
-            }
-            else {
-                // there really isn't anyone in this room...
-                return "?";
-            }
-        }
-        else if (members.length === 1) {
-            return members[0].name;
-        }
-        else if (members.length === 2) {
-            return (
-                members[0].name + " and " + members[1].name
-            );
-        }
-        else {
-            return (
-                members[0].name + " and " + (members.length - 1) + " others"
-            );
-        }
-    }
-};
-
-/**
- * The Room class.
- */
-module.exports = Room;
-
-/**
- * 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 whose Room.timeline was updated.
- * @param {boolean} toStartOfTimeline True if this event was added to the start
- * (beginning; oldest) of the timeline e.g. due to pagination.
- * @example
- * matrixClient.on("Room.timeline", function(event, room, toStartOfTimeline){
- *   if (toStartOfTimeline) {
- *     var messageToAppend = room.timeline[room.timeline.length - 1];
- *   }
- * });
- */
-
-/**
- * Fires whenever the name of a room is updated.
- * @event module:client~MatrixClient#"Room.name"
- * @param {Room} room The room whose Room.name was updated.
- * @example
- * matrixClient.on("Room.name", function(room){
- *   var newName = room.name;
- * });
- */

lib/models/user.js

@@ -1,99 +0,0 @@
-"use strict";
-/**
- * @module models/user
- */
- var EventEmitter = require("events").EventEmitter;
- var utils = require("../utils");
-
-/**
- * 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 {Number} lastActiveAgo The last time the user performed some action in ms.
- */
-function User(userId) {
-    this.userId = userId;
-    this.presence = "offline";
-    this.displayName = userId;
-    this.avatarUrl = null;
-    this.lastActiveAgo = 0;
-}
-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;
-    }
-    var eventsToFire = [];
-    if (event.getContent().presence !== this.presence) {
-        eventsToFire.push("User.presence");
-    }
-    if (event.getContent().avatar_url !== this.avatarUrl) {
-        eventsToFire.push("User.avatarUrl");
-    }
-    if (event.getContent().displayname !== this.displayName) {
-        eventsToFire.push("User.displayName");
-    }
-
-    this.presence = event.getContent().presence;
-    this.displayName = event.getContent().displayname;
-    this.avatarUrl = event.getContent().avatar_url;
-    this.lastActiveAgo = event.getContent().last_active_ago;
-
-    for (var i = 0; i < eventsToFire.length; i++) {
-        this.emit(eventsToFire[i], event, this);
-    }
-};
-
-/**
- * The User class.
- */
-module.exports = User;
-
-/**
- * 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 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;
- * });
- */

lib/store/memory.js

@@ -1,80 +0,0 @@
-"use strict";
-/**
- * This is an internal module. See {@link MatrixInMemoryStore} for the public class.
- * @module store/memory
- */
- var utils = require("../utils");
-
-/**
- * Construct a new in-memory data store for the Matrix Client.
- * @constructor
- */
-module.exports.MatrixInMemoryStore = function MatrixInMemoryStore() {
-    this.rooms = {
-        // roomId: Room
-    };
-    this.users = {
-        // userId: User
-    };
-};
-
-module.exports.MatrixInMemoryStore.prototype = {
-
-    /**
-     * Store the given room.
-     * @param {Room} room The room to be stored. All properties must be stored.
-     */
-    storeRoom: function(room) {
-        this.rooms[room.roomId] = room;
-    },
-
-    /**
-     * Retrieve a room by its' room ID.
-     * @param {string} roomId The room ID.
-     * @return {Room} The room or null.
-     */
-    getRoom: function(roomId) {
-        return this.rooms[roomId] || null;
-    },
-
-    /**
-     * Retrieve all known rooms.
-     * @return {Room[]} A list of rooms, which may be empty.
-     */
-    getRooms: function() {
-        return utils.values(this.rooms);
-    },
-
-    /**
-     * Retrieve a summary of all the rooms.
-     * @return {RoomSummary[]} A summary of each room.
-     */
-    getRoomSummaries: function() {
-        return utils.map(utils.values(this.rooms), function(room) {
-            return room.summary;
-        });
-    },
-
-    /**
-     * Store a User.
-     * @param {User} user The user to store.
-     */
-    storeUser: function(user) {
-        this.users[user.userId] = user;
-    },
-
-    /**
-     * Retrieve a User by its' user ID.
-     * @param {string} userId The user ID.
-     * @return {User} The user or null.
-     */
-    getUser: function(userId) {
-        return this.users[userId] || null;
-    }
-
-    // TODO
-    //setMaxHistoryPerRoom: function(maxHistory) {},
-
-    // TODO
-    //reapOldMessages: function() {},
-};

lib/utils.js

@@ -1,275 +0,0 @@
-"use strict";
-/**
- * This is an internal module.
- * @module utils
- */
-
-/**
- * Encode a dictionary of query parameters.
- * @param {Object} params A dict of key/values to encode e.g.
- * {"foo": "bar", "baz": "taz"}
- * @return {string} The encoded string e.g. foo=bar&baz=taz
- */
-module.exports.encodeParams = function(params) {
-    var qs = "";
-    for (var key in params) {
-        if (!params.hasOwnProperty(key)) { continue; }
-        qs += "&" + encodeURIComponent(key) + "=" +
-                encodeURIComponent(params[key]);
-    }
-    return qs.substring(1);
-};
-
-/**
- * Encodes a URI according to a set of template variables. Variables will be
- * passed through encodeURIComponent.
- * @param {string} pathTemplate The path with template variables e.g. '/foo/$bar'.
- * @param {Object} variables The key/value pairs to replace the template
- * variables with. E.g. { "$bar": "baz" }.
- * @return {string} The result of replacing all template variables e.g. '/foo/baz'.
- */
-module.exports.encodeUri = function(pathTemplate, variables) {
-    for (var key in variables) {
-        if (!variables.hasOwnProperty(key)) { continue; }
-        pathTemplate = pathTemplate.replace(
-            key, encodeURIComponent(variables[key])
-        );
-    }
-    return pathTemplate;
-};
-
-/**
- * Applies a map function to the given array.
- * @param {Array} array The array to apply the function to.
- * @param {Function} fn The function that will be invoked for each element in
- * the array with the signature <code>fn(element){...}</code>
- * @return {Array} A new array with the results of the function.
- */
-module.exports.map = function(array, fn) {
-    var results = new Array(array.length);
-    for (var i = 0; i < array.length; i++) {
-        results[i] = fn(array[i]);
-    }
-    return results;
-};
-
-/**
- * Applies a filter function to the given array.
- * @param {Array} array The array to apply the function to.
- * @param {Function} fn The function that will be invoked for each element in
- * the array. It should return true to keep the element. The function signature
- * looks like <code>fn(element, index, array){...}</code>.
- * @return {Array} A new array with the results of the function.
- */
-module.exports.filter = function(array, fn) {
-    var results = [];
-    for (var i = 0; i < array.length; i++) {
-        if (fn(array[i], i, array)) {
-            results.push(array[i]);
-        }
-    }
-    return results;
-};
-
-/**
- * Get the keys for an object. Same as <code>Object.keys()</code>.
- * @param {Object} obj The object to get the keys for.
- * @return {string[]} The keys of the object.
- */
-module.exports.keys = function(obj) {
-    var keys = [];
-    for (var key in obj) {
-        if (!obj.hasOwnProperty(key)) { continue; }
-        keys.push(key);
-    }
-    return keys;
-};
-
-/**
- * Get the values for an object.
- * @param {Object} obj The object to get the values for.
- * @return {Array<*>} The values of the object.
- */
-module.exports.values = function(obj) {
-    var values = [];
-    for (var key in obj) {
-        if (!obj.hasOwnProperty(key)) { continue; }
-        values.push(obj[key]);
-    }
-    return values;
-};
-
-/**
- * Invoke a function for each item in the array.
- * @param {Array} array The array.
- * @param {Function} fn The function to invoke for each element. Has the
- * function signature <code>fn(element, index)</code>.
- */
-module.exports.forEach = function(array, fn) {
-    for (var i = 0; i < array.length; i++) {
-        fn(array[i], i);
-    }
-};
-
-/**
- * Checks if the given thing is a function.
- * @param {*} value The thing to check.
- * @return {boolean} True if it is a function.
- */
-module.exports.isFunction = function(value) {
-    return Object.prototype.toString.call(value) == "[object Function]";
-};
-
-/**
- * Checks if the given thing is an array.
- * @param {*} value The thing to check.
- * @return {boolean} True if it is an array.
- */
-module.exports.isArray = function(value) {
-    return Boolean(value && value.constructor === Array);
-};
-
-/**
- * Checks that the given object has the specified keys.
- * @param {Object} obj The object to check.
- * @param {string[]} keys The list of keys that 'obj' must have.
- * @throws If the object is missing keys.
- */
-module.exports.checkObjectHasKeys = function(obj, keys) {
-    for (var i = 0; i < keys.length; i++) {
-        if (!obj.hasOwnProperty(keys[i])) {
-            throw new Error("Missing required key: " + keys[i]);
-        }
-    }
-};
-
-/**
- * Checks that the given object has no extra keys other than the specified ones.
- * @param {Object} obj The object to check.
- * @param {string[]} allowedKeys The list of allowed key names.
- * @throws If there are extra keys.
- */
-module.exports.checkObjectHasNoAdditionalKeys = function(obj, allowedKeys) {
-    for (var key in obj) {
-        if (!obj.hasOwnProperty(key)) { continue; }
-        if (allowedKeys.indexOf(key) === -1) {
-            throw new Error("Unknown key: " + key);
-        }
-    }
-};
-
-/**
- * Assigns all the properties in src to dst. If these properties are Objects,
- * then both src and dst will refer to the same thing.
- * @param {Object} src The object to copy properties from.
- * @param {Object} dst The object to write properties to.
- */
-module.exports.shallowCopy = function(src, dst) {
-    for (var i in src) {
-        if (src.hasOwnProperty(i)) {
-            dst[i] = src[i];
-        }
-    }
-};
-
-/**
- * Deep copy the given object. The object MUST NOT have circular references and
- * MUST NOT have functions.
- * @param {Object} obj The object to deep copy.
- * @return {Object} A copy of the object without any references to the original.
- */
-module.exports.deepCopy = function(obj) {
-    return JSON.parse(JSON.stringify(obj));
-};
-
-/**
- * Inherit the prototype methods from one constructor into another. This is a
- * port of the Node.js implementation with an Object.create polyfill.
- *
- * @param {function} ctor Constructor function which needs to inherit the
- *     prototype.
- * @param {function} superCtor Constructor function to inherit prototype from.
- */
-module.exports.inherits = function(ctor, superCtor) {
-    // Add Object.create polyfill for IE8
-    // Source:
-    // https://developer.mozilla.org/en-US/docs/Web/JavaScript
-    // /Reference/Global_Objects/Object/create#Polyfill
-    if (typeof Object.create != 'function') {
-      // Production steps of ECMA-262, Edition 5, 15.2.3.5
-      // Reference: http://es5.github.io/#x15.2.3.5
-      Object.create = (function() {
-        // To save on memory, use a shared constructor
-        function Temp() {}
-
-        // make a safe reference to Object.prototype.hasOwnProperty
-        var hasOwn = Object.prototype.hasOwnProperty;
-
-        return function(O) {
-          // 1. If Type(O) is not Object or Null throw a TypeError exception.
-          if (typeof O != 'object') {
-            throw new TypeError('Object prototype may only be an Object or null');
-          }
-
-          // 2. Let obj be the result of creating a new object as if by the
-          //    expression new Object() where Object is the standard built-in
-          //    constructor with that name
-          // 3. Set the [[Prototype]] internal property of obj to O.
-          Temp.prototype = O;
-          var obj = new Temp();
-          Temp.prototype = null; // Let's not keep a stray reference to O...
-
-          // 4. If the argument Properties is present and not undefined, add
-          //    own properties to obj as if by calling the standard built-in
-          //    function Object.defineProperties with arguments obj and
-          //    Properties.
-          if (arguments.length > 1) {
-            // Object.defineProperties does ToObject on its first argument.
-            var Properties = Object(arguments[1]);
-            for (var prop in Properties) {
-              if (hasOwn.call(Properties, prop)) {
-                obj[prop] = Properties[prop];
-              }
-            }
-          }
-
-          // 5. Return obj
-          return obj;
-        };
-      })();
-    }
-    // END polyfill
-
-    // Add util.inherits from Node.js
-    // Source:
-    // https://github.com/joyent/node/blob/master/lib/util.js
-    // Copyright Joyent, Inc. and other Node contributors.
-    //
-    // Permission is hereby granted, free of charge, to any person obtaining a
-    // copy of this software and associated documentation files (the
-    // "Software"), to deal in the Software without restriction, including
-    // without limitation the rights to use, copy, modify, merge, publish,
-    // distribute, sublicense, and/or sell copies of the Software, and to permit
-    // persons to whom the Software is furnished to do so, subject to the
-    // following conditions:
-    //
-    // The above copyright notice and this permission notice shall be included
-    // in all copies or substantial portions of the Software.
-    //
-    // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-    // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-    // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
-    // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
-    // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-    // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
-    // USE OR OTHER DEALINGS IN THE SOFTWARE.
-    ctor.super_ = superCtor;
-    ctor.prototype = Object.create(superCtor.prototype, {
-        constructor: {
-            value: ctor,
-            enumerable: false,
-            writable: true,
-            configurable: true
-        }
-    });
-};

package.json

@@ -1,15 +1,27 @@
 {
   "name": "matrix-js-sdk",
-  "version": "0.1.0",
+  "version": "2.3.2",
   "description": "Matrix Client-Server SDK for Javascript",
   "main": "index.js",
   "scripts": {
-    "test": "istanbul cover --report cobertura -i \"lib/**/*.js\" jasmine-node -- spec --verbose --junitreport --forceexit --captureExceptions",
-    "build": "jshint -c .jshint lib/ && browserify browser-index.js -o dist/browser-matrix-dev.js",
-    "watch": "watchify browser-index.js -o dist/browser-matrix-dev.js -v",
-    "lint": "jshint -c .jshint lib spec && gjslint --unix_mode --disable 0131,0211,0200 --max_line_length 90 -r spec/ -r lib/"
+    "test:build": "babel -s -d specbuild spec",
+    "test:run": "istanbul cover --report text --report cobertura --config .istanbul.yml -i \"lib/**/*.js\" node_modules/mocha/bin/_mocha -- --recursive specbuild --colors --reporter mocha-jenkins-reporter --reporter-options junit_report_path=reports/test-results.xml",
+    "test:watch": "mocha --watch --compilers js:babel-core/register --recursive spec --colors",
+    "test": "yarn test:build && yarn test:run",
+    "check": "yarn test:build && _mocha --recursive specbuild --colors",
+    "gendoc": "babel --no-babelrc --plugins transform-class-properties -d .jsdocbuild src && jsdoc -r .jsdocbuild -P package.json -R README.md -d .jsdoc",
+    "start": "yarn start:init && yarn start:watch",
+    "start:watch": "babel -s -w --skip-initial-build -d lib src",
+    "start:init": "babel -s -d lib src",
+    "clean": "rimraf lib dist",
+    "build": "babel -s -d lib src && rimraf dist && mkdir dist && browserify -d browser-index.js | exorcist dist/browser-matrix.js.map > dist/browser-matrix.js && terser -c -m -o dist/browser-matrix.min.js --source-map \"content='dist/browser-matrix.js.map'\" dist/browser-matrix.js",
+    "dist": "yarn build",
+    "watch": "watchify -d browser-index.js -o 'exorcist dist/browser-matrix.js.map > dist/browser-matrix.js' -v",
+    "lint": "eslint --max-warnings 101 src spec",
+    "prepare": "yarn clean && yarn build && git rev-parse HEAD > git-revision.txt"
   },
   "repository": {
+    "type": "git",
     "url": "https://github.com/matrix-org/matrix-js-sdk"
   },
   "keywords": [
@@ -17,17 +29,70 @@
   ],
   "browser": "browser-index.js",
   "author": "matrix.org",
-  "license": "Apache 2.0",
+  "license": "Apache-2.0",
+  "files": [
+    ".babelrc",
+    ".eslintrc.js",
+    "spec/.eslintrc.js",
+    "CHANGELOG.md",
+    "CONTRIBUTING.rst",
+    "LICENSE",
+    "README.md",
+    "RELEASING.md",
+    "examples",
+    "git-hooks",
+    "git-revision.txt",
+    "index.js",
+    "browser-index.js",
+    "jenkins.sh",
+    "lib",
+    "package.json",
+    "release.sh",
+    "spec",
+    "src"
+  ],
   "dependencies": {
+    "another-json": "^0.2.0",
+    "babel-runtime": "^6.26.0",
+    "bluebird": "^3.5.0",
     "browser-request": "^0.3.3",
-    "browserify": "^10.2.3",
-    "q": "^1.4.1",
-    "request": "^2.53.0"
+    "bs58": "^4.0.1",
+    "content-type": "^1.0.2",
+    "loglevel": "1.6.1",
+    "qs": "^6.5.2",
+    "request": "^2.88.0",
+    "unhomoglyph": "^1.0.2"
   },
   "devDependencies": {
-    "watchify": "^3.2.1",
-    "istanbul": "^0.3.13",
-    "jasmine-node": "^1.14.5",
-    "jshint": "^2.8.0"
+    "babel-cli": "^6.18.0",
+    "babel-eslint": "^10.0.1",
+    "babel-plugin-transform-async-to-bluebird": "^1.1.1",
+    "babel-plugin-transform-class-properties": "^6.24.1",
+    "babel-plugin-transform-runtime": "^6.23.0",
+    "babel-preset-es2015": "^6.18.0",
+    "browserify": "^16.2.3",
+    "browserify-shim": "^3.8.13",
+    "eslint": "^5.12.0",
+    "eslint-config-google": "^0.7.1",
+    "eslint-plugin-babel": "^5.3.0",
+    "exorcist": "^0.4.0",
+    "expect": "^1.20.2",
+    "istanbul": "^0.4.5",
+    "jsdoc": "^3.5.5",
+    "lolex": "^1.5.2",
+    "matrix-mock-request": "^1.2.3",
+    "mocha": "^5.2.0",
+    "mocha-jenkins-reporter": "^0.4.0",
+    "olm": "https://packages.matrix.org/npm/olm/olm-3.1.0.tgz",
+    "rimraf": "^2.5.4",
+    "source-map-support": "^0.4.11",
+    "sourceify": "^0.1.0",
+    "terser": "^4.0.0",
+    "watchify": "^3.11.1"
+  },
+  "browserify": {
+    "transform": [
+      "sourceify"
+    ]
   }
 }

release.sh

@@ -0,0 +1,331 @@
+#!/bin/bash
+#
+# Script to perform a release of matrix-js-sdk.
+#
+# Requires:
+#   github-changelog-generator; install via:
+#     pip install git+https://github.com/matrix-org/github-changelog-generator.git
+#   jq; install from your distribution's package manager (https://stedolan.github.io/jq/)
+#   hub; install via brew (macOS) or source/pre-compiled binaries (debian) (https://github.com/github/hub) - Tested on v2.2.9
+#   npm; typically installed by Node.js
+#   yarn; install via brew (macOS) or similar (https://yarnpkg.com/docs/install/)
+
+set -e
+
+jq --version > /dev/null || (echo "jq is required: please install it"; kill $$)
+if [[ `command -v hub` ]] && [[ `hub --version` =~ hub[[:space:]]version[[:space:]]([0-9]*).([0-9]*) ]]; then
+    HUB_VERSION_MAJOR=${BASH_REMATCH[1]}
+    HUB_VERSION_MINOR=${BASH_REMATCH[2]}
+    if [[ $HUB_VERSION_MAJOR -lt 2 ]] || [[ $HUB_VERSION_MAJOR -eq 2 && $HUB_VERSION_MINOR -lt 5 ]]; then
+        echo "hub version 2.5 is required, you have $HUB_VERSION_MAJOR.$HUB_VERSION_MINOR installed"
+        exit
+    fi
+else
+    echo "hub is required: please install it"
+    exit
+fi
+npm --version > /dev/null || (echo "npm is required: please install it"; kill $$)
+yarn --version > /dev/null || (echo "yarn is required: please install it"; kill $$)
+
+USAGE="$0 [-xz] [-c changelog_file] vX.Y.Z"
+
+help() {
+    cat <<EOF
+$USAGE
+
+    -c changelog_file:  specify name of file containing changelog
+    -x:                 skip updating the changelog
+    -z:                 skip generating the jsdoc
+EOF
+}
+
+ret=0
+cat package.json | jq '.dependencies[]' | grep -q '#develop' || ret=$?
+if [ "$ret" -eq 0 ]; then
+    echo "package.json contains develop dependencies. Refusing to release."
+    exit
+fi
+
+if ! git diff-index --quiet --cached HEAD; then
+    echo "this git checkout has staged (uncommitted) changes. Refusing to release."
+    exit
+fi
+
+if ! git diff-files --quiet; then
+    echo "this git checkout has uncommitted changes. Refusing to release."
+    exit
+fi
+
+skip_changelog=
+skip_jsdoc=
+changelog_file="CHANGELOG.md"
+expected_npm_user="matrixdotorg"
+while getopts hc:u:xz f; do
+    case $f in
+        h)
+            help
+            exit 0
+            ;;
+        c)
+            changelog_file="$OPTARG"
+            ;;
+        x)
+            skip_changelog=1
+            ;;
+        z)
+            skip_jsdoc=1
+            ;;
+        u)
+            expected_npm_user="$OPTARG"
+            ;;
+    esac
+done
+shift `expr $OPTIND - 1`
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $USAGE" >&2
+    exit 1
+fi
+
+if [ -z "$skip_changelog" ]; then
+    # update_changelog doesn't have a --version flag
+    update_changelog -h > /dev/null || (echo "github-changelog-generator is required: please install it"; exit)
+fi
+
+# Login and publish continues to use `npm`, as it seems to have more clearly
+# defined options and semantics than `yarn` for writing to the registry.
+actual_npm_user=`npm whoami`;
+if [ $expected_npm_user != $actual_npm_user ]; then
+    echo "you need to be logged into npm as $expected_npm_user, but you are logged in as $actual_npm_user" >&2
+    exit 1
+fi
+
+# ignore leading v on release
+release="${1#v}"
+tag="v${release}"
+rel_branch="release-$tag"
+
+prerelease=0
+# We check if this build is a prerelease by looking to
+# see if the version has a hyphen in it. Crude,
+# but semver doesn't support postreleases so anything
+# with a hyphen is a prerelease.
+echo $release | grep -q '-' && prerelease=1
+
+if [ $prerelease -eq 1 ]; then
+    echo Making a PRE-RELEASE
+fi
+
+if [ -z "$skip_changelog" ]; then
+    if ! command -v update_changelog >/dev/null 2>&1; then
+        echo "release.sh requires github-changelog-generator. Try:" >&2
+        echo "    pip install git+https://github.com/matrix-org/github-changelog-generator.git" >&2
+        exit 1
+    fi
+fi
+
+# we might already be on the release branch, in which case, yay
+# If we're on any branch starting with 'release', we don't create
+# a separate release branch (this allows us to use the same
+# release branch for releases and release candidates).
+curbranch=$(git symbolic-ref --short HEAD)
+if [[ "$curbranch" != release* ]]; then
+    echo "Creating release branch"
+    git checkout -b "$rel_branch"
+else
+    echo "Using current branch ($curbranch) for release"
+    rel_branch=$curbranch
+fi
+
+if [ -z "$skip_changelog" ]; then
+    echo "Generating changelog"
+    update_changelog -f "$changelog_file" "$release"
+    read -p "Edit $changelog_file manually, or press enter to continue " REPLY
+
+    if [ -n "$(git ls-files --modified $changelog_file)" ]; then
+        echo "Committing updated changelog"
+        git commit "$changelog_file" -m "Prepare changelog for $tag"
+    fi
+fi
+latest_changes=`mktemp`
+cat "${changelog_file}" | `dirname $0`/scripts/changelog_head.py > "${latest_changes}"
+
+set -x
+
+# Bump package.json and build the dist
+echo "yarn version"
+# yarn version will automatically commit its modification
+# and make a release tag. We don't want it to create the tag
+# because it can only sign with the default key, but we can
+# only turn off both of these behaviours, so we have to
+# manually commit the result.
+yarn version --no-git-tag-version --new-version "$release"
+
+# commit yarn.lock if it exists, is versioned, and is modified
+if [[ -f yarn.lock && `git status --porcelain yarn.lock | grep '^ M'` ]];
+then
+    pkglock='yarn.lock'
+else
+    pkglock=''
+fi
+git commit package.json $pkglock -m "$tag"
+
+
+# figure out if we should be signing this release
+signing_id=
+if [ -f release_config.yaml ]; then
+    signing_id=`cat release_config.yaml | python -c "import yaml; import sys; print yaml.load(sys.stdin)['signing_id']"`
+fi
+
+
+# If there is a 'dist' script in the package.json,
+# run it in a separate checkout of the project, then
+# upload any files in the 'dist' directory as release
+# assets.
+# We make a completely separate checkout to be sure
+# we're using released versions of the dependencies
+# (rather than whatever we're pulling in from yarn link)
+assets=''
+dodist=0
+jq -e .scripts.dist package.json 2> /dev/null || dodist=$?
+if [ $dodist -eq 0 ]; then
+    projdir=`pwd`
+    builddir=`mktemp -d 2>/dev/null || mktemp -d -t 'mytmpdir'`
+    echo "Building distribution copy in $builddir"
+    pushd "$builddir"
+    git clone "$projdir" .
+    git checkout "$rel_branch"
+    yarn install
+    # We haven't tagged yet, so tell the dist script what version
+    # it's building
+    DIST_VERSION="$tag" yarn dist
+
+    popd
+
+    for i in "$builddir"/dist/*; do
+        assets="$assets -a $i"
+        if [ -n "$signing_id" ]
+        then
+            gpg -u "$signing_id" --armor --output "$i".asc --detach-sig "$i"
+            assets="$assets -a $i.asc"
+        fi
+    done
+fi
+
+if [ -n "$signing_id" ]; then
+    # make a signed tag
+    # gnupg seems to fail to get the right tty device unless we set it here
+    GIT_COMMITTER_EMAIL="$signing_id" GPG_TTY=`tty` git tag -u "$signing_id" -F "${latest_changes}" "$tag"
+else
+    git tag -a -F "${latest_changes}" "$tag"
+fi
+
+# push the tag and the release branch
+git push origin "$rel_branch" "$tag"
+
+if [ -n "$signing_id" ]; then
+    # make a signature for the source tarball.
+    #
+    # github will make us a tarball from the tag - we want to create a
+    # signature for it, which means that first of all we need to check that
+    # it's correct.
+    #
+    # we can't deterministically build exactly the same tarball, due to
+    # differences in gzip implementation - but we *can* build the same tar - so
+    # the easiest way to check the validity of the tarball from git is to unzip
+    # it and compare it with our own idea of what the tar should look like.
+
+    # the name of the sig file we want to create
+    source_sigfile="${tag}-src.tar.gz.asc"
+
+    tarfile="$tag.tar.gz"
+    gh_project_url=$(git remote get-url origin |
+                            sed -e 's#^git@github\.com:#https://github.com/#' \
+                                -e 's#^git\+ssh://git@github\.com/#https://github.com/#' \
+                                -e 's/\.git$//')
+    project_name="${gh_project_url##*/}"
+    curl -L "${gh_project_url}/archive/${tarfile}" -o "${tarfile}"
+
+    # unzip it and compare it with the tar we would generate
+    if ! cmp --silent <(gunzip -c $tarfile) \
+         <(git archive --format tar --prefix="${project_name}-${release}/" "$tag"); then
+
+        # we don't bail out here, because really it's more likely that our comparison
+        # screwed up and it's super annoying to abort the script at this point.
+        cat >&2 <<EOF
+!!!!!!!!!!!!!!!!!
+!!!! WARNING !!!!
+
+Mismatch between our own tarfile and that generated by github: not signing
+source tarball.
+
+To resolve, determine if $tarfile is correct, and if so sign it with gpg and
+attach it to the release as $source_sigfile.
+
+!!!!!!!!!!!!!!!!!
+EOF
+    else
+        gpg -u "$signing_id" --armor --output "$source_sigfile" --detach-sig "$tarfile"
+        assets="$assets -a $source_sigfile"
+    fi
+fi
+
+hubflags=''
+if [ $prerelease -eq 1 ]; then
+    hubflags='-p'
+fi
+
+release_text=`mktemp`
+echo "$tag" > "${release_text}"
+echo >> "${release_text}"
+cat "${latest_changes}" >> "${release_text}"
+hub release create $hubflags $assets -F "${release_text}" "$tag"
+
+if [ $dodist -eq 0 ]; then
+    rm -rf "$builddir"
+fi
+rm "${release_text}"
+rm "${latest_changes}"
+
+# Login and publish continues to use `npm`, as it seems to have more clearly
+# defined options and semantics than `yarn` for writing to the registry.
+npm publish
+
+if [ -z "$skip_jsdoc" ]; then
+    echo "generating jsdocs"
+    yarn gendoc
+
+    echo "copying jsdocs to gh-pages branch"
+    git checkout gh-pages
+    git pull
+    cp -a ".jsdoc/matrix-js-sdk/$release" .
+    perl -i -pe 'BEGIN {$rel=shift} $_ =~ /^<\/ul>/ && print
+        "<li><a href=\"${rel}/index.html\">Version ${rel}</a></li>\n"' \
+        $release index.html
+    git add "$release"
+    git commit --no-verify -m "Add jsdoc for $release" index.html "$release"
+fi
+
+# if it is a pre-release, leave it on the release branch for now.
+if [ $prerelease -eq 1 ]; then
+    git checkout "$rel_branch"
+    exit 0
+fi
+
+# merge release branch to master
+echo "updating master branch"
+git checkout master
+git pull
+git merge "$rel_branch"
+
+# push master and docs (if generated) to github
+git push origin master
+if [ -z "$skip_jsdoc" ]; then
+    git push origin gh-pages
+fi
+
+# finally, merge master back onto develop
+git checkout develop
+git pull
+git merge master
+git push origin develop

scripts/changelog_head.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+
+"""
+Outputs the body of the first entry of changelog file on stdin
+"""
+
+import re
+import sys
+
+found_first_header = False
+for line in sys.stdin:
+    line = line.strip()
+    if re.match(r"^Changes in \[.*\]", line):
+        if found_first_header:
+            break
+        found_first_header = True
+    elif not re.match(r"^=+$", line) and len(line) > 0:
+        print line

spec/.eslintrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+    env: {
+        mocha: true,
+    },
+}

spec/MockStorageApi.js

@@ -0,0 +1,56 @@
+/*
+Copyright 2015, 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.
+*/
+
+/**
+ * A mock implementation of the webstorage api
+ * @constructor
+ */
+function MockStorageApi() {
+    this.data = {};
+    this.keys = [];
+    this.length = 0;
+}
+
+MockStorageApi.prototype = {
+    setItem: function(k, v) {
+        this.data[k] = v;
+        this._recalc();
+    },
+    getItem: function(k) {
+        return this.data[k] || null;
+    },
+    removeItem: function(k) {
+        delete this.data[k];
+        this._recalc();
+    },
+    key: function(index) {
+        return this.keys[index];
+    },
+    _recalc: function() {
+        const keys = [];
+        for (const k in this.data) {
+            if (!this.data.hasOwnProperty(k)) {
+                continue;
+            }
+            keys.push(k);
+        }
+        this.keys = keys;
+        this.length = keys.length;
+    },
+};
+
+/** */
+module.exports = MockStorageApi;

spec/TestClient.js

@@ -0,0 +1,234 @@
+/*
+Copyright 2016 OpenMarket Ltd
+Copyright 2017 Vector Creations Ltd
+Copyright 2018-2019 New Vector 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.
+*/
+
+"use strict";
+
+// load olm before the sdk if possible
+import './olm-loader';
+
+import sdk from '..';
+import testUtils from './test-utils';
+import MockHttpBackend from 'matrix-mock-request';
+import expect from 'expect';
+import Promise from 'bluebird';
+import LocalStorageCryptoStore from '../lib/crypto/store/localStorage-crypto-store';
+import logger from '../src/logger';
+
+/**
+ * Wrapper for a MockStorageApi, MockHttpBackend and MatrixClient
+ *
+ * @constructor
+ * @param {string} userId
+ * @param {string} deviceId
+ * @param {string} accessToken
+ *
+ * @param {WebStorage=} sessionStoreBackend a web storage object to use for the
+ *     session store. If undefined, we will create a MockStorageApi.
+ * @param {object} options additional options to pass to the client
+ */
+export default function TestClient(
+    userId, deviceId, accessToken, sessionStoreBackend, options,
+) {
+    this.userId = userId;
+    this.deviceId = deviceId;
+
+    if (sessionStoreBackend === undefined) {
+        sessionStoreBackend = new testUtils.MockStorageApi();
+    }
+    const sessionStore = new sdk.WebStorageSessionStore(sessionStoreBackend);
+
+    this.httpBackend = new MockHttpBackend();
+
+    options = Object.assign({
+        baseUrl: "http://" + userId + ".test.server",
+        userId: userId,
+        accessToken: accessToken,
+        deviceId: deviceId,
+        sessionStore: sessionStore,
+        request: this.httpBackend.requestFn,
+    }, options);
+    if (!options.cryptoStore) {
+        // expose this so the tests can get to it
+        this.cryptoStore = new LocalStorageCryptoStore(sessionStoreBackend);
+        options.cryptoStore = this.cryptoStore;
+    }
+    this.client = sdk.createClient(options);
+
+    this.deviceKeys = null;
+    this.oneTimeKeys = {};
+}
+
+TestClient.prototype.toString = function() {
+    return 'TestClient[' + this.userId + ']';
+};
+
+/**
+ * start the client, and wait for it to initialise.
+ *
+ * @return {Promise}
+ */
+TestClient.prototype.start = function() {
+    logger.log(this + ': starting');
+    this.httpBackend.when("GET", "/pushrules").respond(200, {});
+    this.httpBackend.when("POST", "/filter").respond(200, { filter_id: "fid" });
+    this.expectDeviceKeyUpload();
+
+    // we let the client do a very basic initial sync, which it needs before
+    // it will upload one-time keys.
+    this.httpBackend.when("GET", "/sync").respond(200, { next_batch: 1 });
+
+    this.client.startClient({
+        // set this so that we can get hold of failed events
+        pendingEventOrdering: 'detached',
+    });
+
+    return Promise.all([
+        this.httpBackend.flushAllExpected(),
+        testUtils.syncPromise(this.client),
+    ]).then(() => {
+        logger.log(this + ': started');
+    });
+};
+
+/**
+ * stop the client
+ * @return {Promise} Resolves once the mock http backend has finished all pending flushes
+ */
+TestClient.prototype.stop = function() {
+    this.client.stopClient();
+    return this.httpBackend.stop();
+};
+
+/**
+ * Set up expectations that the client will upload device keys.
+ */
+TestClient.prototype.expectDeviceKeyUpload = function() {
+    const self = this;
+    this.httpBackend.when("POST", "/keys/upload").respond(200, function(path, content) {
+        expect(content.one_time_keys).toBe(undefined);
+        expect(content.device_keys).toBeTruthy();
+
+        logger.log(self + ': received device keys');
+        // we expect this to happen before any one-time keys are uploaded.
+        expect(Object.keys(self.oneTimeKeys).length).toEqual(0);
+
+        self.deviceKeys = content.device_keys;
+        return {one_time_key_counts: {signed_curve25519: 0}};
+    });
+};
+
+
+/**
+ * If one-time keys have already been uploaded, return them. Otherwise,
+ * set up an expectation that the keys will be uploaded, and wait for
+ * that to happen.
+ *
+ * @returns {Promise} for the one-time keys
+ */
+TestClient.prototype.awaitOneTimeKeyUpload = function() {
+    if (Object.keys(this.oneTimeKeys).length != 0) {
+        // already got one-time keys
+        return Promise.resolve(this.oneTimeKeys);
+    }
+
+    this.httpBackend.when("POST", "/keys/upload")
+        .respond(200, (path, content) => {
+            expect(content.device_keys).toBe(undefined);
+            expect(content.one_time_keys).toBe(undefined);
+            return {one_time_key_counts: {
+                signed_curve25519: Object.keys(this.oneTimeKeys).length,
+            }};
+        });
+
+    this.httpBackend.when("POST", "/keys/upload")
+          .respond(200, (path, content) => {
+              expect(content.device_keys).toBe(undefined);
+              expect(content.one_time_keys).toBeTruthy();
+              expect(content.one_time_keys).toNotEqual({});
+              logger.log('%s: received %i one-time keys', this,
+                          Object.keys(content.one_time_keys).length);
+              this.oneTimeKeys = content.one_time_keys;
+              return {one_time_key_counts: {
+                  signed_curve25519: Object.keys(this.oneTimeKeys).length,
+              }};
+          });
+
+    // this can take ages
+    return this.httpBackend.flush('/keys/upload', 2, 1000).then((flushed) => {
+        expect(flushed).toEqual(2);
+        return this.oneTimeKeys;
+    });
+};
+
+/**
+ * Set up expectations that the client will query device keys.
+ *
+ * We check that the query contains each of the users in `response`.
+ *
+ * @param {Object} response   response to the query.
+ */
+TestClient.prototype.expectKeyQuery = function(response) {
+    this.httpBackend.when('POST', '/keys/query').respond(
+        200, (path, content) => {
+            Object.keys(response.device_keys).forEach((userId) => {
+                expect(content.device_keys[userId]).toEqual(
+                    {},
+                    "Expected key query for " + userId + ", got " +
+                    Object.keys(content.device_keys),
+                );
+            });
+            return response;
+        });
+};
+
+
+/**
+ * get the uploaded curve25519 device key
+ *
+ * @return {string} base64 device key
+ */
+TestClient.prototype.getDeviceKey = function() {
+    const keyId = 'curve25519:' + this.deviceId;
+    return this.deviceKeys.keys[keyId];
+};
+
+
+/**
+ * get the uploaded ed25519 device key
+ *
+ * @return {string} base64 device key
+ */
+TestClient.prototype.getSigningKey = function() {
+    const keyId = 'ed25519:' + this.deviceId;
+    return this.deviceKeys.keys[keyId];
+};
+
+/**
+ * flush a single /sync request, and wait for the syncing event
+ *
+ * @returns {Promise} promise which completes once the sync has been flushed
+ */
+TestClient.prototype.flushSync = function() {
+    logger.log(`${this}: flushSync`);
+    return Promise.all([
+        this.httpBackend.flush('/sync', 1),
+        testUtils.syncPromise(this.client),
+    ]).then(() => {
+        logger.log(`${this}: flushSync completed`);
+    });
+};

spec/integ/devicelist-integ-spec.js

@@ -0,0 +1,403 @@
+/*
+Copyright 2017 Vector Creations Ltd
+Copyright 2018 New Vector 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.
+*/
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+import TestClient from '../TestClient';
+import testUtils from '../test-utils';
+import logger from '../../src/logger';
+
+const ROOM_ID = "!room:id";
+
+/**
+ * get a /sync response which contains a single e2e room (ROOM_ID), with the
+ * members given
+ *
+ * @param {string[]} roomMembers
+ *
+ * @return {object} sync response
+ */
+function getSyncResponse(roomMembers) {
+    const stateEvents = [
+        testUtils.mkEvent({
+            type: 'm.room.encryption',
+            skey: '',
+            content: {
+                algorithm: 'm.megolm.v1.aes-sha2',
+            },
+        }),
+    ];
+
+    Array.prototype.push.apply(
+        stateEvents,
+        roomMembers.map(
+            (m) => testUtils.mkMembership({
+                mship: 'join',
+                sender: m,
+            }),
+        ),
+    );
+
+    const syncResponse = {
+        next_batch: 1,
+        rooms: {
+            join: {
+                [ROOM_ID]: {
+                    state: {
+                        events: stateEvents,
+                    },
+                },
+            },
+        },
+    };
+
+    return syncResponse;
+}
+
+
+describe("DeviceList management:", function() {
+    if (!global.Olm) {
+        logger.warn('not running deviceList tests: Olm not present');
+        return;
+    }
+
+    let sessionStoreBackend;
+    let aliceTestClient;
+
+    async function createTestClient() {
+        const testClient = new TestClient(
+            "@alice:localhost", "xzcvb", "akjgkrgjs", sessionStoreBackend,
+        );
+        await testClient.client.initCrypto();
+        return testClient;
+    }
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        // we create our own sessionStoreBackend so that we can use it for
+        // another TestClient.
+        sessionStoreBackend = new testUtils.MockStorageApi();
+
+        aliceTestClient = await createTestClient();
+    });
+
+    afterEach(function() {
+        return aliceTestClient.stop();
+    });
+
+    it("Alice shouldn't do a second /query for non-e2e-capable devices", function() {
+        aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+        return aliceTestClient.start().then(function() {
+            const syncResponse = getSyncResponse(['@bob:xyz']);
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(200, syncResponse);
+
+            return aliceTestClient.flushSync();
+        }).then(function() {
+            logger.log("Forcing alice to download our device keys");
+
+            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(200, {
+                device_keys: {
+                    '@bob:xyz': {},
+                },
+            });
+
+            return Promise.all([
+                aliceTestClient.client.downloadKeys(['@bob:xyz']),
+                aliceTestClient.httpBackend.flush('/keys/query', 1),
+            ]);
+        }).then(function() {
+            logger.log("Telling alice to send a megolm message");
+
+            aliceTestClient.httpBackend.when(
+                'PUT', '/send/',
+            ).respond(200, {
+                    event_id: '$event_id',
+            });
+
+            return Promise.all([
+                aliceTestClient.client.sendTextMessage(ROOM_ID, 'test'),
+
+                // the crypto stuff can take a while, so give the requests a whole second.
+                aliceTestClient.httpBackend.flushAllExpected({
+                    timeout: 1000,
+                }),
+            ]);
+        });
+    });
+
+
+    it("We should not get confused by out-of-order device query responses",
+       () => {
+           // https://github.com/vector-im/riot-web/issues/3126
+           aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+           return aliceTestClient.start().then(() => {
+               aliceTestClient.httpBackend.when('GET', '/sync').respond(
+                   200, getSyncResponse(['@bob:xyz', '@chris:abc']));
+               return aliceTestClient.flushSync();
+           }).then(() => {
+               // to make sure the initial device queries are flushed out, we
+               // attempt to send a message.
+
+               aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
+                   200, {
+                       device_keys: {
+                           '@bob:xyz': {},
+                           '@chris:abc': {},
+                       },
+                   },
+               );
+
+               aliceTestClient.httpBackend.when('PUT', '/send/').respond(
+                   200, {event_id: '$event1'});
+
+               return Promise.all([
+                   aliceTestClient.client.sendTextMessage(ROOM_ID, 'test'),
+                   aliceTestClient.httpBackend.flush('/keys/query', 1).then(
+                       () => aliceTestClient.httpBackend.flush('/send/', 1),
+                   ),
+                   aliceTestClient.client._crypto._deviceList.saveIfDirty(),
+               ]);
+           }).then(() => {
+               aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                   expect(data.syncToken).toEqual(1);
+               });
+
+               // invalidate bob's and chris's device lists in separate syncs
+               aliceTestClient.httpBackend.when('GET', '/sync').respond(200, {
+                   next_batch: '2',
+                   device_lists: {
+                       changed: ['@bob:xyz'],
+                   },
+               });
+               aliceTestClient.httpBackend.when('GET', '/sync').respond(200, {
+                   next_batch: '3',
+                   device_lists: {
+                       changed: ['@chris:abc'],
+                   },
+               });
+               // flush both syncs
+               return aliceTestClient.flushSync().then(() => {
+                   return aliceTestClient.flushSync();
+               });
+           }).then(() => {
+               // check that we don't yet have a request for chris's devices.
+               aliceTestClient.httpBackend.when('POST', '/keys/query', {
+                   device_keys: {
+                       '@chris:abc': {},
+                   },
+                   token: '3',
+               }).respond(200, {
+                   device_keys: {'@chris:abc': {}},
+               });
+               return aliceTestClient.httpBackend.flush('/keys/query', 1);
+           }).then((flushed) => {
+               expect(flushed).toEqual(0);
+               return aliceTestClient.client._crypto._deviceList.saveIfDirty();
+           }).then(() => {
+               aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                   const bobStat = data.trackingStatus['@bob:xyz'];
+                   if (bobStat != 1 && bobStat != 2) {
+                       throw new Error('Unexpected status for bob: wanted 1 or 2, got ' +
+                                       bobStat);
+                   }
+                   const chrisStat = data.trackingStatus['@chris:abc'];
+                   if (chrisStat != 1 && chrisStat != 2) {
+                       throw new Error(
+                           'Unexpected status for chris: wanted 1 or 2, got ' + chrisStat,
+                       );
+                   }
+               });
+
+               // now add an expectation for a query for bob's devices, and let
+               // it complete.
+               aliceTestClient.httpBackend.when('POST', '/keys/query', {
+                   device_keys: {
+                       '@bob:xyz': {},
+                   },
+                   token: '2',
+               }).respond(200, {
+                   device_keys: {'@bob:xyz': {}},
+               });
+               return aliceTestClient.httpBackend.flush('/keys/query', 1);
+           }).then((flushed) => {
+               expect(flushed).toEqual(1);
+
+               // wait for the client to stop processing the response
+               return aliceTestClient.client.downloadKeys(['@bob:xyz']);
+           }).then(() => {
+               return aliceTestClient.client._crypto._deviceList.saveIfDirty();
+           }).then(() => {
+               aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                   const bobStat = data.trackingStatus['@bob:xyz'];
+                   expect(bobStat).toEqual(3);
+                   const chrisStat = data.trackingStatus['@chris:abc'];
+                   if (chrisStat != 1 && chrisStat != 2) {
+                       throw new Error(
+                           'Unexpected status for chris: wanted 1 or 2, got ' + bobStat,
+                       );
+                   }
+               });
+
+               // now let the query for chris's devices complete.
+               return aliceTestClient.httpBackend.flush('/keys/query', 1);
+           }).then((flushed) => {
+               expect(flushed).toEqual(1);
+
+               // wait for the client to stop processing the response
+               return aliceTestClient.client.downloadKeys(['@chris:abc']);
+           }).then(() => {
+               return aliceTestClient.client._crypto._deviceList.saveIfDirty();
+           }).then(() => {
+               aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                   const bobStat = data.trackingStatus['@bob:xyz'];
+                   const chrisStat = data.trackingStatus['@bob:xyz'];
+
+                   expect(bobStat).toEqual(3);
+                   expect(chrisStat).toEqual(3);
+                   expect(data.syncToken).toEqual(3);
+               });
+           });
+       }).timeout(3000);
+
+    // https://github.com/vector-im/riot-web/issues/4983
+    describe("Alice should know she has stale device lists", () => {
+        beforeEach(async function() {
+            await aliceTestClient.start();
+
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(
+                200, getSyncResponse(['@bob:xyz']));
+            await aliceTestClient.flushSync();
+
+            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
+                200, {
+                    device_keys: {
+                        '@bob:xyz': {},
+                    },
+                },
+            );
+            await aliceTestClient.httpBackend.flush('/keys/query', 1);
+            await aliceTestClient.client._crypto._deviceList.saveIfDirty();
+
+            aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                const bobStat = data.trackingStatus['@bob:xyz'];
+
+                expect(bobStat).toBeGreaterThan(
+                    0, "Alice should be tracking bob's device list",
+                );
+            });
+        });
+
+        it("when Bob leaves", async function() {
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(
+                200, {
+                    next_batch: 2,
+                    device_lists: {
+                        left: ['@bob:xyz'],
+                    },
+                    rooms: {
+                        join: {
+                            [ROOM_ID]: {
+                                timeline: {
+                                    events: [
+                                        testUtils.mkMembership({
+                                            mship: 'leave',
+                                            sender: '@bob:xyz',
+                                        }),
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                },
+            );
+
+
+            await aliceTestClient.flushSync();
+            await aliceTestClient.client._crypto._deviceList.saveIfDirty();
+
+            aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                const bobStat = data.trackingStatus['@bob:xyz'];
+
+                expect(bobStat).toEqual(
+                    0, "Alice should have marked bob's device list as untracked",
+                );
+            });
+        });
+
+        it("when Alice leaves", async function() {
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(
+                200, {
+                    next_batch: 2,
+                    device_lists: {
+                        left: ['@bob:xyz'],
+                    },
+                    rooms: {
+                        leave: {
+                            [ROOM_ID]: {
+                                timeline: {
+                                    events: [
+                                        testUtils.mkMembership({
+                                            mship: 'leave',
+                                            sender: '@bob:xyz',
+                                        }),
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                },
+            );
+
+            await aliceTestClient.flushSync();
+            await aliceTestClient.client._crypto._deviceList.saveIfDirty();
+
+            aliceTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                const bobStat = data.trackingStatus['@bob:xyz'];
+
+                expect(bobStat).toEqual(
+                    0, "Alice should have marked bob's device list as untracked",
+                );
+            });
+        });
+
+        it("when Bob leaves whilst Alice is offline", async function() {
+            aliceTestClient.stop();
+
+            const anotherTestClient = await createTestClient();
+
+            try {
+                await anotherTestClient.start();
+                anotherTestClient.httpBackend.when('GET', '/sync').respond(
+                    200, getSyncResponse([]));
+                await anotherTestClient.flushSync();
+                await anotherTestClient.client._crypto._deviceList.saveIfDirty();
+
+                anotherTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+                    const bobStat = data.trackingStatus['@bob:xyz'];
+
+                    expect(bobStat).toEqual(
+                        0, "Alice should have marked bob's device list as untracked",
+                    );
+                });
+            } finally {
+                anotherTestClient.stop();
+            }
+        });
+    });
+});

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

@@ -0,0 +1,771 @@
+/*
+Copyright 2016 OpenMarket Ltd
+Copyright 2017 Vector Creations Ltd
+Copyright 2018 New Vector 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.
+*/
+
+/* This file consists of a set of integration tests which try to simulate
+ * communication via an Olm-encrypted room between two users, Alice and Bob.
+ *
+ * Note that megolm (group) conversation is not tested here.
+ *
+ * See also `megolm.spec.js`.
+ */
+
+"use strict";
+import 'source-map-support/register';
+
+// load olm before the sdk if possible
+import '../olm-loader';
+
+import expect from 'expect';
+const sdk = require("../..");
+import Promise from 'bluebird';
+const utils = require("../../lib/utils");
+const testUtils = require("../test-utils");
+const TestClient = require('../TestClient').default;
+import logger from '../../src/logger';
+
+let aliTestClient;
+const roomId = "!room:localhost";
+const aliUserId = "@ali:localhost";
+const aliDeviceId = "zxcvb";
+const aliAccessToken = "aseukfgwef";
+let bobTestClient;
+const bobUserId = "@bob:localhost";
+const bobDeviceId = "bvcxz";
+const bobAccessToken = "fewgfkuesa";
+let aliMessages;
+let bobMessages;
+
+function bobUploadsDeviceKeys() {
+    bobTestClient.expectDeviceKeyUpload();
+    return Promise.all([
+        bobTestClient.client.uploadKeys(),
+        bobTestClient.httpBackend.flush(),
+    ]).then(() => {
+        expect(Object.keys(bobTestClient.deviceKeys).length).toNotEqual(0);
+    });
+}
+
+/**
+ * Set an expectation that ali will query bobs keys; then flush the http request.
+ *
+ * @return {promise} resolves once the http request has completed.
+ */
+function expectAliQueryKeys() {
+    // can't query keys before bob has uploaded them
+    expect(bobTestClient.deviceKeys).toBeTruthy();
+
+    const bobKeys = {};
+    bobKeys[bobDeviceId] = bobTestClient.deviceKeys;
+    aliTestClient.httpBackend.when("POST", "/keys/query")
+            .respond(200, function(path, content) {
+        expect(content.device_keys[bobUserId]).toEqual(
+            {},
+            "Expected Alice to key query for " + bobUserId + ", got " +
+            Object.keys(content.device_keys),
+        );
+        const result = {};
+        result[bobUserId] = bobKeys;
+        return {device_keys: result};
+    });
+    return aliTestClient.httpBackend.flush("/keys/query", 1);
+}
+
+/**
+ * Set an expectation that bob will query alis keys; then flush the http request.
+ *
+ * @return {promise} which resolves once the http request has completed.
+ */
+function expectBobQueryKeys() {
+    // can't query keys before ali has uploaded them
+    expect(aliTestClient.deviceKeys).toBeTruthy();
+
+    const aliKeys = {};
+    aliKeys[aliDeviceId] = aliTestClient.deviceKeys;
+    logger.log("query result will be", aliKeys);
+
+    bobTestClient.httpBackend.when(
+        "POST", "/keys/query",
+    ).respond(200, function(path, content) {
+        expect(content.device_keys[aliUserId]).toEqual(
+            {},
+            "Expected Bob to key query for " + aliUserId + ", got " +
+            Object.keys(content.device_keys),
+        );
+        const result = {};
+        result[aliUserId] = aliKeys;
+        return {device_keys: result};
+    });
+    return bobTestClient.httpBackend.flush("/keys/query", 1);
+}
+
+/**
+ * Set an expectation that ali will claim one of bob's keys; then flush the http request.
+ *
+ * @return {promise} resolves once the http request has completed.
+ */
+function expectAliClaimKeys() {
+    return bobTestClient.awaitOneTimeKeyUpload().then((keys) => {
+        aliTestClient.httpBackend.when(
+            "POST", "/keys/claim",
+        ).respond(200, function(path, content) {
+            const claimType = content.one_time_keys[bobUserId][bobDeviceId];
+            expect(claimType).toEqual("signed_curve25519");
+            let keyId = null;
+            for (keyId in keys) {
+                if (bobTestClient.oneTimeKeys.hasOwnProperty(keyId)) {
+                    if (keyId.indexOf(claimType + ":") === 0) {
+                        break;
+                    }
+                }
+            }
+            const result = {};
+            result[bobUserId] = {};
+            result[bobUserId][bobDeviceId] = {};
+            result[bobUserId][bobDeviceId][keyId] = keys[keyId];
+            return {one_time_keys: result};
+        });
+    }).then(() => {
+        // it can take a while to process the key query, so give it some extra
+        // time, and make sure the claim actually happens rather than ploughing on
+        // confusingly.
+        return aliTestClient.httpBackend.flush("/keys/claim", 1, 500).then((r) => {
+            expect(r).toEqual(1, "Ali did not claim Bob's keys");
+        });
+    });
+}
+
+
+function aliDownloadsKeys() {
+    // can't query keys before bob has uploaded them
+    expect(bobTestClient.getSigningKey()).toBeTruthy();
+
+    const p1 = aliTestClient.client.downloadKeys([bobUserId]).then(function() {
+        return aliTestClient.client.getStoredDevicesForUser(bobUserId);
+    }).then((devices) => {
+        expect(devices.length).toEqual(1);
+        expect(devices[0].deviceId).toEqual("bvcxz");
+    });
+    const p2 = expectAliQueryKeys();
+
+    // 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();
+    }).then(() => {
+        aliTestClient.cryptoStore.getEndToEndDeviceData(null, (data) => {
+            const devices = data.devices[bobUserId];
+            expect(devices[bobDeviceId].keys).toEqual(bobTestClient.deviceKeys.keys);
+            expect(devices[bobDeviceId].verified).
+                toBe(0); // DeviceVerification.UNVERIFIED
+        });
+    });
+}
+
+function aliEnablesEncryption() {
+    return aliTestClient.client.setRoomEncryption(roomId, {
+        algorithm: "m.olm.v1.curve25519-aes-sha2",
+    }).then(function() {
+        expect(aliTestClient.client.isRoomEncrypted(roomId)).toBeTruthy();
+    });
+}
+
+function bobEnablesEncryption() {
+    return bobTestClient.client.setRoomEncryption(roomId, {
+        algorithm: "m.olm.v1.curve25519-aes-sha2",
+    }).then(function() {
+       expect(bobTestClient.client.isRoomEncrypted(roomId)).toBeTruthy();
+    });
+}
+
+/**
+ * Ali sends a message, first claiming e2e keys. Set the expectations and
+ * check the results.
+ *
+ * @return {promise} which resolves to the ciphertext for Bob's device.
+ */
+function aliSendsFirstMessage() {
+    return Promise.all([
+        sendMessage(aliTestClient.client),
+        expectAliQueryKeys()
+            .then(expectAliClaimKeys)
+            .then(expectAliSendMessageRequest),
+    ]).spread(function(_, ciphertext) {
+        return ciphertext;
+    });
+}
+
+/**
+ * Ali sends a message without first claiming e2e keys. Set the expectations
+ * and check the results.
+ *
+ * @return {promise} which resolves to the ciphertext for Bob's device.
+ */
+function aliSendsMessage() {
+    return Promise.all([
+        sendMessage(aliTestClient.client),
+        expectAliSendMessageRequest(),
+    ]).spread(function(_, ciphertext) {
+        return ciphertext;
+    });
+}
+
+/**
+ * Bob sends a message, first querying (but not claiming) e2e keys. Set the
+ * expectations and check the results.
+ *
+ * @return {promise} which resolves to the ciphertext for Ali's device.
+ */
+function bobSendsReplyMessage() {
+    return Promise.all([
+        sendMessage(bobTestClient.client),
+        expectBobQueryKeys()
+            .then(expectBobSendMessageRequest),
+    ]).spread(function(_, ciphertext) {
+        return ciphertext;
+    });
+}
+
+/**
+ * Set an expectation that Ali will send a message, and flush the request
+ *
+ * @return {promise} which resolves to the ciphertext for Bob's device.
+ */
+function expectAliSendMessageRequest() {
+    return expectSendMessageRequest(aliTestClient.httpBackend).then(function(content) {
+        aliMessages.push(content);
+        expect(utils.keys(content.ciphertext)).toEqual([bobTestClient.getDeviceKey()]);
+        const ciphertext = content.ciphertext[bobTestClient.getDeviceKey()];
+        expect(ciphertext).toBeTruthy();
+        return ciphertext;
+    });
+}
+
+/**
+ * Set an expectation that Bob will send a message, and flush the request
+ *
+ * @return {promise} which resolves to the ciphertext for Bob's device.
+ */
+function expectBobSendMessageRequest() {
+    return expectSendMessageRequest(bobTestClient.httpBackend).then(function(content) {
+        bobMessages.push(content);
+        const aliKeyId = "curve25519:" + aliDeviceId;
+        const aliDeviceCurve25519Key = aliTestClient.deviceKeys.keys[aliKeyId];
+        expect(utils.keys(content.ciphertext)).toEqual([aliDeviceCurve25519Key]);
+        const ciphertext = content.ciphertext[aliDeviceCurve25519Key];
+        expect(ciphertext).toBeTruthy();
+        return ciphertext;
+    });
+}
+
+function sendMessage(client) {
+    return client.sendMessage(
+        roomId, {msgtype: "m.text", body: "Hello, World"},
+    );
+}
+
+function expectSendMessageRequest(httpBackend) {
+    const path = "/send/m.room.encrypted/";
+    const deferred = Promise.defer();
+    httpBackend.when("PUT", path).respond(200, function(path, content) {
+        deferred.resolve(content);
+        return {
+            event_id: "asdfgh",
+        };
+    });
+
+    // it can take a while to process the key query
+    return httpBackend.flush(path, 1).then(() => deferred.promise);
+}
+
+function aliRecvMessage() {
+    const message = bobMessages.shift();
+    return recvMessage(
+        aliTestClient.httpBackend, aliTestClient.client, bobUserId, message,
+    );
+}
+
+function bobRecvMessage() {
+    const message = aliMessages.shift();
+    return recvMessage(
+        bobTestClient.httpBackend, bobTestClient.client, aliUserId, message,
+    );
+}
+
+function recvMessage(httpBackend, client, sender, message) {
+    const syncData = {
+        next_batch: "x",
+        rooms: {
+            join: {
+
+            },
+        },
+    };
+    syncData.rooms.join[roomId] = {
+        timeline: {
+            events: [
+                testUtils.mkEvent({
+                    type: "m.room.encrypted",
+                    room: roomId,
+                    content: message,
+                    sender: sender,
+                }),
+            ],
+        },
+    };
+    httpBackend.when("GET", "/sync").respond(200, syncData);
+
+    const eventPromise = new Promise((resolve, reject) => {
+        const onEvent = function(event) {
+            // ignore the m.room.member events
+            if (event.getType() == "m.room.member") {
+                return;
+            }
+            logger.log(client.credentials.userId + " received event",
+                        event);
+
+            client.removeListener("event", onEvent);
+            resolve(event);
+        };
+        client.on("event", onEvent);
+    });
+
+    httpBackend.flush();
+
+    return eventPromise.then((event) => {
+        expect(event.isEncrypted()).toBeTruthy();
+
+        // it may still be being decrypted
+        return testUtils.awaitDecryption(event);
+    }).then((event) => {
+        expect(event.getType()).toEqual("m.room.message");
+        expect(event.getContent()).toEqual({
+            msgtype: "m.text",
+            body: "Hello, World",
+        });
+        expect(event.isEncrypted()).toBeTruthy();
+    });
+}
+
+
+/**
+ * Send an initial sync response to the client (which just includes the member
+ * list for our test room).
+ *
+ * @param {TestClient} testClient
+ * @returns {Promise} which resolves when the sync has been flushed.
+ */
+function firstSync(testClient) {
+    // send a sync response including our test room.
+    const syncData = {
+        next_batch: "x",
+        rooms: {
+            join: { },
+        },
+    };
+    syncData.rooms.join[roomId] = {
+        state: {
+            events: [
+                testUtils.mkMembership({
+                    mship: "join",
+                    user: aliUserId,
+                }),
+                testUtils.mkMembership({
+                    mship: "join",
+                    user: bobUserId,
+                }),
+            ],
+        },
+        timeline: {
+            events: [],
+        },
+    };
+
+    testClient.httpBackend.when("GET", "/sync").respond(200, syncData);
+    return testClient.flushSync();
+}
+
+
+describe("MatrixClient crypto", function() {
+    if (!sdk.CRYPTO_ENABLED) {
+        return;
+    }
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        aliTestClient = new TestClient(aliUserId, aliDeviceId, aliAccessToken);
+        await aliTestClient.client.initCrypto();
+
+        bobTestClient = new TestClient(bobUserId, bobDeviceId, bobAccessToken);
+        await bobTestClient.client.initCrypto();
+
+        aliMessages = [];
+        bobMessages = [];
+    });
+
+    afterEach(function() {
+        aliTestClient.httpBackend.verifyNoOutstandingExpectation();
+        bobTestClient.httpBackend.verifyNoOutstandingExpectation();
+
+        return Promise.all([aliTestClient.stop(), bobTestClient.stop()]);
+    });
+
+    it("Bob uploads device keys", function() {
+        return Promise.resolve()
+            .then(bobUploadsDeviceKeys);
+    });
+
+    it("Ali downloads Bobs device keys", function(done) {
+        Promise.resolve()
+            .then(bobUploadsDeviceKeys)
+            .then(aliDownloadsKeys)
+            .nodeify(done);
+    });
+
+    it("Ali gets keys with an invalid signature", function(done) {
+        Promise.resolve()
+            .then(bobUploadsDeviceKeys)
+            .then(function() {
+                // tamper bob's keys
+                const bobDeviceKeys = bobTestClient.deviceKeys;
+                expect(bobDeviceKeys.keys["curve25519:" + bobDeviceId]).toBeTruthy();
+                bobDeviceKeys.keys["curve25519:" + bobDeviceId] += "abc";
+
+                return Promise.all([
+                    aliTestClient.client.downloadKeys([bobUserId]),
+                    expectAliQueryKeys(),
+                ]);
+            }).then(function() {
+                return aliTestClient.client.getStoredDevicesForUser(bobUserId);
+            }).then((devices) => {
+                // should get an empty list
+                expect(devices).toEqual([]);
+            })
+            .nodeify(done);
+    });
+
+    it("Ali gets keys with an incorrect userId", function(done) {
+        const eveUserId = "@eve:localhost";
+
+        const bobDeviceKeys = {
+            algorithms: ['m.olm.v1.curve25519-aes-sha2', 'm.megolm.v1.aes-sha2'],
+            device_id: 'bvcxz',
+            keys: {
+                'ed25519:bvcxz': 'pYuWKMCVuaDLRTM/eWuB8OlXEb61gZhfLVJ+Y54tl0Q',
+                'curve25519:bvcxz': '7Gni0loo/nzF0nFp9847RbhElGewzwUXHPrljjBGPTQ',
+            },
+            user_id: '@eve:localhost',
+            signatures: {
+                '@eve:localhost': {
+                    'ed25519:bvcxz': 'CliUPZ7dyVPBxvhSA1d+X+LYa5b2AYdjcTwG' +
+                        '0stXcIxjaJNemQqtdgwKDtBFl3pN2I13SEijRDCf1A8bYiQMDg',
+                },
+            },
+        };
+
+        const bobKeys = {};
+        bobKeys[bobDeviceId] = bobDeviceKeys;
+        aliTestClient.httpBackend.when(
+            "POST", "/keys/query",
+        ).respond(200, function(path, content) {
+            const result = {};
+            result[bobUserId] = bobKeys;
+            return {device_keys: result};
+        });
+
+        Promise.all([
+            aliTestClient.client.downloadKeys([bobUserId, eveUserId]),
+            aliTestClient.httpBackend.flush("/keys/query", 1),
+        ]).then(function() {
+            return Promise.all([
+                aliTestClient.client.getStoredDevicesForUser(bobUserId),
+                aliTestClient.client.getStoredDevicesForUser(eveUserId),
+            ]);
+        }).spread((bobDevices, eveDevices) => {
+            // should get an empty list
+            expect(bobDevices).toEqual([]);
+            expect(eveDevices).toEqual([]);
+        }).nodeify(done);
+    });
+
+    it("Ali gets keys with an incorrect deviceId", function(done) {
+        const bobDeviceKeys = {
+            algorithms: ['m.olm.v1.curve25519-aes-sha2', 'm.megolm.v1.aes-sha2'],
+            device_id: 'bad_device',
+            keys: {
+                'ed25519:bad_device': 'e8XlY5V8x2yJcwa5xpSzeC/QVOrU+D5qBgyTK0ko+f0',
+                'curve25519:bad_device': 'YxuuLG/4L5xGeP8XPl5h0d7DzyYVcof7J7do+OXz0xc',
+            },
+            user_id: '@bob:localhost',
+            signatures: {
+                '@bob:localhost': {
+                    'ed25519:bad_device': 'fEFTq67RaSoIEVBJ8DtmRovbwUBKJ0A' +
+                        'me9m9PDzM9azPUwZ38Xvf6vv1A7W1PSafH4z3Y2ORIyEnZgHaNby3CQ',
+                },
+            },
+        };
+
+        const bobKeys = {};
+        bobKeys[bobDeviceId] = bobDeviceKeys;
+        aliTestClient.httpBackend.when(
+            "POST", "/keys/query",
+        ).respond(200, function(path, content) {
+            const result = {};
+            result[bobUserId] = bobKeys;
+            return {device_keys: result};
+        });
+
+        Promise.all([
+            aliTestClient.client.downloadKeys([bobUserId]),
+            aliTestClient.httpBackend.flush("/keys/query", 1),
+        ]).then(function() {
+            return aliTestClient.client.getStoredDevicesForUser(bobUserId);
+        }).then((devices) => {
+            // should get an empty list
+            expect(devices).toEqual([]);
+        }).nodeify(done);
+    });
+
+
+    it("Bob starts his client and uploads device keys and one-time keys", function() {
+        return Promise.resolve()
+            .then(() => bobTestClient.start())
+            .then(() => bobTestClient.awaitOneTimeKeyUpload())
+            .then((keys) => {
+                expect(Object.keys(keys).length).toEqual(5);
+                expect(Object.keys(bobTestClient.deviceKeys).length).toNotEqual(0);
+            });
+    });
+
+    it("Ali sends a message", function(done) {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => bobTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(aliEnablesEncryption)
+            .then(aliSendsFirstMessage)
+            .nodeify(done);
+    });
+
+    it("Bob receives a message", function() {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        return Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => bobTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(aliEnablesEncryption)
+            .then(aliSendsFirstMessage)
+            .then(bobRecvMessage);
+    });
+
+    it("Bob receives a message with a bogus sender", function() {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        return Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => bobTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(aliEnablesEncryption)
+            .then(aliSendsFirstMessage)
+            .then(function() {
+                const message = aliMessages.shift();
+                const syncData = {
+                    next_batch: "x",
+                    rooms: {
+                        join: {
+
+                        },
+                    },
+                };
+                syncData.rooms.join[roomId] = {
+                    timeline: {
+                        events: [
+                            testUtils.mkEvent({
+                                type: "m.room.encrypted",
+                                room: roomId,
+                                content: message,
+                                sender: "@bogus:sender",
+                            }),
+                        ],
+                    },
+                };
+                bobTestClient.httpBackend.when("GET", "/sync").respond(200, syncData);
+
+                const eventPromise = new Promise((resolve, reject) => {
+                    const onEvent = function(event) {
+                        logger.log(bobUserId + " received event",
+                                    event);
+                        resolve(event);
+                    };
+                    bobTestClient.client.once("event", onEvent);
+                });
+
+                bobTestClient.httpBackend.flush();
+                return eventPromise;
+            }).then((event) => {
+                expect(event.isEncrypted()).toBeTruthy();
+
+                // it may still be being decrypted
+                return testUtils.awaitDecryption(event);
+            }).then((event) => {
+                expect(event.getType()).toEqual("m.room.message");
+                expect(event.getContent().msgtype).toEqual("m.bad.encrypted");
+            });
+    });
+
+    it("Ali blocks Bob's device", function(done) {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => bobTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(aliEnablesEncryption)
+            .then(aliDownloadsKeys)
+            .then(function() {
+                aliTestClient.client.setDeviceBlocked(bobUserId, bobDeviceId, true);
+                const p1 = sendMessage(aliTestClient.client);
+                const p2 = expectSendMessageRequest(aliTestClient.httpBackend)
+                      .then(function(sentContent) {
+                          // no unblocked devices, so the ciphertext should be empty
+                          expect(sentContent.ciphertext).toEqual({});
+                      });
+                return Promise.all([p1, p2]);
+            }).nodeify(done);
+    });
+
+    it("Bob receives two pre-key messages", function(done) {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => bobTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(aliEnablesEncryption)
+            .then(aliSendsFirstMessage)
+            .then(bobRecvMessage)
+            .then(aliSendsMessage)
+            .then(bobRecvMessage)
+            .nodeify(done);
+    });
+
+    it("Bob replies to the message", function() {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        bobTestClient.expectKeyQuery({device_keys: {[bobUserId]: {}}});
+        return Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => bobTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(() => firstSync(bobTestClient))
+            .then(aliEnablesEncryption)
+            .then(aliSendsFirstMessage)
+            .then(bobRecvMessage)
+            .then(bobEnablesEncryption)
+            .then(bobSendsReplyMessage).then(function(ciphertext) {
+                expect(ciphertext.type).toEqual(1, "Unexpected cipghertext type.");
+            }).then(aliRecvMessage);
+    });
+
+    it("Ali does a key query when encryption is enabled", function() {
+        // enabling encryption in the room should make alice download devices
+        // for both members.
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
+        return Promise.resolve()
+            .then(() => aliTestClient.start())
+            .then(() => firstSync(aliTestClient))
+            .then(() => {
+                const syncData = {
+                    next_batch: '2',
+                    rooms: {
+                        join: {},
+                    },
+                };
+                syncData.rooms.join[roomId] = {
+                    state: {
+                        events: [
+                            testUtils.mkEvent({
+                                type: 'm.room.encryption',
+                                skey: '',
+                                content: {
+                                    algorithm: 'm.olm.v1.curve25519-aes-sha2',
+                                },
+                            }),
+                        ],
+                    },
+                };
+
+                aliTestClient.httpBackend.when('GET', '/sync').respond(
+                    200, syncData);
+                return aliTestClient.httpBackend.flush('/sync', 1);
+            }).then(() => {
+                aliTestClient.expectKeyQuery({
+                    device_keys: {
+                        [bobUserId]: {},
+                    },
+                });
+                return aliTestClient.httpBackend.flushAllExpected();
+            });
+    });
+
+    it("Upload new oneTimeKeys based on a /sync request - no count-asking", function() {
+        // Send a response which causes a key upload
+        const httpBackend = aliTestClient.httpBackend;
+        const syncDataEmpty = {
+            next_batch: "a",
+            device_one_time_keys_count: {
+                signed_curve25519: 0,
+            },
+        };
+
+        // enqueue expectations:
+        // * Sync with empty one_time_keys => upload keys
+
+        return Promise.resolve()
+            .then(() => {
+                logger.log(aliTestClient + ': starting');
+                httpBackend.when("GET", "/pushrules").respond(200, {});
+                httpBackend.when("POST", "/filter").respond(200, { filter_id: "fid" });
+                aliTestClient.expectDeviceKeyUpload();
+
+                // we let the client do a very basic initial sync, which it needs before
+                // it will upload one-time keys.
+                httpBackend.when("GET", "/sync").respond(200, syncDataEmpty);
+
+                aliTestClient.client.startClient({});
+
+                return httpBackend.flushAllExpected().then(() => {
+                    logger.log(aliTestClient + ': started');
+                });
+            })
+            .then(() => httpBackend.when("POST", "/keys/upload")
+                .respond(200, (path, content) => {
+                    expect(content.one_time_keys).toBeTruthy();
+                    expect(content.one_time_keys).toNotEqual({});
+                    expect(Object.keys(content.one_time_keys).length)
+                        .toBeGreaterThanOrEqualTo(1);
+                    logger.log('received %i one-time keys',
+                                Object.keys(content.one_time_keys).length);
+                    // cancel futher calls by telling the client
+                    // we have more than we need
+                    return {
+                       one_time_key_counts: {
+                           signed_curve25519: 70,
+                       },
+                    };
+                }))
+            .then(() => httpBackend.flushAllExpected());
+    });
+});

spec/integ/matrix-client-event-emitter.spec.js

@@ -0,0 +1,342 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const HttpBackend = require("matrix-mock-request");
+const utils = require("../test-utils");
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+describe("MatrixClient events", function() {
+    const baseUrl = "http://localhost.or.something";
+    let client;
+    let httpBackend;
+    const selfUserId = "@alice:localhost";
+    const selfAccessToken = "aseukfgwef";
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        sdk.request(httpBackend.requestFn);
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: selfUserId,
+            accessToken: selfAccessToken,
+        });
+        httpBackend.when("GET", "/pushrules").respond(200, {});
+        httpBackend.when("POST", "/filter").respond(200, { filter_id: "a filter id" });
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        client.stopClient();
+        return httpBackend.stop();
+    });
+
+    describe("emissions", function() {
+        const SYNC_DATA = {
+            next_batch: "s_5_3",
+            presence: {
+                events: [
+                    utils.mkPresence({
+                        user: "@foo:bar", name: "Foo Bar", presence: "online",
+                    }),
+                ],
+            },
+            rooms: {
+                join: {
+                    "!erufh:bar": {
+                        timeline: {
+                            events: [
+                                utils.mkMessage({
+                                    room: "!erufh:bar", user: "@foo:bar", msg: "hmmm",
+                                }),
+                            ],
+                            prev_batch: "s",
+                        },
+                        state: {
+                            events: [
+                                utils.mkMembership({
+                                    room: "!erufh:bar", mship: "join", user: "@foo:bar",
+                                }),
+                                utils.mkEvent({
+                                    type: "m.room.create", room: "!erufh:bar",
+                                    user: "@foo:bar",
+                                    content: {
+                                        creator: "@foo:bar",
+                                    },
+                                }),
+                            ],
+                        },
+                    },
+                },
+            },
+        };
+        const NEXT_SYNC_DATA = {
+            next_batch: "e_6_7",
+            rooms: {
+                join: {
+                    "!erufh:bar": {
+                        timeline: {
+                            events: [
+                                utils.mkMessage({
+                                    room: "!erufh:bar", user: "@foo:bar",
+                                    msg: "ello ello",
+                                }),
+                                utils.mkMessage({
+                                    room: "!erufh:bar", user: "@foo:bar", msg: ":D",
+                                }),
+                            ],
+                        },
+                        ephemeral: {
+                            events: [
+                                utils.mkEvent({
+                                    type: "m.typing", room: "!erufh:bar", content: {
+                                        user_ids: ["@foo:bar"],
+                                    },
+                                }),
+                            ],
+                        },
+                    },
+                },
+            },
+        };
+
+        it("should emit events from both the first and subsequent /sync calls",
+        function() {
+            httpBackend.when("GET", "/sync").respond(200, SYNC_DATA);
+            httpBackend.when("GET", "/sync").respond(200, NEXT_SYNC_DATA);
+
+            let expectedEvents = [];
+            expectedEvents = expectedEvents.concat(
+                SYNC_DATA.presence.events,
+                SYNC_DATA.rooms.join["!erufh:bar"].timeline.events,
+                SYNC_DATA.rooms.join["!erufh:bar"].state.events,
+                NEXT_SYNC_DATA.rooms.join["!erufh:bar"].timeline.events,
+                NEXT_SYNC_DATA.rooms.join["!erufh:bar"].ephemeral.events,
+            );
+
+            client.on("event", function(event) {
+                let found = false;
+                for (let i = 0; i < expectedEvents.length; i++) {
+                    if (expectedEvents[i].event_id === event.getId()) {
+                        expectedEvents.splice(i, 1);
+                        found = true;
+                        break;
+                    }
+                }
+                expect(found).toBe(
+                    true, "Unexpected 'event' emitted: " + event.getType(),
+                );
+            });
+
+            client.startClient();
+
+            return Promise.all([
+                // wait for two SYNCING events
+                utils.syncPromise(client).then(() => {
+                    return utils.syncPromise(client);
+                }),
+                httpBackend.flushAllExpected(),
+            ]).then(() => {
+                expect(expectedEvents.length).toEqual(
+                    0, "Failed to see all events from /sync calls",
+                );
+            });
+        });
+
+        it("should emit User events", function(done) {
+            httpBackend.when("GET", "/sync").respond(200, SYNC_DATA);
+            httpBackend.when("GET", "/sync").respond(200, NEXT_SYNC_DATA);
+            let fired = false;
+            client.on("User.presence", function(event, user) {
+                fired = true;
+                expect(user).toBeTruthy();
+                expect(event).toBeTruthy();
+                if (!user || !event) {
+                    return;
+                }
+
+                expect(event.event).toMatch(SYNC_DATA.presence.events[0]);
+                expect(user.presence).toEqual(
+                    SYNC_DATA.presence.events[0].content.presence,
+                );
+            });
+            client.startClient();
+
+            httpBackend.flushAllExpected().done(function() {
+                expect(fired).toBe(true, "User.presence didn't fire.");
+                done();
+            });
+        });
+
+        it("should emit Room events", function() {
+            httpBackend.when("GET", "/sync").respond(200, SYNC_DATA);
+            httpBackend.when("GET", "/sync").respond(200, NEXT_SYNC_DATA);
+            let roomInvokeCount = 0;
+            let roomNameInvokeCount = 0;
+            let timelineFireCount = 0;
+            client.on("Room", function(room) {
+                roomInvokeCount++;
+                expect(room.roomId).toEqual("!erufh:bar");
+            });
+            client.on("Room.timeline", function(event, room) {
+                timelineFireCount++;
+                expect(room.roomId).toEqual("!erufh:bar");
+            });
+            client.on("Room.name", function(room) {
+                roomNameInvokeCount++;
+            });
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                utils.syncPromise(client, 2),
+            ]).then(function() {
+                expect(roomInvokeCount).toEqual(
+                    1, "Room fired wrong number of times.",
+                );
+                expect(roomNameInvokeCount).toEqual(
+                    1, "Room.name fired wrong number of times.",
+                );
+                expect(timelineFireCount).toEqual(
+                    3, "Room.timeline fired the wrong number of times",
+                );
+            });
+        });
+
+        it("should emit RoomState events", function() {
+            httpBackend.when("GET", "/sync").respond(200, SYNC_DATA);
+            httpBackend.when("GET", "/sync").respond(200, NEXT_SYNC_DATA);
+
+            const roomStateEventTypes = [
+                "m.room.member", "m.room.create",
+            ];
+            let eventsInvokeCount = 0;
+            let membersInvokeCount = 0;
+            let newMemberInvokeCount = 0;
+            client.on("RoomState.events", function(event, state) {
+                eventsInvokeCount++;
+                const index = roomStateEventTypes.indexOf(event.getType());
+                expect(index).toNotEqual(
+                    -1, "Unexpected room state event type: " + event.getType(),
+                );
+                if (index >= 0) {
+                    roomStateEventTypes.splice(index, 1);
+                }
+            });
+            client.on("RoomState.members", function(event, state, member) {
+                membersInvokeCount++;
+                expect(member.roomId).toEqual("!erufh:bar");
+                expect(member.userId).toEqual("@foo:bar");
+                expect(member.membership).toEqual("join");
+            });
+            client.on("RoomState.newMember", function(event, state, member) {
+                newMemberInvokeCount++;
+                expect(member.roomId).toEqual("!erufh:bar");
+                expect(member.userId).toEqual("@foo:bar");
+                expect(member.membership).toBeFalsy();
+            });
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                utils.syncPromise(client, 2),
+            ]).then(function() {
+                expect(membersInvokeCount).toEqual(
+                    1, "RoomState.members fired wrong number of times",
+                );
+                expect(newMemberInvokeCount).toEqual(
+                    1, "RoomState.newMember fired wrong number of times",
+                );
+                expect(eventsInvokeCount).toEqual(
+                    2, "RoomState.events fired wrong number of times",
+                );
+            });
+        });
+
+        it("should emit RoomMember events", function() {
+            httpBackend.when("GET", "/sync").respond(200, SYNC_DATA);
+            httpBackend.when("GET", "/sync").respond(200, NEXT_SYNC_DATA);
+
+            let typingInvokeCount = 0;
+            let powerLevelInvokeCount = 0;
+            let nameInvokeCount = 0;
+            let membershipInvokeCount = 0;
+            client.on("RoomMember.name", function(event, member) {
+                nameInvokeCount++;
+            });
+            client.on("RoomMember.typing", function(event, member) {
+                typingInvokeCount++;
+                expect(member.typing).toBe(true);
+            });
+            client.on("RoomMember.powerLevel", function(event, member) {
+                powerLevelInvokeCount++;
+            });
+            client.on("RoomMember.membership", function(event, member) {
+                membershipInvokeCount++;
+                expect(member.membership).toEqual("join");
+            });
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                utils.syncPromise(client, 2),
+            ]).then(function() {
+                expect(typingInvokeCount).toEqual(
+                    1, "RoomMember.typing fired wrong number of times",
+                );
+                expect(powerLevelInvokeCount).toEqual(
+                    0, "RoomMember.powerLevel fired wrong number of times",
+                );
+                expect(nameInvokeCount).toEqual(
+                    0, "RoomMember.name fired wrong number of times",
+                );
+                expect(membershipInvokeCount).toEqual(
+                    1, "RoomMember.membership fired wrong number of times",
+                );
+            });
+        });
+
+        it("should emit Session.logged_out on M_UNKNOWN_TOKEN", function() {
+            const error = { errcode: 'M_UNKNOWN_TOKEN' };
+            httpBackend.when("GET", "/sync").respond(401, error);
+
+            let sessionLoggedOutCount = 0;
+            client.on("Session.logged_out", function(errObj) {
+                sessionLoggedOutCount++;
+                expect(errObj.data).toEqual(error);
+            });
+
+            client.startClient();
+
+            return httpBackend.flushAllExpected().then(function() {
+                expect(sessionLoggedOutCount).toEqual(
+                    1, "Session.logged_out fired wrong number of times",
+                );
+            });
+        });
+
+        it("should emit Session.logged_out on M_UNKNOWN_TOKEN (soft logout)", function() {
+            const error = { errcode: 'M_UNKNOWN_TOKEN', soft_logout: true };
+            httpBackend.when("GET", "/sync").respond(401, error);
+
+            let sessionLoggedOutCount = 0;
+            client.on("Session.logged_out", function(errObj) {
+                sessionLoggedOutCount++;
+                expect(errObj.data).toEqual(error);
+            });
+
+            client.startClient();
+
+            return httpBackend.flushAllExpected().then(function() {
+                expect(sessionLoggedOutCount).toEqual(
+                    1, "Session.logged_out fired wrong number of times",
+                );
+            });
+        });
+    });
+});

spec/integ/matrix-client-event-timeline.spec.js

@@ -0,0 +1,770 @@
+"use strict";
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const HttpBackend = require("matrix-mock-request");
+const utils = require("../test-utils");
+const EventTimeline = sdk.EventTimeline;
+import logger from '../../src/logger';
+
+const baseUrl = "http://localhost.or.something";
+const userId = "@alice:localhost";
+const userName = "Alice";
+const accessToken = "aseukfgwef";
+const roomId = "!foo:bar";
+const otherUserId = "@bob:localhost";
+
+const USER_MEMBERSHIP_EVENT = utils.mkMembership({
+    room: roomId, mship: "join", user: userId, name: userName,
+});
+
+const ROOM_NAME_EVENT = utils.mkEvent({
+    type: "m.room.name", room: roomId, user: otherUserId,
+    content: {
+        name: "Old room name",
+    },
+});
+
+const INITIAL_SYNC_DATA = {
+    next_batch: "s_5_3",
+    rooms: {
+        join: {
+            "!foo:bar": {  // roomId
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomId, user: otherUserId, msg: "hello",
+                        }),
+                    ],
+                    prev_batch: "f_1_1",
+                },
+                state: {
+                    events: [
+                        ROOM_NAME_EVENT,
+                        utils.mkMembership({
+                            room: roomId, mship: "join",
+                            user: otherUserId, name: "Bob",
+                        }),
+                        USER_MEMBERSHIP_EVENT,
+                        utils.mkEvent({
+                            type: "m.room.create", room: roomId, user: userId,
+                            content: {
+                                creator: userId,
+                            },
+                        }),
+                    ],
+                },
+            },
+        },
+    },
+};
+
+const EVENTS = [
+    utils.mkMessage({
+        room: roomId, user: userId, msg: "we",
+    }),
+    utils.mkMessage({
+        room: roomId, user: userId, msg: "could",
+    }),
+    utils.mkMessage({
+        room: roomId, user: userId, msg: "be",
+    }),
+    utils.mkMessage({
+        room: roomId, user: userId, msg: "heroes",
+    }),
+];
+
+// start the client, and wait for it to initialise
+function startClient(httpBackend, client) {
+    httpBackend.when("GET", "/pushrules").respond(200, {});
+    httpBackend.when("POST", "/filter").respond(200, { filter_id: "fid" });
+    httpBackend.when("GET", "/sync").respond(200, INITIAL_SYNC_DATA);
+
+    client.startClient();
+
+    // set up a promise which will resolve once the client is initialised
+    const deferred = Promise.defer();
+    client.on("sync", function(state) {
+        logger.log("sync", state);
+        if (state != "SYNCING") {
+            return;
+        }
+        deferred.resolve();
+    });
+
+    return Promise.all([
+        httpBackend.flushAllExpected(),
+        deferred.promise,
+    ]);
+}
+
+describe("getEventTimeline support", function() {
+    let httpBackend;
+    let client;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        sdk.request(httpBackend.requestFn);
+    });
+
+    afterEach(function() {
+        if (client) {
+            client.stopClient();
+        }
+        return httpBackend.stop();
+    });
+
+    it("timeline support must be enabled to work", function(done) {
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            accessToken: accessToken,
+        });
+
+        startClient(httpBackend, client,
+        ).then(function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+            expect(function() {
+                client.getEventTimeline(timelineSet, "event");
+            }).toThrow();
+        }).nodeify(done);
+    });
+
+    it("timeline support works when enabled", function() {
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            accessToken: accessToken,
+            timelineSupport: true,
+        });
+
+        return startClient(httpBackend, client).then(() => {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+            expect(function() {
+                client.getEventTimeline(timelineSet, "event");
+            }).toNotThrow();
+        });
+    });
+
+
+    it("scrollback should be able to scroll back to before a gappy /sync",
+      function(done) {
+        // need a client with timelineSupport disabled to make this work
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            accessToken: accessToken,
+        });
+        let room;
+
+        startClient(httpBackend, client,
+        ).then(function() {
+            room = client.getRoom(roomId);
+
+            httpBackend.when("GET", "/sync").respond(200, {
+                next_batch: "s_5_4",
+                rooms: {
+                    join: {
+                        "!foo:bar": {
+                            timeline: {
+                                events: [
+                                    EVENTS[0],
+                                ],
+                                prev_batch: "f_1_1",
+                            },
+                        },
+                    },
+                },
+            });
+
+            httpBackend.when("GET", "/sync").respond(200, {
+                next_batch: "s_5_5",
+                rooms: {
+                    join: {
+                        "!foo:bar": {
+                            timeline: {
+                                events: [
+                                    EVENTS[1],
+                                ],
+                                limited: true,
+                                prev_batch: "f_1_2",
+                            },
+                        },
+                    },
+                },
+            });
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                utils.syncPromise(client, 2),
+            ]);
+        }).then(function() {
+            expect(room.timeline.length).toEqual(1);
+            expect(room.timeline[0].event).toEqual(EVENTS[1]);
+
+            httpBackend.when("GET", "/messages").respond(200, {
+                chunk: [EVENTS[0]],
+                start: "pagin_start",
+                end: "pagin_end",
+            });
+            httpBackend.flush("/messages", 1);
+            return client.scrollback(room);
+        }).then(function() {
+            expect(room.timeline.length).toEqual(2);
+            expect(room.timeline[0].event).toEqual(EVENTS[0]);
+            expect(room.timeline[1].event).toEqual(EVENTS[1]);
+            expect(room.oldState.paginationToken).toEqual("pagin_end");
+        }).nodeify(done);
+    });
+});
+
+import expect from 'expect';
+
+describe("MatrixClient event timelines", function() {
+    let client = null;
+    let httpBackend = null;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        sdk.request(httpBackend.requestFn);
+
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            accessToken: accessToken,
+            timelineSupport: true,
+        });
+
+        return startClient(httpBackend, client);
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        client.stopClient();
+    });
+
+    describe("getEventTimeline", function() {
+        it("should create a new timeline for new events", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/event1%3Abar")
+                .respond(200, function() {
+                    return {
+                        start: "start_token",
+                        events_before: [EVENTS[1], EVENTS[0]],
+                        event: EVENTS[2],
+                        events_after: [EVENTS[3]],
+                        state: [
+                            ROOM_NAME_EVENT,
+                            USER_MEMBERSHIP_EVENT,
+                        ],
+                        end: "end_token",
+                    };
+                });
+
+            return Promise.all([
+                client.getEventTimeline(timelineSet, "event1:bar").then(function(tl) {
+                    expect(tl.getEvents().length).toEqual(4);
+                    for (let i = 0; i < 4; i++) {
+                        expect(tl.getEvents()[i].event).toEqual(EVENTS[i]);
+                        expect(tl.getEvents()[i].sender.name).toEqual(userName);
+                    }
+                    expect(tl.getPaginationToken(EventTimeline.BACKWARDS))
+                        .toEqual("start_token");
+                    expect(tl.getPaginationToken(EventTimeline.FORWARDS))
+                        .toEqual("end_token");
+                }),
+                httpBackend.flushAllExpected(),
+            ]);
+        });
+
+        it("should return existing timeline for known events", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+            httpBackend.when("GET", "/sync").respond(200, {
+                next_batch: "s_5_4",
+                rooms: {
+                    join: {
+                        "!foo:bar": {
+                            timeline: {
+                                events: [
+                                    EVENTS[0],
+                                ],
+                                prev_batch: "f_1_2",
+                            },
+                        },
+                    },
+                },
+            });
+
+            return Promise.all([
+                httpBackend.flush("/sync"),
+                utils.syncPromise(client),
+            ]).then(function() {
+                return client.getEventTimeline(timelineSet, EVENTS[0].event_id);
+            }).then(function(tl) {
+                expect(tl.getEvents().length).toEqual(2);
+                expect(tl.getEvents()[1].event).toEqual(EVENTS[0]);
+                expect(tl.getEvents()[1].sender.name).toEqual(userName);
+                expect(tl.getPaginationToken(EventTimeline.BACKWARDS))
+                    .toEqual("f_1_1");
+                // expect(tl.getPaginationToken(EventTimeline.FORWARDS))
+                //    .toEqual("s_5_4");
+            });
+        });
+
+        it("should update timelines where they overlap a previous /sync", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+            httpBackend.when("GET", "/sync").respond(200, {
+                next_batch: "s_5_4",
+                rooms: {
+                    join: {
+                        "!foo:bar": {
+                            timeline: {
+                                events: [
+                                    EVENTS[3],
+                                ],
+                                prev_batch: "f_1_2",
+                            },
+                        },
+                    },
+                },
+            });
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[2].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token",
+                        events_before: [EVENTS[1]],
+                        event: EVENTS[2],
+                        events_after: [EVENTS[3]],
+                        end: "end_token",
+                        state: [],
+                    };
+                });
+
+            const deferred = Promise.defer();
+            client.on("sync", function() {
+                client.getEventTimeline(timelineSet, EVENTS[2].event_id,
+                ).then(function(tl) {
+                    expect(tl.getEvents().length).toEqual(4);
+                    expect(tl.getEvents()[0].event).toEqual(EVENTS[1]);
+                    expect(tl.getEvents()[1].event).toEqual(EVENTS[2]);
+                    expect(tl.getEvents()[3].event).toEqual(EVENTS[3]);
+                    expect(tl.getPaginationToken(EventTimeline.BACKWARDS))
+                        .toEqual("start_token");
+                    // expect(tl.getPaginationToken(EventTimeline.FORWARDS))
+                    //    .toEqual("s_5_4");
+                }).done(() => deferred.resolve(),
+                        (e) => deferred.reject(e));
+            });
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                deferred.promise,
+            ]);
+        });
+
+        it("should join timelines where they overlap a previous /context",
+          function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+
+            // we fetch event 0, then 2, then 3, and finally 1. 1 is returned
+            // with context which joins them all up.
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[0].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token0",
+                        events_before: [],
+                        event: EVENTS[0],
+                        events_after: [],
+                        end: "end_token0",
+                        state: [],
+                    };
+                });
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[2].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token2",
+                        events_before: [],
+                        event: EVENTS[2],
+                        events_after: [],
+                        end: "end_token2",
+                        state: [],
+                    };
+                });
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[3].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token3",
+                        events_before: [],
+                        event: EVENTS[3],
+                        events_after: [],
+                        end: "end_token3",
+                        state: [],
+                    };
+                });
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[1].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token4",
+                        events_before: [EVENTS[0]],
+                        event: EVENTS[1],
+                        events_after: [EVENTS[2], EVENTS[3]],
+                        end: "end_token4",
+                        state: [],
+                    };
+                });
+
+            let tl0;
+            let tl3;
+            return Promise.all([
+                client.getEventTimeline(timelineSet, EVENTS[0].event_id,
+                ).then(function(tl) {
+                    expect(tl.getEvents().length).toEqual(1);
+                    tl0 = tl;
+                    return client.getEventTimeline(timelineSet, EVENTS[2].event_id);
+                }).then(function(tl) {
+                    expect(tl.getEvents().length).toEqual(1);
+                    return client.getEventTimeline(timelineSet, EVENTS[3].event_id);
+                }).then(function(tl) {
+                    expect(tl.getEvents().length).toEqual(1);
+                    tl3 = tl;
+                    return client.getEventTimeline(timelineSet, EVENTS[1].event_id);
+                }).then(function(tl) {
+                    // we expect it to get merged in with event 2
+                    expect(tl.getEvents().length).toEqual(2);
+                    expect(tl.getEvents()[0].event).toEqual(EVENTS[1]);
+                    expect(tl.getEvents()[1].event).toEqual(EVENTS[2]);
+                    expect(tl.getNeighbouringTimeline(EventTimeline.BACKWARDS))
+                        .toBe(tl0);
+                    expect(tl.getNeighbouringTimeline(EventTimeline.FORWARDS))
+                        .toBe(tl3);
+                    expect(tl0.getPaginationToken(EventTimeline.BACKWARDS))
+                        .toEqual("start_token0");
+                    expect(tl0.getPaginationToken(EventTimeline.FORWARDS))
+                        .toBe(null);
+                    expect(tl3.getPaginationToken(EventTimeline.BACKWARDS))
+                        .toBe(null);
+                    expect(tl3.getPaginationToken(EventTimeline.FORWARDS))
+                        .toEqual("end_token3");
+                }),
+                httpBackend.flushAllExpected(),
+            ]);
+        });
+
+        it("should fail gracefully if there is no event field", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+            // we fetch event 0, then 2, then 3, and finally 1. 1 is returned
+            // with context which joins them all up.
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/event1")
+                .respond(200, function() {
+                    return {
+                        start: "start_token",
+                        events_before: [],
+                        events_after: [],
+                        end: "end_token",
+                        state: [],
+                    };
+                });
+
+            return Promise.all([
+                client.getEventTimeline(timelineSet, "event1",
+                ).then(function(tl) {
+                    // could do with a fail()
+                    expect(true).toBeFalsy();
+                }, function(e) {
+                    expect(String(e)).toMatch(/'event'/);
+                }),
+                httpBackend.flushAllExpected(),
+            ]);
+        });
+    });
+
+    describe("paginateEventTimeline", function() {
+        it("should allow you to paginate backwards", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[0].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token0",
+                        events_before: [],
+                        event: EVENTS[0],
+                        events_after: [],
+                        end: "end_token0",
+                        state: [],
+                    };
+                });
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/messages")
+                .check(function(req) {
+                    const params = req.queryParams;
+                    expect(params.dir).toEqual("b");
+                    expect(params.from).toEqual("start_token0");
+                    expect(params.limit).toEqual(30);
+                }).respond(200, function() {
+                    return {
+                        chunk: [EVENTS[1], EVENTS[2]],
+                        end: "start_token1",
+                    };
+                });
+
+            let tl;
+            return Promise.all([
+                client.getEventTimeline(timelineSet, EVENTS[0].event_id,
+                ).then(function(tl0) {
+                    tl = tl0;
+                    return client.paginateEventTimeline(tl, {backwards: true});
+                }).then(function(success) {
+                    expect(success).toBeTruthy();
+                    expect(tl.getEvents().length).toEqual(3);
+                    expect(tl.getEvents()[0].event).toEqual(EVENTS[2]);
+                    expect(tl.getEvents()[1].event).toEqual(EVENTS[1]);
+                    expect(tl.getEvents()[2].event).toEqual(EVENTS[0]);
+                    expect(tl.getPaginationToken(EventTimeline.BACKWARDS))
+                        .toEqual("start_token1");
+                    expect(tl.getPaginationToken(EventTimeline.FORWARDS))
+                        .toEqual("end_token0");
+                }),
+                httpBackend.flushAllExpected(),
+            ]);
+        });
+
+
+        it("should allow you to paginate forwards", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/context/" +
+                             encodeURIComponent(EVENTS[0].event_id))
+                .respond(200, function() {
+                    return {
+                        start: "start_token0",
+                        events_before: [],
+                        event: EVENTS[0],
+                        events_after: [],
+                        end: "end_token0",
+                        state: [],
+                    };
+                });
+
+            httpBackend.when("GET", "/rooms/!foo%3Abar/messages")
+                .check(function(req) {
+                    const params = req.queryParams;
+                    expect(params.dir).toEqual("f");
+                    expect(params.from).toEqual("end_token0");
+                    expect(params.limit).toEqual(20);
+                }).respond(200, function() {
+                    return {
+                        chunk: [EVENTS[1], EVENTS[2]],
+                        end: "end_token1",
+                    };
+                });
+
+            let tl;
+            return Promise.all([
+                client.getEventTimeline(timelineSet, EVENTS[0].event_id,
+                ).then(function(tl0) {
+                    tl = tl0;
+                    return client.paginateEventTimeline(
+                        tl, {backwards: false, limit: 20});
+                }).then(function(success) {
+                    expect(success).toBeTruthy();
+                    expect(tl.getEvents().length).toEqual(3);
+                    expect(tl.getEvents()[0].event).toEqual(EVENTS[0]);
+                    expect(tl.getEvents()[1].event).toEqual(EVENTS[1]);
+                    expect(tl.getEvents()[2].event).toEqual(EVENTS[2]);
+                    expect(tl.getPaginationToken(EventTimeline.BACKWARDS))
+                        .toEqual("start_token0");
+                    expect(tl.getPaginationToken(EventTimeline.FORWARDS))
+                        .toEqual("end_token1");
+                }),
+                httpBackend.flushAllExpected(),
+            ]);
+        });
+    });
+
+    describe("event timeline for sent events", function() {
+        const TXN_ID = "txn1";
+        const event = utils.mkMessage({
+            room: roomId, user: userId, msg: "a body",
+        });
+        event.unsigned = {transaction_id: TXN_ID};
+
+        beforeEach(function() {
+            // set up handlers for both the message send, and the
+            // /sync
+            httpBackend.when("PUT", "/send/m.room.message/" + TXN_ID)
+                .respond(200, {
+                    event_id: event.event_id,
+                });
+            httpBackend.when("GET", "/sync").respond(200, {
+                next_batch: "s_5_4",
+                rooms: {
+                    join: {
+                        "!foo:bar": {
+                            timeline: {
+                                events: [
+                                    event,
+                                ],
+                                prev_batch: "f_1_1",
+                            },
+                        },
+                    },
+                },
+            });
+        });
+
+        it("should work when /send returns before /sync", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+
+            return Promise.all([
+                client.sendTextMessage(roomId, "a body", TXN_ID).then(function(res) {
+                    expect(res.event_id).toEqual(event.event_id);
+                    return client.getEventTimeline(timelineSet, event.event_id);
+                }).then(function(tl) {
+                    // 2 because the initial sync contained an event
+                    expect(tl.getEvents().length).toEqual(2);
+                    expect(tl.getEvents()[1].getContent().body).toEqual("a body");
+
+                    // now let the sync complete, and check it again
+                    return Promise.all([
+                        httpBackend.flush("/sync", 1),
+                        utils.syncPromise(client),
+                    ]);
+                }).then(function() {
+                    return client.getEventTimeline(timelineSet, event.event_id);
+                }).then(function(tl) {
+                    expect(tl.getEvents().length).toEqual(2);
+                    expect(tl.getEvents()[1].event).toEqual(event);
+                }),
+
+                httpBackend.flush("/send/m.room.message/" + TXN_ID, 1),
+            ]);
+        });
+
+        it("should work when /send returns after /sync", function() {
+            const room = client.getRoom(roomId);
+            const timelineSet = room.getTimelineSets()[0];
+
+            return Promise.all([
+                // initiate the send, and set up checks to be done when it completes
+                // - but note that it won't complete until after the /sync does, below.
+                client.sendTextMessage(roomId, "a body", TXN_ID).then(function(res) {
+                    logger.log("sendTextMessage completed");
+                    expect(res.event_id).toEqual(event.event_id);
+                    return client.getEventTimeline(timelineSet, event.event_id);
+                }).then(function(tl) {
+                    logger.log("getEventTimeline completed (2)");
+                    expect(tl.getEvents().length).toEqual(2);
+                    expect(tl.getEvents()[1].getContent().body).toEqual("a body");
+                }),
+
+                Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    return client.getEventTimeline(timelineSet, event.event_id);
+                }).then(function(tl) {
+                    logger.log("getEventTimeline completed (1)");
+                    expect(tl.getEvents().length).toEqual(2);
+                    expect(tl.getEvents()[1].event).toEqual(event);
+
+                    // now let the send complete.
+                    return httpBackend.flush("/send/m.room.message/" + TXN_ID, 1);
+                }),
+            ]);
+        });
+    });
+
+
+    it("should handle gappy syncs after redactions", function(done) {
+        // https://github.com/vector-im/vector-web/issues/1389
+
+        // a state event, followed by a redaction thereof
+        const event = utils.mkMembership({
+            room: roomId, mship: "join", user: otherUserId,
+        });
+        const redaction = utils.mkEvent({
+            type: "m.room.redaction",
+            room_id: roomId,
+            sender: otherUserId,
+            content: {},
+        });
+        redaction.redacts = event.event_id;
+
+        const syncData = {
+            next_batch: "batch1",
+            rooms: {
+                join: {},
+            },
+        };
+        syncData.rooms.join[roomId] = {
+            timeline: {
+                events: [
+                    event,
+                    redaction,
+                ],
+                limited: false,
+            },
+        };
+        httpBackend.when("GET", "/sync").respond(200, syncData);
+
+        Promise.all([
+            httpBackend.flushAllExpected(),
+            utils.syncPromise(client),
+        ]).then(function() {
+            const room = client.getRoom(roomId);
+            const tl = room.getLiveTimeline();
+            expect(tl.getEvents().length).toEqual(3);
+            expect(tl.getEvents()[1].isRedacted()).toBe(true);
+
+            const sync2 = {
+                next_batch: "batch2",
+                rooms: {
+                    join: {},
+                },
+            };
+            sync2.rooms.join[roomId] = {
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomId, user: otherUserId, msg: "world",
+                        }),
+                    ],
+                    limited: true,
+                    prev_batch: "newerTok",
+                },
+            };
+            httpBackend.when("GET", "/sync").respond(200, sync2);
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                utils.syncPromise(client),
+            ]);
+        }).then(function() {
+            const room = client.getRoom(roomId);
+            const tl = room.getLiveTimeline();
+            expect(tl.getEvents().length).toEqual(1);
+        }).nodeify(done);
+    });
+});

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

@@ -0,0 +1,419 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const HttpBackend = require("matrix-mock-request");
+const publicGlobals = require("../../lib/matrix");
+const Room = publicGlobals.Room;
+const MemoryStore = publicGlobals.MemoryStore;
+const Filter = publicGlobals.Filter;
+const utils = require("../test-utils");
+const MockStorageApi = require("../MockStorageApi");
+
+import expect from 'expect';
+
+describe("MatrixClient", function() {
+    const baseUrl = "http://localhost.or.something";
+    let client = null;
+    let httpBackend = null;
+    let store = null;
+    let sessionStore = null;
+    const userId = "@alice:localhost";
+    const accessToken = "aseukfgwef";
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        store = new MemoryStore();
+
+        const mockStorage = new MockStorageApi();
+        sessionStore = new sdk.WebStorageSessionStore(mockStorage);
+
+        sdk.request(httpBackend.requestFn);
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            deviceId: "aliceDevice",
+            accessToken: accessToken,
+            store: store,
+            sessionStore: sessionStore,
+        });
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        return httpBackend.stop();
+    });
+
+    describe("uploadContent", function() {
+        const buf = new Buffer('hello world');
+        it("should upload the file", function(done) {
+            httpBackend.when(
+                "POST", "/_matrix/media/r0/upload",
+            ).check(function(req) {
+                expect(req.rawData).toEqual(buf);
+                expect(req.queryParams.filename).toEqual("hi.txt");
+                if (!(req.queryParams.access_token == accessToken ||
+                        req.headers["Authorization"] == "Bearer " + accessToken)) {
+                    expect(true).toBe(false);
+                }
+                expect(req.headers["Content-Type"]).toEqual("text/plain");
+                expect(req.opts.json).toBeFalsy();
+                expect(req.opts.timeout).toBe(undefined);
+            }).respond(200, "content", true);
+
+            const prom = client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            });
+
+            expect(prom).toBeTruthy();
+
+            const uploads = client.getCurrentUploads();
+            expect(uploads.length).toEqual(1);
+            expect(uploads[0].promise).toBe(prom);
+            expect(uploads[0].loaded).toEqual(0);
+
+            prom.then(function(response) {
+                // for backwards compatibility, we return the raw JSON
+                expect(response).toEqual("content");
+
+                const uploads = client.getCurrentUploads();
+                expect(uploads.length).toEqual(0);
+            }).nodeify(done);
+
+            httpBackend.flush();
+        });
+
+        it("should parse the response if rawResponse=false", function(done) {
+            httpBackend.when(
+                "POST", "/_matrix/media/r0/upload",
+            ).check(function(req) {
+                expect(req.opts.json).toBeFalsy();
+            }).respond(200, { "content_uri": "uri" });
+
+            client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            }, {
+                rawResponse: false,
+            }).then(function(response) {
+                expect(response.content_uri).toEqual("uri");
+            }).nodeify(done);
+
+            httpBackend.flush();
+        });
+
+        it("should parse errors into a MatrixError", function(done) {
+            httpBackend.when(
+                "POST", "/_matrix/media/r0/upload",
+            ).check(function(req) {
+                expect(req.rawData).toEqual(buf);
+                expect(req.opts.json).toBeFalsy();
+            }).respond(400, {
+                "errcode": "M_SNAFU",
+                "error": "broken",
+            });
+
+            client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            }).then(function(response) {
+                throw Error("request not failed");
+            }, function(error) {
+                expect(error.httpStatus).toEqual(400);
+                expect(error.errcode).toEqual("M_SNAFU");
+                expect(error.message).toEqual("broken");
+            }).nodeify(done);
+
+            httpBackend.flush();
+        });
+
+        it("should return a promise which can be cancelled", function(done) {
+            const prom = client.uploadContent({
+                stream: buf,
+                name: "hi.txt",
+                type: "text/plain",
+            });
+
+            const uploads = client.getCurrentUploads();
+            expect(uploads.length).toEqual(1);
+            expect(uploads[0].promise).toBe(prom);
+            expect(uploads[0].loaded).toEqual(0);
+
+            prom.then(function(response) {
+                throw Error("request not aborted");
+            }, function(error) {
+                expect(error).toEqual("aborted");
+
+                const uploads = client.getCurrentUploads();
+                expect(uploads.length).toEqual(0);
+            }).nodeify(done);
+
+            const r = client.cancelUpload(prom);
+            expect(r).toBe(true);
+        });
+    });
+
+    describe("joinRoom", function() {
+        it("should no-op if you've already joined a room", function() {
+            const roomId = "!foo:bar";
+            const room = new Room(roomId, userId);
+            room.addLiveEvents([
+                utils.mkMembership({
+                    user: userId, room: roomId, mship: "join", event: true,
+                }),
+            ]);
+            store.storeRoom(room);
+            client.joinRoom(roomId);
+            httpBackend.verifyNoOutstandingRequests();
+        });
+    });
+
+    describe("getFilter", function() {
+        const filterId = "f1lt3r1d";
+
+        it("should return a filter from the store if allowCached", function(done) {
+            const filter = Filter.fromJson(userId, filterId, {
+                event_format: "client",
+            });
+            store.storeFilter(filter);
+            client.getFilter(userId, filterId, true).done(function(gotFilter) {
+                expect(gotFilter).toEqual(filter);
+                done();
+            });
+            httpBackend.verifyNoOutstandingRequests();
+        });
+
+        it("should do an HTTP request if !allowCached even if one exists",
+        function(done) {
+            const httpFilterDefinition = {
+                event_format: "federation",
+            };
+
+            httpBackend.when(
+                "GET", "/user/" + encodeURIComponent(userId) + "/filter/" + filterId,
+            ).respond(200, httpFilterDefinition);
+
+            const storeFilter = Filter.fromJson(userId, filterId, {
+                event_format: "client",
+            });
+            store.storeFilter(storeFilter);
+            client.getFilter(userId, filterId, false).done(function(gotFilter) {
+                expect(gotFilter.getDefinition()).toEqual(httpFilterDefinition);
+                done();
+            });
+
+            httpBackend.flush();
+        });
+
+        it("should do an HTTP request if nothing is in the cache and then store it",
+        function(done) {
+            const httpFilterDefinition = {
+                event_format: "federation",
+            };
+            expect(store.getFilter(userId, filterId)).toBe(null);
+
+            httpBackend.when(
+                "GET", "/user/" + encodeURIComponent(userId) + "/filter/" + filterId,
+            ).respond(200, httpFilterDefinition);
+            client.getFilter(userId, filterId, true).done(function(gotFilter) {
+                expect(gotFilter.getDefinition()).toEqual(httpFilterDefinition);
+                expect(store.getFilter(userId, filterId)).toBeTruthy();
+                done();
+            });
+
+            httpBackend.flush();
+        });
+    });
+
+    describe("createFilter", function() {
+        const filterId = "f1llllllerid";
+
+        it("should do an HTTP request and then store the filter", function(done) {
+            expect(store.getFilter(userId, filterId)).toBe(null);
+
+            const filterDefinition = {
+                event_format: "client",
+            };
+
+            httpBackend.when(
+                "POST", "/user/" + encodeURIComponent(userId) + "/filter",
+            ).check(function(req) {
+                expect(req.data).toEqual(filterDefinition);
+            }).respond(200, {
+                filter_id: filterId,
+            });
+
+            client.createFilter(filterDefinition).done(function(gotFilter) {
+                expect(gotFilter.getDefinition()).toEqual(filterDefinition);
+                expect(store.getFilter(userId, filterId)).toEqual(gotFilter);
+                done();
+            });
+
+            httpBackend.flush();
+        });
+    });
+
+    describe("searching", function() {
+        const response = {
+            search_categories: {
+                room_events: {
+                    count: 24,
+                    results: {
+                        "$flibble:localhost": {
+                            rank: 0.1,
+                            result: {
+                                type: "m.room.message",
+                                user_id: "@alice:localhost",
+                                room_id: "!feuiwhf:localhost",
+                                content: {
+                                    body: "a result",
+                                    msgtype: "m.text",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+
+        it("searchMessageText should perform a /search for room_events", function(done) {
+            client.searchMessageText({
+                query: "monkeys",
+            });
+            httpBackend.when("POST", "/search").check(function(req) {
+                expect(req.data).toEqual({
+                    search_categories: {
+                        room_events: {
+                            search_term: "monkeys",
+                        },
+                    },
+                });
+            }).respond(200, response);
+
+            httpBackend.flush().done(function() {
+                done();
+            });
+        });
+    });
+
+
+    describe("downloadKeys", function() {
+        if (!sdk.CRYPTO_ENABLED) {
+            return;
+        }
+
+        beforeEach(function() {
+            return client.initCrypto();
+        });
+
+        it("should do an HTTP request and then store the keys", function(done) {
+            const ed25519key = "7wG2lzAqbjcyEkOP7O4gU7ItYcn+chKzh5sT/5r2l78";
+            // ed25519key = client.getDeviceEd25519Key();
+            const borisKeys = {
+                dev1: {
+                    algorithms: ["1"],
+                    device_id: "dev1",
+                    keys: { "ed25519:dev1": ed25519key },
+                    signatures: {
+                        boris: {
+                            "ed25519:dev1":
+                                "RAhmbNDq1efK3hCpBzZDsKoGSsrHUxb25NW5/WbEV9R" +
+                                "JVwLdP032mg5QsKt/pBDUGtggBcnk43n3nBWlA88WAw",
+                        },
+                    },
+                    unsigned: { "abc": "def" },
+                    user_id: "boris",
+                },
+            };
+            const chazKeys = {
+                dev2: {
+                    algorithms: ["2"],
+                    device_id: "dev2",
+                    keys: { "ed25519:dev2": ed25519key },
+                    signatures: {
+                        chaz: {
+                           "ed25519:dev2":
+                                "FwslH/Q7EYSb7swDJbNB5PSzcbEO1xRRBF1riuijqvL" +
+                                "EkrK9/XVN8jl4h7thGuRITQ01siBQnNmMK9t45QfcCQ",
+                        },
+                    },
+                    unsigned: { "ghi": "def" },
+                    user_id: "chaz",
+                },
+            };
+
+            /*
+            function sign(o) {
+                var anotherjson = require('another-json');
+                var b = JSON.parse(JSON.stringify(o));
+                delete(b.signatures);
+                delete(b.unsigned);
+                return client._crypto._olmDevice.sign(anotherjson.stringify(b));
+            };
+
+            logger.log("Ed25519: " + ed25519key);
+            logger.log("boris:", sign(borisKeys.dev1));
+            logger.log("chaz:", sign(chazKeys.dev2));
+            */
+
+            httpBackend.when("POST", "/keys/query").check(function(req) {
+                expect(req.data).toEqual({device_keys: {
+                    'boris': {},
+                    'chaz': {},
+                }});
+            }).respond(200, {
+                device_keys: {
+                    boris: borisKeys,
+                    chaz: chazKeys,
+                },
+            });
+
+            client.downloadKeys(["boris", "chaz"]).then(function(res) {
+                assertObjectContains(res.boris.dev1, {
+                    verified: 0, // DeviceVerification.UNVERIFIED
+                    keys: { "ed25519:dev1": ed25519key },
+                    algorithms: ["1"],
+                    unsigned: { "abc": "def" },
+                });
+
+                assertObjectContains(res.chaz.dev2, {
+                    verified: 0, // DeviceVerification.UNVERIFIED
+                    keys: { "ed25519:dev2": ed25519key },
+                    algorithms: ["2"],
+                    unsigned: { "ghi": "def" },
+                });
+            }).nodeify(done);
+
+            httpBackend.flush();
+        });
+    });
+
+    describe("deleteDevice", function() {
+        const auth = {a: 1};
+        it("should pass through an auth dict", function(done) {
+            httpBackend.when(
+                "DELETE", "/_matrix/client/r0/devices/my_device",
+            ).check(function(req) {
+                expect(req.data).toEqual({auth: auth});
+            }).respond(200);
+
+            client.deleteDevice(
+                "my_device", auth,
+            ).nodeify(done);
+
+            httpBackend.flush();
+        });
+    });
+});
+
+function assertObjectContains(obj, expected) {
+    for (const k in expected) {
+        if (expected.hasOwnProperty(k)) {
+            expect(obj[k]).toEqual(expected[k]);
+        }
+    }
+}

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

@@ -0,0 +1,188 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const MatrixClient = sdk.MatrixClient;
+const HttpBackend = require("matrix-mock-request");
+const utils = require("../test-utils");
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+describe("MatrixClient opts", function() {
+    const baseUrl = "http://localhost.or.something";
+    let client = null;
+    let httpBackend = null;
+    const userId = "@alice:localhost";
+    const userB = "@bob:localhost";
+    const accessToken = "aseukfgwef";
+    const roomId = "!foo:bar";
+    const syncData = {
+        next_batch: "s_5_3",
+        presence: {},
+        rooms: {
+            join: {
+                "!foo:bar": { // roomId
+                    timeline: {
+                        events: [
+                            utils.mkMessage({
+                                room: roomId, user: userB, msg: "hello",
+                            }),
+                        ],
+                        prev_batch: "f_1_1",
+                    },
+                    state: {
+                        events: [
+                            utils.mkEvent({
+                                type: "m.room.name", room: roomId, user: userB,
+                                content: {
+                                    name: "Old room name",
+                                },
+                            }),
+                            utils.mkMembership({
+                                room: roomId, mship: "join", user: userB, name: "Bob",
+                            }),
+                            utils.mkMembership({
+                                room: roomId, mship: "join", user: userId, name: "Alice",
+                            }),
+                            utils.mkEvent({
+                                type: "m.room.create", room: roomId, user: userId,
+                                content: {
+                                    creator: userId,
+                                },
+                            }),
+                        ],
+                    },
+                },
+            },
+        },
+    };
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        return httpBackend.stop();
+    });
+
+    describe("without opts.store", function() {
+        beforeEach(function() {
+            client = new MatrixClient({
+                request: httpBackend.requestFn,
+                store: undefined,
+                baseUrl: baseUrl,
+                userId: userId,
+                accessToken: accessToken,
+                scheduler: new sdk.MatrixScheduler(),
+            });
+        });
+
+        afterEach(function() {
+            client.stopClient();
+        });
+
+        it("should be able to send messages", function(done) {
+            const eventId = "$flibble:wibble";
+            httpBackend.when("PUT", "/txn1").respond(200, {
+                event_id: eventId,
+            });
+            client.sendTextMessage("!foo:bar", "a body", "txn1").done(function(res) {
+                expect(res.event_id).toEqual(eventId);
+                done();
+            });
+            httpBackend.flush("/txn1", 1);
+        });
+
+        it("should be able to sync / get new events", async function() {
+            const expectedEventTypes = [ // from /initialSync
+                "m.room.message", "m.room.name", "m.room.member", "m.room.member",
+                "m.room.create",
+            ];
+            client.on("event", function(event) {
+                expect(expectedEventTypes.indexOf(event.getType())).toNotEqual(
+                    -1, "Recv unexpected event type: " + event.getType(),
+                );
+                expectedEventTypes.splice(
+                    expectedEventTypes.indexOf(event.getType()), 1,
+                );
+            });
+            httpBackend.when("GET", "/pushrules").respond(200, {});
+            httpBackend.when("POST", "/filter").respond(200, { filter_id: "foo" });
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            await client.startClient();
+            await httpBackend.flush("/pushrules", 1);
+            await httpBackend.flush("/filter", 1);
+            await Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]);
+            expect(expectedEventTypes.length).toEqual(
+                0, "Expected to see event types: " + expectedEventTypes,
+            );
+        });
+    });
+
+    describe("without opts.scheduler", function() {
+        beforeEach(function() {
+            client = new MatrixClient({
+                request: httpBackend.requestFn,
+                store: new sdk.MemoryStore(),
+                baseUrl: baseUrl,
+                userId: userId,
+                accessToken: accessToken,
+                scheduler: undefined,
+            });
+        });
+
+        it("shouldn't retry sending events", function(done) {
+            httpBackend.when("PUT", "/txn1").fail(500, {
+                errcode: "M_SOMETHING",
+                error: "Ruh roh",
+            });
+            client.sendTextMessage("!foo:bar", "a body", "txn1").done(function(res) {
+                expect(false).toBe(true, "sendTextMessage resolved but shouldn't");
+            }, function(err) {
+                expect(err.errcode).toEqual("M_SOMETHING");
+                done();
+            });
+            httpBackend.flush("/txn1", 1);
+        });
+
+        it("shouldn't queue events", function(done) {
+            httpBackend.when("PUT", "/txn1").respond(200, {
+                event_id: "AAA",
+            });
+            httpBackend.when("PUT", "/txn2").respond(200, {
+                event_id: "BBB",
+            });
+            let sentA = false;
+            let sentB = false;
+            client.sendTextMessage("!foo:bar", "a body", "txn1").done(function(res) {
+                sentA = true;
+                expect(sentB).toBe(true);
+            });
+            client.sendTextMessage("!foo:bar", "b body", "txn2").done(function(res) {
+                sentB = true;
+                expect(sentA).toBe(false);
+            });
+            httpBackend.flush("/txn2", 1).done(function() {
+                httpBackend.flush("/txn1", 1).done(function() {
+                    done();
+                });
+            });
+        });
+
+        it("should be able to send messages", function(done) {
+            httpBackend.when("PUT", "/txn1").respond(200, {
+                event_id: "foo",
+            });
+            client.sendTextMessage("!foo:bar", "a body", "txn1").done(function(res) {
+                expect(res.event_id).toEqual("foo");
+                done();
+            });
+            httpBackend.flush("/txn1", 1);
+        });
+    });
+});

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

@@ -0,0 +1,129 @@
+"use strict";
+import 'source-map-support/register';
+import Promise from 'bluebird';
+
+const sdk = require("../..");
+const HttpBackend = require("matrix-mock-request");
+const utils = require("../test-utils");
+const EventStatus = sdk.EventStatus;
+
+import expect from 'expect';
+
+describe("MatrixClient retrying", function() {
+    const baseUrl = "http://localhost.or.something";
+    let client = null;
+    let httpBackend = null;
+    let scheduler;
+    const userId = "@alice:localhost";
+    const accessToken = "aseukfgwef";
+    const roomId = "!room:here";
+    let room;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        sdk.request(httpBackend.requestFn);
+        scheduler = new sdk.MatrixScheduler();
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            accessToken: accessToken,
+            scheduler: scheduler,
+        });
+        room = new sdk.Room(roomId);
+        client.store.storeRoom(room);
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        return httpBackend.stop();
+    });
+
+    xit("should retry according to MatrixScheduler.retryFn", function() {
+
+    });
+
+    xit("should queue according to MatrixScheduler.queueFn", function() {
+
+    });
+
+    xit("should mark events as EventStatus.NOT_SENT when giving up", function() {
+
+    });
+
+    xit("should mark events as EventStatus.QUEUED when queued", function() {
+
+    });
+
+    it("should mark events as EventStatus.CANCELLED when cancelled", function() {
+        // send a couple of events; the second will be queued
+        const p1 = client.sendMessage(roomId, "m1").then(function(ev) {
+            // we expect the first message to fail
+            throw new Error('Message 1 unexpectedly sent successfully');
+        }, (e) => {
+            // this is expected
+        });
+
+        // XXX: it turns out that the promise returned by this message
+        // never gets resolved.
+        // https://github.com/matrix-org/matrix-js-sdk/issues/496
+        client.sendMessage(roomId, "m2");
+
+        // both events should be in the timeline at this point
+        const tl = room.getLiveTimeline().getEvents();
+        expect(tl.length).toEqual(2);
+        const ev1 = tl[0];
+        const ev2 = tl[1];
+
+        expect(ev1.status).toEqual(EventStatus.SENDING);
+        expect(ev2.status).toEqual(EventStatus.SENDING);
+
+        // the first message should get sent, and the second should get queued
+        httpBackend.when("PUT", "/send/m.room.message/").check(function(rq) {
+            // ev2 should now have been queued
+            expect(ev2.status).toEqual(EventStatus.QUEUED);
+
+            // now we can cancel the second and check everything looks sane
+            client.cancelPendingEvent(ev2);
+            expect(ev2.status).toEqual(EventStatus.CANCELLED);
+            expect(tl.length).toEqual(1);
+
+            // shouldn't be able to cancel the first message yet
+            expect(function() {
+                client.cancelPendingEvent(ev1);
+            }).toThrow();
+        }).respond(400); // fail the first message
+
+        // wait for the localecho of ev1 to be updated
+        const p3 = new Promise((resolve, reject) => {
+            room.on("Room.localEchoUpdated", (ev0) => {
+                if(ev0 === ev1) {
+                    resolve();
+                }
+            });
+        }).then(function() {
+            expect(ev1.status).toEqual(EventStatus.NOT_SENT);
+            expect(tl.length).toEqual(1);
+
+            // cancel the first message
+            client.cancelPendingEvent(ev1);
+            expect(ev1.status).toEqual(EventStatus.CANCELLED);
+            expect(tl.length).toEqual(0);
+        });
+
+        return Promise.all([
+            p1,
+            p3,
+            httpBackend.flushAllExpected(),
+        ]);
+    });
+
+    describe("resending", function() {
+        xit("should be able to resend a NOT_SENT event", function() {
+
+        });
+        xit("should be able to resend a sent event", function() {
+
+        });
+    });
+});

spec/integ/matrix-client-room-timeline.spec.js

@@ -0,0 +1,614 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const EventStatus = sdk.EventStatus;
+const HttpBackend = require("matrix-mock-request");
+const utils = require("../test-utils");
+
+import Promise from 'bluebird';
+import expect from 'expect';
+
+describe("MatrixClient room timelines", function() {
+    const baseUrl = "http://localhost.or.something";
+    let client = null;
+    let httpBackend = null;
+    const userId = "@alice:localhost";
+    const userName = "Alice";
+    const accessToken = "aseukfgwef";
+    const roomId = "!foo:bar";
+    const otherUserId = "@bob:localhost";
+    const USER_MEMBERSHIP_EVENT = utils.mkMembership({
+        room: roomId, mship: "join", user: userId, name: userName,
+    });
+    const ROOM_NAME_EVENT = utils.mkEvent({
+        type: "m.room.name", room: roomId, user: otherUserId,
+        content: {
+            name: "Old room name",
+        },
+    });
+    let NEXT_SYNC_DATA;
+    const SYNC_DATA = {
+        next_batch: "s_5_3",
+        rooms: {
+            join: {
+                "!foo:bar": { // roomId
+                    timeline: {
+                        events: [
+                            utils.mkMessage({
+                                room: roomId, user: otherUserId, msg: "hello",
+                            }),
+                        ],
+                        prev_batch: "f_1_1",
+                    },
+                    state: {
+                        events: [
+                            ROOM_NAME_EVENT,
+                            utils.mkMembership({
+                                room: roomId, mship: "join",
+                                user: otherUserId, name: "Bob",
+                            }),
+                            USER_MEMBERSHIP_EVENT,
+                            utils.mkEvent({
+                                type: "m.room.create", room: roomId, user: userId,
+                                content: {
+                                    creator: userId,
+                                },
+                            }),
+                        ],
+                    },
+                },
+            },
+        },
+    };
+
+    function setNextSyncData(events) {
+        events = events || [];
+        NEXT_SYNC_DATA = {
+            next_batch: "n",
+            presence: { events: [] },
+            rooms: {
+                invite: {},
+                join: {
+                    "!foo:bar": {
+                        timeline: { events: [] },
+                        state: { events: [] },
+                        ephemeral: { events: [] },
+                    },
+                },
+                leave: {},
+            },
+        };
+        events.forEach(function(e) {
+            if (e.room_id !== roomId) {
+                throw new Error("setNextSyncData only works with one room id");
+            }
+            if (e.state_key) {
+                if (e.__prev_event === undefined) {
+                    throw new Error(
+                        "setNextSyncData needs the prev state set to '__prev_event' " +
+                        "for " + e.type,
+                    );
+                }
+                if (e.__prev_event !== null) {
+                    // push the previous state for this event type
+                    NEXT_SYNC_DATA.rooms.join[roomId].state.events.push(e.__prev_event);
+                }
+                // push the current
+                NEXT_SYNC_DATA.rooms.join[roomId].timeline.events.push(e);
+            } else if (["m.typing", "m.receipt"].indexOf(e.type) !== -1) {
+                NEXT_SYNC_DATA.rooms.join[roomId].ephemeral.events.push(e);
+            } else {
+                NEXT_SYNC_DATA.rooms.join[roomId].timeline.events.push(e);
+            }
+        });
+    }
+
+    beforeEach(function(done) {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        sdk.request(httpBackend.requestFn);
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: userId,
+            accessToken: accessToken,
+            // these tests should work with or without timelineSupport
+            timelineSupport: true,
+        });
+        setNextSyncData();
+        httpBackend.when("GET", "/pushrules").respond(200, {});
+        httpBackend.when("POST", "/filter").respond(200, { filter_id: "fid" });
+        httpBackend.when("GET", "/sync").respond(200, SYNC_DATA);
+        httpBackend.when("GET", "/sync").respond(200, function() {
+            return NEXT_SYNC_DATA;
+        });
+        client.startClient();
+        httpBackend.flush("/pushrules").then(function() {
+            return httpBackend.flush("/filter");
+        }).nodeify(done);
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        client.stopClient();
+        return httpBackend.stop();
+    });
+
+    describe("local echo events", function() {
+        it("should be added immediately after calling MatrixClient.sendEvent " +
+        "with EventStatus.SENDING and the right event.sender", function(done) {
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                expect(room.timeline.length).toEqual(1);
+
+                client.sendTextMessage(roomId, "I am a fish", "txn1");
+                // check it was added
+                expect(room.timeline.length).toEqual(2);
+                // check status
+                expect(room.timeline[1].status).toEqual(EventStatus.SENDING);
+                // check member
+                const member = room.timeline[1].sender;
+                expect(member.userId).toEqual(userId);
+                expect(member.name).toEqual(userName);
+
+                httpBackend.flush("/sync", 1).done(function() {
+                    done();
+                });
+            });
+            httpBackend.flush("/sync", 1);
+        });
+
+        it("should be updated correctly when the send request finishes " +
+        "BEFORE the event comes down the event stream", function(done) {
+            const eventId = "$foo:bar";
+            httpBackend.when("PUT", "/txn1").respond(200, {
+                event_id: eventId,
+            });
+
+            const ev = utils.mkMessage({
+                body: "I am a fish", user: userId, room: roomId,
+            });
+            ev.event_id = eventId;
+            ev.unsigned = {transaction_id: "txn1"};
+            setNextSyncData([ev]);
+
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                client.sendTextMessage(roomId, "I am a fish", "txn1").done(
+                function() {
+                    expect(room.timeline[1].getId()).toEqual(eventId);
+                    httpBackend.flush("/sync", 1).done(function() {
+                        expect(room.timeline[1].getId()).toEqual(eventId);
+                        done();
+                    });
+                });
+                httpBackend.flush("/txn1", 1);
+            });
+            httpBackend.flush("/sync", 1);
+        });
+
+        it("should be updated correctly when the send request finishes " +
+        "AFTER the event comes down the event stream", function(done) {
+            const eventId = "$foo:bar";
+            httpBackend.when("PUT", "/txn1").respond(200, {
+                event_id: eventId,
+            });
+
+            const ev = utils.mkMessage({
+                body: "I am a fish", user: userId, room: roomId,
+            });
+            ev.event_id = eventId;
+            ev.unsigned = {transaction_id: "txn1"};
+            setNextSyncData([ev]);
+
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                const promise = client.sendTextMessage(roomId, "I am a fish", "txn1");
+                httpBackend.flush("/sync", 1).done(function() {
+                    expect(room.timeline.length).toEqual(2);
+                    httpBackend.flush("/txn1", 1);
+                    promise.done(function() {
+                        expect(room.timeline.length).toEqual(2);
+                        expect(room.timeline[1].getId()).toEqual(eventId);
+                        done();
+                    });
+                });
+            });
+            httpBackend.flush("/sync", 1);
+        });
+    });
+
+    describe("paginated events", function() {
+        let sbEvents;
+        const sbEndTok = "pagin_end";
+
+        beforeEach(function() {
+            sbEvents = [];
+            httpBackend.when("GET", "/messages").respond(200, function() {
+                return {
+                    chunk: sbEvents,
+                    start: "pagin_start",
+                    end: sbEndTok,
+                };
+            });
+        });
+
+        it("should set Room.oldState.paginationToken to null at the start" +
+        " of the timeline.", function(done) {
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                expect(room.timeline.length).toEqual(1);
+
+                client.scrollback(room).done(function() {
+                    expect(room.timeline.length).toEqual(1);
+                    expect(room.oldState.paginationToken).toBe(null);
+
+                    // still have a sync to flush
+                    httpBackend.flush("/sync", 1).then(() => {
+                        done();
+                    });
+                });
+
+                httpBackend.flush("/messages", 1);
+            });
+            httpBackend.flush("/sync", 1);
+        });
+
+        it("should set the right event.sender values", function(done) {
+            // We're aiming for an eventual timeline of:
+            //
+            // 'Old Alice' joined the room
+            // <Old Alice> I'm old alice
+            // @alice:localhost changed their name from 'Old Alice' to 'Alice'
+            // <Alice> I'm alice
+            // ------^ /messages results above this point, /sync result below
+            // <Bob> hello
+
+            // make an m.room.member event for alice's join
+            const joinMshipEvent = utils.mkMembership({
+                mship: "join", user: userId, room: roomId, name: "Old Alice",
+                url: null,
+            });
+
+            // make an m.room.member event with prev_content for alice's nick
+            // change
+            const oldMshipEvent = utils.mkMembership({
+                mship: "join", user: userId, room: roomId, name: userName,
+                url: "mxc://some/url",
+            });
+            oldMshipEvent.prev_content = {
+                displayname: "Old Alice",
+                avatar_url: null,
+                membership: "join",
+            };
+
+            // set the list of events to return on scrollback (/messages)
+            // N.B. synapse returns /messages in reverse chronological order
+            sbEvents = [
+                utils.mkMessage({
+                    user: userId, room: roomId, msg: "I'm alice",
+                }),
+                oldMshipEvent,
+                utils.mkMessage({
+                    user: userId, room: roomId, msg: "I'm old alice",
+                }),
+                joinMshipEvent,
+            ];
+
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                // sync response
+                expect(room.timeline.length).toEqual(1);
+
+                client.scrollback(room).done(function() {
+                    expect(room.timeline.length).toEqual(5);
+                    const joinMsg = room.timeline[0];
+                    expect(joinMsg.sender.name).toEqual("Old Alice");
+                    const oldMsg = room.timeline[1];
+                    expect(oldMsg.sender.name).toEqual("Old Alice");
+                    const newMsg = room.timeline[3];
+                    expect(newMsg.sender.name).toEqual(userName);
+
+                    // still have a sync to flush
+                    httpBackend.flush("/sync", 1).then(() => {
+                        done();
+                    });
+                });
+
+                httpBackend.flush("/messages", 1);
+            });
+            httpBackend.flush("/sync", 1);
+        });
+
+        it("should add it them to the right place in the timeline", function(done) {
+            // set the list of events to return on scrollback
+            sbEvents = [
+                utils.mkMessage({
+                    user: userId, room: roomId, msg: "I am new",
+                }),
+                utils.mkMessage({
+                    user: userId, room: roomId, msg: "I am old",
+                }),
+            ];
+
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                expect(room.timeline.length).toEqual(1);
+
+                client.scrollback(room).done(function() {
+                    expect(room.timeline.length).toEqual(3);
+                    expect(room.timeline[0].event).toEqual(sbEvents[1]);
+                    expect(room.timeline[1].event).toEqual(sbEvents[0]);
+
+                    // still have a sync to flush
+                    httpBackend.flush("/sync", 1).then(() => {
+                        done();
+                    });
+                });
+
+                httpBackend.flush("/messages", 1);
+            });
+            httpBackend.flush("/sync", 1);
+        });
+
+        it("should use 'end' as the next pagination token", function(done) {
+            // set the list of events to return on scrollback
+            sbEvents = [
+                utils.mkMessage({
+                    user: userId, room: roomId, msg: "I am new",
+                }),
+            ];
+
+            client.on("sync", function(state) {
+                if (state !== "PREPARED") {
+                    return;
+                }
+                const room = client.getRoom(roomId);
+                expect(room.oldState.paginationToken).toBeTruthy();
+
+                client.scrollback(room, 1).done(function() {
+                    expect(room.oldState.paginationToken).toEqual(sbEndTok);
+                });
+
+                httpBackend.flush("/messages", 1).done(function() {
+                    // still have a sync to flush
+                    httpBackend.flush("/sync", 1).then(() => {
+                        done();
+                    });
+                });
+            });
+            httpBackend.flush("/sync", 1);
+        });
+    });
+
+    describe("new events", function() {
+        it("should be added to the right place in the timeline", function() {
+            const eventData = [
+                utils.mkMessage({user: userId, room: roomId}),
+                utils.mkMessage({user: userId, room: roomId}),
+            ];
+            setNextSyncData(eventData);
+
+            return Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]).then(() => {
+                const room = client.getRoom(roomId);
+
+                let index = 0;
+                client.on("Room.timeline", function(event, rm, toStart) {
+                    expect(toStart).toBe(false);
+                    expect(rm).toEqual(room);
+                    expect(event.event).toEqual(eventData[index]);
+                    index += 1;
+                });
+
+                httpBackend.flush("/messages", 1);
+                return Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    expect(index).toEqual(2);
+                    expect(room.timeline.length).toEqual(3);
+                    expect(room.timeline[2].event).toEqual(
+                        eventData[1],
+                    );
+                    expect(room.timeline[1].event).toEqual(
+                        eventData[0],
+                    );
+                });
+            });
+        });
+
+        it("should set the right event.sender values", function() {
+            const eventData = [
+                utils.mkMessage({user: userId, room: roomId}),
+                utils.mkMembership({
+                    user: userId, room: roomId, mship: "join", name: "New Name",
+                }),
+                utils.mkMessage({user: userId, room: roomId}),
+            ];
+            eventData[1].__prev_event = USER_MEMBERSHIP_EVENT;
+            setNextSyncData(eventData);
+
+            return Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]).then(() => {
+                const room = client.getRoom(roomId);
+                return Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    const preNameEvent = room.timeline[room.timeline.length - 3];
+                    const postNameEvent = room.timeline[room.timeline.length - 1];
+                    expect(preNameEvent.sender.name).toEqual(userName);
+                    expect(postNameEvent.sender.name).toEqual("New Name");
+                });
+            });
+        });
+
+        it("should set the right room.name", function() {
+            const secondRoomNameEvent = utils.mkEvent({
+                user: userId, room: roomId, type: "m.room.name", content: {
+                    name: "Room 2",
+                },
+            });
+            secondRoomNameEvent.__prev_event = ROOM_NAME_EVENT;
+            setNextSyncData([secondRoomNameEvent]);
+
+            return Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]).then(() => {
+                const room = client.getRoom(roomId);
+                let nameEmitCount = 0;
+                client.on("Room.name", function(rm) {
+                    nameEmitCount += 1;
+                });
+
+                return Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    expect(nameEmitCount).toEqual(1);
+                    expect(room.name).toEqual("Room 2");
+                    // do another round
+                    const thirdRoomNameEvent = utils.mkEvent({
+                        user: userId, room: roomId, type: "m.room.name", content: {
+                            name: "Room 3",
+                        },
+                    });
+                    thirdRoomNameEvent.__prev_event = secondRoomNameEvent;
+                    setNextSyncData([thirdRoomNameEvent]);
+                    httpBackend.when("GET", "/sync").respond(200, NEXT_SYNC_DATA);
+                    return Promise.all([
+                        httpBackend.flush("/sync", 1),
+                        utils.syncPromise(client),
+                    ]);
+                }).then(function() {
+                    expect(nameEmitCount).toEqual(2);
+                    expect(room.name).toEqual("Room 3");
+                });
+            });
+        });
+
+        it("should set the right room members", function() {
+            const userC = "@cee:bar";
+            const userD = "@dee:bar";
+            const eventData = [
+                utils.mkMembership({
+                    user: userC, room: roomId, mship: "join", name: "C",
+                }),
+                utils.mkMembership({
+                    user: userC, room: roomId, mship: "invite", skey: userD,
+                }),
+            ];
+            eventData[0].__prev_event = null;
+            eventData[1].__prev_event = null;
+            setNextSyncData(eventData);
+
+            return Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]).then(() => {
+                const room = client.getRoom(roomId);
+                return Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    expect(room.currentState.getMembers().length).toEqual(4);
+                    expect(room.currentState.getMember(userC).name).toEqual("C");
+                    expect(room.currentState.getMember(userC).membership).toEqual(
+                        "join",
+                    );
+                    expect(room.currentState.getMember(userD).name).toEqual(userD);
+                    expect(room.currentState.getMember(userD).membership).toEqual(
+                        "invite",
+                    );
+                });
+            });
+        });
+    });
+
+    describe("gappy sync", function() {
+        it("should copy the last known state to the new timeline", function() {
+            const eventData = [
+                utils.mkMessage({user: userId, room: roomId}),
+            ];
+            setNextSyncData(eventData);
+            NEXT_SYNC_DATA.rooms.join[roomId].timeline.limited = true;
+
+            return Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]).then(() => {
+                const room = client.getRoom(roomId);
+
+                httpBackend.flush("/messages", 1);
+                return Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    expect(room.timeline.length).toEqual(1);
+                    expect(room.timeline[0].event).toEqual(eventData[0]);
+                    expect(room.currentState.getMembers().length).toEqual(2);
+                    expect(room.currentState.getMember(userId).name).toEqual(userName);
+                    expect(room.currentState.getMember(userId).membership).toEqual(
+                        "join",
+                    );
+                    expect(room.currentState.getMember(otherUserId).name).toEqual("Bob");
+                    expect(room.currentState.getMember(otherUserId).membership).toEqual(
+                        "join",
+                    );
+                });
+            });
+        });
+
+        it("should emit a 'Room.timelineReset' event", function() {
+            const eventData = [
+                utils.mkMessage({user: userId, room: roomId}),
+            ];
+            setNextSyncData(eventData);
+            NEXT_SYNC_DATA.rooms.join[roomId].timeline.limited = true;
+
+            return Promise.all([
+                httpBackend.flush("/sync", 1),
+                utils.syncPromise(client),
+            ]).then(() => {
+                const room = client.getRoom(roomId);
+
+                let emitCount = 0;
+                client.on("Room.timelineReset", function(emitRoom) {
+                    expect(emitRoom).toEqual(room);
+                    emitCount++;
+                });
+
+                httpBackend.flush("/messages", 1);
+                return Promise.all([
+                    httpBackend.flush("/sync", 1),
+                    utils.syncPromise(client),
+                ]).then(function() {
+                    expect(emitCount).toEqual(1);
+                });
+            });
+        });
+    });
+});

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

@@ -0,0 +1,768 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const HttpBackend = require("matrix-mock-request");
+const utils = require("../test-utils");
+const MatrixEvent = sdk.MatrixEvent;
+const EventTimeline = sdk.EventTimeline;
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+describe("MatrixClient syncing", function() {
+    const baseUrl = "http://localhost.or.something";
+    let client = null;
+    let httpBackend = null;
+    const selfUserId = "@alice:localhost";
+    const selfAccessToken = "aseukfgwef";
+    const otherUserId = "@bob:localhost";
+    const userA = "@alice:bar";
+    const userB = "@bob:bar";
+    const userC = "@claire:bar";
+    const roomOne = "!foo:localhost";
+    const roomTwo = "!bar:localhost";
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new HttpBackend();
+        sdk.request(httpBackend.requestFn);
+        client = sdk.createClient({
+            baseUrl: baseUrl,
+            userId: selfUserId,
+            accessToken: selfAccessToken,
+        });
+        httpBackend.when("GET", "/pushrules").respond(200, {});
+        httpBackend.when("POST", "/filter").respond(200, { filter_id: "a filter id" });
+    });
+
+    afterEach(function() {
+        httpBackend.verifyNoOutstandingExpectation();
+        client.stopClient();
+        return httpBackend.stop();
+    });
+
+    describe("startClient", function() {
+        const syncData = {
+            next_batch: "batch_token",
+            rooms: {},
+            presence: {},
+        };
+
+        it("should /sync after /pushrules and /filter.", function(done) {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            client.startClient();
+
+            httpBackend.flushAllExpected().done(function() {
+                done();
+            });
+        });
+
+        it("should pass the 'next_batch' token from /sync to the since= param " +
+            " of the next /sync", function(done) {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/sync").check(function(req) {
+                expect(req.queryParams.since).toEqual(syncData.next_batch);
+            }).respond(200, syncData);
+
+            client.startClient();
+
+            httpBackend.flushAllExpected().done(function() {
+                done();
+            });
+        });
+    });
+
+    describe("resolving invites to profile info", function() {
+        const syncData = {
+            next_batch: "s_5_3",
+            presence: {
+                events: [],
+            },
+            rooms: {
+                join: {
+
+                },
+            },
+        };
+
+        beforeEach(function() {
+            syncData.presence.events = [];
+            syncData.rooms.join[roomOne] = {
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomOne, user: otherUserId, msg: "hello",
+                        }),
+                    ],
+                },
+                state: {
+                    events: [
+                        utils.mkMembership({
+                            room: roomOne, mship: "join", user: otherUserId,
+                        }),
+                        utils.mkMembership({
+                            room: roomOne, mship: "join", user: selfUserId,
+                        }),
+                        utils.mkEvent({
+                            type: "m.room.create", room: roomOne, user: selfUserId,
+                            content: {
+                                creator: selfUserId,
+                            },
+                        }),
+                    ],
+                },
+            };
+        });
+
+        it("should resolve incoming invites from /sync", function() {
+            syncData.rooms.join[roomOne].state.events.push(
+                utils.mkMembership({
+                    room: roomOne, mship: "invite", user: userC,
+                }),
+            );
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/profile/" + encodeURIComponent(userC)).respond(
+                200, {
+                    avatar_url: "mxc://flibble/wibble",
+                    displayname: "The Boss",
+                },
+            );
+
+            client.startClient({
+                resolveInvitesToProfiles: true,
+            });
+
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                const member = client.getRoom(roomOne).getMember(userC);
+                expect(member.name).toEqual("The Boss");
+                expect(
+                    member.getAvatarUrl("home.server.url", null, null, null, false),
+                ).toBeTruthy();
+            });
+        });
+
+        it("should use cached values from m.presence wherever possible", function() {
+            syncData.presence.events = [
+                utils.mkPresence({
+                    user: userC, presence: "online", name: "The Ghost",
+                }),
+            ];
+            syncData.rooms.join[roomOne].state.events.push(
+                utils.mkMembership({
+                    room: roomOne, mship: "invite", user: userC,
+                }),
+            );
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            client.startClient({
+                resolveInvitesToProfiles: true,
+            });
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                const member = client.getRoom(roomOne).getMember(userC);
+                expect(member.name).toEqual("The Ghost");
+            });
+        });
+
+        it("should result in events on the room member firing", function() {
+            syncData.presence.events = [
+                utils.mkPresence({
+                    user: userC, presence: "online", name: "The Ghost",
+                }),
+            ];
+            syncData.rooms.join[roomOne].state.events.push(
+                utils.mkMembership({
+                    room: roomOne, mship: "invite", user: userC,
+                }),
+            );
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            let latestFiredName = null;
+            client.on("RoomMember.name", function(event, m) {
+                if (m.userId === userC && m.roomId === roomOne) {
+                    latestFiredName = m.name;
+                }
+            });
+
+            client.startClient({
+                resolveInvitesToProfiles: true,
+            });
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                expect(latestFiredName).toEqual("The Ghost");
+            });
+        });
+
+        it("should no-op if resolveInvitesToProfiles is not set", function() {
+            syncData.rooms.join[roomOne].state.events.push(
+                utils.mkMembership({
+                    room: roomOne, mship: "invite", user: userC,
+                }),
+            );
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                const member = client.getRoom(roomOne).getMember(userC);
+                expect(member.name).toEqual(userC);
+                expect(
+                    member.getAvatarUrl("home.server.url", null, null, null, false),
+                ).toBe(null);
+            });
+        });
+    });
+
+    describe("users", function() {
+        const syncData = {
+            next_batch: "nb",
+            presence: {
+                events: [
+                    utils.mkPresence({
+                        user: userA, presence: "online",
+                    }),
+                    utils.mkPresence({
+                        user: userB, presence: "unavailable",
+                    }),
+                ],
+            },
+        };
+
+        it("should create users for presence events from /sync",
+        function() {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                expect(client.getUser(userA).presence).toEqual("online");
+                expect(client.getUser(userB).presence).toEqual("unavailable");
+            });
+        });
+    });
+
+    describe("room state", function() {
+        const msgText = "some text here";
+        const otherDisplayName = "Bob Smith";
+
+        const syncData = {
+            rooms: {
+                join: {
+
+                },
+            },
+        };
+        syncData.rooms.join[roomOne] = {
+            timeline: {
+                events: [
+                    utils.mkMessage({
+                        room: roomOne, user: otherUserId, msg: "hello",
+                    }),
+                ],
+            },
+            state: {
+                events: [
+                    utils.mkEvent({
+                        type: "m.room.name", room: roomOne, user: otherUserId,
+                        content: {
+                            name: "Old room name",
+                        },
+                    }),
+                    utils.mkMembership({
+                        room: roomOne, mship: "join", user: otherUserId,
+                    }),
+                    utils.mkMembership({
+                        room: roomOne, mship: "join", user: selfUserId,
+                    }),
+                    utils.mkEvent({
+                        type: "m.room.create", room: roomOne, user: selfUserId,
+                        content: {
+                            creator: selfUserId,
+                        },
+                    }),
+                ],
+            },
+        };
+        syncData.rooms.join[roomTwo] = {
+            timeline: {
+                events: [
+                    utils.mkMessage({
+                        room: roomTwo, user: otherUserId, msg: "hiii",
+                    }),
+                ],
+            },
+            state: {
+                events: [
+                    utils.mkMembership({
+                        room: roomTwo, mship: "join", user: otherUserId,
+                        name: otherDisplayName,
+                    }),
+                    utils.mkMembership({
+                        room: roomTwo, mship: "join", user: selfUserId,
+                    }),
+                    utils.mkEvent({
+                        type: "m.room.create", room: roomTwo, user: selfUserId,
+                        content: {
+                            creator: selfUserId,
+                        },
+                    }),
+                ],
+            },
+        };
+
+        const nextSyncData = {
+            rooms: {
+                join: {
+
+                },
+            },
+        };
+
+        nextSyncData.rooms.join[roomOne] = {
+            state: {
+                events: [
+                    utils.mkEvent({
+                        type: "m.room.name", room: roomOne, user: selfUserId,
+                        content: { name: "A new room name" },
+                    }),
+                ],
+            },
+        };
+
+        nextSyncData.rooms.join[roomTwo] = {
+            timeline: {
+                events: [
+                    utils.mkMessage({
+                        room: roomTwo, user: otherUserId, msg: msgText,
+                    }),
+                ],
+            },
+            ephemeral: {
+                events: [
+                    utils.mkEvent({
+                        type: "m.typing", room: roomTwo,
+                        content: { user_ids: [otherUserId] },
+                    }),
+                ],
+            },
+        };
+
+        it("should continually recalculate the right room name.", function() {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/sync").respond(200, nextSyncData);
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(2),
+            ]).then(function() {
+                const room = client.getRoom(roomOne);
+                // should have clobbered the name to the one from /events
+                expect(room.name).toEqual(
+                    nextSyncData.rooms.join[roomOne].state.events[0].content.name,
+                );
+            });
+        });
+
+        it("should store the right events in the timeline.", function() {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/sync").respond(200, nextSyncData);
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(2),
+            ]).then(function() {
+                const room = client.getRoom(roomTwo);
+                // should have added the message from /events
+                expect(room.timeline.length).toEqual(2);
+                expect(room.timeline[1].getContent().body).toEqual(msgText);
+            });
+        });
+
+        it("should set the right room name.", function() {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/sync").respond(200, nextSyncData);
+
+            client.startClient();
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(2),
+            ]).then(function() {
+                const room = client.getRoom(roomTwo);
+                // should use the display name of the other person.
+                expect(room.name).toEqual(otherDisplayName);
+            });
+        });
+
+        it("should set the right user's typing flag.", function() {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/sync").respond(200, nextSyncData);
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(2),
+            ]).then(function() {
+                const room = client.getRoom(roomTwo);
+                let member = room.getMember(otherUserId);
+                expect(member).toBeTruthy();
+                expect(member.typing).toEqual(true);
+                member = room.getMember(selfUserId);
+                expect(member).toBeTruthy();
+                expect(member.typing).toEqual(false);
+            });
+        });
+
+        // XXX: This test asserts that the js-sdk obeys the spec and treats state
+        // events that arrive in the incremental sync as if they preceeded the
+        // timeline events, however this breaks peeking, so it's disabled
+        // (see sync.js)
+        xit("should correctly interpret state in incremental sync.", function() {
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+            httpBackend.when("GET", "/sync").respond(200, nextSyncData);
+
+            client.startClient();
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(2),
+            ]).then(function() {
+                const room = client.getRoom(roomOne);
+                const stateAtStart = room.getLiveTimeline().getState(
+                    EventTimeline.BACKWARDS,
+                );
+                const startRoomNameEvent = stateAtStart.getStateEvents('m.room.name', '');
+                expect(startRoomNameEvent.getContent().name).toEqual('Old room name');
+
+                const stateAtEnd = room.getLiveTimeline().getState(
+                    EventTimeline.FORWARDS,
+                );
+                const endRoomNameEvent = stateAtEnd.getStateEvents('m.room.name', '');
+                expect(endRoomNameEvent.getContent().name).toEqual('A new room name');
+            });
+        });
+
+        xit("should update power levels for users in a room", function() {
+
+        });
+
+        xit("should update the room topic", function() {
+
+        });
+    });
+
+    describe("timeline", function() {
+        beforeEach(function() {
+            const syncData = {
+                next_batch: "batch_token",
+                rooms: {
+                    join: {},
+                },
+            };
+            syncData.rooms.join[roomOne] = {
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomOne, user: otherUserId, msg: "hello",
+                        }),
+                    ],
+                    prev_batch: "pagTok",
+                },
+            };
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            client.startClient();
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]);
+        });
+
+        it("should set the back-pagination token on new rooms", function() {
+            const syncData = {
+                next_batch: "batch_token",
+                rooms: {
+                    join: {},
+                },
+            };
+            syncData.rooms.join[roomTwo] = {
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomTwo, user: otherUserId, msg: "roomtwo",
+                        }),
+                    ],
+                    prev_batch: "roomtwotok",
+                },
+            };
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                const room = client.getRoom(roomTwo);
+                expect(room).toExist();
+                const tok = room.getLiveTimeline()
+                    .getPaginationToken(EventTimeline.BACKWARDS);
+                expect(tok).toEqual("roomtwotok");
+            });
+        });
+
+        it("should set the back-pagination token on gappy syncs", function() {
+            const syncData = {
+                next_batch: "batch_token",
+                rooms: {
+                    join: {},
+                },
+            };
+            syncData.rooms.join[roomOne] = {
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomOne, user: otherUserId, msg: "world",
+                        }),
+                    ],
+                    limited: true,
+                    prev_batch: "newerTok",
+                },
+            };
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            let resetCallCount = 0;
+            // the token should be set *before* timelineReset is emitted
+            client.on("Room.timelineReset", function(room) {
+                resetCallCount++;
+
+                const tl = room.getLiveTimeline();
+                expect(tl.getEvents().length).toEqual(0);
+                const tok = tl.getPaginationToken(EventTimeline.BACKWARDS);
+                expect(tok).toEqual("newerTok");
+            });
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                const room = client.getRoom(roomOne);
+                const tl = room.getLiveTimeline();
+                expect(tl.getEvents().length).toEqual(1);
+                expect(resetCallCount).toEqual(1);
+            });
+        });
+    });
+
+    describe("receipts", function() {
+        const syncData = {
+            rooms: {
+                join: {
+
+                },
+            },
+        };
+        syncData.rooms.join[roomOne] = {
+            timeline: {
+                events: [
+                    utils.mkMessage({
+                        room: roomOne, user: otherUserId, msg: "hello",
+                    }),
+                    utils.mkMessage({
+                        room: roomOne, user: otherUserId, msg: "world",
+                    }),
+                ],
+            },
+            state: {
+                events: [
+                    utils.mkEvent({
+                        type: "m.room.name", room: roomOne, user: otherUserId,
+                        content: {
+                            name: "Old room name",
+                        },
+                    }),
+                    utils.mkMembership({
+                        room: roomOne, mship: "join", user: otherUserId,
+                    }),
+                    utils.mkMembership({
+                        room: roomOne, mship: "join", user: selfUserId,
+                    }),
+                    utils.mkEvent({
+                        type: "m.room.create", room: roomOne, user: selfUserId,
+                        content: {
+                            creator: selfUserId,
+                        },
+                    }),
+                ],
+            },
+        };
+
+        beforeEach(function() {
+            syncData.rooms.join[roomOne].ephemeral = {
+                events: [],
+            };
+        });
+
+        it("should sync receipts from /sync.", function() {
+            const ackEvent = syncData.rooms.join[roomOne].timeline.events[0];
+            const receipt = {};
+            receipt[ackEvent.event_id] = {
+                "m.read": {},
+            };
+            receipt[ackEvent.event_id]["m.read"][userC] = {
+                ts: 176592842636,
+            };
+            syncData.rooms.join[roomOne].ephemeral.events = [{
+                content: receipt,
+                room_id: roomOne,
+                type: "m.receipt",
+            }];
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            client.startClient();
+
+            return Promise.all([
+                httpBackend.flushAllExpected(),
+                awaitSyncEvent(),
+            ]).then(function() {
+                const room = client.getRoom(roomOne);
+                expect(room.getReceiptsForEvent(new MatrixEvent(ackEvent))).toEqual([{
+                    type: "m.read",
+                    userId: userC,
+                    data: {
+                        ts: 176592842636,
+                    },
+                }]);
+            });
+        });
+    });
+
+    describe("of a room", function() {
+        xit("should sync when a join event (which changes state) for the user" +
+        " arrives down the event stream (e.g. join from another device)", function() {
+
+        });
+
+        xit("should sync when the user explicitly calls joinRoom", function() {
+
+        });
+    });
+
+    describe("syncLeftRooms", function() {
+        beforeEach(function(done) {
+            client.startClient();
+
+            httpBackend.flushAllExpected().then(function() {
+                // the /sync call from syncLeftRooms ends up in the request
+                // queue behind the call from the running client; add a response
+                // to flush the client's one out.
+                httpBackend.when("GET", "/sync").respond(200, {});
+
+                done();
+            });
+        });
+
+        it("should create and use an appropriate filter", function() {
+            httpBackend.when("POST", "/filter").check(function(req) {
+                expect(req.data).toEqual({
+                    room: { timeline: {limit: 1},
+                            include_leave: true }});
+            }).respond(200, { filter_id: "another_id" });
+
+            const defer = Promise.defer();
+
+            httpBackend.when("GET", "/sync").check(function(req) {
+                expect(req.queryParams.filter).toEqual("another_id");
+                defer.resolve();
+            }).respond(200, {});
+
+            client.syncLeftRooms();
+
+            // first flush the filter request; this will make syncLeftRooms
+            // make its /sync call
+            return Promise.all([
+                httpBackend.flush("/filter").then(function() {
+                    // flush the syncs
+                    return httpBackend.flushAllExpected();
+                }),
+                defer.promise,
+            ]);
+        });
+
+        it("should set the back-pagination token on left rooms", function() {
+            const syncData = {
+                next_batch: "batch_token",
+                rooms: {
+                    leave: {},
+                },
+            };
+
+            syncData.rooms.leave[roomTwo] = {
+                timeline: {
+                    events: [
+                        utils.mkMessage({
+                            room: roomTwo, user: otherUserId, msg: "hello",
+                        }),
+                    ],
+                    prev_batch: "pagTok",
+                },
+            };
+
+            httpBackend.when("POST", "/filter").respond(200, {
+                filter_id: "another_id",
+            });
+
+            httpBackend.when("GET", "/sync").respond(200, syncData);
+
+            return Promise.all([
+                client.syncLeftRooms().then(function() {
+                    const room = client.getRoom(roomTwo);
+                    const tok = room.getLiveTimeline().getPaginationToken(
+                        EventTimeline.BACKWARDS);
+
+                    expect(tok).toEqual("pagTok");
+                }),
+
+                // first flush the filter request; this will make syncLeftRooms
+                // make its /sync call
+                httpBackend.flush("/filter").then(function() {
+                    return httpBackend.flushAllExpected();
+                }),
+            ]);
+        });
+    });
+
+    /**
+     * waits for the MatrixClient to emit one or more 'sync' events.
+     *
+     * @param {Number?} numSyncs number of syncs to wait for
+     * @returns {Promise} promise which resolves after the sync events have happened
+     */
+    function awaitSyncEvent(numSyncs) {
+        return utils.syncPromise(client, numSyncs);
+    }
+});

spec/integ/matrix-client.spec.js

@@ -1,438 +0,0 @@
-"use strict";
-var sdk = require("../..");
-var HttpBackend = require("../mock-request");
-var utils = require("../test-utils");
-
-describe("MatrixClient", function() {
-    var baseUrl = "http://localhost.or.something";
-    var client, httpBackend;
-    var selfUserId = "@alice:localhost";
-    var selfAccessToken = "aseukfgwef";
-    var otherUserId = "@bob:localhost";
-
-    beforeEach(function() {
-        utils.beforeEach(this);
-        httpBackend = new HttpBackend();
-        sdk.request(httpBackend.requestFn);
-        client = sdk.createClient({
-            baseUrl: baseUrl,
-            userId: selfUserId,
-            accessToken: selfAccessToken
-        });
-    });
-
-    afterEach(function() {
-        httpBackend.verifyNoOutstandingExpectation();
-    });
-
-    describe("startClient", function() {
-        var initialSync = {
-            end: "s_5_3",
-            presence: [],
-            rooms: []
-        };
-        var eventData = {
-            start: "s_5_3",
-            end: "e_6_7",
-            chunk: []
-        };
-
-        it("should start with /initialSync then move onto /events.", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                done();
-            });
-        });
-
-        it("should pass the 'end' token from /initialSync to the from= param " +
-            " of /events", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").check(function(req) {
-                expect(req.queryParams.from).toEqual(initialSync.end);
-            }).respond(200, eventData);
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                done();
-            });
-        });
-    });
-
-    describe("EventEmitter", function() {
-        var initialSync = {
-            end: "s_5_3",
-            presence: [{
-                event_id: "$wefiuewh:bar",
-                type: "m.presence",
-                content: {
-                    user_id: "@foo:bar",
-                    displayname: "Foo Bar",
-                    presence: "online"
-                }
-            }],
-            rooms: [{
-                room_id: "!erufh:bar",
-                membership: "join",
-                messages: {
-                    start: "s",
-                    end: "t",
-                    chunk: [
-                        utils.mkMessage("!erufh:bar", "@foo:bar", "hmmm")
-                    ]
-                },
-                state: [
-                    utils.mkMembership("!erufh:bar", "join", "@foo:bar"),
-                    utils.mkEvent("m.room.create", "!erufh:bar", "@foo:bar", {
-                        creator: "@foo:bar"
-                    })
-                ]
-            }]
-        };
-        var eventData = {
-            start: "s_5_3",
-            end: "e_6_7",
-            chunk: [
-                utils.mkMessage("!erufh:bar", "@foo:bar", "ello ello"),
-                utils.mkMessage("!erufh:bar", "@foo:bar", ":D"),
-                utils.mkEvent("m.typing", "!erufh:bar", "bar", {
-                    user_ids: ["@foo:bar"]
-                })
-            ]
-        };
-
-        it("should emit events from both /initialSync and /events", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            // initial sync events are unordered, so make an array of the types
-            // that should be emitted and we'll just pick them off one by one,
-            // so long as this is emptied we're good.
-            var initialSyncEventTypes = [
-                "m.presence", "m.room.member", "m.room.message", "m.room.create"
-            ];
-            var chunkIndex = 0;
-            client.on("event", function(event) {
-                if (initialSyncEventTypes.length === 0) {
-                    if (chunkIndex + 1 >= eventData.chunk.length) {
-                        return;
-                    }
-                    // this should be /events now
-                    expect(eventData.chunk[chunkIndex].event_id).toEqual(
-                        event.getId()
-                    );
-                    chunkIndex++;
-                    return;
-                }
-                var index = initialSyncEventTypes.indexOf(event.getType());
-                expect(index).not.toEqual(
-                    -1, "Unexpected event type: " + event.getType()
-                );
-                if (index >= 0) {
-                    initialSyncEventTypes.splice(index, 1);
-                }
-            });
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                expect(initialSyncEventTypes.length).toEqual(
-                    0, "Failed to see all events from /initialSync"
-                );
-                expect(chunkIndex + 1).toEqual(
-                    eventData.chunk.length, "Failed to see all events from /events"
-                );
-                done();
-            });
-        });
-
-        it("should emit User events", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-            var fired = false;
-            client.on("User.presence", function(event, user) {
-                fired = true;
-                expect(user).toBeDefined();
-                expect(event).toBeDefined();
-                if (!user || !event) { return; }
-
-                expect(event.event).toEqual(initialSync.presence[0]);
-                expect(user.presence).toEqual(
-                    initialSync.presence[0].content.presence
-                );
-            });
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                expect(fired).toBe(true, "User.presence didn't fire.");
-                done();
-            });
-        });
-
-        it("should emit Room events", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-            var roomInvokeCount = 0;
-            var roomNameInvokeCount = 0;
-            var timelineFireCount = 0;
-            client.on("Room", function(room) {
-                roomInvokeCount++;
-                expect(room.roomId).toEqual("!erufh:bar");
-            });
-            client.on("Room.timeline", function(event, room) {
-                timelineFireCount++;
-                expect(room.roomId).toEqual("!erufh:bar");
-            });
-            client.on("Room.name", function(room) {
-                roomNameInvokeCount++;
-            });
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                expect(roomInvokeCount).toEqual(
-                    1, "Room fired wrong number of times."
-                );
-                expect(roomNameInvokeCount).toEqual(
-                    1, "Room.name fired wrong number of times."
-                );
-                expect(timelineFireCount).toEqual(
-                    3, "Room.timeline fired the wrong number of times"
-                );
-                done();
-            });
-        });
-
-        it("should emit RoomState events", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            var roomStateEventTypes = [
-                "m.room.member", "m.room.create"
-            ];
-            var eventsInvokeCount = 0;
-            var membersInvokeCount = 0;
-            var newMemberInvokeCount = 0;
-            client.on("RoomState.events", function(event, state) {
-                eventsInvokeCount++;
-                var index = roomStateEventTypes.indexOf(event.getType());
-                expect(index).not.toEqual(
-                    -1, "Unexpected room state event type: " + event.getType()
-                );
-                if (index >= 0) {
-                    roomStateEventTypes.splice(index, 1);
-                }
-            });
-            client.on("RoomState.members", function(event, state, member) {
-                membersInvokeCount++;
-                expect(member.roomId).toEqual("!erufh:bar");
-                expect(member.userId).toEqual("@foo:bar");
-                expect(member.membership).toEqual("join");
-            });
-            client.on("RoomState.newMember", function(event, state, member) {
-                newMemberInvokeCount++;
-                expect(member.roomId).toEqual("!erufh:bar");
-                expect(member.userId).toEqual("@foo:bar");
-                expect(member.membership).toBeFalsy();
-            });
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                expect(membersInvokeCount).toEqual(
-                    1, "RoomState.members fired wrong number of times"
-                );
-                expect(newMemberInvokeCount).toEqual(
-                    1, "RoomState.newMember fired wrong number of times"
-                );
-                expect(eventsInvokeCount).toEqual(
-                    2, "RoomState.events fired wrong number of times"
-                );
-                done();
-            });
-        });
-
-        it("should emit RoomMember events", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            var typingInvokeCount = 0;
-            var powerLevelInvokeCount = 0;
-            var nameInvokeCount = 0;
-            var membershipInvokeCount = 0;
-            client.on("RoomMember.name", function(event, member) {
-                nameInvokeCount++;
-            });
-            client.on("RoomMember.typing", function(event, member) {
-                typingInvokeCount++;
-                expect(member.typing).toBe(true);
-            });
-            client.on("RoomMember.powerLevel", function(event, member) {
-                powerLevelInvokeCount++;
-            });
-            client.on("RoomMember.membership", function(event, member) {
-                membershipInvokeCount++;
-                expect(member.membership).toEqual("join");
-            });
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                expect(typingInvokeCount).toEqual(
-                    1, "RoomMember.typing fired wrong number of times"
-                );
-                expect(powerLevelInvokeCount).toEqual(
-                    0, "RoomMember.powerLevel fired wrong number of times"
-                );
-                expect(nameInvokeCount).toEqual(
-                    0, "RoomMember.name fired wrong number of times"
-                );
-                expect(membershipInvokeCount).toEqual(
-                    1, "RoomMember.membership fired wrong number of times"
-                );
-                done();
-            });
-        });
-    });
-
-    describe("room state", function() {
-        var roomOne = "!foo:localhost";
-        var roomTwo = "!bar:localhost";
-        var msgText = "some text here";
-        var otherDisplayName = "Bob Smith";
-        var initialSync = {
-            end: "s_5_3",
-            presence: [],
-            rooms: [
-                {
-                    membership: "join",
-                    room_id: roomOne,
-                    messages: {
-                        start: "f_1_1",
-                        end: "f_2_2",
-                        chunk: [
-                            utils.mkMessage(roomOne, otherUserId, "hello")
-                        ]
-                    },
-                    state: [
-                        utils.mkEvent(
-                            "m.room.name", roomOne, otherUserId,
-                            {
-                                name: "Old room name"
-                            }
-                        ),
-                        utils.mkMembership(roomOne, "join", otherUserId),
-                        utils.mkMembership(roomOne, "join", selfUserId),
-                        utils.mkEvent(
-                            "m.room.create", roomOne, selfUserId,
-                            {
-                                creator: selfUserId
-                            }
-                        )
-                    ]
-                },
-                {
-                    membership: "join",
-                    room_id: roomTwo,
-                    messages: {
-                        start: "f_1_1",
-                        end: "f_2_2",
-                        chunk: [
-                            utils.mkMessage(roomTwo, otherUserId, "hiii")
-                        ]
-                    },
-                    state: [
-                        utils.mkMembership(
-                            roomTwo, "join", otherUserId, null, otherDisplayName
-                        ),
-                        utils.mkMembership(roomTwo, "join", selfUserId),
-                        utils.mkEvent(
-                            "m.room.create", roomTwo, selfUserId,
-                            {
-                                creator: selfUserId
-                            }
-                        )
-                    ]
-                }
-            ]
-        };
-        var eventData = {
-            start: "s_5_3",
-            end: "e_6_7",
-            chunk: [
-                utils.mkEvent("m.room.name", roomOne, selfUserId, {
-                    name: "A new room name"
-                }),
-                utils.mkMessage(roomTwo, otherUserId, msgText),
-                utils.mkEvent("m.typing", roomTwo, undefined, {
-                    user_ids: [otherUserId]
-                })
-            ]
-        };
-
-        it("should continually recalculate the right room name.", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                var room = client.getRoom(roomOne);
-                // should have clobbered the name to the one from /events
-                expect(room.name).toEqual(eventData.chunk[0].content.name);
-                done();
-            });
-        });
-
-        it("should store the right events in the timeline.", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                var room = client.getRoom(roomTwo);
-                // should have added the message from /events
-                expect(room.timeline.length).toEqual(2);
-                expect(room.timeline[1].getContent().body).toEqual(msgText);
-                done();
-            });
-        });
-
-        it("should set the right room name.", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            client.startClient();
-            httpBackend.flush().done(function() {
-                var room = client.getRoom(roomTwo);
-                // should use the display name of the other person.
-                expect(room.name).toEqual(otherDisplayName);
-                done();
-            });
-        });
-
-        it("should set the right user's typing flag.", function(done) {
-            httpBackend.when("GET", "/initialSync").respond(200, initialSync);
-            httpBackend.when("GET", "/events").respond(200, eventData);
-
-            client.startClient();
-
-            httpBackend.flush().done(function() {
-                var room = client.getRoom(roomTwo);
-                var member = room.getMember(otherUserId);
-                expect(member).toBeDefined();
-                expect(member.typing).toEqual(true);
-                member = room.getMember(selfUserId);
-                expect(member).toBeDefined();
-                expect(member.typing).toEqual(false);
-                done();
-            });
-        });
-    });
-
-});

spec/integ/megolm-integ.spec.js

@@ -0,0 +1,974 @@
+/*
+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.
+*/
+
+"use strict";
+
+const anotherjson = require('another-json');
+import Promise from 'bluebird';
+import expect from 'expect';
+
+const utils = require('../../lib/utils');
+const testUtils = require('../test-utils');
+const TestClient = require('../TestClient').default;
+import logger from '../../src/logger';
+
+const ROOM_ID = "!room:id";
+
+/**
+ * start an Olm session with a given recipient
+ *
+ * @param {Olm.Account} olmAccount
+ * @param {TestClient} recipientTestClient
+ * @return {Promise} promise for Olm.Session
+ */
+function createOlmSession(olmAccount, recipientTestClient) {
+    return recipientTestClient.awaitOneTimeKeyUpload().then((keys) => {
+        const otkId = utils.keys(keys)[0];
+        const otk = keys[otkId];
+
+        const session = new global.Olm.Session();
+        session.create_outbound(
+            olmAccount, recipientTestClient.getDeviceKey(), otk.key,
+        );
+        return session;
+    });
+}
+
+/**
+ * encrypt an event with olm
+ *
+ * @param {object} opts
+ * @param {string=} opts.sender
+ * @param {string} opts.senderKey
+ * @param {Olm.Session} opts.p2pSession
+ * @param {TestClient} opts.recipient
+ * @param {object=} opts.plaincontent
+ * @param {string=} opts.plaintype
+ *
+ * @return {object} event
+ */
+function encryptOlmEvent(opts) {
+    expect(opts.senderKey).toBeTruthy();
+    expect(opts.p2pSession).toBeTruthy();
+    expect(opts.recipient).toBeTruthy();
+
+    const plaintext = {
+        content: opts.plaincontent || {},
+        recipient: opts.recipient.userId,
+        recipient_keys: {
+            ed25519: opts.recipient.getSigningKey(),
+        },
+        sender: opts.sender || '@bob:xyz',
+        type: opts.plaintype || 'm.test',
+    };
+
+    const event = {
+        content: {
+            algorithm: 'm.olm.v1.curve25519-aes-sha2',
+            ciphertext: {},
+            sender_key: opts.senderKey,
+        },
+        sender: opts.sender || '@bob:xyz',
+        type: 'm.room.encrypted',
+    };
+    event.content.ciphertext[opts.recipient.getDeviceKey()] =
+        opts.p2pSession.encrypt(JSON.stringify(plaintext));
+    return event;
+}
+
+/**
+ * encrypt an event with megolm
+ *
+ * @param {object} opts
+ * @param {string} opts.senderKey
+ * @param {Olm.OutboundGroupSession} opts.groupSession
+ * @param {object=} opts.plaintext
+ * @param {string=} opts.room_id
+ *
+ * @return {object} event
+ */
+function encryptMegolmEvent(opts) {
+    expect(opts.senderKey).toBeTruthy();
+    expect(opts.groupSession).toBeTruthy();
+
+    const plaintext = opts.plaintext || {};
+    if (!plaintext.content) {
+        plaintext.content = {
+            body: '42',
+            msgtype: "m.text",
+        };
+    }
+    if (!plaintext.type) {
+        plaintext.type = "m.room.message";
+    }
+    if (!plaintext.room_id) {
+        expect(opts.room_id).toBeTruthy();
+        plaintext.room_id = opts.room_id;
+    }
+
+    return {
+        event_id: 'test_megolm_event',
+        content: {
+            algorithm: "m.megolm.v1.aes-sha2",
+            ciphertext: opts.groupSession.encrypt(JSON.stringify(plaintext)),
+            device_id: "testDevice",
+            sender_key: opts.senderKey,
+            session_id: opts.groupSession.session_id(),
+        },
+        type: "m.room.encrypted",
+    };
+}
+
+/**
+ * build an encrypted room_key event to share a group session
+ *
+ * @param {object} opts
+ * @param {string} opts.senderKey
+ * @param {TestClient} opts.recipient
+ * @param {Olm.Session} opts.p2pSession
+ * @param {Olm.OutboundGroupSession} opts.groupSession
+ * @param {string=} opts.room_id
+ *
+ * @return {object} event
+ */
+function encryptGroupSessionKey(opts) {
+    return encryptOlmEvent({
+        senderKey: opts.senderKey,
+        recipient: opts.recipient,
+        p2pSession: opts.p2pSession,
+        plaincontent: {
+            algorithm: 'm.megolm.v1.aes-sha2',
+            room_id: opts.room_id,
+            session_id: opts.groupSession.session_id(),
+            session_key: opts.groupSession.session_key(),
+        },
+        plaintype: 'm.room_key',
+    });
+}
+
+/**
+ * get a /sync response which contains a single room (ROOM_ID),
+ * with the members given
+ *
+ * @param {string[]} roomMembers
+ *
+ * @return {object} event
+ */
+function getSyncResponse(roomMembers) {
+    const roomResponse = {
+        state: {
+            events: [
+                testUtils.mkEvent({
+                    type: 'm.room.encryption',
+                    skey: '',
+                    content: {
+                        algorithm: 'm.megolm.v1.aes-sha2',
+                    },
+                }),
+            ],
+        },
+    };
+
+    for (let i = 0; i < roomMembers.length; i++) {
+        roomResponse.state.events.push(
+            testUtils.mkMembership({
+                mship: 'join',
+                sender: roomMembers[i],
+            }),
+        );
+    }
+
+    const syncResponse = {
+        next_batch: 1,
+        rooms: {
+            join: {},
+        },
+    };
+    syncResponse.rooms.join[ROOM_ID] = roomResponse;
+    return syncResponse;
+}
+
+
+describe("megolm", function() {
+    if (!global.Olm) {
+        logger.warn('not running megolm tests: Olm not present');
+        return;
+    }
+    const Olm = global.Olm;
+
+    let testOlmAccount;
+    let testSenderKey;
+    let aliceTestClient;
+
+    /**
+     * Get the device keys for testOlmAccount in a format suitable for a
+     * response to /keys/query
+     *
+     * @param {string} userId The user ID to query for
+     * @returns {Object} The fake query response
+     */
+    function getTestKeysQueryResponse(userId) {
+        const testE2eKeys = JSON.parse(testOlmAccount.identity_keys());
+        const testDeviceKeys = {
+            algorithms: ['m.olm.v1.curve25519-aes-sha2', 'm.megolm.v1.aes-sha2'],
+            device_id: 'DEVICE_ID',
+            keys: {
+                'curve25519:DEVICE_ID': testE2eKeys.curve25519,
+                'ed25519:DEVICE_ID': testE2eKeys.ed25519,
+            },
+            user_id: userId,
+        };
+        const j = anotherjson.stringify(testDeviceKeys);
+        const sig = testOlmAccount.sign(j);
+        testDeviceKeys.signatures = {};
+        testDeviceKeys.signatures[userId] = {
+            'ed25519:DEVICE_ID': sig,
+        };
+
+        const queryResponse = {
+            device_keys: {},
+        };
+
+        queryResponse.device_keys[userId] = {
+            'DEVICE_ID': testDeviceKeys,
+        };
+
+        return queryResponse;
+    }
+
+    /**
+     * Get a one-time key for testOlmAccount in a format suitable for a
+     * response to /keys/claim
+
+     * @param {string} userId The user ID to query for
+     * @returns {Object} The fake key claim response
+     */
+    function getTestKeysClaimResponse(userId) {
+        testOlmAccount.generate_one_time_keys(1);
+        const testOneTimeKeys = JSON.parse(testOlmAccount.one_time_keys());
+        testOlmAccount.mark_keys_as_published();
+
+        const keyId = utils.keys(testOneTimeKeys.curve25519)[0];
+        const oneTimeKey = testOneTimeKeys.curve25519[keyId];
+        const keyResult = {
+            'key': oneTimeKey,
+        };
+        const j = anotherjson.stringify(keyResult);
+        const sig = testOlmAccount.sign(j);
+        keyResult.signatures = {};
+        keyResult.signatures[userId] = {
+            'ed25519:DEVICE_ID': sig,
+        };
+
+        const claimResponse = {one_time_keys: {}};
+        claimResponse.one_time_keys[userId] = {
+            'DEVICE_ID': {},
+        };
+        claimResponse.one_time_keys[userId].DEVICE_ID['signed_curve25519:' + keyId] =
+            keyResult;
+        return claimResponse;
+    }
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        aliceTestClient = new TestClient(
+            "@alice:localhost", "xzcvb", "akjgkrgjs",
+        );
+        await aliceTestClient.client.initCrypto();
+
+        testOlmAccount = new Olm.Account();
+        testOlmAccount.create();
+        const testE2eKeys = JSON.parse(testOlmAccount.identity_keys());
+        testSenderKey = testE2eKeys.curve25519;
+    });
+
+    afterEach(function() {
+        return aliceTestClient.stop();
+    });
+
+    it("Alice receives a megolm message", 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,
+            });
+
+            // encrypt a message with the group session
+            const messageEncrypted = encryptMegolmEvent({
+                senderKey: testSenderKey,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // 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.getContent().body).toEqual('42');
+        });
+    });
+
+    it("Alice receives a megolm message before the session keys", function() {
+        // https://github.com/vector-im/riot-web/issues/2273
+        let roomKeyEncrypted;
+
+        return aliceTestClient.start().then(() => {
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((p2pSession) => {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+
+            // make the room_key event, but don't send it yet
+            roomKeyEncrypted = encryptGroupSessionKey({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // encrypt a message with the group session
+            const messageEncrypted = encryptMegolmEvent({
+                senderKey: testSenderKey,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // Alice just gets the message event to start with
+            const syncResponse = {
+                next_batch: 1,
+                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.getContent().msgtype).toEqual('m.bad.encrypted');
+
+            // now she gets the room_key event
+            const syncResponse = {
+                next_batch: 2,
+                to_device: {
+                    events: [roomKeyEncrypted],
+                },
+            };
+
+            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];
+
+            if (event.getContent().msgtype != 'm.bad.encrypted') {
+                return event;
+            }
+
+            return new Promise((resolve, reject) => {
+                event.once('Event.decrypted', (ev) => {
+                    logger.log(`${Date.now()} event ${event.getId()} now decrypted`);
+                    resolve(ev);
+                });
+            });
+        }).then((event) => {
+            expect(event.getContent().body).toEqual('42');
+        });
+    });
+
+    it("Alice gets a second room_key message", function() {
+        return aliceTestClient.start().then(() => {
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((p2pSession) => {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+
+            // make the room_key event
+            const roomKeyEncrypted1 = encryptGroupSessionKey({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // encrypt a message with the group session
+            const messageEncrypted = encryptMegolmEvent({
+                senderKey: testSenderKey,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // make a second room_key event now that we have advanced the group
+            // session.
+            const roomKeyEncrypted2 = encryptGroupSessionKey({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // on the first sync, send the best room key
+            aliceTestClient.httpBackend.when("GET", "/sync").respond(200, {
+                next_batch: 1,
+                to_device: {
+                    events: [roomKeyEncrypted1],
+                },
+            });
+
+            // on the second sync, send the advanced room key, along with the
+            // message.  This simulates the situation where Alice has been sent a
+            // later copy of the room key and is reloading the client.
+            const syncResponse2 = {
+                next_batch: 2,
+                to_device: {
+                    events: [roomKeyEncrypted2],
+                },
+                rooms: {
+                    join: {},
+                },
+            };
+            syncResponse2.rooms.join[ROOM_ID] = {
+                timeline: {
+                    events: [messageEncrypted],
+                },
+            };
+            aliceTestClient.httpBackend.when("GET", "/sync").respond(200, syncResponse2);
+
+            // flush both syncs
+            return aliceTestClient.flushSync().then(() => {
+                return aliceTestClient.flushSync();
+            });
+        }).then(function() {
+            const room = aliceTestClient.client.getRoom(ROOM_ID);
+            const event = room.getLiveTimeline().getEvents()[0];
+            expect(event.getContent().body).toEqual('42');
+        });
+    });
+
+    it('Alice sends a megolm message', function() {
+        let p2pSession;
+
+        aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+        return aliceTestClient.start().then(() => {
+            // establish an olm session with alice
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((_p2pSession) => {
+            p2pSession = _p2pSession;
+
+            const syncResponse = getSyncResponse(['@bob:xyz']);
+
+            const olmEvent = encryptOlmEvent({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+            });
+
+            syncResponse.to_device = { events: [olmEvent] };
+
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(200, syncResponse);
+            return aliceTestClient.flushSync();
+        }).then(function() {
+            // start out with the device unknown - the send should be rejected.
+            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
+                200, getTestKeysQueryResponse('@bob:xyz'),
+            );
+
+            return Promise.all([
+                aliceTestClient.client.sendTextMessage(ROOM_ID, 'test').then(() => {
+                    throw new Error("sendTextMessage failed on an unknown device");
+                }, (e) => {
+                    expect(e.name).toEqual("UnknownDeviceError");
+                }),
+                aliceTestClient.httpBackend.flushAllExpected(),
+            ]);
+        }).then(function() {
+            // mark the device as known, and resend.
+            aliceTestClient.client.setDeviceKnown('@bob:xyz', 'DEVICE_ID');
+
+            let inboundGroupSession;
+            aliceTestClient.httpBackend.when(
+                'PUT', '/sendToDevice/m.room.encrypted/',
+            ).respond(200, function(path, content) {
+                const m = content.messages['@bob:xyz'].DEVICE_ID;
+                const ct = m.ciphertext[testSenderKey];
+                const decrypted = JSON.parse(p2pSession.decrypt(ct.type, ct.body));
+
+                expect(decrypted.type).toEqual('m.room_key');
+                inboundGroupSession = new Olm.InboundGroupSession();
+                inboundGroupSession.create(decrypted.content.session_key);
+                return {};
+            });
+
+            aliceTestClient.httpBackend.when(
+                'PUT', '/send/',
+            ).respond(200, function(path, content) {
+                const ct = content.ciphertext;
+                const r = inboundGroupSession.decrypt(ct);
+                logger.log('Decrypted received megolm message', r);
+
+                expect(r.message_index).toEqual(0);
+                const decrypted = JSON.parse(r.plaintext);
+                expect(decrypted.type).toEqual('m.room.message');
+                expect(decrypted.content.body).toEqual('test');
+
+                return {
+                    event_id: '$event_id',
+                };
+            });
+
+            const room = aliceTestClient.client.getRoom(ROOM_ID);
+            const pendingMsg = room.getPendingEvents()[0];
+
+            return Promise.all([
+                aliceTestClient.client.resendEvent(pendingMsg, room),
+
+                // the crypto stuff can take a while, so give the requests a whole second.
+                aliceTestClient.httpBackend.flushAllExpected({
+                    timeout: 1000,
+                }),
+            ]);
+        });
+    });
+
+    it("We shouldn't attempt to send to blocked devices", function() {
+        aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+        return aliceTestClient.start().then(() => {
+            // establish an olm session with alice
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((p2pSession) => {
+            const syncResponse = getSyncResponse(['@bob:xyz']);
+
+            const olmEvent = encryptOlmEvent({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+            });
+
+            syncResponse.to_device = { events: [olmEvent] };
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(200, syncResponse);
+
+            return aliceTestClient.flushSync();
+        }).then(function() {
+            logger.log('Forcing alice to download our device keys');
+
+            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
+                200, getTestKeysQueryResponse('@bob:xyz'),
+            );
+
+            return Promise.all([
+                aliceTestClient.client.downloadKeys(['@bob:xyz']),
+                aliceTestClient.httpBackend.flush('/keys/query', 1),
+            ]);
+        }).then(function() {
+            logger.log('Telling alice to block our device');
+            aliceTestClient.client.setDeviceBlocked('@bob:xyz', 'DEVICE_ID');
+
+            logger.log('Telling alice to send a megolm message');
+            aliceTestClient.httpBackend.when(
+                'PUT', '/send/',
+            ).respond(200, {
+                event_id: '$event_id',
+            });
+
+            return Promise.all([
+                aliceTestClient.client.sendTextMessage(ROOM_ID, 'test'),
+
+                // the crypto stuff can take a while, so give the requests a whole second.
+                aliceTestClient.httpBackend.flushAllExpected({
+                    timeout: 1000,
+                }),
+            ]);
+        });
+    });
+
+    it("We should start a new megolm session when a device is blocked", function() {
+        let p2pSession;
+        let megolmSessionId;
+
+        aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+        return aliceTestClient.start().then(() => {
+            // establish an olm session with alice
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((_p2pSession) => {
+            p2pSession = _p2pSession;
+
+            const syncResponse = getSyncResponse(['@bob:xyz']);
+
+            const olmEvent = encryptOlmEvent({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+            });
+
+            syncResponse.to_device = { events: [olmEvent] };
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(200, syncResponse);
+
+            return aliceTestClient.flushSync();
+        }).then(function() {
+            logger.log("Fetching bob's devices and marking known");
+
+            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
+                200, getTestKeysQueryResponse('@bob:xyz'),
+            );
+
+            return Promise.all([
+                aliceTestClient.client.downloadKeys(['@bob:xyz']),
+                aliceTestClient.httpBackend.flushAllExpected(),
+            ]).then((keys) => {
+                aliceTestClient.client.setDeviceKnown('@bob:xyz', 'DEVICE_ID');
+            });
+        }).then(function() {
+            logger.log('Telling alice to send a megolm message');
+
+            aliceTestClient.httpBackend.when(
+                'PUT', '/sendToDevice/m.room.encrypted/',
+            ).respond(200, function(path, content) {
+                logger.log('sendToDevice: ', content);
+                const m = content.messages['@bob:xyz'].DEVICE_ID;
+                const ct = m.ciphertext[testSenderKey];
+                expect(ct.type).toEqual(1); // normal message
+                const decrypted = JSON.parse(p2pSession.decrypt(ct.type, ct.body));
+                logger.log('decrypted sendToDevice:', decrypted);
+                expect(decrypted.type).toEqual('m.room_key');
+                megolmSessionId = decrypted.content.session_id;
+                return {};
+            });
+
+            aliceTestClient.httpBackend.when(
+                'PUT', '/send/',
+            ).respond(200, function(path, content) {
+                logger.log('/send:', content);
+                expect(content.session_id).toEqual(megolmSessionId);
+                return {
+                    event_id: '$event_id',
+                };
+            });
+
+            return Promise.all([
+                aliceTestClient.client.sendTextMessage(ROOM_ID, 'test'),
+
+                // the crypto stuff can take a while, so give the requests a whole second.
+                aliceTestClient.httpBackend.flushAllExpected({
+                    timeout: 1000,
+                }),
+            ]);
+        }).then(function() {
+            logger.log('Telling alice to block our device');
+            aliceTestClient.client.setDeviceBlocked('@bob:xyz', 'DEVICE_ID');
+
+            logger.log('Telling alice to send another megolm message');
+            aliceTestClient.httpBackend.when(
+                'PUT', '/send/',
+            ).respond(200, function(path, content) {
+                logger.log('/send:', content);
+                expect(content.session_id).toNotEqual(megolmSessionId);
+                return {
+                    event_id: '$event_id',
+                };
+            });
+
+            return Promise.all([
+                aliceTestClient.client.sendTextMessage(ROOM_ID, 'test2'),
+                aliceTestClient.httpBackend.flushAllExpected(),
+            ]);
+        });
+    });
+
+    // https://github.com/vector-im/riot-web/issues/2676
+    it("Alice should send to her other devices", function() {
+        // for this test, we make the testOlmAccount be another of Alice's devices.
+        // it ought to get included in messages Alice sends.
+
+        let p2pSession;
+        let inboundGroupSession;
+        let decrypted;
+
+        return aliceTestClient.start().then(function() {
+            // an encrypted room with just alice
+            const syncResponse = {
+                next_batch: 1,
+                rooms: {
+                    join: {},
+                },
+            };
+            syncResponse.rooms.join[ROOM_ID] = {
+                state: {
+                    events: [
+                        testUtils.mkEvent({
+                            type: 'm.room.encryption',
+                            skey: '',
+                            content: {
+                                algorithm: 'm.megolm.v1.aes-sha2',
+                            },
+                        }),
+                        testUtils.mkMembership({
+                            mship: 'join',
+                            sender: aliceTestClient.userId,
+                        }),
+                    ],
+                },
+            };
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(200, syncResponse);
+
+            // the completion of the first initialsync hould make Alice
+            // invalidate the device cache for all members in e2e rooms (ie,
+            // herself), and do a key query.
+            aliceTestClient.expectKeyQuery(
+                getTestKeysQueryResponse(aliceTestClient.userId),
+            );
+
+            return aliceTestClient.httpBackend.flushAllExpected();
+        }).then(function() {
+            // start out with the device unknown - the send should be rejected.
+            return aliceTestClient.client.sendTextMessage(ROOM_ID, 'test').then(() => {
+                throw new Error("sendTextMessage failed on an unknown device");
+            }, (e) => {
+                expect(e.name).toEqual("UnknownDeviceError");
+                expect(Object.keys(e.devices)).toEqual([aliceTestClient.userId]);
+                expect(Object.keys(e.devices[aliceTestClient.userId])).
+                    toEqual(['DEVICE_ID']);
+            });
+        }).then(function() {
+            // mark the device as known, and resend.
+            aliceTestClient.client.setDeviceKnown(aliceTestClient.userId, 'DEVICE_ID');
+            aliceTestClient.httpBackend.when('POST', '/keys/claim').respond(
+                200, function(path, content) {
+                expect(content.one_time_keys[aliceTestClient.userId].DEVICE_ID)
+                    .toEqual("signed_curve25519");
+                return getTestKeysClaimResponse(aliceTestClient.userId);
+            });
+
+            aliceTestClient.httpBackend.when(
+                'PUT', '/sendToDevice/m.room.encrypted/',
+            ).respond(200, function(path, content) {
+                logger.log("sendToDevice: ", content);
+                const m = content.messages[aliceTestClient.userId].DEVICE_ID;
+                const ct = m.ciphertext[testSenderKey];
+                expect(ct.type).toEqual(0); // pre-key message
+
+                p2pSession = new Olm.Session();
+                p2pSession.create_inbound(testOlmAccount, ct.body);
+                const decrypted = JSON.parse(p2pSession.decrypt(ct.type, ct.body));
+
+                expect(decrypted.type).toEqual('m.room_key');
+                inboundGroupSession = new Olm.InboundGroupSession();
+                inboundGroupSession.create(decrypted.content.session_key);
+                return {};
+            });
+
+            aliceTestClient.httpBackend.when(
+                'PUT', '/send/',
+            ).respond(200, function(path, content) {
+                const ct = content.ciphertext;
+                const r = inboundGroupSession.decrypt(ct);
+                logger.log('Decrypted received megolm message', r);
+                decrypted = JSON.parse(r.plaintext);
+
+                return {
+                    event_id: '$event_id',
+                };
+            });
+
+            // Grab the event that we'll need to resend
+            const room = aliceTestClient.client.getRoom(ROOM_ID);
+            const pendingEvents = room.getPendingEvents();
+            expect(pendingEvents.length).toEqual(1);
+            const unsentEvent = pendingEvents[0];
+
+            return Promise.all([
+                aliceTestClient.client.resendEvent(unsentEvent, room),
+
+                // the crypto stuff can take a while, so give the requests a whole second.
+                aliceTestClient.httpBackend.flushAllExpected({
+                    timeout: 1000,
+                }),
+            ]);
+        }).then(function() {
+            expect(decrypted.type).toEqual('m.room.message');
+            expect(decrypted.content.body).toEqual('test');
+        });
+    });
+
+
+    it('Alice should wait for device list to complete when sending a megolm message',
+    function() {
+        let downloadPromise;
+        let sendPromise;
+
+        aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+        return aliceTestClient.start().then(() => {
+            // establish an olm session with alice
+            return createOlmSession(testOlmAccount, aliceTestClient);
+        }).then((p2pSession) => {
+            const syncResponse = getSyncResponse(['@bob:xyz']);
+
+            const olmEvent = encryptOlmEvent({
+                senderKey: testSenderKey,
+                recipient: aliceTestClient,
+                p2pSession: p2pSession,
+            });
+
+            syncResponse.to_device = { events: [olmEvent] };
+
+            aliceTestClient.httpBackend.when('GET', '/sync').respond(200, syncResponse);
+            return aliceTestClient.flushSync();
+        }).then(function() {
+            // this will block
+            logger.log('Forcing alice to download our device keys');
+            downloadPromise = aliceTestClient.client.downloadKeys(['@bob:xyz']);
+
+            // so will this.
+            sendPromise = aliceTestClient.client.sendTextMessage(ROOM_ID, 'test')
+            .then(() => {
+                throw new Error("sendTextMessage failed on an unknown device");
+            }, (e) => {
+                expect(e.name).toEqual("UnknownDeviceError");
+            });
+
+            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
+                200, getTestKeysQueryResponse('@bob:xyz'),
+            );
+
+            return aliceTestClient.httpBackend.flushAllExpected();
+        }).then(function() {
+            return Promise.all([downloadPromise, sendPromise]);
+        });
+    });
+
+
+    it("Alice exports megolm keys and imports them to a new device", function() {
+        let messageEncrypted;
+
+        aliceTestClient.expectKeyQuery({device_keys: {'@alice:localhost': {}}});
+        return aliceTestClient.start().then(() => {
+            // establish an olm session with alice
+            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,
+            });
+
+            // encrypt a message with the group session
+            messageEncrypted = encryptMegolmEvent({
+                senderKey: testSenderKey,
+                groupSession: groupSession,
+                room_id: ROOM_ID,
+            });
+
+            // 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.getContent().body).toEqual('42');
+
+            return aliceTestClient.client.exportRoomKeys();
+        }).then(function(exported) {
+            // start a new client
+            aliceTestClient.stop();
+
+            aliceTestClient = new TestClient(
+                "@alice:localhost", "device2", "access_token2",
+            );
+            return aliceTestClient.client.initCrypto().then(() => {
+                aliceTestClient.client.importRoomKeys(exported);
+                return aliceTestClient.start();
+            });
+        }).then(function() {
+            const syncResponse = {
+                next_batch: 1,
+                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.getContent().body).toEqual('42');
+        });
+    });
+});

spec/mock-request.js

@@ -1,186 +0,0 @@
-"use strict";
-var q = require("q");
-
-/**
- * Construct a mock HTTP backend, heavily inspired by Angular.js.
- * @constructor
- */
-function HttpBackend() {
-    this.requests = [];
-    this.expectedRequests = [];
-    var self = this;
-    // the request function dependency that the SDK needs.
-    this.requestFn = function(opts, callback) {
-        var realReq = new Request(opts.method, opts.uri, opts.body, opts.qs);
-        realReq.callback = callback;
-        self.requests.push(realReq);
-    };
-}
-HttpBackend.prototype = {
-    /**
-     * Respond to all of the requests (flush the queue).
-     * @return {Promise} resolved when there is nothing left to flush.
-     */
-    flush: function() {
-        var defer = q.defer();
-        var self = this;
-        console.log("HTTP backend flushing...");
-        var tryFlush = function() {
-            // if there's more real requests and more expected requests, flush 'em.
-            console.log(
-                "  trying to flush queue => reqs=%s expected=%s",
-                self.requests.length, self.expectedRequests.length
-            );
-            if (self._takeFromQueue()) {
-                // try again on the next tick.
-                console.log("  flushed. Trying for more.");
-                setTimeout(tryFlush, 0);
-            }
-            else {
-                console.log("  no more flushes.");
-                defer.resolve();
-            }
-        };
-
-        setTimeout(tryFlush, 0);
-
-        return defer.promise;
-    },
-
-    /**
-     * Attempts to resolve requests/expected requests.
-     * @return {boolean} true if something was resolved.
-     */
-    _takeFromQueue: function() {
-        var req = null;
-        var i, j;
-        var matchingReq, expectedReq, testResponse = null;
-        for (i = 0; i < this.requests.length; i++) {
-            req = this.requests[i];
-            for (j = 0; j < this.expectedRequests.length; j++) {
-                expectedReq = this.expectedRequests[j];
-                if (expectedReq.method === req.method &&
-                        req.path.indexOf(expectedReq.path) !== -1) {
-                    if (!expectedReq.data || (JSON.stringify(expectedReq.data) ===
-                            JSON.stringify(req.data))) {
-                        matchingReq = expectedReq;
-                        this.expectedRequests.splice(j, 1);
-                        break;
-                    }
-                }
-            }
-
-            if (matchingReq) {
-                // remove from request queue
-                this.requests.splice(i, 1);
-                i--;
-
-                for (j = 0; j < matchingReq.checks.length; j++) {
-                    matchingReq.checks[j](req);
-                }
-                testResponse = matchingReq.response;
-                console.log("    responding to %s", matchingReq.path);
-
-                req.callback(
-                    testResponse.err, testResponse.response, testResponse.body
-                );
-            }
-        }
-        if (testResponse) {  // flushed something
-            return true;
-        }
-        return false;
-    },
-
-    /**
-     * Makes sure that the SDK hasn't sent any more requests to the backend.
-     */
-    verifyNoOutstandingRequests: function() {
-        var firstOutstandingReq = this.requests[0] || {};
-        expect(this.requests.length).toEqual(0,
-            "Expected no more HTTP requests but received request to " +
-            firstOutstandingReq.path
-        );
-    },
-
-    /**
-     * Makes sure that the test doesn't have any unresolved requests.
-     */
-    verifyNoOutstandingExpectation: function() {
-        var firstOutstandingExpectation = this.expectedRequests[0] || {};
-        expect(this.expectedRequests.length).toEqual(0,
-            "Expected to see HTTP request for " + firstOutstandingExpectation.path
-        );
-    },
-
-    /**
-     * Create an expected request.
-     * @param {string} method The HTTP method
-     * @param {string} path The path (which can be partial)
-     * @param {Object} data The expected data.
-     * @return {Request} An expected request.
-     */
-    when: function(method, path, data) {
-        var pendingReq = new Request(method, path, data);
-        this.expectedRequests.push(pendingReq);
-        return pendingReq;
-    }
-};
-
-function Request(method, path, data, queryParams) {
-    this.method = method;
-    this.path = path;
-    this.data = data;
-    this.queryParams = queryParams;
-    this.callback = null;
-    this.response = null;
-    this.checks = [];
-}
-Request.prototype = {
-    /**
-     * Execute a check when this request has been satisfied.
-     * @param {Function} fn The function to execute.
-     * @return {Request} for chaining calls.
-     */
-    check: function(fn) {
-        this.checks.push(fn);
-        return this;
-    },
-
-    /**
-     * Respond with the given data when this request is satisfied.
-     * @param {Number} code The HTTP status code.
-     * @param {Object} data The HTTP JSON body.
-     */
-    respond: function(code, data) {
-        this.response = {
-            response: {
-                statusCode: code,
-                headers: {}
-            },
-            body: data,
-            err: null
-        };
-    },
-
-    /**
-     * Fail with an Error when this request is satisfied.
-     * @param {Number} code The HTTP status code.
-     * @param {Error} err The error to throw (e.g. Network Error)
-     */
-    fail: function(code, err) {
-        this.response = {
-            response: {
-                statusCode: code,
-                headers: {}
-            },
-            body: null,
-            err: err
-        };
-    }
-};
-
-/**
- * The HttpBackend class.
- */
-module.exports = HttpBackend;

spec/olm-loader.js

@@ -0,0 +1,25 @@
+/*
+Copyright 2017 Vector creations 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.
+*/
+
+import logger from '../src/logger';
+
+// try to load the olm library.
+try {
+    global.Olm = require('olm');
+    logger.log('loaded libolm');
+} catch (e) {
+    logger.warn("unable to run crypto tests: libolm not available");
+}

spec/test-utils.js

@@ -1,78 +1,244 @@
 "use strict";
+import expect from 'expect';
+import Promise from 'bluebird';
+
+// load olm before the sdk if possible
+import './olm-loader';
+
+import logger from '../src/logger';
+import sdk from '..';
+const MatrixEvent = sdk.MatrixEvent;
+
+/**
+ * Return a promise that is resolved when the client next emits a
+ * SYNCING event.
+ * @param {Object} client The client
+ * @param {Number=} count Number of syncs to wait for (default 1)
+ * @return {Promise} Resolves once the client has emitted a SYNCING event
+ */
+module.exports.syncPromise = function(client, count) {
+    if (count === undefined) {
+        count = 1;
+    }
+    if (count <= 0) {
+        return Promise.resolve();
+    }
+
+    const p = new Promise((resolve, reject) => {
+        const cb = (state) => {
+            logger.log(`${Date.now()} syncPromise(${count}): ${state}`);
+            if (state == 'SYNCING') {
+                resolve();
+            } else {
+                client.once('sync', cb);
+            }
+        };
+        client.once('sync', cb);
+    });
+
+    return p.then(() => {
+        return module.exports.syncPromise(client, count-1);
+    });
+};
 
 /**
  * Perform common actions before each test case, e.g. printing the test case
  * name to stdout.
- * @param {TestCase} testCase The test case that is about to be run.
+ * @param {Mocha.Context} context  The test context
  */
-module.exports.beforeEach = function(testCase) {
-    var desc = testCase.suite.description + " : " + testCase.description;
-    console.log(desc);
-    console.log(new Array(1 + desc.length).join("="));
+module.exports.beforeEach = function(context) {
+    const desc = context.currentTest.fullTitle();
+
+    logger.log(desc);
+    logger.log(new Array(1 + desc.length).join("="));
 };
 
 /**
- * Create a JSON object representing an Event.
- * @param {string} type The event.type
- * @param {string} room The event.room_id
- * @param {string} userId The event.user_id
- * @param {Object} content The event.content
+ * Create a spy for an object and automatically spy its methods.
+ * @param {*} constr The class constructor (used with 'new')
+ * @param {string} name The name of the class
+ * @return {Object} An instantiated object with spied methods/properties.
+ */
+module.exports.mock = function(constr, name) {
+    // Based on
+    // http://eclipsesource.com/blogs/2014/03/27/mocks-in-jasmine-tests/
+    const HelperConstr = new Function(); // jshint ignore:line
+    HelperConstr.prototype = constr.prototype;
+    const result = new HelperConstr();
+    result.toString = function() {
+        return "mock" + (name ? " of " + name : "");
+    };
+    for (const key in constr.prototype) { // eslint-disable-line guard-for-in
+        try {
+            if (constr.prototype[key] instanceof Function) {
+                result[key] = expect.createSpy();
+            }
+        } catch (ex) {
+            // Direct access to some non-function fields of DOM prototypes may
+            // cause exceptions.
+            // Overwriting will not work either in that case.
+        }
+    }
+    return result;
+};
+
+/**
+ * Create an Event.
+ * @param {Object} opts Values for the event.
+ * @param {string} opts.type The event.type
+ * @param {string} opts.room The event.room_id
+ * @param {string} opts.sender The event.sender
+ * @param {string} opts.skey Optional. The state key (auto inserts empty string)
+ * @param {Object} opts.content The event.content
+ * @param {boolean} opts.event True to make a MatrixEvent.
  * @return {Object} a JSON object representing this event.
  */
-module.exports.mkEvent = function(type, room, userId, content) {
-    var event = {
-        type: type,
-        room_id: room,
-        user_id: userId,
-        content: content,
-        event_id: "$" + Math.random() + "-" + Math.random()
+module.exports.mkEvent = function(opts) {
+    if (!opts.type || !opts.content) {
+        throw new Error("Missing .type or .content =>" + JSON.stringify(opts));
+    }
+    const event = {
+        type: opts.type,
+        room_id: opts.room,
+        sender: opts.sender || opts.user, // opts.user for backwards-compat
+        content: opts.content,
+        event_id: "$" + Math.random() + "-" + Math.random(),
     };
-    if (["m.room.name", "m.room.topic", "m.room.create", "m.room.join_rules",
+    if (opts.skey !== undefined) {
+        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(type) !== -1) {
+         "com.example.state"].indexOf(opts.type) !== -1) {
         event.state_key = "";
     }
-    return event;
+    return opts.event ? new MatrixEvent(event) : event;
 };
 
 /**
- * Create an m.room.member POJO.
- * @param {string} room The room ID for the event.
- * @param {string} membership The content.membership for the event.
- * @param {string} userId The user ID for the event.
- * @param {string} otherUserId The other user ID for the event if applicable
+ * Create an m.presence event.
+ * @param {Object} opts Values for the presence.
+ * @return {Object|MatrixEvent} The event
+ */
+module.exports.mkPresence = function(opts) {
+    if (!opts.user) {
+        throw new Error("Missing user");
+    }
+    const event = {
+        event_id: "$" + Math.random() + "-" + Math.random(),
+        type: "m.presence",
+        sender: opts.sender || opts.user, // opts.user for backwards-compat
+        content: {
+            avatar_url: opts.url,
+            displayname: opts.name,
+            last_active_ago: opts.ago,
+            presence: opts.presence || "offline",
+        },
+    };
+    return opts.event ? new MatrixEvent(event) : event;
+};
+
+/**
+ * Create an m.room.member event.
+ * @param {Object} opts Values for the membership.
+ * @param {string} opts.room The room ID for the event.
+ * @param {string} opts.mship The content.membership for the event.
+ * @param {string} opts.sender The sender user ID for the event.
+ * @param {string} opts.skey The target user ID for the event if applicable
  * e.g. for invites/bans.
- * @param {string} displayName The content.displayname for the event.
- * @param {string} avatarUrl The content.avatar_url for the event.
- * @return {Object} The event
+ * @param {string} opts.name The content.displayname for the event.
+ * @param {string} opts.url The content.avatar_url for the event.
+ * @param {boolean} opts.event True to make a MatrixEvent.
+ * @return {Object|MatrixEvent} The event
  */
-module.exports.mkMembership = function(room, membership, userId, otherUserId,
-                                       displayName, avatarUrl) {
-    var event = module.exports.mkEvent("m.room.member", room, userId, {
-        membership: membership,
-        displayname: displayName,
-        avatar_url: avatarUrl
-    });
-    event.state_key = userId;
-    if (["invite", "ban"].indexOf(membership) !== -1) {
-        event.state_key = otherUserId;
+module.exports.mkMembership = function(opts) {
+    opts.type = "m.room.member";
+    if (!opts.skey) {
+        opts.skey = opts.sender || opts.user;
     }
-    return event;
+    if (!opts.mship) {
+        throw new Error("Missing .mship => " + JSON.stringify(opts));
+    }
+    opts.content = {
+        membership: opts.mship,
+    };
+    if (opts.name) {
+        opts.content.displayname = opts.name;
+    }
+    if (opts.url) {
+        opts.content.avatar_url = opts.url;
+    }
+    return module.exports.mkEvent(opts);
 };
 
 /**
- * Create an m.room.message POJO.
- * @param {string} room The room ID for the event.
- * @param {string} userId The user ID for the event.
- * @param {string} msg The content.body for the event.
- * @return {Object} The event
+ * Create an m.room.message event.
+ * @param {Object} opts Values for the message
+ * @param {string} opts.room The room ID for the event.
+ * @param {string} opts.user The user ID for the event.
+ * @param {string} opts.msg Optional. The content.body for the event.
+ * @param {boolean} opts.event True to make a MatrixEvent.
+ * @return {Object|MatrixEvent} The event
  */
-module.exports.mkMessage = function(room, userId, msg) {
-    if (!msg) {
-        msg = "Random->" + Math.random();
+module.exports.mkMessage = function(opts) {
+    opts.type = "m.room.message";
+    if (!opts.msg) {
+        opts.msg = "Random->" + Math.random();
     }
-    return module.exports.mkEvent("m.room.message", room, userId, {
+    if (!opts.room || !opts.user) {
+        throw new Error("Missing .room or .user from %s", opts);
+    }
+    opts.content = {
         msgtype: "m.text",
-        body: msg
+        body: opts.msg,
+    };
+    return module.exports.mkEvent(opts);
+};
+
+
+/**
+ * A mock implementation of webstorage
+ *
+ * @constructor
+ */
+module.exports.MockStorageApi = function() {
+    this.data = {};
+};
+module.exports.MockStorageApi.prototype = {
+    get length() {
+        return Object.keys(this.data).length;
+    },
+    key: function(i) {
+        return Object.keys(this.data)[i];
+    },
+    setItem: function(k, v) {
+        this.data[k] = v;
+    },
+    getItem: function(k) {
+        return this.data[k] || null;
+    },
+    removeItem: function(k) {
+        delete this.data[k];
+    },
+};
+
+
+/**
+ * If an event is being decrypted, wait for it to finish being decrypted.
+ *
+ * @param {MatrixEvent} event
+ * @returns {Promise} promise which resolves (to `event`) when the event has been decrypted
+ */
+module.exports.awaitDecryption = function(event) {
+    if (!event.isBeingDecrypted()) {
+        return Promise.resolve(event);
+    }
+
+    logger.log(`${Date.now()} event ${event.getId()} is being decrypted; waiting`);
+
+    return new Promise((resolve, reject) => {
+        event.once('Event.decrypted', (ev) => {
+            logger.log(`${Date.now()} event ${event.getId()} now decrypted`);
+            resolve(ev);
+        });
     });
 };

spec/unit/autodiscovery.spec.js

@@ -0,0 +1,670 @@
+/*
+Copyright 2018 New Vector 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.
+*/
+"use strict";
+
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const utils = require("../test-utils");
+
+const AutoDiscovery = sdk.AutoDiscovery;
+
+import expect from 'expect';
+import MockHttpBackend from "matrix-mock-request";
+
+
+describe("AutoDiscovery", function() {
+    let httpBackend = null;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new MockHttpBackend();
+        sdk.request(httpBackend.requestFn);
+    });
+
+    it("should throw an error when no domain is specified", function() {
+        return Promise.all([
+            AutoDiscovery.findClientConfig(/* no args */).then(() => {
+                throw new Error("Expected a failure, not success with no args");
+            }, () => {
+                return true;
+            }),
+
+            AutoDiscovery.findClientConfig("").then(() => {
+                throw new Error("Expected a failure, not success with an empty string");
+            }, () => {
+                return true;
+            }),
+
+            AutoDiscovery.findClientConfig(null).then(() => {
+                throw new Error("Expected a failure, not success with null");
+            }, () => {
+                return true;
+            }),
+
+            AutoDiscovery.findClientConfig(true).then(() => {
+                throw new Error("Expected a failure, not success with a non-string");
+            }, () => {
+                return true;
+            }),
+        ]);
+    });
+
+    it("should return PROMPT when .well-known 404s", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(404, {});
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns a 500 error", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(500, {});
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns a 400 error", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(400, {});
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns an empty body", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, "");
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns not-JSON", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, "abc");
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known does not have a base_url for " +
+        "m.homeserver (empty string)", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known does not have a base_url for " +
+        "m.homeserver (no property)", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {},
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (disallowed scheme)", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "mxc://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (verification failure: 404)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").respond(404, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HOMESERVER,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (verification failure: 500)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").respond(500, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HOMESERVER,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (verification failure: 200 but wrong content)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").respond(200, {
+            not_matrix_versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HOMESERVER,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS when .well-known has a verifiably accurate base_url for " +
+        "m.homeserver", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri).toEqual("https://example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS with the right homeserver URL", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when the identity server configuration is wrong " +
+        "(missing base_url)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                not_base_url: "https://identity.example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IS,
+
+                        // We still expect the base_url to be here for debugging purposes.
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IS_BASE_URL,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when the identity server configuration is wrong " +
+        "(empty base_url)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IS,
+
+                        // We still expect the base_url to be here for debugging purposes.
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IS_BASE_URL,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when the identity server configuration is wrong " +
+        "(validation error: 404)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/_matrix/identity/api/v1").respond(404, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "https://identity.example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IS,
+
+                        // We still expect the base_url to be here for debugging purposes.
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IDENTITY_SERVER,
+                        base_url: "https://identity.example.org",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when the identity server configuration is wrong " +
+        "(validation error: 500)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/_matrix/identity/api/v1").respond(500, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "https://identity.example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IS,
+
+                        // We still expect the base_url to be here for debugging purposes
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_IDENTITY_SERVER,
+                        base_url: "https://identity.example.org",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS when the identity server configuration is " +
+        "verifiably accurate", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/_matrix/identity/api/v1").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://identity.example.org/_matrix/identity/api/v1");
+        }).respond(200, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "https://identity.example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://identity.example.org",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS and preserve non-standard keys from the " +
+        ".well-known response", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/_matrix/identity/api/v1").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://identity.example.org/_matrix/identity/api/v1");
+        }).respond(200, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "https://identity.example.org",
+            },
+            "org.example.custom.property": {
+                cupcakes: "yes",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://identity.example.org",
+                    },
+                    "org.example.custom.property": {
+                        cupcakes: "yes",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+});

spec/unit/content-repo.spec.js

@@ -0,0 +1,95 @@
+"use strict";
+import 'source-map-support/register';
+const ContentRepo = require("../../lib/content-repo");
+const testUtils = require("../test-utils");
+
+import expect from 'expect';
+
+describe("ContentRepo", function() {
+    const baseUrl = "https://my.home.server";
+
+    beforeEach(function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+    });
+
+    describe("getHttpUriForMxc", function() {
+        it("should do nothing to HTTP URLs when allowing direct links", function() {
+            const httpUrl = "http://example.com/image.jpeg";
+            expect(
+                ContentRepo.getHttpUriForMxc(
+                    baseUrl, httpUrl, undefined, undefined, undefined, true,
+                ),
+            ).toEqual(httpUrl);
+        });
+
+        it("should return the empty string HTTP URLs by default", function() {
+            const httpUrl = "http://example.com/image.jpeg";
+            expect(ContentRepo.getHttpUriForMxc(baseUrl, httpUrl)).toEqual("");
+        });
+
+        it("should return a download URL if no width/height/resize are specified",
+        function() {
+            const mxcUri = "mxc://server.name/resourceid";
+            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri)).toEqual(
+                baseUrl + "/_matrix/media/r0/download/server.name/resourceid",
+            );
+        });
+
+        it("should return the empty string for null input", function() {
+            expect(ContentRepo.getHttpUriForMxc(null)).toEqual("");
+        });
+
+        it("should return a thumbnail URL if a width/height/resize is specified",
+        function() {
+            const mxcUri = "mxc://server.name/resourceid";
+            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri, 32, 64, "crop")).toEqual(
+                baseUrl + "/_matrix/media/r0/thumbnail/server.name/resourceid" +
+                "?width=32&height=64&method=crop",
+            );
+        });
+
+        it("should put fragments from mxc:// URIs after any query parameters",
+        function() {
+            const mxcUri = "mxc://server.name/resourceid#automade";
+            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri, 32)).toEqual(
+                baseUrl + "/_matrix/media/r0/thumbnail/server.name/resourceid" +
+                "?width=32#automade",
+            );
+        });
+
+        it("should put fragments from mxc:// URIs at the end of the HTTP URI",
+        function() {
+            const mxcUri = "mxc://server.name/resourceid#automade";
+            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri)).toEqual(
+                baseUrl + "/_matrix/media/r0/download/server.name/resourceid#automade",
+            );
+        });
+    });
+
+    describe("getIdenticonUri", function() {
+        it("should do nothing for null input", function() {
+            expect(ContentRepo.getIdenticonUri(null)).toEqual(null);
+        });
+
+        it("should set w/h by default to 96", function() {
+            expect(ContentRepo.getIdenticonUri(baseUrl, "foobar")).toEqual(
+                baseUrl + "/_matrix/media/unstable/identicon/foobar" +
+                "?width=96&height=96",
+            );
+        });
+
+        it("should be able to set custom w/h", function() {
+            expect(ContentRepo.getIdenticonUri(baseUrl, "foobar", 32, 64)).toEqual(
+                baseUrl + "/_matrix/media/unstable/identicon/foobar" +
+                "?width=32&height=64",
+            );
+        });
+
+        it("should URL encode the identicon string", function() {
+            expect(ContentRepo.getIdenticonUri(baseUrl, "foo#bar", 32, 64)).toEqual(
+                baseUrl + "/_matrix/media/unstable/identicon/foo%23bar" +
+                "?width=32&height=64",
+            );
+        });
+    });
+});

spec/unit/crypto.spec.js

@@ -0,0 +1,366 @@
+import 'source-map-support/register';
+
+import '../olm-loader';
+
+import Crypto from '../../lib/crypto';
+import expect from 'expect';
+
+import WebStorageSessionStore from '../../lib/store/session/webstorage';
+import MemoryCryptoStore from '../../lib/crypto/store/memory-crypto-store.js';
+import MockStorageApi from '../MockStorageApi';
+import TestClient from '../TestClient';
+import {MatrixEvent} from '../../lib/models/event';
+import Room from '../../lib/models/room';
+import olmlib from '../../lib/crypto/olmlib';
+import lolex from 'lolex';
+
+const EventEmitter = require("events").EventEmitter;
+
+const sdk = require("../..");
+
+const Olm = global.Olm;
+
+describe("Crypto", function() {
+    if (!sdk.CRYPTO_ENABLED) {
+        return;
+    }
+
+    beforeEach(function(done) {
+        Olm.init().then(done);
+    });
+
+    it("Crypto exposes the correct olm library version", function() {
+        expect(Crypto.getOlmVersion()[0]).toEqual(3);
+    });
+
+
+    describe('Session management', function() {
+        const otkResponse = {
+            one_time_keys: {
+                '@alice:home.server': {
+                    aliceDevice: {
+                        'signed_curve25519:FLIBBLE': {
+                            key: 'YmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmI',
+                            signatures: {
+                                '@alice:home.server': {
+                                    'ed25519:aliceDevice': 'totally a valid signature',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        let crypto;
+        let mockBaseApis;
+        let mockRoomList;
+
+        let fakeEmitter;
+
+        beforeEach(async function() {
+            const mockStorage = new MockStorageApi();
+            const sessionStore = new WebStorageSessionStore(mockStorage);
+            const cryptoStore = new MemoryCryptoStore(mockStorage);
+
+            cryptoStore.storeEndToEndDeviceData({
+                devices: {
+                    '@bob:home.server': {
+                        'BOBDEVICE': {
+                            keys: {
+                                'curve25519:BOBDEVICE': 'this is a key',
+                            },
+                        },
+                    },
+                },
+                trackingStatus: {},
+            });
+
+            mockBaseApis = {
+                sendToDevice: expect.createSpy(),
+                getKeyBackupVersion: expect.createSpy(),
+                isGuest: expect.createSpy(),
+            };
+            mockRoomList = {};
+
+            fakeEmitter = new EventEmitter();
+
+            crypto = new Crypto(
+                mockBaseApis,
+                sessionStore,
+                "@alice:home.server",
+                "FLIBBLE",
+                sessionStore,
+                cryptoStore,
+                mockRoomList,
+            );
+            crypto.registerEventHandlers(fakeEmitter);
+            await crypto.init();
+        });
+
+        afterEach(async function() {
+            await crypto.stop();
+        });
+
+        it("restarts wedged Olm sessions", async function() {
+            const prom = new Promise((resolve) => {
+                mockBaseApis.claimOneTimeKeys = function() {
+                    resolve();
+                    return otkResponse;
+                };
+            });
+
+            fakeEmitter.emit('toDeviceEvent', {
+                getType: expect.createSpy().andReturn('m.room.message'),
+                getContent: expect.createSpy().andReturn({
+                    msgtype: 'm.bad.encrypted',
+                }),
+                getWireContent: expect.createSpy().andReturn({
+                    algorithm: 'm.olm.v1.curve25519-aes-sha2',
+                    sender_key: 'this is a key',
+                }),
+                getSender: expect.createSpy().andReturn('@bob:home.server'),
+            });
+
+            await prom;
+        });
+    });
+
+    describe('Key requests', function() {
+        let aliceClient;
+        let bobClient;
+
+        beforeEach(async function() {
+            aliceClient = (new TestClient(
+                "@alice:example.com", "alicedevice",
+            )).client;
+            bobClient = (new TestClient(
+                "@bob:example.com", "bobdevice",
+            )).client;
+            await aliceClient.initCrypto();
+            await bobClient.initCrypto();
+        });
+
+        afterEach(async function() {
+            aliceClient.stopClient();
+            bobClient.stopClient();
+        });
+
+        it(
+            "does not cancel keyshare requests if some messages are not decrypted",
+            async function() {
+                function awaitEvent(emitter, event) {
+                    return new Promise((resolve, reject) => {
+                        emitter.once(event, (result) => {
+                            resolve(result);
+                        });
+                    });
+                }
+
+                async function keyshareEventForEvent(event, index) {
+                    const eventContent = event.getWireContent();
+                    const key = await aliceClient._crypto._olmDevice
+                        .getInboundGroupSessionKey(
+                            roomId, eventContent.sender_key, eventContent.session_id,
+                            index,
+                        );
+                    const ksEvent = new MatrixEvent({
+                        type: "m.forwarded_room_key",
+                        sender: "@alice:example.com",
+                        content: {
+                            algorithm: olmlib.MEGOLM_ALGORITHM,
+                            room_id: roomId,
+                            sender_key: eventContent.sender_key,
+                            sender_claimed_ed25519_key: key.sender_claimed_ed25519_key,
+                            session_id: eventContent.session_id,
+                            session_key: key.key,
+                            chain_index: key.chain_index,
+                            forwarding_curve25519_key_chain:
+                            key.forwarding_curve_key_chain,
+                        },
+                    });
+                    // make onRoomKeyEvent think this was an encrypted event
+                    ksEvent._senderCurve25519Key = "akey";
+                    return ksEvent;
+                }
+
+                const encryptionCfg = {
+                    "algorithm": "m.megolm.v1.aes-sha2",
+                };
+                const roomId = "!someroom";
+                const aliceRoom = new Room(roomId, aliceClient, "@alice:example.com", {});
+                const bobRoom = new Room(roomId, bobClient, "@bob:example.com", {});
+                aliceClient.store.storeRoom(aliceRoom);
+                bobClient.store.storeRoom(bobRoom);
+                await aliceClient.setRoomEncryption(roomId, encryptionCfg);
+                await bobClient.setRoomEncryption(roomId, encryptionCfg);
+                const events = [
+                    new MatrixEvent({
+                        type: "m.room.message",
+                        sender: "@alice:example.com",
+                        room_id: roomId,
+                        event_id: "$1",
+                        content: {
+                            msgtype: "m.text",
+                            body: "1",
+                        },
+                    }),
+                    new MatrixEvent({
+                        type: "m.room.message",
+                        sender: "@alice:example.com",
+                        room_id: roomId,
+                        event_id: "$2",
+                        content: {
+                            msgtype: "m.text",
+                            body: "2",
+                        },
+                    }),
+                ];
+                await Promise.all(events.map(async (event) => {
+                    // 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;
+                    try {
+                        await bobClient._crypto.decryptEvent(event);
+                    } catch (e) {
+                        // we expect this to fail because we don't have the
+                        // decryption keys yet
+                    }
+                }));
+
+                const bobDecryptor = bobClient._crypto._getRoomDecryptor(
+                    roomId, olmlib.MEGOLM_ALGORITHM,
+                );
+
+                let eventPromise = Promise.all(events.map((ev) => {
+                    return awaitEvent(ev, "Event.decrypted");
+                }));
+
+                // keyshare the session key starting at the second message, so
+                // the first message can't be decrypted yet, but the second one
+                // can
+                let ksEvent = await keyshareEventForEvent(events[1], 1);
+                await bobDecryptor.onRoomKeyEvent(ksEvent);
+                await eventPromise;
+                expect(events[0].getContent().msgtype).toBe("m.bad.encrypted");
+                expect(events[1].getContent().msgtype).toNotBe("m.bad.encrypted");
+
+                const cryptoStore = bobClient._cryptoStore;
+                const eventContent = events[0].getWireContent();
+                const senderKey = eventContent.sender_key;
+                const sessionId = eventContent.session_id;
+                const roomKeyRequestBody = {
+                    algorithm: olmlib.MEGOLM_ALGORITHM,
+                    room_id: roomId,
+                    sender_key: senderKey,
+                    session_id: sessionId,
+                };
+                // the room key request should still be there, since we haven't
+                // decrypted everything
+                expect(await cryptoStore.getOutgoingRoomKeyRequest(roomKeyRequestBody))
+                    .toExist();
+
+                // keyshare the session key starting at the first message, so
+                // that it can now be decrypted
+                eventPromise = awaitEvent(events[0], "Event.decrypted");
+                ksEvent = await keyshareEventForEvent(events[0], 0);
+                await bobDecryptor.onRoomKeyEvent(ksEvent);
+                await eventPromise;
+                expect(events[0].getContent().msgtype).toNotBe("m.bad.encrypted");
+                // the room key request should be gone since we've now decypted everything
+                expect(await cryptoStore.getOutgoingRoomKeyRequest(roomKeyRequestBody))
+                    .toNotExist();
+            },
+        );
+
+        it("creates a new keyshare request if we request a keyshare", async function() {
+            // make sure that cancelAndResend... creates a new keyshare request
+            // if there wasn't an already-existing one
+            const event = new MatrixEvent({
+                sender: "@bob:example.com",
+                room_id: "!someroom",
+                content: {
+                    algorithm: olmlib.MEGOLM_ALGORITHM,
+                    session_id: "sessionid",
+                    sender_key: "senderkey",
+                },
+            });
+            await aliceClient.cancelAndResendEventRoomKeyRequest(event);
+            const cryptoStore = aliceClient._cryptoStore;
+            const roomKeyRequestBody = {
+                algorithm: olmlib.MEGOLM_ALGORITHM,
+                room_id: "!someroom",
+                session_id: "sessionid",
+                sender_key: "senderkey",
+            };
+            expect(await cryptoStore.getOutgoingRoomKeyRequest(roomKeyRequestBody))
+                .toExist();
+        });
+
+        it("uses a new txnid for re-requesting keys", async function() {
+            const event = new MatrixEvent({
+                sender: "@bob:example.com",
+                room_id: "!someroom",
+                content: {
+                    algorithm: olmlib.MEGOLM_ALGORITHM,
+                    session_id: "sessionid",
+                    sender_key: "senderkey",
+                },
+            });
+            /* return a promise and a function. When the function is called,
+             * the promise will be resolved.
+             */
+            function awaitFunctionCall() {
+                let func;
+                const promise = new Promise((resolve, reject) => {
+                    func = function(...args) {
+                        resolve(args);
+                        return new Promise((resolve, reject) => {
+                            // give us some time to process the result before
+                            // continuing
+                            global.setTimeout(resolve, 1);
+                        });
+                    };
+                });
+                return {func, promise};
+            }
+
+            aliceClient.startClient();
+
+            const clock = lolex.install();
+
+            try {
+                let promise;
+                // make a room key request, and record the transaction ID for the
+                // sendToDevice call
+                ({promise, func: aliceClient.sendToDevice} = awaitFunctionCall());
+                await aliceClient.cancelAndResendEventRoomKeyRequest(event);
+                clock.runToLast();
+                let args = await promise;
+                const txnId = args[2];
+                clock.runToLast();
+
+                // give the room key request manager time to update the state
+                // of the request
+                await Promise.resolve();
+
+                // cancel and resend the room key request
+                ({promise, func: aliceClient.sendToDevice} = awaitFunctionCall());
+                await aliceClient.cancelAndResendEventRoomKeyRequest(event);
+                clock.runToLast();
+                // the first call to sendToDevice will be the cancellation
+                args = await promise;
+                // the second call to sendToDevice will be the key request
+                ({promise, func: aliceClient.sendToDevice} = awaitFunctionCall());
+                clock.runToLast();
+                args = await promise;
+                clock.runToLast();
+                expect(args[2]).toNotBe(txnId);
+            } finally {
+                clock.uninstall();
+            }
+        });
+    });
+});

spec/unit/crypto/DeviceList.spec.js

@@ -0,0 +1,156 @@
+/*
+Copyright 2017 Vector Creations Ltd
+Copyright 2018, 2019 New Vector 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.
+*/
+
+import DeviceList from '../../../lib/crypto/DeviceList';
+import MemoryCryptoStore from '../../../lib/crypto/store/memory-crypto-store.js';
+import testUtils from '../../test-utils';
+import utils from '../../../lib/utils';
+import logger from '../../../src/logger';
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+const signedDeviceList = {
+    "failures": {},
+    "device_keys": {
+        "@test1:sw1v.org": {
+            "HGKAWHRVJQ": {
+                "signatures": {
+                    "@test1:sw1v.org": {
+                        "ed25519:HGKAWHRVJQ":
+                            "8PB450fxKDn5s8IiRZ2N2t6MiueQYVRLHFEzqIi1eLdxx1w" +
+                            "XEPC1/1Uz9T4gwnKlMVAKkhB5hXQA/3kjaeLABw",
+                    },
+                },
+                "user_id": "@test1:sw1v.org",
+                "keys": {
+                    "ed25519:HGKAWHRVJQ":
+                        "0gI/T6C+mn1pjtvnnW2yB2l1IIBb/5ULlBXi/LXFSEQ",
+                    "curve25519:HGKAWHRVJQ":
+                        "mbIZED1dBsgIgkgzxDpxKkJmsr4hiWlGzQTvUnQe3RY",
+                },
+                "algorithms": [
+                    "m.olm.v1.curve25519-aes-sha2",
+                    "m.megolm.v1.aes-sha2",
+                ],
+                "device_id": "HGKAWHRVJQ",
+                "unsigned": {},
+            },
+        },
+    },
+};
+
+describe('DeviceList', function() {
+    let downloadSpy;
+    let cryptoStore;
+    let deviceLists = [];
+
+    beforeEach(function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        deviceLists = [];
+
+        downloadSpy = expect.createSpy();
+        cryptoStore = new MemoryCryptoStore();
+    });
+
+    afterEach(function() {
+        for (const dl of deviceLists) {
+            dl.stop();
+        }
+    });
+
+    function createTestDeviceList() {
+        const baseApis = {
+            downloadKeysForUsers: downloadSpy,
+        };
+        const mockOlm = {
+            verifySignature: function(key, message, signature) {},
+        };
+        const dl = new DeviceList(baseApis, cryptoStore, mockOlm);
+        deviceLists.push(dl);
+        return dl;
+    }
+
+    it("should successfully download and store device keys", function() {
+        const dl = createTestDeviceList();
+
+        dl.startTrackingDeviceList('@test1:sw1v.org');
+
+        const queryDefer1 = Promise.defer();
+        downloadSpy.andReturn(queryDefer1.promise);
+
+        const prom1 = dl.refreshOutdatedDeviceLists();
+        expect(downloadSpy).toHaveBeenCalledWith(['@test1:sw1v.org'], {});
+        queryDefer1.resolve(utils.deepCopy(signedDeviceList));
+
+        return prom1.then(() => {
+            const storedKeys = dl.getRawStoredDevicesForUser('@test1:sw1v.org');
+            expect(Object.keys(storedKeys)).toEqual(['HGKAWHRVJQ']);
+        });
+    });
+
+    it("should have an outdated devicelist on an invalidation while an " +
+       "update is in progress", function() {
+        const dl = createTestDeviceList();
+
+        dl.startTrackingDeviceList('@test1:sw1v.org');
+
+        const queryDefer1 = Promise.defer();
+        downloadSpy.andReturn(queryDefer1.promise);
+
+        const prom1 = dl.refreshOutdatedDeviceLists();
+        expect(downloadSpy).toHaveBeenCalledWith(['@test1:sw1v.org'], {});
+        downloadSpy.reset();
+
+        // outdated notif arrives while the request is in flight.
+        const queryDefer2 = Promise.defer();
+        downloadSpy.andReturn(queryDefer2.promise);
+
+        dl.invalidateUserDeviceList('@test1:sw1v.org');
+        dl.refreshOutdatedDeviceLists();
+
+        dl.saveIfDirty().then(() => {
+            // the first request completes
+            queryDefer1.resolve({
+                device_keys: {
+                    '@test1:sw1v.org': {},
+                },
+            });
+            return prom1;
+        }).then(() => {
+            // uh-oh; user restarts before second request completes. The new instance
+            // should know we never got a complete device list.
+            logger.log("Creating new devicelist to simulate app reload");
+            downloadSpy.reset();
+            const dl2 = createTestDeviceList();
+            const queryDefer3 = Promise.defer();
+            downloadSpy.andReturn(queryDefer3.promise);
+
+            const prom3 = dl2.refreshOutdatedDeviceLists();
+            expect(downloadSpy).toHaveBeenCalledWith(['@test1:sw1v.org'], {});
+
+            queryDefer3.resolve(utils.deepCopy(signedDeviceList));
+
+            // allow promise chain to complete
+            return prom3;
+        }).then(() => {
+            const storedKeys = dl.getRawStoredDevicesForUser('@test1:sw1v.org');
+            expect(Object.keys(storedKeys)).toEqual(['HGKAWHRVJQ']);
+        });
+    });
+});

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

@@ -0,0 +1,350 @@
+import '../../../olm-loader';
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+import sdk from '../../../..';
+import algorithms from '../../../../lib/crypto/algorithms';
+import MemoryCryptoStore from '../../../../lib/crypto/store/memory-crypto-store.js';
+import MockStorageApi from '../../../MockStorageApi';
+import testUtils from '../../../test-utils';
+import OlmDevice from '../../../../lib/crypto/OlmDevice';
+import Crypto from '../../../../lib/crypto';
+import logger from '../../../../src/logger';
+
+const MatrixEvent = sdk.MatrixEvent;
+const MegolmDecryption = algorithms.DECRYPTION_CLASSES['m.megolm.v1.aes-sha2'];
+const MegolmEncryption = algorithms.ENCRYPTION_CLASSES['m.megolm.v1.aes-sha2'];
+
+const ROOM_ID = '!ROOM:ID';
+
+const Olm = global.Olm;
+
+describe("MegolmDecryption", function() {
+    if (!global.Olm) {
+        logger.warn('Not running megolm unit tests: libolm not present');
+        return;
+    }
+
+    let megolmDecryption;
+    let mockOlmLib;
+    let mockCrypto;
+    let mockBaseApis;
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        await Olm.init();
+
+        mockCrypto = testUtils.mock(Crypto, 'Crypto');
+        mockBaseApis = {};
+
+        const mockStorage = new MockStorageApi();
+        const cryptoStore = new MemoryCryptoStore(mockStorage);
+
+        const olmDevice = new OlmDevice(cryptoStore);
+
+        megolmDecryption = new MegolmDecryption({
+            userId: '@user:id',
+            crypto: mockCrypto,
+            olmDevice: olmDevice,
+            baseApis: mockBaseApis,
+            roomId: ROOM_ID,
+        });
+
+
+        // we stub out the olm encryption bits
+        mockOlmLib = {};
+        mockOlmLib.ensureOlmSessionsForDevices = expect.createSpy();
+        mockOlmLib.encryptMessageForDevice =
+            expect.createSpy().andReturn(Promise.resolve());
+        megolmDecryption.olmlib = mockOlmLib;
+    });
+
+    describe('receives some keys:', function() {
+        let groupSession;
+        beforeEach(async function() {
+            groupSession = new global.Olm.OutboundGroupSession();
+            groupSession.create();
+
+            // construct a fake decrypted key event via the use of a mocked
+            // 'crypto' implementation.
+            const event = new MatrixEvent({
+                type: 'm.room.encrypted',
+            });
+            const decryptedData = {
+                clearEvent: {
+                    type: 'm.room_key',
+                    content: {
+                        algorithm: 'm.megolm.v1.aes-sha2',
+                        room_id: ROOM_ID,
+                        session_id: groupSession.session_id(),
+                        session_key: groupSession.session_key(),
+                    },
+                },
+                senderCurve25519Key: "SENDER_CURVE25519",
+                claimedEd25519Key: "SENDER_ED25519",
+            };
+
+            const mockCrypto = {
+                decryptEvent: function() {
+                    return Promise.resolve(decryptedData);
+                },
+            };
+
+            await event.attemptDecryption(mockCrypto).then(() => {
+                megolmDecryption.onRoomKeyEvent(event);
+            });
+        });
+
+        it('can decrypt an event', function() {
+            const event = new MatrixEvent({
+                type: 'm.room.encrypted',
+                room_id: ROOM_ID,
+                content: {
+                    algorithm: 'm.megolm.v1.aes-sha2',
+                    sender_key: "SENDER_CURVE25519",
+                    session_id: groupSession.session_id(),
+                    ciphertext: groupSession.encrypt(JSON.stringify({
+                        room_id: ROOM_ID,
+                        content: 'testytest',
+                    })),
+                },
+            });
+
+            return megolmDecryption.decryptEvent(event).then((res) => {
+                expect(res.clearEvent.content).toEqual('testytest');
+            });
+        });
+
+        it('can respond to a key request event', function() {
+            const keyRequest = {
+                userId: '@alice:foo',
+                deviceId: 'alidevice',
+                requestBody: {
+                    room_id: ROOM_ID,
+                    sender_key: "SENDER_CURVE25519",
+                    session_id: groupSession.session_id(),
+                },
+            };
+
+            return megolmDecryption.hasKeysForKeyRequest(
+                keyRequest,
+            ).then((hasKeys) => {
+                expect(hasKeys).toBe(true);
+
+                // set up some pre-conditions for the share call
+                const deviceInfo = {};
+                mockCrypto.getStoredDevice.andReturn(deviceInfo);
+
+                mockOlmLib.ensureOlmSessionsForDevices.andReturn(
+                    Promise.resolve({'@alice:foo': {'alidevice': {
+                        sessionId: 'alisession',
+                    }}}),
+                );
+
+                const awaitEncryptForDevice = new Promise((res, rej) => {
+                    mockOlmLib.encryptMessageForDevice.andCall(() => {
+                        res();
+                        return Promise.resolve();
+                    });
+                });
+
+                mockBaseApis.sendToDevice = expect.createSpy();
+
+                // do the share
+                megolmDecryption.shareKeysWithDevice(keyRequest);
+
+                // it's asynchronous, so we have to wait a bit
+                return awaitEncryptForDevice;
+            }).then(() => {
+                // check that it called encryptMessageForDevice with
+                // appropriate args.
+                expect(mockOlmLib.encryptMessageForDevice.calls.length)
+                    .toEqual(1);
+
+                const call = mockOlmLib.encryptMessageForDevice.calls[0];
+                const payload = call.arguments[6];
+
+                expect(payload.type).toEqual("m.forwarded_room_key");
+                expect(payload.content).toInclude({
+                    sender_key: "SENDER_CURVE25519",
+                    sender_claimed_ed25519_key: "SENDER_ED25519",
+                    session_id: groupSession.session_id(),
+                    chain_index: 0,
+                    forwarding_curve25519_key_chain: [],
+                });
+                expect(payload.content.session_key).toExist();
+            });
+        });
+
+        it("can detect replay attacks", function() {
+            // trying to decrypt two different messages (marked by different
+            // event IDs or timestamps) using the same (sender key, session id,
+            // message index) triple should result in an exception being thrown
+            // as it should be detected as a replay attack.
+            const sessionId = groupSession.session_id();
+            const cipherText = groupSession.encrypt(JSON.stringify({
+                room_id: ROOM_ID,
+                content: 'testytest',
+            }));
+            const event1 = new MatrixEvent({
+                type: 'm.room.encrypted',
+                room_id: ROOM_ID,
+                content: {
+                    algorithm: 'm.megolm.v1.aes-sha2',
+                    sender_key: "SENDER_CURVE25519",
+                    session_id: sessionId,
+                    ciphertext: cipherText,
+                },
+                event_id: "$event1",
+                origin_server_ts: 1507753886000,
+            });
+
+            const successHandler = expect.createSpy();
+            const failureHandler = expect.createSpy()
+                .andCall((err) => {
+                    expect(err.toString()).toMatch(
+                        /Duplicate message index, possible replay attack/,
+                    );
+                });
+
+            return megolmDecryption.decryptEvent(event1).then((res) => {
+                const event2 = new MatrixEvent({
+                    type: 'm.room.encrypted',
+                    room_id: ROOM_ID,
+                    content: {
+                        algorithm: 'm.megolm.v1.aes-sha2',
+                        sender_key: "SENDER_CURVE25519",
+                        session_id: sessionId,
+                        ciphertext: cipherText,
+                    },
+                    event_id: "$event2",
+                    origin_server_ts: 1507754149000,
+                });
+
+                return megolmDecryption.decryptEvent(event2);
+            }).then(
+                successHandler,
+                failureHandler,
+            ).then(() => {
+                expect(successHandler).toNotHaveBeenCalled();
+                expect(failureHandler).toHaveBeenCalled();
+            });
+        });
+
+        it("allows re-decryption of the same event", function() {
+            // in contrast with the previous test, if the event ID and
+            // timestamp are the same, then it should not be considered a
+            // replay attack
+            const sessionId = groupSession.session_id();
+            const cipherText = groupSession.encrypt(JSON.stringify({
+                room_id: ROOM_ID,
+                content: 'testytest',
+            }));
+            const event = new MatrixEvent({
+                type: 'm.room.encrypted',
+                room_id: ROOM_ID,
+                content: {
+                    algorithm: 'm.megolm.v1.aes-sha2',
+                    sender_key: "SENDER_CURVE25519",
+                    session_id: sessionId,
+                    ciphertext: cipherText,
+                },
+                event_id: "$event1",
+                origin_server_ts: 1507753886000,
+            });
+
+            return megolmDecryption.decryptEvent(event).then((res) => {
+                return megolmDecryption.decryptEvent(event);
+                // test is successful if no exception is thrown
+            });
+        });
+
+        it("re-uses sessions for sequential messages", async function() {
+            const mockStorage = new MockStorageApi();
+            const cryptoStore = new MemoryCryptoStore(mockStorage);
+
+            const olmDevice = new OlmDevice(cryptoStore);
+            olmDevice.verifySignature = expect.createSpy();
+            await olmDevice.init();
+
+            mockBaseApis.claimOneTimeKeys = expect.createSpy().andReturn(Promise.resolve({
+                one_time_keys: {
+                    '@alice:home.server': {
+                        aliceDevice: {
+                            'signed_curve25519:flooble': {
+                                key: 'YmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmI',
+                                signatures: {
+                                    '@alice:home.server': {
+                                        'ed25519:aliceDevice': 'totally valid',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            }));
+            mockBaseApis.sendToDevice = expect.createSpy().andReturn(Promise.resolve());
+
+            mockCrypto.downloadKeys.andReturn(Promise.resolve({
+                '@alice:home.server': {
+                    aliceDevice: {
+                        deviceId: 'aliceDevice',
+                        isBlocked: expect.createSpy().andReturn(false),
+                        isUnverified: expect.createSpy().andReturn(false),
+                        getIdentityKey: expect.createSpy().andReturn(
+                            'YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE',
+                        ),
+                        getFingerprint: expect.createSpy().andReturn(''),
+                    },
+                },
+            }));
+
+            const megolmEncryption = new MegolmEncryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: mockBaseApis,
+                roomId: ROOM_ID,
+                config: {
+                    rotation_period_ms: 9999999999999,
+                },
+            });
+            const mockRoom = {
+                getEncryptionTargetMembers: expect.createSpy().andReturn(
+                    [{userId: "@alice:home.server"}],
+                ),
+                getBlacklistUnverifiedDevices: expect.createSpy().andReturn(false),
+            };
+            const ct1 = await megolmEncryption.encryptMessage(mockRoom, "a.fake.type", {
+                body: "Some text",
+            });
+            expect(mockRoom.getEncryptionTargetMembers).toHaveBeenCalled();
+
+            // this should have claimed a key for alice as it's starting a new session
+            expect(mockBaseApis.claimOneTimeKeys).toHaveBeenCalled(
+                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519',
+            );
+            expect(mockCrypto.downloadKeys).toHaveBeenCalledWith(
+                ['@alice:home.server'], false,
+            );
+            expect(mockBaseApis.sendToDevice).toHaveBeenCalled();
+            expect(mockBaseApis.claimOneTimeKeys).toHaveBeenCalled(
+                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519',
+            );
+
+            mockBaseApis.claimOneTimeKeys.reset();
+
+            const ct2 = await megolmEncryption.encryptMessage(mockRoom, "a.fake.type", {
+                body: "Some more text",
+            });
+
+            // this should *not* have claimed a key as it should be using the same session
+            expect(mockBaseApis.claimOneTimeKeys).toNotHaveBeenCalled();
+
+            // likewise they should show the same session ID
+            expect(ct2.session_id).toEqual(ct1.session_id);
+        });
+    });
+});

spec/unit/crypto/algorithms/olm.spec.js

@@ -0,0 +1,143 @@
+/*
+Copyright 2018,2019 New Vector 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.
+*/
+
+import '../../../olm-loader';
+
+import expect from 'expect';
+import MemoryCryptoStore from '../../../../lib/crypto/store/memory-crypto-store.js';
+import MockStorageApi from '../../../MockStorageApi';
+import testUtils from '../../../test-utils';
+import logger from '../../../../src/logger';
+
+import OlmDevice from '../../../../lib/crypto/OlmDevice';
+import olmlib from '../../../../lib/crypto/olmlib';
+import DeviceInfo from '../../../../lib/crypto/deviceinfo';
+
+function makeOlmDevice() {
+    const mockStorage = new MockStorageApi();
+    const cryptoStore = new MemoryCryptoStore(mockStorage);
+    const olmDevice = new OlmDevice(cryptoStore);
+    return olmDevice;
+}
+
+async function setupSession(initiator, opponent) {
+    await opponent.generateOneTimeKeys(1);
+    const keys = await opponent.getOneTimeKeys();
+    const firstKey = Object.values(keys['curve25519'])[0];
+
+    const sid = await initiator.createOutboundSession(
+        opponent.deviceCurve25519Key, firstKey,
+    );
+    return sid;
+}
+
+describe("OlmDecryption", function() {
+    if (!global.Olm) {
+        logger.warn('Not running megolm unit tests: libolm not present');
+        return;
+    }
+
+    let aliceOlmDevice;
+    let bobOlmDevice;
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        await global.Olm.init();
+
+        aliceOlmDevice = makeOlmDevice();
+        bobOlmDevice = makeOlmDevice();
+        await aliceOlmDevice.init();
+        await bobOlmDevice.init();
+    });
+
+    describe('olm', function() {
+        it("can decrypt messages", async function() {
+            const sid = await setupSession(aliceOlmDevice, bobOlmDevice);
+
+            const ciphertext = await aliceOlmDevice.encryptMessage(
+                bobOlmDevice.deviceCurve25519Key,
+                sid,
+                "The olm or proteus is an aquatic salamander in the family Proteidae",
+            );
+
+            const result = await bobOlmDevice.createInboundSession(
+                aliceOlmDevice.deviceCurve25519Key,
+                ciphertext.type,
+                ciphertext.body,
+            );
+            expect(result.payload).toEqual(
+                "The olm or proteus is an aquatic salamander in the family Proteidae",
+            );
+        });
+
+        it("creates only one session at a time", async function() {
+            // if we call ensureOlmSessionsForDevices multiple times, it should
+            // only try to create one session at a time, even if the server is
+            // slow
+            let count = 0;
+            const baseApis = {
+                claimOneTimeKeys: () => {
+                    // simulate a very slow server (.5 seconds to respond)
+                    count++;
+                    return new Promise((resolve, reject) => {
+                        setTimeout(reject, 500);
+                    });
+                },
+            };
+            const devicesByUser = {
+                "@bob:example.com": [
+                    DeviceInfo.fromStorage({
+                        keys: {
+                            "curve25519:ABCDEFG": "akey",
+                        },
+                    }, "ABCDEFG"),
+                ],
+            };
+            function alwaysSucceed(promise) {
+                // swallow any exception thrown by a promise, so that
+                // Promise.all doesn't abort
+                return promise.catch(() => {});
+            }
+
+            // start two tasks that try to ensure that there's an olm session
+            const promises = Promise.all([
+                alwaysSucceed(olmlib.ensureOlmSessionsForDevices(
+                    aliceOlmDevice, baseApis, devicesByUser,
+                )),
+                alwaysSucceed(olmlib.ensureOlmSessionsForDevices(
+                    aliceOlmDevice, baseApis, devicesByUser,
+                )),
+            ]);
+
+            await new Promise((resolve) => {
+                setTimeout(resolve, 200);
+            });
+
+            // after .2s, both tasks should have started, but one should be
+            // waiting on the other before trying to create a session, so
+            // claimOneTimeKeys should have only been called once
+            expect(count).toBe(1);
+
+            await promises;
+
+            // after waiting for both tasks to complete, the first task should
+            // have failed, so the second task should have tried to create a
+            // new session and will have called claimOneTimeKeys
+            expect(count).toBe(2);
+        });
+    });
+});

spec/unit/crypto/backup.spec.js

@@ -0,0 +1,472 @@
+/*
+Copyright 2018 New Vector 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.
+*/
+
+import '../../olm-loader';
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+import sdk from '../../..';
+import algorithms from '../../../lib/crypto/algorithms';
+import WebStorageSessionStore from '../../../lib/store/session/webstorage';
+import MemoryCryptoStore from '../../../lib/crypto/store/memory-crypto-store.js';
+import MockStorageApi from '../../MockStorageApi';
+import testUtils from '../../test-utils';
+
+import OlmDevice from '../../../lib/crypto/OlmDevice';
+import Crypto from '../../../lib/crypto';
+import logger from '../../../src/logger';
+
+const Olm = global.Olm;
+
+const MatrixClient = sdk.MatrixClient;
+const MatrixEvent = sdk.MatrixEvent;
+const MegolmDecryption = algorithms.DECRYPTION_CLASSES['m.megolm.v1.aes-sha2'];
+
+const ROOM_ID = '!ROOM:ID';
+
+const SESSION_ID = 'o+21hSjP+mgEmcfdslPsQdvzWnkdt0Wyo00Kp++R8Kc';
+const ENCRYPTED_EVENT = new MatrixEvent({
+    type: 'm.room.encrypted',
+    room_id: '!ROOM:ID',
+    content: {
+        algorithm: 'm.megolm.v1.aes-sha2',
+        sender_key: 'SENDER_CURVE25519',
+        session_id: SESSION_ID,
+        ciphertext: 'AwgAEjD+VwXZ7PoGPRS/H4kwpAsMp/g+WPvJVtPEKE8fmM9IcT/N'
+            + 'CiwPb8PehecDKP0cjm1XO88k6Bw3D17aGiBHr5iBoP7oSw8CXULXAMTkBl'
+            + 'mkufRQq2+d0Giy1s4/Cg5n13jSVrSb2q7VTSv1ZHAFjUCsLSfR0gxqcQs',
+    },
+    event_id: '$event1',
+    origin_server_ts: 1507753886000,
+});
+
+const KEY_BACKUP_DATA = {
+    first_message_index: 0,
+    forwarded_count: 0,
+    is_verified: false,
+    session_data: {
+        ciphertext: '2z2M7CZ+azAiTHN1oFzZ3smAFFt+LEOYY6h3QO3XXGdw'
+            + '6YpNn/gpHDO6I/rgj1zNd4FoTmzcQgvKdU8kN20u5BWRHxaHTZ'
+            + 'Slne5RxE6vUdREsBgZePglBNyG0AogR/PVdcrv/v18Y6rLM5O9'
+            + 'SELmwbV63uV9Kuu/misMxoqbuqEdG7uujyaEKtjlQsJ5MGPQOy'
+            + 'Syw7XrnesSwF6XWRMxcPGRV0xZr3s9PI350Wve3EncjRgJ9IGF'
+            + 'ru1bcptMqfXgPZkOyGvrphHoFfoK7nY3xMEHUiaTRfRIjq8HNV'
+            + '4o8QY1qmWGnxNBQgOlL8MZlykjg3ULmQ3DtFfQPj/YYGS3jzxv'
+            + 'C+EBjaafmsg+52CTeK3Rswu72PX450BnSZ1i3If4xWAUKvjTpe'
+            + 'Ug5aDLqttOv1pITolTJDw5W/SD+b5rjEKg1CFCHGEGE9wwV3Nf'
+            + 'QHVCQL+dfpd7Or0poy4dqKMAi3g0o3Tg7edIF8d5rREmxaALPy'
+            + 'iie8PHD8mj/5Y0GLqrac4CD6+Mop7eUTzVovprjg',
+        mac: '5lxYBHQU80M',
+        ephemeral: '/Bn0A4UMFwJaDDvh0aEk1XZj3k1IfgCxgFY9P9a0b14',
+    },
+};
+
+const BACKUP_INFO = {
+    algorithm: "m.megolm_backup.v1",
+    version: 1,
+    auth_data: {
+        public_key: "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+    },
+};
+
+function makeTestClient(sessionStore, cryptoStore) {
+    const scheduler = [
+        "getQueueForEvent", "queueEvent", "removeEventFromQueue",
+        "setProcessFunction",
+    ].reduce((r, k) => {r[k] = expect.createSpy(); return r;}, {});
+    const store = [
+        "getRoom", "getRooms", "getUser", "getSyncToken", "scrollback",
+        "save", "wantsSave", "setSyncToken", "storeEvents", "storeRoom",
+        "storeUser", "getFilterIdByName", "setFilterIdByName", "getFilter",
+        "storeFilter", "getSyncAccumulator", "startup", "deleteAllData",
+    ].reduce((r, k) => {r[k] = expect.createSpy(); return r;}, {});
+    store.getSavedSync = expect.createSpy().andReturn(Promise.resolve(null));
+    store.getSavedSyncToken = expect.createSpy().andReturn(Promise.resolve(null));
+    store.setSyncData = expect.createSpy().andReturn(Promise.resolve(null));
+    return new MatrixClient({
+        baseUrl: "https://my.home.server",
+        idBaseUrl: "https://identity.server",
+        accessToken: "my.access.token",
+        request: function() {}, // NOP
+        store: store,
+        scheduler: scheduler,
+        userId: "@alice:bar",
+        deviceId: "device",
+        sessionStore: sessionStore,
+        cryptoStore: cryptoStore,
+    });
+}
+
+describe("MegolmBackup", function() {
+    if (!global.Olm) {
+        logger.warn('Not running megolm backup unit tests: libolm not present');
+        return;
+    }
+
+    let olmDevice;
+    let mockOlmLib;
+    let mockCrypto;
+    let mockStorage;
+    let sessionStore;
+    let cryptoStore;
+    let megolmDecryption;
+    beforeEach(async function() {
+        await Olm.init();
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        mockCrypto = testUtils.mock(Crypto, 'Crypto');
+        mockCrypto.backupKey = new Olm.PkEncryption();
+        mockCrypto.backupKey.set_recipient_key(
+            "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+        );
+        mockCrypto.backupInfo = BACKUP_INFO;
+
+        mockStorage = new MockStorageApi();
+        sessionStore = new WebStorageSessionStore(mockStorage);
+        cryptoStore = new MemoryCryptoStore(mockStorage);
+
+        olmDevice = new OlmDevice(cryptoStore);
+
+        // we stub out the olm encryption bits
+        mockOlmLib = {};
+        mockOlmLib.ensureOlmSessionsForDevices = expect.createSpy();
+        mockOlmLib.encryptMessageForDevice =
+            expect.createSpy().andReturn(Promise.resolve());
+    });
+
+    describe("backup", function() {
+        let mockBaseApis;
+        let realSetTimeout;
+
+        beforeEach(function() {
+            mockBaseApis = {};
+
+            megolmDecryption = new MegolmDecryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: mockBaseApis,
+                roomId: ROOM_ID,
+            });
+
+            megolmDecryption.olmlib = mockOlmLib;
+
+            // clobber the setTimeout function to run 100x faster.
+            // ideally we would use lolex, but we have no oportunity
+            // to tick the clock between the first try and the retry.
+            realSetTimeout = global.setTimeout;
+            global.setTimeout = function(f, n) {
+                return realSetTimeout(f, n/100);
+            };
+        });
+
+        afterEach(function() {
+            global.setTimeout = realSetTimeout;
+        });
+
+        it('automatically calls the key back up', function() {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+
+            // construct a fake decrypted key event via the use of a mocked
+            // 'crypto' implementation.
+            const event = new MatrixEvent({
+                type: 'm.room.encrypted',
+            });
+            const decryptedData = {
+                clearEvent: {
+                    type: 'm.room_key',
+                    content: {
+                        algorithm: 'm.megolm.v1.aes-sha2',
+                        room_id: ROOM_ID,
+                        session_id: groupSession.session_id(),
+                        session_key: groupSession.session_key(),
+                    },
+                },
+                senderCurve25519Key: "SENDER_CURVE25519",
+                claimedEd25519Key: "SENDER_ED25519",
+            };
+
+            mockCrypto.decryptEvent = function() {
+                return Promise.resolve(decryptedData);
+            };
+            mockCrypto.cancelRoomKeyRequest = function() {};
+
+            mockCrypto.backupGroupSession = expect.createSpy();
+
+            return event.attemptDecryption(mockCrypto).then(() => {
+                return megolmDecryption.onRoomKeyEvent(event);
+            }).then(() => {
+                expect(mockCrypto.backupGroupSession).toHaveBeenCalled();
+            });
+        });
+
+        it('sends backups to the server', 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 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: "m.megolm_backup.v1",
+                        version: 1,
+                        auth_data: {
+                            public_key: "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+                        },
+                    });
+                    let numCalls = 0;
+                    return new Promise((resolve, reject) => {
+                        client._http.authedRequest = function(
+                            callback, method, path, queryParams, data, opts,
+                        ) {
+                            ++numCalls;
+                            expect(numCalls).toBeLessThanOrEqualTo(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).toExist();
+                            expect(data.rooms[ROOM_ID].sessions).toIncludeKey(
+                                groupSession.session_id(),
+                            );
+                            resolve();
+                            return Promise.resolve({});
+                        };
+                        client._crypto.backupGroupSession(
+                            "roomId",
+                            "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
+                            [],
+                            groupSession.session_id(),
+                            groupSession.session_key(),
+                        );
+                    }).then(() => {
+                        expect(numCalls).toBe(1);
+                    });
+                });
+        });
+
+        it('retries when a backup fails', function() {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+            const ibGroupSession = new Olm.InboundGroupSession();
+            ibGroupSession.create(groupSession.session_key());
+
+            const scheduler = [
+                "getQueueForEvent", "queueEvent", "removeEventFromQueue",
+                "setProcessFunction",
+            ].reduce((r, k) => {r[k] = expect.createSpy(); return r;}, {});
+            const store = [
+                "getRoom", "getRooms", "getUser", "getSyncToken", "scrollback",
+                "save", "wantsSave", "setSyncToken", "storeEvents", "storeRoom",
+                "storeUser", "getFilterIdByName", "setFilterIdByName", "getFilter",
+                "storeFilter", "getSyncAccumulator", "startup", "deleteAllData",
+            ].reduce((r, k) => {r[k] = expect.createSpy(); return r;}, {});
+            store.getSavedSync = expect.createSpy().andReturn(Promise.resolve(null));
+            store.getSavedSyncToken = expect.createSpy().andReturn(Promise.resolve(null));
+            store.setSyncData = expect.createSpy().andReturn(Promise.resolve(null));
+            const client = new MatrixClient({
+                baseUrl: "https://my.home.server",
+                idBaseUrl: "https://identity.server",
+                accessToken: "my.access.token",
+                request: function() {}, // NOP
+                store: store,
+                scheduler: scheduler,
+                userId: "@alice:bar",
+                deviceId: "device",
+                sessionStore: sessionStore,
+                cryptoStore: cryptoStore,
+            });
+
+            megolmDecryption = new MegolmDecryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: client,
+                roomId: ROOM_ID,
+            });
+
+            megolmDecryption.olmlib = mockOlmLib;
+
+            return client.initCrypto()
+                .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: "foobar",
+                        version: 1,
+                        auth_data: {
+                            public_key: "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+                        },
+                    });
+                    let numCalls = 0;
+                    return new Promise((resolve, reject) => {
+                        client._http.authedRequest = function(
+                            callback, method, path, queryParams, data, opts,
+                        ) {
+                            ++numCalls;
+                            expect(numCalls).toBeLessThanOrEqualTo(2);
+                            if (numCalls >= 3) {
+                                // 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).toExist();
+                            expect(data.rooms[ROOM_ID].sessions).toIncludeKey(
+                                groupSession.session_id(),
+                            );
+                            if (numCalls > 1) {
+                                resolve();
+                                return Promise.resolve({});
+                            } else {
+                                return Promise.reject(
+                                    new Error("this is an expected failure"),
+                                );
+                            }
+                        };
+                        client._crypto.backupGroupSession(
+                            "roomId",
+                            "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
+                            [],
+                            groupSession.session_id(),
+                            groupSession.session_key(),
+                        );
+                    }).then(() => {
+                        expect(numCalls).toBe(2);
+                    });
+                });
+        });
+    });
+
+    describe("restore", function() {
+        let client;
+
+        beforeEach(function() {
+            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();
+        });
+
+        afterEach(function() {
+            client.stopClient();
+        });
+
+        it('can restore from backup', function() {
+            client._http.authedRequest = function() {
+                return Promise.resolve(KEY_BACKUP_DATA);
+            };
+            return client.restoreKeyBackupWithRecoveryKey(
+                "EsTc LW2K PGiF wKEA 3As5 g5c4 BXwk qeeJ ZJV8 Q9fu gUMN UE4d",
+                ROOM_ID,
+                SESSION_ID,
+                BACKUP_INFO,
+            ).then(() => {
+                return megolmDecryption.decryptEvent(ENCRYPTED_EVENT);
+            }).then((res) => {
+                expect(res.clearEvent.content).toEqual('testytest');
+            });
+        });
+
+        it('can restore backup by room', function() {
+            client._http.authedRequest = function() {
+                return Promise.resolve({
+                    rooms: {
+                        [ROOM_ID]: {
+                            sessions: {
+                                [SESSION_ID]: KEY_BACKUP_DATA,
+                            },
+                        },
+                    },
+                });
+            };
+            return client.restoreKeyBackupWithRecoveryKey(
+                "EsTc LW2K PGiF wKEA 3As5 g5c4 BXwk qeeJ ZJV8 Q9fu gUMN UE4d",
+                null, null, BACKUP_INFO,
+            ).then(() => {
+                return megolmDecryption.decryptEvent(ENCRYPTED_EVENT);
+            }).then((res) => {
+                expect(res.clearEvent.content).toEqual('testytest');
+            });
+        });
+    });
+});

spec/unit/crypto/verification/qr_code.spec.js

@@ -0,0 +1,146 @@
+/*
+Copyright 2018-2019 New Vector 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.
+*/
+import logger from '../../../../src/logger';
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    logger.warn("unable to run device verification tests: libolm not available");
+}
+
+import expect from 'expect';
+import DeviceInfo from '../../../../lib/crypto/deviceinfo';
+
+import {ShowQRCode, ScanQRCode} from '../../../../lib/crypto/verification/QRCode';
+
+const Olm = global.Olm;
+
+describe("QR code verification", function() {
+    if (!global.Olm) {
+        logger.warn('Not running device verification tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await Olm.init();
+    });
+
+    describe("showing", function() {
+        it("should emit an event to show a QR code", async function() {
+            const qrCode = new ShowQRCode({
+                getUserId: () => "@alice:example.com",
+                deviceId: "ABCDEFG",
+                getDeviceEd25519Key: function() {
+                    return "device+ed25519+key";
+                },
+            });
+            const spy = expect.createSpy().andCall((e) => {
+                qrCode.done();
+            });
+            qrCode.on("show_qr_code", spy);
+            await qrCode.verify();
+            expect(spy).toHaveBeenCalledWith({
+                url: "https://matrix.to/#/@alice:example.com?device=ABCDEFG"
+                    + "&action=verify&key_ed25519%3AABCDEFG=device%2Bed25519%2Bkey",
+            });
+        });
+    });
+
+    describe("scanning", function() {
+        const QR_CODE_URL = "https://matrix.to/#/@alice:example.com?device=ABCDEFG"
+              + "&action=verify&key_ed25519%3AABCDEFG=device%2Bed25519%2Bkey";
+        it("should verify when a QR code is sent", async function() {
+            const device = DeviceInfo.fromStorage(
+                {
+                    algorithms: [],
+                    keys: {
+                        "curve25519:ABCDEFG": "device+curve25519+key",
+                        "ed25519:ABCDEFG": "device+ed25519+key",
+                    },
+                    verified: false,
+                    known: false,
+                    unsigned: {},
+                },
+                "ABCDEFG",
+            );
+            const client = {
+                getStoredDevice: expect.createSpy().andReturn(device),
+                setDeviceVerified: expect.createSpy(),
+            };
+            const qrCode = new ScanQRCode(client);
+            qrCode.on("confirm_user_id", ({userId, confirm}) => {
+                if (userId === "@alice:example.com") {
+                    confirm();
+                } else {
+                    qrCode.cancel(new Error("Incorrect user"));
+                }
+            });
+            qrCode.on("scan", ({done}) => {
+                done(QR_CODE_URL);
+            });
+            await qrCode.verify();
+            expect(client.getStoredDevice)
+                .toHaveBeenCalledWith("@alice:example.com", "ABCDEFG");
+            expect(client.setDeviceVerified)
+                .toHaveBeenCalledWith("@alice:example.com", "ABCDEFG");
+        });
+
+        it("should error when the user ID doesn't match", async function() {
+            const client = {
+                getStoredDevice: expect.createSpy(),
+                setDeviceVerified: expect.createSpy(),
+            };
+            const qrCode = new ScanQRCode(client, "@bob:example.com", "ABCDEFG");
+            qrCode.on("scan", ({done}) => {
+                done(QR_CODE_URL);
+            });
+            const spy = expect.createSpy();
+            await qrCode.verify().catch(spy);
+            expect(spy).toHaveBeenCalled();
+            expect(client.getStoredDevice).toNotHaveBeenCalled();
+            expect(client.setDeviceVerified).toNotHaveBeenCalled();
+        });
+
+        it("should error if the key doesn't match", async function() {
+            const device = DeviceInfo.fromStorage(
+                {
+                    algorithms: [],
+                    keys: {
+                        "curve25519:ABCDEFG": "device+curve25519+key",
+                        "ed25519:ABCDEFG": "a+different+device+ed25519+key",
+                    },
+                    verified: false,
+                    known: false,
+                    unsigned: {},
+                },
+                "ABCDEFG",
+            );
+            const client = {
+                getStoredDevice: expect.createSpy().andReturn(device),
+                setDeviceVerified: expect.createSpy(),
+            };
+            const qrCode = new ScanQRCode(client, "@alice:example.com", "ABCDEFG");
+            qrCode.on("scan", ({done}) => {
+                done(QR_CODE_URL);
+            });
+            const spy = expect.createSpy();
+            await qrCode.verify().catch(spy);
+            expect(spy).toHaveBeenCalled();
+            expect(client.getStoredDevice).toHaveBeenCalled();
+            expect(client.setDeviceVerified).toNotHaveBeenCalled();
+        });
+    });
+});

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

@@ -0,0 +1,82 @@
+/*
+Copyright 2019 New Vector 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.
+*/
+import logger from '../../../../src/logger';
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    logger.warn("unable to run device verification tests: libolm not available");
+}
+
+import expect from 'expect';
+
+import {verificationMethods} from '../../../../lib/crypto';
+
+import SAS from '../../../../lib/crypto/verification/SAS';
+
+const Olm = global.Olm;
+
+import {makeTestClients} from './util';
+
+describe("verification request", function() {
+    if (!global.Olm) {
+        logger.warn('Not running device verification unit tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await Olm.init();
+    });
+
+    it("should request and accept a verification", async function() {
+        const [alice, bob] = await makeTestClients(
+            [
+                {userId: "@alice:example.com", deviceId: "Osborne2"},
+                {userId: "@bob:example.com", deviceId: "Dynabook"},
+            ],
+            {
+                verificationMethods: [verificationMethods.SAS],
+            },
+        );
+        alice._crypto._deviceList.getRawStoredDevicesForUser = function() {
+            return {
+                Dynabook: {
+                    keys: {
+                        "ed25519:Dynabook": "bob+base64+ed25519+key",
+                    },
+                },
+            };
+        };
+        alice.downloadKeys = () => {
+            return Promise.resolve();
+        };
+        bob.downloadKeys = () => {
+            return Promise.resolve();
+        };
+        bob.on("crypto.verification.request", (request) => {
+            const bobVerifier = request.beginKeyVerification(verificationMethods.SAS);
+            bobVerifier.verify();
+
+            // XXX: Private function access (but it's a test, so we're okay)
+            bobVerifier._endTimer();
+        });
+        const aliceVerifier = await alice.requestVerification("@bob:example.com");
+        expect(aliceVerifier).toBeAn(SAS);
+
+        // XXX: Private function access (but it's a test, so we're okay)
+        aliceVerifier._endTimer();
+    });
+});

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

@@ -0,0 +1,276 @@
+/*
+Copyright 2018-2019 New Vector 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.
+*/
+import logger from '../../../../src/logger';
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    logger.warn("unable to run device verification tests: libolm not available");
+}
+
+import expect from 'expect';
+
+import sdk from '../../../..';
+
+import {verificationMethods} from '../../../../lib/crypto';
+import DeviceInfo from '../../../../lib/crypto/deviceinfo';
+
+import SAS from '../../../../lib/crypto/verification/SAS';
+
+const Olm = global.Olm;
+
+const MatrixEvent = sdk.MatrixEvent;
+
+import {makeTestClients} from './util';
+
+describe("SAS verification", function() {
+    if (!global.Olm) {
+        logger.warn('Not running device verification unit tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await Olm.init();
+    });
+
+    it("should error on an unexpected event", async function() {
+        const sas = new SAS({}, "@alice:example.com", "ABCDEFG");
+        sas.handleEvent(new MatrixEvent({
+            sender: "@alice:example.com",
+            type: "es.inquisition",
+            content: {},
+        }));
+        const spy = expect.createSpy();
+        await sas.verify()
+            .catch(spy);
+        expect(spy).toHaveBeenCalled();
+
+        // Cancel the SAS for cleanup (we started a verification, so abort)
+        sas.cancel();
+    });
+
+    describe("verification", function() {
+        let alice;
+        let bob;
+        let aliceSasEvent;
+        let bobSasEvent;
+        let aliceVerifier;
+        let bobPromise;
+
+        beforeEach(async function() {
+            [alice, bob] = await makeTestClients(
+                [
+                    {userId: "@alice:example.com", deviceId: "Osborne2"},
+                    {userId: "@bob:example.com", deviceId: "Dynabook"},
+                ],
+                {
+                    verificationMethods: [verificationMethods.SAS],
+                },
+            );
+
+            alice.setDeviceVerified = expect.createSpy();
+            alice.getDeviceEd25519Key = () => {
+                return "alice+base64+ed25519+key";
+            };
+            alice.getStoredDevice = () => {
+                return DeviceInfo.fromStorage(
+                    {
+                        keys: {
+                            "ed25519:Dynabook": "bob+base64+ed25519+key",
+                        },
+                    },
+                    "Dynabook",
+                );
+            };
+            alice.downloadKeys = () => {
+                return Promise.resolve();
+            };
+
+            bob.setDeviceVerified = expect.createSpy();
+            bob.getStoredDevice = () => {
+                return DeviceInfo.fromStorage(
+                    {
+                        keys: {
+                            "ed25519:Osborne2": "alice+base64+ed25519+key",
+                        },
+                    },
+                    "Osborne2",
+                );
+            };
+            bob.getDeviceEd25519Key = () => {
+                return "bob+base64+ed25519+key";
+            };
+            bob.downloadKeys = () => {
+                return Promise.resolve();
+            };
+
+            aliceSasEvent = null;
+            bobSasEvent = null;
+
+            bobPromise = new Promise((resolve, reject) => {
+                bob.on("crypto.verification.start", (verifier) => {
+                    verifier.on("show_sas", (e) => {
+                        if (!e.sas.emoji || !e.sas.decimal) {
+                            e.cancel();
+                        } else if (!aliceSasEvent) {
+                            bobSasEvent = e;
+                        } else {
+                            try {
+                                expect(e.sas).toEqual(aliceSasEvent.sas);
+                                e.confirm();
+                                aliceSasEvent.confirm();
+                            } catch (error) {
+                                e.mismatch();
+                                aliceSasEvent.mismatch();
+                            }
+                        }
+                    });
+                    resolve(verifier);
+                });
+            });
+
+            aliceVerifier = alice.beginKeyVerification(
+                verificationMethods.SAS, bob.getUserId(), bob.deviceId,
+            );
+            aliceVerifier.on("show_sas", (e) => {
+                if (!e.sas.emoji || !e.sas.decimal) {
+                    e.cancel();
+                } else if (!bobSasEvent) {
+                    aliceSasEvent = e;
+                } else {
+                    try {
+                        expect(e.sas).toEqual(bobSasEvent.sas);
+                        e.confirm();
+                        bobSasEvent.confirm();
+                    } catch (error) {
+                        e.mismatch();
+                        bobSasEvent.mismatch();
+                    }
+                }
+            });
+        });
+
+        it("should verify a key", async function() {
+            let macMethod;
+            const origSendToDevice = alice.sendToDevice;
+            bob.sendToDevice = function(type, map) {
+                if (type === "m.key.verification.accept") {
+                    macMethod = map[alice.getUserId()][alice.deviceId]
+                        .message_authentication_code;
+                }
+                return origSendToDevice.call(this, type, map);
+            };
+
+            await Promise.all([
+                aliceVerifier.verify(),
+                bobPromise.then((verifier) => verifier.verify()),
+            ]);
+
+            // make sure that it uses the preferred method
+            expect(macMethod).toBe("hkdf-hmac-sha256");
+
+            // make sure Alice and Bob verified each other
+            expect(alice.setDeviceVerified)
+                .toHaveBeenCalledWith(bob.getUserId(), bob.deviceId);
+            expect(bob.setDeviceVerified)
+                .toHaveBeenCalledWith(alice.getUserId(), alice.deviceId);
+        });
+
+        it("should be able to verify using the old MAC", async function() {
+            // pretend that Alice can only understand the old (incorrect) MAC,
+            // and make sure that she can still verify with Bob
+            let macMethod;
+            const origSendToDevice = alice.sendToDevice;
+            alice.sendToDevice = function(type, map) {
+                if (type === "m.key.verification.start") {
+                    // Note: this modifies not only the message that Bob
+                    // receives, but also the copy of the message that Alice
+                    // has, since it is the same object.  If this does not
+                    // happen, the verification will fail due to a hash
+                    // commitment mismatch.
+                    map[bob.getUserId()][bob.deviceId]
+                        .message_authentication_codes = ['hmac-sha256'];
+                }
+                return origSendToDevice.call(this, type, map);
+            };
+            bob.sendToDevice = function(type, map) {
+                if (type === "m.key.verification.accept") {
+                    macMethod = map[alice.getUserId()][alice.deviceId]
+                        .message_authentication_code;
+                }
+                return origSendToDevice.call(this, type, map);
+            };
+
+            await Promise.all([
+                aliceVerifier.verify(),
+                bobPromise.then((verifier) => verifier.verify()),
+            ]);
+
+            expect(macMethod).toBe("hmac-sha256");
+
+            expect(alice.setDeviceVerified)
+                .toHaveBeenCalledWith(bob.getUserId(), bob.deviceId);
+            expect(bob.setDeviceVerified)
+                .toHaveBeenCalledWith(alice.getUserId(), alice.deviceId);
+        });
+    });
+
+    it("should send a cancellation message on error", async function() {
+        const [alice, bob] = await makeTestClients(
+            [
+                {userId: "@alice:example.com", deviceId: "Osborne2"},
+                {userId: "@bob:example.com", deviceId: "Dynabook"},
+            ],
+            {
+                verificationMethods: [verificationMethods.SAS],
+            },
+        );
+        alice.setDeviceVerified = expect.createSpy();
+        alice.downloadKeys = () => {
+            return Promise.resolve();
+        };
+        bob.setDeviceVerified = expect.createSpy();
+        bob.downloadKeys = () => {
+            return Promise.resolve();
+        };
+
+        const bobPromise = new Promise((resolve, reject) => {
+            bob.on("crypto.verification.start", (verifier) => {
+                verifier.on("show_sas", (e) => {
+                    e.mismatch();
+                });
+                resolve(verifier);
+            });
+        });
+
+        const aliceVerifier = alice.beginKeyVerification(
+            verificationMethods.SAS, bob.getUserId(), bob.deviceId,
+        );
+
+        const aliceSpy = expect.createSpy();
+        const bobSpy = expect.createSpy();
+        await Promise.all([
+            aliceVerifier.verify().catch(aliceSpy),
+            bobPromise.then((verifier) => verifier.verify()).catch(bobSpy),
+        ]);
+        expect(aliceSpy).toHaveBeenCalled();
+        expect(bobSpy).toHaveBeenCalled();
+        expect(alice.setDeviceVerified)
+            .toNotHaveBeenCalled();
+        expect(bob.setDeviceVerified)
+            .toNotHaveBeenCalled();
+    });
+});

spec/unit/crypto/verification/util.js

@@ -0,0 +1,63 @@
+/*
+Copyright 2019 New Vector 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.
+*/
+
+import TestClient from '../../../TestClient';
+
+import sdk from '../../../..';
+const MatrixEvent = sdk.MatrixEvent;
+
+export async function makeTestClients(userInfos, options) {
+    const clients = [];
+    const clientMap = {};
+    const sendToDevice = function(type, map) {
+        // console.log(this.getUserId(), "sends", type, map);
+        for (const [userId, devMap] of Object.entries(map)) {
+            if (userId in clientMap) {
+                for (const [deviceId, msg] of Object.entries(devMap)) {
+                    if (deviceId in clientMap[userId]) {
+                        const event = new MatrixEvent({
+                            sender: this.getUserId(), // eslint-disable-line babel/no-invalid-this
+                            type: type,
+                            content: msg,
+                        });
+                        setTimeout(
+                            () => clientMap[userId][deviceId]
+                                .emit("toDeviceEvent", event),
+                            0,
+                        );
+                    }
+                }
+            }
+        }
+    };
+
+    for (const userInfo of userInfos) {
+        const client = (new TestClient(
+            userInfo.userId, userInfo.deviceId, undefined, undefined,
+            options,
+        )).client;
+        if (!(userInfo.userId in clientMap)) {
+            clientMap[userInfo.userId] = {};
+        }
+        clientMap[userInfo.userId][userInfo.deviceId] = client;
+        client.sendToDevice = sendToDevice;
+        clients.push(client);
+    }
+
+    await Promise.all(clients.map((client) => client.initCrypto()));
+
+    return clients;
+}

spec/unit/event-timeline.spec.js

@@ -0,0 +1,378 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const EventTimeline = sdk.EventTimeline;
+const utils = require("../test-utils");
+
+function mockRoomStates(timeline) {
+    timeline._startState = utils.mock(sdk.RoomState, "startState");
+    timeline._endState = utils.mock(sdk.RoomState, "endState");
+}
+
+import expect from 'expect';
+
+describe("EventTimeline", function() {
+    const roomId = "!foo:bar";
+    const userA = "@alice:bar";
+    const userB = "@bertha:bar";
+    let timeline;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        // XXX: this is a horrid hack; should use sinon or something instead to mock
+        const timelineSet = { room: { roomId: roomId }};
+        timelineSet.room.getUnfilteredTimelineSet = function() {
+            return timelineSet;
+        };
+
+        timeline = new EventTimeline(timelineSet);
+    });
+
+    describe("construction", function() {
+        it("getRoomId should get room id", function() {
+            const v = timeline.getRoomId();
+            expect(v).toEqual(roomId);
+        });
+    });
+
+    describe("initialiseState", function() {
+        beforeEach(function() {
+            mockRoomStates(timeline);
+        });
+
+        it("should copy state events to start and end state", function() {
+            const events = [
+                utils.mkMembership({
+                    room: roomId, mship: "invite", user: userB, skey: userA,
+                    event: true,
+                }),
+                utils.mkEvent({
+                    type: "m.room.name", room: roomId, user: userB,
+                    event: true,
+                    content: { name: "New room" },
+                }),
+            ];
+            timeline.initialiseState(events);
+            expect(timeline._startState.setStateEvents).toHaveBeenCalledWith(
+                events,
+            );
+            expect(timeline._endState.setStateEvents).toHaveBeenCalledWith(
+                events,
+            );
+        });
+
+        it("should raise an exception if called after events are added", function() {
+            const event =
+                utils.mkMessage({
+                    room: roomId, user: userA, msg: "Adam stole the plushies",
+                    event: true,
+                });
+
+            const state = [
+                utils.mkMembership({
+                    room: roomId, mship: "invite", user: userB, skey: userA,
+                    event: true,
+                }),
+            ];
+
+            expect(function() {
+                timeline.initialiseState(state);
+            }).toNotThrow();
+            timeline.addEvent(event, false);
+            expect(function() {
+                timeline.initialiseState(state);
+            }).toThrow();
+        });
+    });
+
+    describe("paginationTokens", function() {
+        it("pagination tokens should start null", function() {
+            expect(timeline.getPaginationToken(EventTimeline.BACKWARDS)).toBe(null);
+            expect(timeline.getPaginationToken(EventTimeline.FORWARDS)).toBe(null);
+        });
+
+        it("setPaginationToken should set  token", function() {
+            timeline.setPaginationToken("back", EventTimeline.BACKWARDS);
+            timeline.setPaginationToken("fwd", EventTimeline.FORWARDS);
+            expect(timeline.getPaginationToken(EventTimeline.BACKWARDS)).toEqual("back");
+            expect(timeline.getPaginationToken(EventTimeline.FORWARDS)).toEqual("fwd");
+        });
+    });
+
+
+    describe("neighbouringTimelines", function() {
+        it("neighbouring timelines should start null", function() {
+            expect(timeline.getNeighbouringTimeline(EventTimeline.BACKWARDS)).toBe(null);
+            expect(timeline.getNeighbouringTimeline(EventTimeline.FORWARDS)).toBe(null);
+        });
+
+        it("setNeighbouringTimeline should set neighbour", function() {
+            const prev = {a: "a"};
+            const next = {b: "b"};
+            timeline.setNeighbouringTimeline(prev, EventTimeline.BACKWARDS);
+            timeline.setNeighbouringTimeline(next, EventTimeline.FORWARDS);
+            expect(timeline.getNeighbouringTimeline(EventTimeline.BACKWARDS)).toBe(prev);
+            expect(timeline.getNeighbouringTimeline(EventTimeline.FORWARDS)).toBe(next);
+        });
+
+        it("setNeighbouringTimeline should throw if called twice", function() {
+            const prev = {a: "a"};
+            const next = {b: "b"};
+            expect(function() {
+                timeline.setNeighbouringTimeline(prev, EventTimeline.BACKWARDS);
+            }).toNotThrow();
+            expect(timeline.getNeighbouringTimeline(EventTimeline.BACKWARDS))
+                .toBe(prev);
+            expect(function() {
+                timeline.setNeighbouringTimeline(prev, EventTimeline.BACKWARDS);
+            }).toThrow();
+
+            expect(function() {
+                timeline.setNeighbouringTimeline(next, EventTimeline.FORWARDS);
+            }).toNotThrow();
+            expect(timeline.getNeighbouringTimeline(EventTimeline.FORWARDS))
+                .toBe(next);
+            expect(function() {
+                timeline.setNeighbouringTimeline(next, EventTimeline.FORWARDS);
+            }).toThrow();
+        });
+    });
+
+    describe("addEvent", function() {
+        beforeEach(function() {
+            mockRoomStates(timeline);
+        });
+
+        const events = [
+            utils.mkMessage({
+                room: roomId, user: userA, msg: "hungry hungry hungry",
+                event: true,
+            }),
+            utils.mkMessage({
+                room: roomId, user: userB, msg: "nom nom nom",
+                event: true,
+            }),
+        ];
+
+        it("should be able to add events to the end", function() {
+            timeline.addEvent(events[0], false);
+            const initialIndex = timeline.getBaseIndex();
+            timeline.addEvent(events[1], false);
+            expect(timeline.getBaseIndex()).toEqual(initialIndex);
+            expect(timeline.getEvents().length).toEqual(2);
+            expect(timeline.getEvents()[0]).toEqual(events[0]);
+            expect(timeline.getEvents()[1]).toEqual(events[1]);
+        });
+
+        it("should be able to add events to the start", function() {
+            timeline.addEvent(events[0], true);
+            const initialIndex = timeline.getBaseIndex();
+            timeline.addEvent(events[1], true);
+            expect(timeline.getBaseIndex()).toEqual(initialIndex + 1);
+            expect(timeline.getEvents().length).toEqual(2);
+            expect(timeline.getEvents()[0]).toEqual(events[1]);
+            expect(timeline.getEvents()[1]).toEqual(events[0]);
+        });
+
+        it("should set event.sender for new and old events", function() {
+            const sentinel = {
+                userId: userA,
+                membership: "join",
+                name: "Alice",
+            };
+            const oldSentinel = {
+                userId: userA,
+                membership: "join",
+                name: "Old Alice",
+            };
+            timeline.getState(EventTimeline.FORWARDS).getSentinelMember
+                .andCall(function(uid) {
+                    if (uid === userA) {
+                        return sentinel;
+                    }
+                    return null;
+                });
+            timeline.getState(EventTimeline.BACKWARDS).getSentinelMember
+                .andCall(function(uid) {
+                    if (uid === userA) {
+                        return oldSentinel;
+                    }
+                    return null;
+                });
+
+            const newEv = utils.mkEvent({
+                type: "m.room.name", room: roomId, user: userA, event: true,
+                content: { name: "New Room Name" },
+            });
+            const oldEv = utils.mkEvent({
+                type: "m.room.name", room: roomId, user: userA, event: true,
+                content: { name: "Old Room Name" },
+            });
+
+            timeline.addEvent(newEv, false);
+            expect(newEv.sender).toEqual(sentinel);
+            timeline.addEvent(oldEv, true);
+            expect(oldEv.sender).toEqual(oldSentinel);
+        });
+
+        it("should set event.target for new and old m.room.member events",
+        function() {
+            const sentinel = {
+                userId: userA,
+                membership: "join",
+                name: "Alice",
+            };
+            const oldSentinel = {
+                userId: userA,
+                membership: "join",
+                name: "Old Alice",
+            };
+            timeline.getState(EventTimeline.FORWARDS).getSentinelMember
+                .andCall(function(uid) {
+                    if (uid === userA) {
+                        return sentinel;
+                    }
+                    return null;
+                });
+            timeline.getState(EventTimeline.BACKWARDS).getSentinelMember
+                .andCall(function(uid) {
+                    if (uid === userA) {
+                        return oldSentinel;
+                    }
+                    return null;
+                });
+
+            const newEv = utils.mkMembership({
+                room: roomId, mship: "invite", user: userB, skey: userA, event: true,
+            });
+            const oldEv = utils.mkMembership({
+                room: roomId, mship: "ban", user: userB, skey: userA, event: true,
+            });
+            timeline.addEvent(newEv, false);
+            expect(newEv.target).toEqual(sentinel);
+            timeline.addEvent(oldEv, true);
+            expect(oldEv.target).toEqual(oldSentinel);
+        });
+
+        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,
+                }),
+                utils.mkEvent({
+                    type: "m.room.name", room: roomId, user: userB, event: true,
+                    content: {
+                        name: "New room",
+                    },
+                }),
+            ];
+
+            timeline.addEvent(events[0], false);
+            timeline.addEvent(events[1], false);
+
+            expect(timeline.getState(EventTimeline.FORWARDS).setStateEvents).
+                toHaveBeenCalledWith([events[0]]);
+            expect(timeline.getState(EventTimeline.FORWARDS).setStateEvents).
+                toHaveBeenCalledWith([events[1]]);
+
+            expect(events[0].forwardLooking).toBe(true);
+            expect(events[1].forwardLooking).toBe(true);
+
+            expect(timeline.getState(EventTimeline.BACKWARDS).setStateEvents).
+                toNotHaveBeenCalled();
+        });
+
+
+        it("should call setStateEvents on the right RoomState with the right " +
+           "forwardLooking value for old events", function() {
+            const events = [
+                utils.mkMembership({
+                    room: roomId, mship: "invite", user: userB, skey: userA, event: true,
+                }),
+                utils.mkEvent({
+                    type: "m.room.name", room: roomId, user: userB, event: true,
+                    content: {
+                        name: "New room",
+                    },
+                }),
+            ];
+
+            timeline.addEvent(events[0], true);
+            timeline.addEvent(events[1], true);
+
+            expect(timeline.getState(EventTimeline.BACKWARDS).setStateEvents).
+                toHaveBeenCalledWith([events[0]]);
+            expect(timeline.getState(EventTimeline.BACKWARDS).setStateEvents).
+                toHaveBeenCalledWith([events[1]]);
+
+            expect(events[0].forwardLooking).toBe(false);
+            expect(events[1].forwardLooking).toBe(false);
+
+            expect(timeline.getState(EventTimeline.FORWARDS).setStateEvents).
+                toNotHaveBeenCalled();
+        });
+    });
+
+    describe("removeEvent", function() {
+        const events = [
+            utils.mkMessage({
+                room: roomId, user: userA, msg: "hungry hungry hungry",
+                event: true,
+            }),
+            utils.mkMessage({
+                room: roomId, user: userB, msg: "nom nom nom",
+                event: true,
+            }),
+            utils.mkMessage({
+                room: roomId, user: userB, msg: "piiie",
+                event: true,
+            }),
+        ];
+
+        it("should remove events", function() {
+            timeline.addEvent(events[0], false);
+            timeline.addEvent(events[1], false);
+            expect(timeline.getEvents().length).toEqual(2);
+
+            let ev = timeline.removeEvent(events[0].getId());
+            expect(ev).toBe(events[0]);
+            expect(timeline.getEvents().length).toEqual(1);
+
+            ev = timeline.removeEvent(events[1].getId());
+            expect(ev).toBe(events[1]);
+            expect(timeline.getEvents().length).toEqual(0);
+        });
+
+        it("should update baseIndex", function() {
+            timeline.addEvent(events[0], false);
+            timeline.addEvent(events[1], true);
+            timeline.addEvent(events[2], false);
+            expect(timeline.getEvents().length).toEqual(3);
+            expect(timeline.getBaseIndex()).toEqual(1);
+
+            timeline.removeEvent(events[2].getId());
+            expect(timeline.getEvents().length).toEqual(2);
+            expect(timeline.getBaseIndex()).toEqual(1);
+
+            timeline.removeEvent(events[1].getId());
+            expect(timeline.getEvents().length).toEqual(1);
+            expect(timeline.getBaseIndex()).toEqual(0);
+        });
+
+        // this is basically https://github.com/vector-im/vector-web/issues/937
+        // - removing the last event got baseIndex into such a state that
+        // further addEvent(ev, false) calls made the index increase.
+        it("should not make baseIndex assplode when removing the last event",
+           function() {
+               timeline.addEvent(events[0], true);
+               timeline.removeEvent(events[0].getId());
+               const initialIndex = timeline.getBaseIndex();
+               timeline.addEvent(events[1], false);
+               timeline.addEvent(events[2], false);
+               expect(timeline.getBaseIndex()).toEqual(initialIndex);
+               expect(timeline.getEvents().length).toEqual(2);
+           });
+    });
+});

spec/unit/event.spec.js

@@ -0,0 +1,83 @@
+/*
+Copyright 2017 New Vector 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.
+*/
+
+import sdk from '../..';
+const MatrixEvent = sdk.MatrixEvent;
+
+import testUtils from '../test-utils';
+
+import expect from 'expect';
+import Promise from 'bluebird';
+import logger from '../../src/logger';
+
+describe("MatrixEvent", () => {
+    beforeEach(function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+    });
+
+    describe(".attemptDecryption", () => {
+        let encryptedEvent;
+
+        beforeEach(() => {
+            encryptedEvent = new MatrixEvent({
+                id: 'test_encrypted_event',
+                type: 'm.room.encrypted',
+                content: {
+                    ciphertext: 'secrets',
+                },
+            });
+        });
+
+        it('should retry decryption if a retry is queued', () => {
+            let callCount = 0;
+
+            let prom2;
+
+            const crypto = {
+                decryptEvent: function() {
+                    ++callCount;
+                    logger.log(`decrypt: ${callCount}`);
+                    if (callCount == 1) {
+                        // schedule a second decryption attempt while
+                        // the first one is still running.
+                        prom2 = encryptedEvent.attemptDecryption(crypto);
+
+                        const error = new Error("nope");
+                        error.name = 'DecryptionError';
+                        return Promise.reject(error);
+                    } else {
+                        expect(prom2.isFulfilled()).toBe(
+                            false, 'second attemptDecryption resolved too soon');
+
+                        return Promise.resolve({
+                            clearEvent: {
+                                type: 'm.room.message',
+                            },
+                        });
+                    }
+                },
+            };
+
+            return encryptedEvent.attemptDecryption(crypto).then(() => {
+                expect(callCount).toEqual(2);
+                expect(encryptedEvent.getType()).toEqual('m.room.message');
+
+                // make sure the second attemptDecryption resolves
+                return prom2;
+            });
+        });
+    });
+});

spec/unit/filter.spec.js

@@ -0,0 +1,53 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const Filter = sdk.Filter;
+const utils = require("../test-utils");
+
+import expect from 'expect';
+
+describe("Filter", function() {
+    const filterId = "f1lt3ring15g00d4ursoul";
+    const userId = "@sir_arthur_david:humming.tiger";
+    let filter;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        filter = new Filter(userId);
+    });
+
+    describe("fromJson", function() {
+        it("create a new Filter from the provided values", function() {
+            const definition = {
+                event_fields: ["type", "content"],
+            };
+            const f = Filter.fromJson(userId, filterId, definition);
+            expect(f.getDefinition()).toEqual(definition);
+            expect(f.userId).toEqual(userId);
+            expect(f.filterId).toEqual(filterId);
+        });
+    });
+
+    describe("setTimelineLimit", function() {
+        it("should set room.timeline.limit of the filter definition", function() {
+            filter.setTimelineLimit(10);
+            expect(filter.getDefinition()).toEqual({
+                room: {
+                    timeline: {
+                        limit: 10,
+                    },
+                },
+            });
+        });
+    });
+
+    describe("setDefinition/getDefinition", function() {
+        it("should set and get the filter body", function() {
+            const definition = {
+                event_format: "client",
+            };
+            filter.setDefinition(definition);
+            expect(filter.getDefinition()).toEqual(definition);
+        });
+    });
+});

spec/unit/interactive-auth.spec.js

@@ -0,0 +1,157 @@
+/*
+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.
+*/
+"use strict";
+
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const utils = require("../test-utils");
+
+const InteractiveAuth = sdk.InteractiveAuth;
+const MatrixError = sdk.MatrixError;
+
+import expect from 'expect';
+import logger from '../../src/logger';
+
+// Trivial client object to test interactive auth
+// (we do not need TestClient here)
+class FakeClient {
+    generateClientSecret() {
+        return "testcl1Ent5EcreT";
+    }
+}
+
+describe("InteractiveAuth", function() {
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+    });
+
+    it("should start an auth stage and complete it", function(done) {
+        const doRequest = expect.createSpy();
+        const stateUpdated = expect.createSpy();
+
+        const ia = new InteractiveAuth({
+            matrixClient: new FakeClient(),
+            doRequest: doRequest,
+            stateUpdated: stateUpdated,
+            authData: {
+                session: "sessionId",
+                flows: [
+                    { stages: ["logintype"] },
+                ],
+                params: {
+                    "logintype": { param: "aa" },
+                },
+            },
+        });
+
+        expect(ia.getSessionId()).toEqual("sessionId");
+        expect(ia.getStageParams("logintype")).toEqual({
+            param: "aa",
+        });
+
+        // first we expect a call here
+        stateUpdated.andCall(function(stage) {
+            logger.log('aaaa');
+            expect(stage).toEqual("logintype");
+            ia.submitAuthDict({
+                type: "logintype",
+                foo: "bar",
+            });
+        });
+
+        // .. which should trigger a call here
+        const requestRes = {"a": "b"};
+        doRequest.andCall(function(authData) {
+            logger.log('cccc');
+            expect(authData).toEqual({
+                session: "sessionId",
+                type: "logintype",
+                foo: "bar",
+            });
+            return Promise.resolve(requestRes);
+        });
+
+        ia.attemptAuth().then(function(res) {
+            expect(res).toBe(requestRes);
+            expect(doRequest.calls.length).toEqual(1);
+            expect(stateUpdated.calls.length).toEqual(1);
+        }).nodeify(done);
+    });
+
+    it("should make a request if no authdata is provided", function(done) {
+        const doRequest = expect.createSpy();
+        const stateUpdated = expect.createSpy();
+
+        const ia = new InteractiveAuth({
+            matrixClient: new FakeClient(),
+            stateUpdated: stateUpdated,
+            doRequest: doRequest,
+        });
+
+        expect(ia.getSessionId()).toBe(undefined);
+        expect(ia.getStageParams("logintype")).toBe(undefined);
+
+        // first we expect a call to doRequest
+        doRequest.andCall(function(authData) {
+            logger.log("request1", authData);
+            expect(authData).toEqual({});
+            const err = new MatrixError({
+                session: "sessionId",
+                flows: [
+                    { stages: ["logintype"] },
+                ],
+                params: {
+                    "logintype": { param: "aa" },
+                },
+            });
+            err.httpStatus = 401;
+            throw err;
+        });
+
+        // .. which should be followed by a call to stateUpdated
+        const requestRes = {"a": "b"};
+        stateUpdated.andCall(function(stage) {
+            expect(stage).toEqual("logintype");
+            expect(ia.getSessionId()).toEqual("sessionId");
+            expect(ia.getStageParams("logintype")).toEqual({
+                param: "aa",
+            });
+
+            // submitAuthDict should trigger another call to doRequest
+            doRequest.andCall(function(authData) {
+                logger.log("request2", authData);
+                expect(authData).toEqual({
+                    session: "sessionId",
+                    type: "logintype",
+                    foo: "bar",
+                });
+                return Promise.resolve(requestRes);
+            });
+
+            ia.submitAuthDict({
+                type: "logintype",
+                foo: "bar",
+            });
+        });
+
+        ia.attemptAuth().then(function(res) {
+            expect(res).toBe(requestRes);
+            expect(doRequest.calls.length).toEqual(2);
+            expect(stateUpdated.calls.length).toEqual(1);
+        }).nodeify(done);
+    });
+});

spec/unit/login.spec.js

@@ -0,0 +1,25 @@
+import expect from 'expect';
+import TestClient from '../TestClient';
+
+describe('Login request', function() {
+    let client;
+
+    beforeEach(function() {
+        client = new TestClient();
+    });
+
+    afterEach(function() {
+        client.stop();
+    });
+
+    it('should store "access_token" and "user_id" if in response', async function() {
+        const response = { user_id: 1, access_token: Date.now().toString(16) };
+
+        client.httpBackend.when('POST', '/login').respond(200, response);
+        client.httpBackend.flush('/login', 1, 100);
+        await client.client.login('m.login.any', { user: 'test', password: '12312za' });
+
+        expect(client.client.getAccessToken()).toBe(response.access_token);
+        expect(client.client.getUserId()).toBe(response.user_id);
+    });
+});

spec/unit/matrix-client.spec.js

@@ -0,0 +1,539 @@
+"use strict";
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const MatrixClient = sdk.MatrixClient;
+const utils = require("../test-utils");
+
+import expect from 'expect';
+import lolex from 'lolex';
+import logger from '../../src/logger';
+
+describe("MatrixClient", function() {
+    const userId = "@alice:bar";
+    const identityServerUrl = "https://identity.server";
+    const identityServerDomain = "identity.server";
+    let client;
+    let store;
+    let scheduler;
+    let clock;
+
+    const KEEP_ALIVE_PATH = "/_matrix/client/versions";
+
+    const PUSH_RULES_RESPONSE = {
+        method: "GET",
+        path: "/pushrules/",
+        data: {},
+    };
+
+    const FILTER_PATH = "/user/" + encodeURIComponent(userId) + "/filter";
+
+    const FILTER_RESPONSE = {
+        method: "POST",
+        path: FILTER_PATH,
+        data: { filter_id: "f1lt3r" },
+    };
+
+    const SYNC_DATA = {
+        next_batch: "s_5_3",
+        presence: { events: [] },
+        rooms: {},
+    };
+
+    const SYNC_RESPONSE = {
+        method: "GET",
+        path: "/sync",
+        data: SYNC_DATA,
+    };
+
+    let httpLookups = [
+        // items are objects which look like:
+        // {
+        //   method: "GET",
+        //   path: "/initialSync",
+        //   data: {},
+        //   error: { errcode: M_FORBIDDEN } // if present will reject promise,
+        //   expectBody: {} // additional expects on the body
+        //   expectQueryParams: {} // additional expects on query params
+        //   thenCall: function(){} // function to call *AFTER* returning response.
+        // }
+        // items are popped off when processed and block if no items left.
+    ];
+    let acceptKeepalives;
+    let pendingLookup = null;
+    function httpReq(cb, method, path, qp, data, prefix) {
+        if (path === KEEP_ALIVE_PATH && acceptKeepalives) {
+            return Promise.resolve();
+        }
+        const next = httpLookups.shift();
+        const logLine = (
+            "MatrixClient[UT] RECV " + method + " " + path + "  " +
+            "EXPECT " + (next ? next.method : next) + " " + (next ? next.path : next)
+        );
+        logger.log(logLine);
+
+        if (!next) { // no more things to return
+            if (pendingLookup) {
+                if (pendingLookup.method === method && pendingLookup.path === path) {
+                    return pendingLookup.promise;
+                }
+                // >1 pending thing, and they are different, whine.
+                expect(false).toBe(
+                    true, ">1 pending request. You should probably handle them. " +
+                    "PENDING: " + JSON.stringify(pendingLookup) + " JUST GOT: " +
+                    method + " " + path,
+                );
+            }
+            pendingLookup = {
+                promise: Promise.defer().promise,
+                method: method,
+                path: path,
+            };
+            return pendingLookup.promise;
+        }
+        if (next.path === path && next.method === method) {
+            logger.log(
+                "MatrixClient[UT] Matched. Returning " +
+                (next.error ? "BAD" : "GOOD") + " response",
+            );
+            if (next.expectBody) {
+                expect(next.expectBody).toEqual(data);
+            }
+            if (next.expectQueryParams) {
+                Object.keys(next.expectQueryParams).forEach(function(k) {
+                    expect(qp[k]).toEqual(next.expectQueryParams[k]);
+                });
+            }
+
+            if (next.thenCall) {
+                process.nextTick(next.thenCall, 0); // next tick so we return first.
+            }
+
+            if (next.error) {
+                return Promise.reject({
+                    errcode: next.error.errcode,
+                    httpStatus: next.error.httpStatus,
+                    name: next.error.errcode,
+                    message: "Expected testing error",
+                    data: next.error,
+                });
+            }
+            return Promise.resolve(next.data);
+        }
+        expect(true).toBe(false, "Expected different request. " + logLine);
+        return Promise.defer().promise;
+    }
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        clock = lolex.install();
+        scheduler = [
+            "getQueueForEvent", "queueEvent", "removeEventFromQueue",
+            "setProcessFunction",
+        ].reduce((r, k) => { r[k] = expect.createSpy(); return r; }, {});
+        store = [
+            "getRoom", "getRooms", "getUser", "getSyncToken", "scrollback",
+            "save", "wantsSave", "setSyncToken", "storeEvents", "storeRoom", "storeUser",
+            "getFilterIdByName", "setFilterIdByName", "getFilter", "storeFilter",
+            "getSyncAccumulator", "startup", "deleteAllData",
+        ].reduce((r, k) => { r[k] = expect.createSpy(); return r; }, {});
+        store.getSavedSync = expect.createSpy().andReturn(Promise.resolve(null));
+        store.getSavedSyncToken = expect.createSpy().andReturn(Promise.resolve(null));
+        store.setSyncData = expect.createSpy().andReturn(Promise.resolve(null));
+        store.getClientOptions = expect.createSpy().andReturn(Promise.resolve(null));
+        store.storeClientOptions = expect.createSpy().andReturn(Promise.resolve(null));
+        store.isNewlyCreated = expect.createSpy().andReturn(Promise.resolve(true));
+        client = new MatrixClient({
+            baseUrl: "https://my.home.server",
+            idBaseUrl: identityServerUrl,
+            accessToken: "my.access.token",
+            request: function() {}, // NOP
+            store: store,
+            scheduler: scheduler,
+            userId: userId,
+        });
+        // FIXME: We shouldn't be yanking _http like this.
+        client._http = [
+            "authedRequest", "authedRequestWithPrefix", "getContentUri",
+            "request", "requestWithPrefix", "uploadContent",
+        ].reduce((r, k) => { r[k] = expect.createSpy(); return r; }, {});
+        client._http.authedRequest.andCall(httpReq);
+        client._http.authedRequestWithPrefix.andCall(httpReq);
+        client._http.requestWithPrefix.andCall(httpReq);
+        client._http.request.andCall(httpReq);
+
+        // set reasonable working defaults
+        acceptKeepalives = true;
+        pendingLookup = null;
+        httpLookups = [];
+        httpLookups.push(PUSH_RULES_RESPONSE);
+        httpLookups.push(FILTER_RESPONSE);
+        httpLookups.push(SYNC_RESPONSE);
+    });
+
+    afterEach(function() {
+        clock.uninstall();
+        // need to re-stub the requests with NOPs because there are no guarantees
+        // clients from previous tests will be GC'd before the next test. This
+        // means they may call /events and then fail an expect() which will fail
+        // a DIFFERENT test (pollution between tests!) - we return unresolved
+        // promises to stop the client from continuing to run.
+        client._http.authedRequest.andCall(function() {
+            return Promise.defer().promise;
+        });
+        client._http.authedRequestWithPrefix.andCall(function() {
+            return Promise.defer().promise;
+        });
+    });
+
+    it("should not POST /filter if a matching filter already exists", async function() {
+        httpLookups = [];
+        httpLookups.push(PUSH_RULES_RESPONSE);
+        httpLookups.push(SYNC_RESPONSE);
+        const filterId = "ehfewf";
+        store.getFilterIdByName.andReturn(filterId);
+        const filter = new sdk.Filter(0, filterId);
+        filter.setDefinition({"room": {"timeline": {"limit": 8}}});
+        store.getFilter.andReturn(filter);
+        const syncPromise = new Promise((resolve, reject) => {
+            client.on("sync", function syncListener(state) {
+                if (state === "SYNCING") {
+                    expect(httpLookups.length).toEqual(0);
+                    client.removeListener("sync", syncListener);
+                    resolve();
+                } else if (state === "ERROR") {
+                    reject(new Error("sync error"));
+                }
+            });
+        });
+        await client.startClient();
+        await syncPromise;
+    });
+
+    describe("getSyncState", function() {
+        it("should return null if the client isn't started", function() {
+            expect(client.getSyncState()).toBe(null);
+        });
+
+        it("should return the same sync state as emitted sync events", async function() {
+            const syncingPromise = new Promise((resolve) => {
+                client.on("sync", function syncListener(state) {
+                    expect(state).toEqual(client.getSyncState());
+                    if (state === "SYNCING") {
+                        client.removeListener("sync", syncListener);
+                        resolve();
+                    }
+                });
+            });
+            await client.startClient();
+            await syncingPromise;
+        });
+    });
+
+    describe("getOrCreateFilter", function() {
+        it("should POST createFilter if no id is present in localStorage", function() {
+        });
+        it("should use an existing filter if id is present in localStorage", function() {
+        });
+        it("should handle localStorage filterId missing from the server", function(done) {
+            function getFilterName(userId, suffix) {
+                // scope this on the user ID because people may login on many accounts
+                // and they all need to be stored!
+                return "FILTER_SYNC_" + userId + (suffix ? "_" + suffix : "");
+            }
+            const invalidFilterId = 'invalidF1lt3r';
+            httpLookups = [];
+            httpLookups.push({
+                method: "GET",
+                path: FILTER_PATH + '/' + invalidFilterId,
+                error: {
+                    errcode: "M_UNKNOWN",
+                    name: "M_UNKNOWN",
+                    message: "No row found",
+                    data: { errcode: "M_UNKNOWN", error: "No row found" },
+                    httpStatus: 404,
+                },
+            });
+            httpLookups.push(FILTER_RESPONSE);
+            store.getFilterIdByName.andReturn(invalidFilterId);
+
+            const filterName = getFilterName(client.credentials.userId);
+            client.store.setFilterIdByName(filterName, invalidFilterId);
+            const filter = new sdk.Filter(client.credentials.userId);
+
+            client.getOrCreateFilter(filterName, filter).then(function(filterId) {
+                expect(filterId).toEqual(FILTER_RESPONSE.data.filter_id);
+                done();
+            });
+        });
+    });
+
+    describe("retryImmediately", function() {
+        it("should return false if there is no request waiting", async function() {
+            await client.startClient();
+            expect(client.retryImmediately()).toBe(false);
+        });
+
+        it("should work on /filter", function(done) {
+            httpLookups = [];
+            httpLookups.push(PUSH_RULES_RESPONSE);
+            httpLookups.push({
+                method: "POST", path: FILTER_PATH, error: { errcode: "NOPE_NOPE_NOPE" },
+            });
+            httpLookups.push(FILTER_RESPONSE);
+            httpLookups.push(SYNC_RESPONSE);
+
+            client.on("sync", function syncListener(state) {
+                if (state === "ERROR" && httpLookups.length > 0) {
+                    expect(httpLookups.length).toEqual(2);
+                    expect(client.retryImmediately()).toBe(true);
+                    clock.tick(1);
+                } else if (state === "PREPARED" && httpLookups.length === 0) {
+                    client.removeListener("sync", syncListener);
+                    done();
+                } else {
+                    // unexpected state transition!
+                    expect(state).toEqual(null);
+                }
+            });
+            client.startClient();
+        });
+
+        it("should work on /sync", function(done) {
+            httpLookups.push({
+                method: "GET", path: "/sync", error: { errcode: "NOPE_NOPE_NOPE" },
+            });
+            httpLookups.push({
+                method: "GET", path: "/sync", data: SYNC_DATA,
+            });
+
+            client.on("sync", function syncListener(state) {
+                if (state === "ERROR" && httpLookups.length > 0) {
+                    expect(httpLookups.length).toEqual(1);
+                    expect(client.retryImmediately()).toBe(
+                        true, "retryImmediately returned false",
+                    );
+                    clock.tick(1);
+                } else if (state === "RECONNECTING" && httpLookups.length > 0) {
+                    clock.tick(10000);
+                } else if (state === "SYNCING" && httpLookups.length === 0) {
+                    client.removeListener("sync", syncListener);
+                    done();
+                }
+            });
+            client.startClient();
+        });
+
+        it("should work on /pushrules", function(done) {
+            httpLookups = [];
+            httpLookups.push({
+                method: "GET", path: "/pushrules/", error: { errcode: "NOPE_NOPE_NOPE" },
+            });
+            httpLookups.push(PUSH_RULES_RESPONSE);
+            httpLookups.push(FILTER_RESPONSE);
+            httpLookups.push(SYNC_RESPONSE);
+
+            client.on("sync", function syncListener(state) {
+                if (state === "ERROR" && httpLookups.length > 0) {
+                    expect(httpLookups.length).toEqual(3);
+                    expect(client.retryImmediately()).toBe(true);
+                    clock.tick(1);
+                } else if (state === "PREPARED" && httpLookups.length === 0) {
+                    client.removeListener("sync", syncListener);
+                    done();
+                } else {
+                    // unexpected state transition!
+                    expect(state).toEqual(null);
+                }
+            });
+            client.startClient();
+        });
+    });
+
+    describe("emitted sync events", function() {
+        function syncChecker(expectedStates, done) {
+            return function syncListener(state, old) {
+                const expected = expectedStates.shift();
+                logger.log(
+                    "'sync' curr=%s old=%s EXPECT=%s", state, old, expected,
+                );
+                if (!expected) {
+                    done();
+                    return;
+                }
+                expect(state).toEqual(expected[0]);
+                expect(old).toEqual(expected[1]);
+                if (expectedStates.length === 0) {
+                    client.removeListener("sync", syncListener);
+                    done();
+                }
+                // standard retry time is 5 to 10 seconds
+                clock.tick(10000);
+            };
+        }
+
+        it("should transition null -> PREPARED after the first /sync", function(done) {
+            const expectedStates = [];
+            expectedStates.push(["PREPARED", null]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        it("should transition null -> ERROR after a failed /filter", function(done) {
+            const expectedStates = [];
+            httpLookups = [];
+            httpLookups.push(PUSH_RULES_RESPONSE);
+            httpLookups.push({
+                method: "POST", path: FILTER_PATH, error: { errcode: "NOPE_NOPE_NOPE" },
+            });
+            expectedStates.push(["ERROR", null]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        it("should transition ERROR -> CATCHUP after /sync if prev failed",
+        function(done) {
+            const expectedStates = [];
+            acceptKeepalives = false;
+            httpLookups = [];
+            httpLookups.push(PUSH_RULES_RESPONSE);
+            httpLookups.push(FILTER_RESPONSE);
+            httpLookups.push({
+                method: "GET", path: "/sync", error: { errcode: "NOPE_NOPE_NOPE" },
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH,
+                error: { errcode: "KEEPALIVE_FAIL" },
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH, data: {},
+            });
+            httpLookups.push({
+                method: "GET", path: "/sync", data: SYNC_DATA,
+            });
+
+            expectedStates.push(["RECONNECTING", null]);
+            expectedStates.push(["ERROR", "RECONNECTING"]);
+            expectedStates.push(["CATCHUP", "ERROR"]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        it("should transition PREPARED -> SYNCING after /sync", function(done) {
+            const expectedStates = [];
+            expectedStates.push(["PREPARED", null]);
+            expectedStates.push(["SYNCING", "PREPARED"]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        it("should transition SYNCING -> ERROR after a failed /sync", function(done) {
+            acceptKeepalives = false;
+            const expectedStates = [];
+            httpLookups.push({
+                method: "GET", path: "/sync", error: { errcode: "NONONONONO" },
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH,
+                error: { errcode: "KEEPALIVE_FAIL" },
+            });
+
+            expectedStates.push(["PREPARED", null]);
+            expectedStates.push(["SYNCING", "PREPARED"]);
+            expectedStates.push(["RECONNECTING", "SYNCING"]);
+            expectedStates.push(["ERROR", "RECONNECTING"]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        xit("should transition ERROR -> SYNCING after /sync if prev failed",
+        function(done) {
+            const expectedStates = [];
+            httpLookups.push({
+                method: "GET", path: "/sync", error: { errcode: "NONONONONO" },
+            });
+            httpLookups.push(SYNC_RESPONSE);
+
+            expectedStates.push(["PREPARED", null]);
+            expectedStates.push(["SYNCING", "PREPARED"]);
+            expectedStates.push(["ERROR", "SYNCING"]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        it("should transition SYNCING -> SYNCING on subsequent /sync successes",
+        function(done) {
+            const expectedStates = [];
+            httpLookups.push(SYNC_RESPONSE);
+            httpLookups.push(SYNC_RESPONSE);
+
+            expectedStates.push(["PREPARED", null]);
+            expectedStates.push(["SYNCING", "PREPARED"]);
+            expectedStates.push(["SYNCING", "SYNCING"]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+
+        it("should transition ERROR -> ERROR if keepalive keeps failing", function(done) {
+            acceptKeepalives = false;
+            const expectedStates = [];
+            httpLookups.push({
+                method: "GET", path: "/sync", error: { errcode: "NONONONONO" },
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH,
+                error: { errcode: "KEEPALIVE_FAIL" },
+            });
+            httpLookups.push({
+                method: "GET", path: KEEP_ALIVE_PATH,
+                error: { errcode: "KEEPALIVE_FAIL" },
+            });
+
+            expectedStates.push(["PREPARED", null]);
+            expectedStates.push(["SYNCING", "PREPARED"]);
+            expectedStates.push(["RECONNECTING", "SYNCING"]);
+            expectedStates.push(["ERROR", "RECONNECTING"]);
+            expectedStates.push(["ERROR", "ERROR"]);
+            client.on("sync", syncChecker(expectedStates, done));
+            client.startClient();
+        });
+    });
+
+    describe("inviteByEmail", function() {
+        const roomId = "!foo:bar";
+
+        it("should send an invite HTTP POST", function() {
+            httpLookups = [{
+                method: "POST",
+                path: "/rooms/!foo%3Abar/invite",
+                data: {},
+                expectBody: {
+                    id_server: identityServerDomain,
+                    medium: "email",
+                    address: "alice@gmail.com",
+                },
+            }];
+            client.inviteByEmail(roomId, "alice@gmail.com");
+            expect(httpLookups.length).toEqual(0);
+        });
+    });
+
+    describe("guest rooms", function() {
+        it("should only do /sync calls (without filter/pushrules)", function(done) {
+            httpLookups = []; // no /pushrules or /filter
+            httpLookups.push({
+                method: "GET",
+                path: "/sync",
+                data: SYNC_DATA,
+                thenCall: function() {
+                    done();
+                },
+            });
+            client.setGuest(true);
+            client.startClient();
+        });
+
+        xit("should be able to peek into a room using peekInRoom", function(done) {
+        });
+    });
+});

spec/unit/pushprocessor.spec.js

@@ -0,0 +1,309 @@
+"use strict";
+import 'source-map-support/register';
+const PushProcessor = require("../../lib/pushprocessor");
+const utils = require("../test-utils");
+
+import expect from 'expect';
+
+describe('NotificationService', function() {
+    const testUserId = "@ali:matrix.org";
+    const testDisplayName = "Alice M";
+    const testRoomId = "!fl1bb13:localhost";
+
+    let testEvent;
+
+    let pushProcessor;
+
+    // These would be better if individual rules were configured in the tests themselves.
+    const matrixClient = {
+        getRoom: function() {
+            return {
+                currentState: {
+                    getMember: function() {
+                        return {
+                            name: testDisplayName,
+                        };
+                    },
+                    getJoinedMemberCount: function() {
+                        return 0;
+                    },
+                    members: {},
+                },
+            };
+        },
+        credentials: {
+            userId: testUserId,
+        },
+        pushRules: {
+            "device": {},
+            "global": {
+                "content": [
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "enabled": true,
+                        "pattern": "ali",
+                        "rule_id": ".m.rule.contains_user_name",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "enabled": true,
+                        "pattern": "coffee",
+                        "rule_id": "coffee",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "enabled": true,
+                        "pattern": "foo*bar",
+                        "rule_id": "foobar",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "enabled": true,
+                        "pattern": "p[io]ng",
+                        "rule_id": "pingpong",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "enabled": true,
+                        "pattern": "I ate [0-9] pies",
+                        "rule_id": "pies",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "enabled": true,
+                        "pattern": "b[!ai]ke",
+                        "rule_id": "bakebike",
+                    },
+                ],
+                "override": [
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                            {
+                                "set_tweak": "highlight",
+                            },
+                        ],
+                        "conditions": [
+                            {
+                                "kind": "contains_display_name",
+                            },
+                        ],
+                        "enabled": true,
+                        "rule_id": ".m.rule.contains_display_name",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "sound",
+                                "value": "default",
+                            },
+                        ],
+                        "conditions": [
+                            {
+                                "is": "2",
+                                "kind": "room_member_count",
+                            },
+                        ],
+                        "enabled": true,
+                        "rule_id": ".m.rule.room_one_to_one",
+                    },
+                ],
+                "room": [],
+                "sender": [],
+                "underride": [
+                    {
+                        "actions": [
+                            "dont-notify",
+                        ],
+                        "conditions": [
+                            {
+                                "key": "content.msgtype",
+                                "kind": "event_match",
+                                "pattern": "m.notice",
+                            },
+                        ],
+                        "enabled": true,
+                        "rule_id": ".m.rule.suppress_notices",
+                    },
+                    {
+                        "actions": [
+                            "notify",
+                            {
+                                "set_tweak": "highlight",
+                                "value": false,
+                            },
+                        ],
+                        "conditions": [],
+                        "enabled": true,
+                        "rule_id": ".m.rule.fallback",
+                    },
+                ],
+            },
+        },
+    };
+
+    beforeEach(function() {
+        testEvent = utils.mkEvent({
+            type: "m.room.message",
+            room: testRoomId,
+            user: "@alfred:localhost",
+            event: true,
+            content: {
+                body: "",
+                msgtype: "m.text",
+            },
+        });
+        pushProcessor = new PushProcessor(matrixClient);
+    });
+
+    // User IDs
+
+    it('should bing on a user ID.', function() {
+        testEvent.event.content.body = "Hello @ali:matrix.org, how are you?";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on a partial user ID with an @.', function() {
+        testEvent.event.content.body = "Hello @ali, how are you?";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on a partial user ID without @.', function() {
+        testEvent.event.content.body = "Hello ali, how are you?";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on a case-insensitive user ID.', function() {
+        testEvent.event.content.body = "Hello @AlI:matrix.org, how are you?";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    // Display names
+
+    it('should bing on a display name.', function() {
+        testEvent.event.content.body = "Hello Alice M, how are you?";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on a case-insensitive display name.', function() {
+        testEvent.event.content.body = "Hello ALICE M, how are you?";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    // Bing words
+
+    it('should bing on a bing word.', function() {
+        testEvent.event.content.body = "I really like coffee";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on case-insensitive bing words.', function() {
+        testEvent.event.content.body = "Coffee is great";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on wildcard (.*) bing words.', function() {
+        testEvent.event.content.body = "It was foomahbar I think.";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on character group ([abc]) bing words.', function() {
+        testEvent.event.content.body = "Ping!";
+        let actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+        testEvent.event.content.body = "Pong!";
+        actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on character range ([a-z]) bing words.', function() {
+        testEvent.event.content.body = "I ate 6 pies";
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+    });
+
+    it('should bing on character negation ([!a]) bing words.', function() {
+        testEvent.event.content.body = "boke";
+        let actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(true);
+        testEvent.event.content.body = "bake";
+        actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(false);
+    });
+
+    // invalid
+
+    it('should gracefully handle bad input.', function() {
+        testEvent.event.content.body = { "foo": "bar" };
+        const actions = pushProcessor.actionsForEvent(testEvent);
+        expect(actions.tweaks.highlight).toEqual(false);
+    });
+});

spec/unit/realtime-callbacks.spec.js

@@ -0,0 +1,184 @@
+"use strict";
+
+import 'source-map-support/register';
+const callbacks = require("../../lib/realtime-callbacks");
+const testUtils = require("../test-utils.js");
+
+import expect from 'expect';
+import lolex from 'lolex';
+
+describe("realtime-callbacks", function() {
+    let clock;
+
+    function tick(millis) {
+        clock.tick(millis);
+    }
+
+    beforeEach(function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        clock = lolex.install();
+        const fakeDate = clock.Date;
+        callbacks.setNow(fakeDate.now.bind(fakeDate));
+    });
+
+    afterEach(function() {
+        callbacks.setNow();
+        clock.uninstall();
+    });
+
+    describe("setTimeout", function() {
+        it("should call the callback after the timeout", function() {
+            const callback = expect.createSpy();
+            callbacks.setTimeout(callback, 100);
+
+            expect(callback).toNotHaveBeenCalled();
+            tick(100);
+            expect(callback).toHaveBeenCalled();
+        });
+
+
+        it("should default to a zero timeout", function() {
+            const callback = expect.createSpy();
+            callbacks.setTimeout(callback);
+
+            expect(callback).toNotHaveBeenCalled();
+            tick(0);
+            expect(callback).toHaveBeenCalled();
+        });
+
+        it("should pass any parameters to the callback", function() {
+            const callback = expect.createSpy();
+            callbacks.setTimeout(callback, 0, "a", "b", "c");
+            tick(0);
+            expect(callback).toHaveBeenCalledWith("a", "b", "c");
+        });
+
+        it("should set 'this' to the global object", function() {
+            let passed = false;
+            const callback = function() {
+                expect(this).toBe(global); // eslint-disable-line babel/no-invalid-this
+                expect(this.console).toBeTruthy(); // eslint-disable-line babel/no-invalid-this
+                passed = true;
+            };
+            callbacks.setTimeout(callback);
+            tick(0);
+            expect(passed).toBe(true);
+        });
+
+        it("should handle timeouts of several seconds", function() {
+            const callback = expect.createSpy();
+            callbacks.setTimeout(callback, 2000);
+
+            expect(callback).toNotHaveBeenCalled();
+            for (let i = 0; i < 4; i++) {
+                tick(500);
+            }
+            expect(callback).toHaveBeenCalled();
+        });
+
+        it("should call multiple callbacks in the right order", function() {
+            const callback1 = expect.createSpy();
+            const callback2 = expect.createSpy();
+            const callback3 = expect.createSpy();
+            callbacks.setTimeout(callback2, 200);
+            callbacks.setTimeout(callback1, 100);
+            callbacks.setTimeout(callback3, 300);
+
+            expect(callback1).toNotHaveBeenCalled();
+            expect(callback2).toNotHaveBeenCalled();
+            expect(callback3).toNotHaveBeenCalled();
+            tick(100);
+            expect(callback1).toHaveBeenCalled();
+            expect(callback2).toNotHaveBeenCalled();
+            expect(callback3).toNotHaveBeenCalled();
+            tick(100);
+            expect(callback1).toHaveBeenCalled();
+            expect(callback2).toHaveBeenCalled();
+            expect(callback3).toNotHaveBeenCalled();
+            tick(100);
+            expect(callback1).toHaveBeenCalled();
+            expect(callback2).toHaveBeenCalled();
+            expect(callback3).toHaveBeenCalled();
+        });
+
+        it("should treat -ve timeouts the same as a zero timeout", function() {
+            const callback1 = expect.createSpy();
+            const callback2 = expect.createSpy();
+
+            // check that cb1 is called before cb2
+            callback1.andCall(function() {
+                expect(callback2).toNotHaveBeenCalled();
+            });
+
+            callbacks.setTimeout(callback1);
+            callbacks.setTimeout(callback2, -100);
+
+            expect(callback1).toNotHaveBeenCalled();
+            expect(callback2).toNotHaveBeenCalled();
+            tick(0);
+            expect(callback1).toHaveBeenCalled();
+            expect(callback2).toHaveBeenCalled();
+        });
+
+        it("should not get confused by chained calls", function() {
+            const callback2 = expect.createSpy();
+            const callback1 = expect.createSpy();
+            callback1.andCall(function() {
+                callbacks.setTimeout(callback2, 0);
+                expect(callback2).toNotHaveBeenCalled();
+            });
+
+            callbacks.setTimeout(callback1);
+            expect(callback1).toNotHaveBeenCalled();
+            expect(callback2).toNotHaveBeenCalled();
+            tick(0);
+            expect(callback1).toHaveBeenCalled();
+            // the fake timer won't actually run callbacks registered during
+            // one tick until the next tick.
+            tick(1);
+            expect(callback2).toHaveBeenCalled();
+        });
+
+        it("should be immune to exceptions", function() {
+            const callback1 = expect.createSpy();
+            callback1.andCall(function() {
+                throw new Error("prepare to die");
+            });
+            const callback2 = expect.createSpy();
+            callbacks.setTimeout(callback1, 0);
+            callbacks.setTimeout(callback2, 0);
+
+            expect(callback1).toNotHaveBeenCalled();
+            expect(callback2).toNotHaveBeenCalled();
+            tick(0);
+            expect(callback1).toHaveBeenCalled();
+            expect(callback2).toHaveBeenCalled();
+        });
+    });
+
+    describe("cancelTimeout", function() {
+        it("should cancel a pending timeout", function() {
+            const callback = expect.createSpy();
+            const k = callbacks.setTimeout(callback);
+            callbacks.clearTimeout(k);
+            tick(0);
+            expect(callback).toNotHaveBeenCalled();
+        });
+
+        it("should not affect sooner timeouts", function() {
+            const callback1 = expect.createSpy();
+            const callback2 = expect.createSpy();
+
+            callbacks.setTimeout(callback1, 100);
+            const k = callbacks.setTimeout(callback2, 200);
+            callbacks.clearTimeout(k);
+
+            tick(100);
+            expect(callback1).toHaveBeenCalled();
+            expect(callback2).toNotHaveBeenCalled();
+
+            tick(150);
+            expect(callback2).toNotHaveBeenCalled();
+        });
+    });
+});

spec/unit/room-member.spec.js

@@ -1,63 +1,336 @@
 "use strict";
-var sdk = require("../..");
-var RoomMember = sdk.RoomMember;
-var MatrixEvent = sdk.MatrixEvent;
-var utils = require("../test-utils");
+import 'source-map-support/register';
+const sdk = require("../..");
+const RoomMember = sdk.RoomMember;
+const utils = require("../test-utils");
+
+import expect from 'expect';
 
 describe("RoomMember", function() {
-    var roomId = "!foo:bar";
-    var userA = "@alice:bar";
-    var userB = "@bertha:bar";
-    var userC = "@clarissa:bar";
-    var member;
+    const roomId = "!foo:bar";
+    const userA = "@alice:bar";
+    const userB = "@bertha:bar";
+    const userC = "@clarissa:bar";
+    let member;
 
     beforeEach(function() {
-        utils.beforeEach(this);
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
         member = new RoomMember(roomId, userA);
     });
 
-    it("setPowerLevelEvent should set 'powerLevel' and 'powerLevelNorm'.",
-    function() {
-        var event = new MatrixEvent(
-            utils.mkEvent("m.room.power_levels", roomId, userA, {
-                users_default: 20,
-                users: {
-                    "@bertha:bar": 200,
-                    "@invalid:user": 10  // shouldn't barf on this.
-                }
-            })
-        );
-        member.setPowerLevelEvent(event);
-        expect(member.powerLevel).toEqual(20);
-        expect(member.powerLevelNorm).toEqual(10);
+    describe("getAvatarUrl", function() {
+        const hsUrl = "https://my.home.server";
 
-        var memberB = new RoomMember(roomId, userB);
-        memberB.setPowerLevelEvent(event);
-        expect(memberB.powerLevel).toEqual(200);
-        expect(memberB.powerLevelNorm).toEqual(100);
+        it("should return the URL from m.room.member preferentially", function() {
+            member.events.member = utils.mkEvent({
+                event: true,
+                type: "m.room.member",
+                skey: userA,
+                room: roomId,
+                user: userA,
+                content: {
+                    membership: "join",
+                    avatar_url: "mxc://flibble/wibble",
+                },
+            });
+            const url = member.getAvatarUrl(hsUrl);
+            // we don't care about how the mxc->http conversion is done, other
+            // than it contains the mxc body.
+            expect(url.indexOf("flibble/wibble")).toNotEqual(-1);
+        });
+
+        it("should return an identicon HTTP URL if allowDefault was set and there " +
+        "was no m.room.member event", function() {
+            const url = member.getAvatarUrl(hsUrl, 64, 64, "crop", true);
+            expect(url.indexOf("http")).toEqual(0); // don't care about form
+        });
+
+        it("should return nothing if there is no m.room.member and allowDefault=false",
+        function() {
+            const url = member.getAvatarUrl(hsUrl, 64, 64, "crop", false);
+            expect(url).toEqual(null);
+        });
     });
 
-    it("setTypingEvent should set 'typing'", function() {
-        member.typing = false;
-        var memberB = new RoomMember(roomId, userB);
-        memberB.typing = true;
-        var memberC = new RoomMember(roomId, userC);
-        memberC.typing = true;
+    describe("setPowerLevelEvent", function() {
+        it("should set 'powerLevel' and 'powerLevelNorm'.", function() {
+            const event = utils.mkEvent({
+                type: "m.room.power_levels",
+                room: roomId,
+                user: userA,
+                content: {
+                    users_default: 20,
+                    users: {
+                        "@bertha:bar": 200,
+                        "@invalid:user": 10,  // shouldn't barf on this.
+                    },
+                },
+                event: true,
+            });
+            member.setPowerLevelEvent(event);
+            expect(member.powerLevel).toEqual(20);
+            expect(member.powerLevelNorm).toEqual(10);
 
-        var event = new MatrixEvent(
-            utils.mkEvent("m.typing", roomId, userA, {
-                user_ids: [
-                    userA, userC
-                ]
-            })
-        );
-        member.setTypingEvent(event);
-        memberB.setTypingEvent(event);
-        memberC.setTypingEvent(event);
+            const memberB = new RoomMember(roomId, userB);
+            memberB.setPowerLevelEvent(event);
+            expect(memberB.powerLevel).toEqual(200);
+            expect(memberB.powerLevelNorm).toEqual(100);
+        });
 
-        expect(member.typing).toEqual(true);
-        expect(memberB.typing).toEqual(false);
-        expect(memberC.typing).toEqual(true);
+        it("should emit 'RoomMember.powerLevel' if the power level changes.",
+        function() {
+            const event = utils.mkEvent({
+                type: "m.room.power_levels",
+                room: roomId,
+                user: userA,
+                content: {
+                    users_default: 20,
+                    users: {
+                        "@bertha:bar": 200,
+                        "@invalid:user": 10,  // shouldn't barf on this.
+                    },
+                },
+                event: true,
+            });
+            let emitCount = 0;
+
+            member.on("RoomMember.powerLevel", function(emitEvent, emitMember) {
+                emitCount += 1;
+                expect(emitMember).toEqual(member);
+                expect(emitEvent).toEqual(event);
+            });
+
+            member.setPowerLevelEvent(event);
+            expect(emitCount).toEqual(1);
+            member.setPowerLevelEvent(event); // no-op
+            expect(emitCount).toEqual(1);
+        });
+
+        it("should honour power levels of zero.",
+        function() {
+            const event = utils.mkEvent({
+                type: "m.room.power_levels",
+                room: roomId,
+                user: userA,
+                content: {
+                    users_default: 20,
+                    users: {
+                        "@alice:bar": 0,
+                    },
+                },
+                event: true,
+            });
+            let emitCount = 0;
+
+            // set the power level to something other than zero or we
+            // won't get an event
+            member.powerLevel = 1;
+            member.on("RoomMember.powerLevel", function(emitEvent, emitMember) {
+                emitCount += 1;
+                expect(emitMember.userId).toEqual('@alice:bar');
+                expect(emitMember.powerLevel).toEqual(0);
+                expect(emitEvent).toEqual(event);
+            });
+
+            member.setPowerLevelEvent(event);
+            expect(member.powerLevel).toEqual(0);
+            expect(emitCount).toEqual(1);
+        });
     });
 
+    describe("setTypingEvent", function() {
+        it("should set 'typing'", function() {
+            member.typing = false;
+            const memberB = new RoomMember(roomId, userB);
+            memberB.typing = true;
+            const memberC = new RoomMember(roomId, userC);
+            memberC.typing = true;
+
+            const event = utils.mkEvent({
+                type: "m.typing",
+                user: userA,
+                room: roomId,
+                content: {
+                    user_ids: [
+                        userA, userC,
+                    ],
+                },
+                event: true,
+            });
+            member.setTypingEvent(event);
+            memberB.setTypingEvent(event);
+            memberC.setTypingEvent(event);
+
+            expect(member.typing).toEqual(true);
+            expect(memberB.typing).toEqual(false);
+            expect(memberC.typing).toEqual(true);
+        });
+
+        it("should emit 'RoomMember.typing' if the typing state changes",
+        function() {
+            const event = utils.mkEvent({
+                type: "m.typing",
+                room: roomId,
+                content: {
+                    user_ids: [
+                        userA, userC,
+                    ],
+                },
+                event: true,
+            });
+            let emitCount = 0;
+            member.on("RoomMember.typing", function(ev, mem) {
+                expect(mem).toEqual(member);
+                expect(ev).toEqual(event);
+                emitCount += 1;
+            });
+            member.typing = false;
+            member.setTypingEvent(event);
+            expect(emitCount).toEqual(1);
+            member.setTypingEvent(event); // no-op
+            expect(emitCount).toEqual(1);
+        });
+    });
+
+    describe("isOutOfBand", function() {
+        it("should be set by markOutOfBand", function() {
+            const member = new RoomMember();
+            expect(member.isOutOfBand()).toEqual(false);
+            member.markOutOfBand();
+            expect(member.isOutOfBand()).toEqual(true);
+        });
+    });
+
+    describe("setMembershipEvent", function() {
+        const joinEvent = utils.mkMembership({
+            event: true,
+            mship: "join",
+            user: userA,
+            room: roomId,
+            name: "Alice",
+        });
+
+        const inviteEvent = utils.mkMembership({
+            event: true,
+            mship: "invite",
+            user: userB,
+            skey: userA,
+            room: roomId,
+        });
+
+        it("should set 'membership' and assign the event to 'events.member'.",
+        function() {
+            member.setMembershipEvent(inviteEvent);
+            expect(member.membership).toEqual("invite");
+            expect(member.events.member).toEqual(inviteEvent);
+            member.setMembershipEvent(joinEvent);
+            expect(member.membership).toEqual("join");
+            expect(member.events.member).toEqual(joinEvent);
+        });
+
+        it("should set 'name' based on user_id, displayname and room state",
+        function() {
+            const roomState = {
+                getStateEvents: function(type) {
+                    if (type !== "m.room.member") {
+                        return [];
+                    }
+                    return [
+                        utils.mkMembership({
+                            event: true, mship: "join", room: roomId,
+                            user: userB,
+                        }),
+                        utils.mkMembership({
+                            event: true, mship: "join", room: roomId,
+                            user: userC, name: "Alice",
+                        }),
+                        joinEvent,
+                    ];
+                },
+                getUserIdsWithDisplayName: function(displayName) {
+                    return [userA, userC];
+                },
+            };
+            expect(member.name).toEqual(userA); // default = user_id
+            member.setMembershipEvent(joinEvent);
+            expect(member.name).toEqual("Alice"); // prefer displayname
+            member.setMembershipEvent(joinEvent, roomState);
+            expect(member.name).toNotEqual("Alice"); // it should disambig.
+            // user_id should be there somewhere
+            expect(member.name.indexOf(userA)).toNotEqual(-1);
+        });
+
+        it("should emit 'RoomMember.membership' if the membership changes", function() {
+            let emitCount = 0;
+            member.on("RoomMember.membership", function(ev, mem) {
+                emitCount += 1;
+                expect(mem).toEqual(member);
+                expect(ev).toEqual(inviteEvent);
+            });
+            member.setMembershipEvent(inviteEvent);
+            expect(emitCount).toEqual(1);
+            member.setMembershipEvent(inviteEvent); // no-op
+            expect(emitCount).toEqual(1);
+        });
+
+        it("should emit 'RoomMember.name' if the name changes", function() {
+            let emitCount = 0;
+            member.on("RoomMember.name", function(ev, mem) {
+                emitCount += 1;
+                expect(mem).toEqual(member);
+                expect(ev).toEqual(joinEvent);
+            });
+            member.setMembershipEvent(joinEvent);
+            expect(emitCount).toEqual(1);
+            member.setMembershipEvent(joinEvent); // no-op
+            expect(emitCount).toEqual(1);
+        });
+
+        it("should set 'name' to user_id if it is just whitespace", function() {
+            const joinEvent = utils.mkMembership({
+                event: true,
+                mship: "join",
+                user: userA,
+                room: roomId,
+                name: " \u200b ",
+            });
+
+            expect(member.name).toEqual(userA); // default = user_id
+            member.setMembershipEvent(joinEvent);
+            expect(member.name).toEqual(userA); // it should fallback because all whitespace
+        });
+
+        it("should disambiguate users on a fuzzy displayname match", function() {
+            const joinEvent = utils.mkMembership({
+                event: true,
+                mship: "join",
+                user: userA,
+                room: roomId,
+                name: "Alíce\u200b", // note diacritic and zero width char
+            });
+
+            const roomState = {
+                getStateEvents: function(type) {
+                    if (type !== "m.room.member") {
+                        return [];
+                    }
+                    return [
+                        utils.mkMembership({
+                            event: true, mship: "join", room: roomId,
+                            user: userC, name: "Alice",
+                        }),
+                        joinEvent,
+                    ];
+                },
+                getUserIdsWithDisplayName: function(displayName) {
+                    return [userA, userC];
+                },
+            };
+            expect(member.name).toEqual(userA); // default = user_id
+            member.setMembershipEvent(joinEvent, roomState);
+            expect(member.name).toNotEqual("Alíce"); // it should disambig.
+            // user_id should be there somewhere
+            expect(member.name.indexOf(userA)).toNotEqual(-1);
+        });
+    });
 });

spec/unit/room-state.spec.js

@@ -0,0 +1,644 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const RoomState = sdk.RoomState;
+const RoomMember = sdk.RoomMember;
+const utils = require("../test-utils");
+
+import expect from 'expect';
+
+describe("RoomState", function() {
+    const roomId = "!foo:bar";
+    const userA = "@alice:bar";
+    const userB = "@bob:bar";
+    const userC = "@cleo:bar";
+    const userLazy = "@lazy:bar";
+
+    let state;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        state = new RoomState(roomId);
+        state.setStateEvents([
+            utils.mkMembership({  // userA joined
+                event: true, mship: "join", user: userA, room: roomId,
+            }),
+            utils.mkMembership({  // userB joined
+                event: true, mship: "join", user: userB, room: roomId,
+            }),
+            utils.mkEvent({  // Room name is "Room name goes here"
+                type: "m.room.name", user: userA, room: roomId, event: true, content: {
+                    name: "Room name goes here",
+                },
+            }),
+            utils.mkEvent({  // Room creation
+                type: "m.room.create", user: userA, room: roomId, event: true, content: {
+                    creator: userA,
+                },
+            }),
+        ]);
+    });
+
+    describe("getMembers", function() {
+        it("should return an empty list if there are no members", function() {
+            state = new RoomState(roomId);
+            expect(state.getMembers().length).toEqual(0);
+        });
+
+        it("should return a member for each m.room.member event", function() {
+            const members = state.getMembers();
+            expect(members.length).toEqual(2);
+            // ordering unimportant
+            expect([userA, userB].indexOf(members[0].userId)).toNotEqual(-1);
+            expect([userA, userB].indexOf(members[1].userId)).toNotEqual(-1);
+        });
+    });
+
+    describe("getMember", function() {
+        it("should return null if there is no member", function() {
+            expect(state.getMember("@no-one:here")).toEqual(null);
+        });
+
+        it("should return a member if they exist", function() {
+            expect(state.getMember(userB)).toBeTruthy();
+        });
+
+        it("should return a member which changes as state changes", function() {
+            const member = state.getMember(userB);
+            expect(member.membership).toEqual("join");
+            expect(member.name).toEqual(userB);
+
+            state.setStateEvents([
+                utils.mkMembership({
+                    room: roomId, user: userB, mship: "leave", event: true,
+                    name: "BobGone",
+                }),
+            ]);
+
+            expect(member.membership).toEqual("leave");
+            expect(member.name).toEqual("BobGone");
+        });
+    });
+
+    describe("getSentinelMember", function() {
+        it("should return a member with the user id as name", function() {
+            expect(state.getSentinelMember("@no-one:here").name).toEqual("@no-one:here");
+        });
+
+        it("should return a member which doesn't change when the state is updated",
+        function() {
+            const preLeaveUser = state.getSentinelMember(userA);
+            state.setStateEvents([
+                utils.mkMembership({
+                    room: roomId, user: userA, mship: "leave", event: true,
+                    name: "AliceIsGone",
+                }),
+            ]);
+            const postLeaveUser = state.getSentinelMember(userA);
+
+            expect(preLeaveUser.membership).toEqual("join");
+            expect(preLeaveUser.name).toEqual(userA);
+
+            expect(postLeaveUser.membership).toEqual("leave");
+            expect(postLeaveUser.name).toEqual("AliceIsGone");
+        });
+    });
+
+    describe("getStateEvents", function() {
+        it("should return null if a state_key was specified and there was no match",
+        function() {
+            expect(state.getStateEvents("foo.bar.baz", "keyname")).toEqual(null);
+        });
+
+        it("should return an empty list if a state_key was not specified and there" +
+            " was no match", function() {
+            expect(state.getStateEvents("foo.bar.baz")).toEqual([]);
+        });
+
+        it("should return a list of matching events if no state_key was specified",
+        function() {
+            const events = state.getStateEvents("m.room.member");
+            expect(events.length).toEqual(2);
+            // ordering unimportant
+            expect([userA, userB].indexOf(events[0].getStateKey())).toNotEqual(-1);
+            expect([userA, userB].indexOf(events[1].getStateKey())).toNotEqual(-1);
+        });
+
+        it("should return a single MatrixEvent if a state_key was specified",
+        function() {
+            const event = state.getStateEvents("m.room.member", userA);
+            expect(event.getContent()).toEqual({
+                membership: "join",
+            });
+        });
+    });
+
+    describe("setStateEvents", function() {
+        it("should emit 'RoomState.members' for each m.room.member event", function() {
+            const memberEvents = [
+                utils.mkMembership({
+                    user: "@cleo:bar", mship: "invite", room: roomId, event: true,
+                }),
+                utils.mkMembership({
+                    user: "@daisy:bar", mship: "join", room: roomId, event: true,
+                }),
+            ];
+            let emitCount = 0;
+            state.on("RoomState.members", function(ev, st, mem) {
+                expect(ev).toEqual(memberEvents[emitCount]);
+                expect(st).toEqual(state);
+                expect(mem).toEqual(state.getMember(ev.getSender()));
+                emitCount += 1;
+            });
+            state.setStateEvents(memberEvents);
+            expect(emitCount).toEqual(2);
+        });
+
+        it("should emit 'RoomState.newMember' for each new member added", function() {
+            const memberEvents = [
+                utils.mkMembership({
+                    user: "@cleo:bar", mship: "invite", room: roomId, event: true,
+                }),
+                utils.mkMembership({
+                    user: "@daisy:bar", mship: "join", room: roomId, event: true,
+                }),
+            ];
+            let emitCount = 0;
+            state.on("RoomState.newMember", function(ev, st, mem) {
+                expect(state.getMember(mem.userId)).toEqual(mem);
+                expect(mem.userId).toEqual(memberEvents[emitCount].getSender());
+                expect(mem.membership).toBeFalsy();  // not defined yet
+                emitCount += 1;
+            });
+            state.setStateEvents(memberEvents);
+            expect(emitCount).toEqual(2);
+        });
+
+        it("should emit 'RoomState.events' for each state event", function() {
+            const events = [
+                utils.mkMembership({
+                    user: "@cleo:bar", mship: "invite", room: roomId, event: true,
+                }),
+                utils.mkEvent({
+                    user: userB, room: roomId, type: "m.room.topic", event: true,
+                    content: {
+                        topic: "boo!",
+                    },
+                }),
+                utils.mkMessage({  // Not a state event
+                    user: userA, room: roomId, event: true,
+                }),
+            ];
+            let emitCount = 0;
+            state.on("RoomState.events", function(ev, st) {
+                expect(ev).toEqual(events[emitCount]);
+                expect(st).toEqual(state);
+                emitCount += 1;
+            });
+            state.setStateEvents(events);
+            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);
+
+            const powerLevelEvent = utils.mkEvent({
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    users_default: 10,
+                    state_default: 50,
+                    events_default: 25,
+                },
+            });
+
+            state.setStateEvents([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() {
+            const memberEvent = utils.mkMembership({
+                mship: "join", user: userC, room: roomId, event: true,
+            });
+            const powerLevelEvent = utils.mkEvent({
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    users_default: 10,
+                    state_default: 50,
+                    events_default: 25,
+                    users: {},
+                },
+            });
+
+            state.setStateEvents([powerLevelEvent]);
+            state.setStateEvents([memberEvent]);
+
+            // TODO: We do this because we don't DI the RoomMember constructor
+            // so we can't inject a mock :/ so we have to infer.
+            expect(state.members[userC]).toBeTruthy();
+            expect(state.members[userC].powerLevel).toEqual(10);
+        });
+
+        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,
+            });
+            state.setStateEvents([memberEvent]);
+
+            expect(state.members[userA].setMembershipEvent).toNotHaveBeenCalled();
+            expect(state.members[userB].setMembershipEvent).toHaveBeenCalledWith(
+                memberEvent, state,
+            );
+        });
+    });
+
+    describe("setOutOfBandMembers", function() {
+        it("should add a new member", function() {
+            const oobMemberEvent = utils.mkMembership({
+                user: userLazy, mship: "join", room: roomId, event: true,
+            });
+            state.markOutOfBandMembersStarted();
+            state.setOutOfBandMembers([oobMemberEvent]);
+            const member = state.getMember(userLazy);
+            expect(member.userId).toEqual(userLazy);
+            expect(member.isOutOfBand()).toEqual(true);
+        });
+
+        it("should have no effect when not in correct status", function() {
+            state.setOutOfBandMembers([utils.mkMembership({
+                user: userLazy, mship: "join", room: roomId, event: true,
+            })]);
+            expect(state.getMember(userLazy)).toBeFalsy();
+        });
+
+        it("should emit newMember when adding a member", function() {
+            const userLazy = "@oob:hs";
+            const oobMemberEvent = utils.mkMembership({
+                user: userLazy, mship: "join", room: roomId, event: true,
+            });
+            let eventReceived = false;
+            state.once('RoomState.newMember', (_, __, member) => {
+                expect(member.userId).toEqual(userLazy);
+                eventReceived = true;
+            });
+            state.markOutOfBandMembersStarted();
+            state.setOutOfBandMembers([oobMemberEvent]);
+            expect(eventReceived).toEqual(true);
+        });
+
+        it("should never overwrite existing members", function() {
+            const oobMemberEvent = utils.mkMembership({
+                user: userA, mship: "join", room: roomId, event: true,
+            });
+            state.markOutOfBandMembersStarted();
+            state.setOutOfBandMembers([oobMemberEvent]);
+            const memberA = state.getMember(userA);
+            expect(memberA.events.member.getId()).toNotEqual(oobMemberEvent.getId());
+            expect(memberA.isOutOfBand()).toEqual(false);
+        });
+
+        it("should emit members when updating a member", function() {
+            const doesntExistYetUserId = "@doesntexistyet:hs";
+            const oobMemberEvent = utils.mkMembership({
+                user: doesntExistYetUserId, mship: "join", room: roomId, event: true,
+            });
+            let eventReceived = false;
+            state.once('RoomState.members', (_, __, member) => {
+                expect(member.userId).toEqual(doesntExistYetUserId);
+                eventReceived = true;
+            });
+
+            state.markOutOfBandMembersStarted();
+            state.setOutOfBandMembers([oobMemberEvent]);
+            expect(eventReceived).toEqual(true);
+        });
+    });
+
+    describe("clone", function() {
+        it("should contain same information as original", function() {
+            // include OOB members in copy
+            state.markOutOfBandMembersStarted();
+            state.setOutOfBandMembers([utils.mkMembership({
+                user: userLazy, mship: "join", room: roomId, event: true,
+            })]);
+            const copy = state.clone();
+            // check individual members
+            [userA, userB, userLazy].forEach((userId) => {
+                const member = state.getMember(userId);
+                const memberCopy = copy.getMember(userId);
+                expect(member.name).toEqual(memberCopy.name);
+                expect(member.isOutOfBand()).toEqual(memberCopy.isOutOfBand());
+            });
+            // check member keys
+            expect(Object.keys(state.members)).toEqual(Object.keys(copy.members));
+            // check join count
+            expect(state.getJoinedMemberCount()).toEqual(copy.getJoinedMemberCount());
+        });
+
+        it("should mark old copy as not waiting for out of band anymore", function() {
+            state.markOutOfBandMembersStarted();
+            const copy = state.clone();
+            copy.setOutOfBandMembers([utils.mkMembership({
+                user: userA, mship: "join", room: roomId, event: true,
+            })]);
+            // should have no effect as it should be marked in status finished just like copy
+            state.setOutOfBandMembers([utils.mkMembership({
+                user: userLazy, mship: "join", room: roomId, event: true,
+            })]);
+            expect(state.getMember(userLazy)).toBeFalsy();
+        });
+
+        it("should return copy independent of original", function() {
+            const copy = state.clone();
+            copy.setStateEvents([utils.mkMembership({
+                user: userLazy, mship: "join", room: roomId, event: true,
+            })]);
+
+            expect(state.getMember(userLazy)).toBeFalsy();
+            expect(state.getJoinedMemberCount()).toEqual(2);
+            expect(copy.getJoinedMemberCount()).toEqual(3);
+        });
+    });
+
+    describe("setTypingEvent", function() {
+        it("should call setTypingEvent on each RoomMember", function() {
+            const typingEvent = utils.mkEvent({
+                type: "m.typing", room: roomId, event: true, content: {
+                    user_ids: [userA],
+                },
+            });
+            // mock up the room members
+            state.members[userA] = utils.mock(RoomMember);
+            state.members[userB] = utils.mock(RoomMember);
+            state.setTypingEvent(typingEvent);
+
+            expect(state.members[userA].setTypingEvent).toHaveBeenCalledWith(
+                typingEvent,
+            );
+            expect(state.members[userB].setTypingEvent).toHaveBeenCalledWith(
+                typingEvent,
+            );
+        });
+    });
+
+    describe("maySendStateEvent", function() {
+        it("should say any member may send state with no power level event",
+        function() {
+            expect(state.maySendStateEvent('m.room.name', userA)).toEqual(true);
+        });
+
+        it("should say members with power >=50 may send state with power level event " +
+        "but no state default",
+        function() {
+            const powerLevelEvent = {
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    users_default: 10,
+                    // state_default: 50, "intentionally left blank"
+                    events_default: 25,
+                    users: {
+                    },
+                },
+            };
+            powerLevelEvent.content.users[userA] = 50;
+
+            state.setStateEvents([utils.mkEvent(powerLevelEvent)]);
+
+            expect(state.maySendStateEvent('m.room.name', userA)).toEqual(true);
+            expect(state.maySendStateEvent('m.room.name', userB)).toEqual(false);
+        });
+
+        it("should obey state_default",
+        function() {
+            const powerLevelEvent = {
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    users_default: 10,
+                    state_default: 30,
+                    events_default: 25,
+                    users: {
+                    },
+                },
+            };
+            powerLevelEvent.content.users[userA] = 30;
+            powerLevelEvent.content.users[userB] = 29;
+
+            state.setStateEvents([utils.mkEvent(powerLevelEvent)]);
+
+            expect(state.maySendStateEvent('m.room.name', userA)).toEqual(true);
+            expect(state.maySendStateEvent('m.room.name', userB)).toEqual(false);
+        });
+
+        it("should honour explicit event power levels in the power_levels event",
+        function() {
+            const powerLevelEvent = {
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    events: {
+                        "m.room.other_thing": 76,
+                    },
+                    users_default: 10,
+                    state_default: 50,
+                    events_default: 25,
+                    users: {
+                    },
+                },
+            };
+            powerLevelEvent.content.users[userA] = 80;
+            powerLevelEvent.content.users[userB] = 50;
+
+            state.setStateEvents([utils.mkEvent(powerLevelEvent)]);
+
+            expect(state.maySendStateEvent('m.room.name', userA)).toEqual(true);
+            expect(state.maySendStateEvent('m.room.name', userB)).toEqual(true);
+
+            expect(state.maySendStateEvent('m.room.other_thing', userA)).toEqual(true);
+            expect(state.maySendStateEvent('m.room.other_thing', userB)).toEqual(false);
+        });
+    });
+
+    describe("getJoinedMemberCount", function() {
+        beforeEach(() => {
+            state = new RoomState(roomId);
+        });
+
+        it("should update after adding joined member", function() {
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "join",
+                    user: userA, room: roomId}),
+            ]);
+            expect(state.getJoinedMemberCount()).toEqual(1);
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "join",
+                    user: userC, room: roomId}),
+            ]);
+            expect(state.getJoinedMemberCount()).toEqual(2);
+        });
+    });
+
+    describe("getInvitedMemberCount", function() {
+        beforeEach(() => {
+            state = new RoomState(roomId);
+        });
+
+        it("should update after adding invited member", function() {
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "invite",
+                    user: userA, room: roomId}),
+            ]);
+            expect(state.getInvitedMemberCount()).toEqual(1);
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "invite",
+                    user: userC, room: roomId}),
+            ]);
+            expect(state.getInvitedMemberCount()).toEqual(2);
+        });
+    });
+
+    describe("setJoinedMemberCount", function() {
+        beforeEach(() => {
+            state = new RoomState(roomId);
+        });
+
+        it("should, once used, override counting members from state", function() {
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "join",
+                    user: userA, room: roomId}),
+            ]);
+            expect(state.getJoinedMemberCount()).toEqual(1);
+            state.setJoinedMemberCount(100);
+            expect(state.getJoinedMemberCount()).toEqual(100);
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "join",
+                    user: userC, room: roomId}),
+            ]);
+            expect(state.getJoinedMemberCount()).toEqual(100);
+        });
+
+        it("should, once used, override counting members from state, " +
+        "also after clone", function() {
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "join",
+                    user: userA, room: roomId}),
+            ]);
+            state.setJoinedMemberCount(100);
+            const copy = state.clone();
+            copy.setStateEvents([
+                utils.mkMembership({event: true, mship: "join",
+                    user: userC, room: roomId}),
+            ]);
+            expect(state.getJoinedMemberCount()).toEqual(100);
+        });
+    });
+
+    describe("setInvitedMemberCount", function() {
+        beforeEach(() => {
+            state = new RoomState(roomId);
+        });
+
+        it("should, once used, override counting members from state", function() {
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "invite",
+                    user: userB, room: roomId}),
+            ]);
+            expect(state.getInvitedMemberCount()).toEqual(1);
+            state.setInvitedMemberCount(100);
+            expect(state.getInvitedMemberCount()).toEqual(100);
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "invite",
+                    user: userC, room: roomId}),
+            ]);
+            expect(state.getInvitedMemberCount()).toEqual(100);
+        });
+
+        it("should, once used, override counting members from state, " +
+        "also after clone", function() {
+            state.setStateEvents([
+                utils.mkMembership({event: true, mship: "invite",
+                    user: userB, room: roomId}),
+            ]);
+            state.setInvitedMemberCount(100);
+            const copy = state.clone();
+            copy.setStateEvents([
+                utils.mkMembership({event: true, mship: "invite",
+                    user: userC, room: roomId}),
+            ]);
+            expect(state.getInvitedMemberCount()).toEqual(100);
+        });
+    });
+
+    describe("maySendEvent", function() {
+        it("should say any member may send events with no power level event",
+        function() {
+            expect(state.maySendEvent('m.room.message', userA)).toEqual(true);
+            expect(state.maySendMessage(userA)).toEqual(true);
+        });
+
+        it("should obey events_default",
+        function() {
+            const powerLevelEvent = {
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    users_default: 10,
+                    state_default: 30,
+                    events_default: 25,
+                    users: {
+                    },
+                },
+            };
+            powerLevelEvent.content.users[userA] = 26;
+            powerLevelEvent.content.users[userB] = 24;
+
+            state.setStateEvents([utils.mkEvent(powerLevelEvent)]);
+
+            expect(state.maySendEvent('m.room.message', userA)).toEqual(true);
+            expect(state.maySendEvent('m.room.message', userB)).toEqual(false);
+
+            expect(state.maySendMessage(userA)).toEqual(true);
+            expect(state.maySendMessage(userB)).toEqual(false);
+        });
+
+        it("should honour explicit event power levels in the power_levels event",
+        function() {
+            const powerLevelEvent = {
+                type: "m.room.power_levels", room: roomId, user: userA, event: true,
+                content: {
+                    events: {
+                        "m.room.other_thing": 33,
+                    },
+                    users_default: 10,
+                    state_default: 50,
+                    events_default: 25,
+                    users: {
+                    },
+                },
+            };
+            powerLevelEvent.content.users[userA] = 40;
+            powerLevelEvent.content.users[userB] = 30;
+
+            state.setStateEvents([utils.mkEvent(powerLevelEvent)]);
+
+            expect(state.maySendEvent('m.room.message', userA)).toEqual(true);
+            expect(state.maySendEvent('m.room.message', userB)).toEqual(true);
+
+            expect(state.maySendMessage(userA)).toEqual(true);
+            expect(state.maySendMessage(userB)).toEqual(true);
+
+            expect(state.maySendEvent('m.room.other_thing', userA)).toEqual(true);
+            expect(state.maySendEvent('m.room.other_thing', userB)).toEqual(false);
+        });
+    });
+});

spec/unit/scheduler.spec.js

@@ -0,0 +1,374 @@
+// This file had a function whose name is all caps, which displeases eslint
+/* eslint new-cap: "off" */
+
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const MatrixScheduler = sdk.MatrixScheduler;
+const MatrixError = sdk.MatrixError;
+const utils = require("../test-utils");
+
+import expect from 'expect';
+import lolex from 'lolex';
+
+describe("MatrixScheduler", function() {
+    let clock;
+    let scheduler;
+    let retryFn;
+    let queueFn;
+    let defer;
+    const roomId = "!foo:bar";
+    const eventA = utils.mkMessage({
+        user: "@alice:bar", room: roomId, event: true,
+    });
+    const eventB = utils.mkMessage({
+        user: "@alice:bar", room: roomId, event: true,
+    });
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        clock = lolex.install();
+        scheduler = new MatrixScheduler(function(ev, attempts, err) {
+            if (retryFn) {
+                return retryFn(ev, attempts, err);
+            }
+            return -1;
+        }, function(event) {
+            if (queueFn) {
+                return queueFn(event);
+            }
+            return null;
+        });
+        retryFn = null;
+        queueFn = null;
+        defer = Promise.defer();
+    });
+
+    afterEach(function() {
+        clock.uninstall();
+    });
+
+    it("should process events in a queue in a FIFO manner", async function() {
+        retryFn = function() {
+            return 0;
+        };
+        queueFn = function() {
+            return "one_big_queue";
+        };
+        const deferA = Promise.defer();
+        const deferB = Promise.defer();
+        let yieldedA = false;
+        scheduler.setProcessFunction(function(event) {
+            if (yieldedA) {
+                expect(event).toEqual(eventB);
+                return deferB.promise;
+            } else {
+                yieldedA = true;
+                expect(event).toEqual(eventA);
+                return deferA.promise;
+            }
+        });
+        const abPromise = Promise.all([
+            scheduler.queueEvent(eventA),
+            scheduler.queueEvent(eventB),
+        ]);
+        deferB.resolve({b: true});
+        deferA.resolve({a: true});
+        const [a, b] = await abPromise;
+        expect(a.a).toEqual(true);
+        expect(b.b).toEqual(true);
+    });
+
+    it("should invoke the retryFn on failure and wait the amount of time specified",
+    async function() {
+        const waitTimeMs = 1500;
+        const retryDefer = Promise.defer();
+        retryFn = function() {
+            retryDefer.resolve();
+            return waitTimeMs;
+        };
+        queueFn = function() {
+            return "yep";
+        };
+
+        let procCount = 0;
+        scheduler.setProcessFunction(function(ev) {
+            procCount += 1;
+            if (procCount === 1) {
+                expect(ev).toEqual(eventA);
+                return defer.promise;
+            } else if (procCount === 2) {
+                // don't care about this defer
+                return new Promise();
+            }
+            expect(procCount).toBeLessThan(3);
+        });
+
+        scheduler.queueEvent(eventA);
+        // as queueing doesn't start processing synchronously anymore (see commit bbdb5ac)
+        // wait just long enough before it does
+        await Promise.resolve();
+        expect(procCount).toEqual(1);
+        defer.reject({});
+        await retryDefer.promise;
+        expect(procCount).toEqual(1);
+        clock.tick(waitTimeMs);
+        await Promise.resolve();
+        expect(procCount).toEqual(2);
+    });
+
+    it("should give up if the retryFn on failure returns -1 and try the next event",
+    async function() {
+        // Queue A & B.
+        // Reject A and return -1 on retry.
+        // Expect B to be tried next and the promise for A to be rejected.
+        retryFn = function() {
+            return -1;
+        };
+        queueFn = function() {
+            return "yep";
+        };
+
+        const deferA = Promise.defer();
+        const deferB = Promise.defer();
+        let procCount = 0;
+        scheduler.setProcessFunction(function(ev) {
+            procCount += 1;
+            if (procCount === 1) {
+                expect(ev).toEqual(eventA);
+                return deferA.promise;
+            } else if (procCount === 2) {
+                expect(ev).toEqual(eventB);
+                return deferB.promise;
+            }
+            expect(procCount).toBeLessThan(3);
+        });
+
+        const globalA = scheduler.queueEvent(eventA);
+        scheduler.queueEvent(eventB);
+        // as queueing doesn't start processing synchronously anymore (see commit bbdb5ac)
+        // wait just long enough before it does
+        await Promise.resolve();
+        expect(procCount).toEqual(1);
+        deferA.reject({});
+        try {
+            await globalA;
+        } catch(err) {
+            await Promise.resolve();
+            expect(procCount).toEqual(2);
+        }
+    });
+
+    it("should treat each queue separately", function(done) {
+        // Queue messages A B C D.
+        // Bucket A&D into queue_A
+        // Bucket B&C into queue_B
+        // Expect to have processFn invoked for A&B.
+        // Resolve A.
+        // Expect to have processFn invoked for D.
+        const eventC = utils.mkMessage({user: "@a:bar", room: roomId, event: true});
+        const eventD = utils.mkMessage({user: "@b:bar", room: roomId, event: true});
+
+        const buckets = {};
+        buckets[eventA.getId()] = "queue_A";
+        buckets[eventD.getId()] = "queue_A";
+        buckets[eventB.getId()] = "queue_B";
+        buckets[eventC.getId()] = "queue_B";
+
+        retryFn = function() {
+            return 0;
+        };
+        queueFn = function(event) {
+            return buckets[event.getId()];
+        };
+
+        const expectOrder = [
+            eventA.getId(), eventB.getId(), eventD.getId(),
+        ];
+        const deferA = Promise.defer();
+        scheduler.setProcessFunction(function(event) {
+            const id = expectOrder.shift();
+            expect(id).toEqual(event.getId());
+            if (expectOrder.length === 0) {
+                done();
+            }
+            return id === eventA.getId() ? deferA.promise : defer.promise;
+        });
+        scheduler.queueEvent(eventA);
+        scheduler.queueEvent(eventB);
+        scheduler.queueEvent(eventC);
+        scheduler.queueEvent(eventD);
+
+        // wait a bit then resolve A and we should get D (not C) next.
+        setTimeout(function() {
+            deferA.resolve({});
+        }, 1000);
+        clock.tick(1000);
+    });
+
+    describe("queueEvent", function() {
+        it("should return null if the event shouldn't be queued", function() {
+            queueFn = function() {
+                return null;
+            };
+            expect(scheduler.queueEvent(eventA)).toEqual(null);
+        });
+
+        it("should return a Promise if the event is queued", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            const prom = scheduler.queueEvent(eventA);
+            expect(prom).toBeTruthy();
+            expect(prom.then).toBeTruthy();
+        });
+    });
+
+    describe("getQueueForEvent", function() {
+        it("should return null if the event doesn't map to a queue name", function() {
+            queueFn = function() {
+                return null;
+            };
+            expect(scheduler.getQueueForEvent(eventA)).toBe(null);
+        });
+
+        it("should return null if the mapped queue doesn't exist", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            expect(scheduler.getQueueForEvent(eventA)).toBe(null);
+        });
+
+        it("should return a list of events in the queue and modifications to" +
+        " the list should not affect the underlying queue.", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            scheduler.queueEvent(eventA);
+            scheduler.queueEvent(eventB);
+            const queue = scheduler.getQueueForEvent(eventA);
+            expect(queue.length).toEqual(2);
+            expect(queue).toEqual([eventA, eventB]);
+            // modify the queue
+            const eventC = utils.mkMessage(
+                {user: "@a:bar", room: roomId, event: true},
+            );
+            queue.push(eventC);
+            const queueAgain = scheduler.getQueueForEvent(eventA);
+            expect(queueAgain.length).toEqual(2);
+        });
+
+        it("should return a list of events in the queue and modifications to" +
+        " an event in the queue should affect the underlying queue.", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            scheduler.queueEvent(eventA);
+            scheduler.queueEvent(eventB);
+            const queue = scheduler.getQueueForEvent(eventA);
+            queue[1].event.content.body = "foo";
+            const queueAgain = scheduler.getQueueForEvent(eventA);
+            expect(queueAgain[1].event.content.body).toEqual("foo");
+        });
+    });
+
+    describe("removeEventFromQueue", function() {
+        it("should return false if the event doesn't map to a queue name", function() {
+            queueFn = function() {
+                return null;
+            };
+            expect(scheduler.removeEventFromQueue(eventA)).toBe(false);
+        });
+
+        it("should return false if the event isn't in the queue", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            expect(scheduler.removeEventFromQueue(eventA)).toBe(false);
+        });
+
+        it("should return true if the event was removed", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            scheduler.queueEvent(eventA);
+            expect(scheduler.removeEventFromQueue(eventA)).toBe(true);
+        });
+    });
+
+    describe("setProcessFunction", function() {
+        it("should call the processFn if there are queued events", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            let procCount = 0;
+            scheduler.queueEvent(eventA);
+            scheduler.setProcessFunction(function(ev) {
+                procCount += 1;
+                expect(ev).toEqual(eventA);
+                return defer.promise;
+            });
+            // as queueing doesn't start processing synchronously anymore (see commit bbdb5ac)
+            // wait just long enough before it does
+            Promise.resolve().then(() => {
+                expect(procCount).toEqual(1);
+            });
+        });
+
+        it("should not call the processFn if there are no queued events", function() {
+            queueFn = function() {
+                return "yep";
+            };
+            let procCount = 0;
+            scheduler.setProcessFunction(function(ev) {
+                procCount += 1;
+                return defer.promise;
+            });
+            expect(procCount).toEqual(0);
+        });
+    });
+
+    describe("QUEUE_MESSAGES", function() {
+        it("should queue m.room.message events only", function() {
+            expect(MatrixScheduler.QUEUE_MESSAGES(eventA)).toEqual("message");
+            expect(MatrixScheduler.QUEUE_MESSAGES(
+                utils.mkMembership({
+                    user: "@alice:bar", room: roomId, mship: "join", event: true,
+                }),
+            )).toEqual(null);
+        });
+    });
+
+    describe("RETRY_BACKOFF_RATELIMIT", function() {
+        it("should wait at least the time given on M_LIMIT_EXCEEDED", function() {
+            const res = MatrixScheduler.RETRY_BACKOFF_RATELIMIT(
+                eventA, 1, new MatrixError({
+                    errcode: "M_LIMIT_EXCEEDED", retry_after_ms: 5000,
+                }),
+            );
+            expect(res >= 500).toBe(true, "Didn't wait long enough.");
+        });
+
+        it("should give up after 5 attempts", function() {
+            const res = MatrixScheduler.RETRY_BACKOFF_RATELIMIT(
+                eventA, 5, {},
+            );
+            expect(res).toBe(-1, "Didn't give up.");
+        });
+
+        it("should do exponential backoff", function() {
+            expect(MatrixScheduler.RETRY_BACKOFF_RATELIMIT(
+                eventA, 1, {},
+            )).toEqual(2000);
+            expect(MatrixScheduler.RETRY_BACKOFF_RATELIMIT(
+                eventA, 2, {},
+            )).toEqual(4000);
+            expect(MatrixScheduler.RETRY_BACKOFF_RATELIMIT(
+                eventA, 3, {},
+            )).toEqual(8000);
+            expect(MatrixScheduler.RETRY_BACKOFF_RATELIMIT(
+                eventA, 4, {},
+            )).toEqual(16000);
+        });
+    });
+});

spec/unit/sync-accumulator.spec.js

@@ -0,0 +1,413 @@
+/*
+Copyright 2017 Vector Creations 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.
+*/
+
+"use strict";
+import 'source-map-support/register';
+import utils from "../test-utils";
+import sdk from "../..";
+import expect from 'expect';
+
+const SyncAccumulator = sdk.SyncAccumulator;
+
+describe("SyncAccumulator", function() {
+    let sa;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        sa = new SyncAccumulator({
+            maxTimelineEntries: 10,
+        });
+    });
+
+    it("should return the same /sync response if accumulated exactly once", () => {
+        // technically cheating since we also cheekily pre-populate keys we
+        // know that the sync accumulator will pre-populate.
+        // It isn't 100% transitive.
+        const res = {
+            next_batch: "abc",
+            rooms: {
+                invite: {},
+                leave: {},
+                join: {
+                    "!foo:bar": {
+                        account_data: { events: [] },
+                        ephemeral: { events: [] },
+                        unread_notifications: {},
+                        state: {
+                            events: [
+                                member("alice", "join"),
+                                member("bob", "join"),
+                            ],
+                        },
+                        summary: {
+                            "m.heroes": undefined,
+                            "m.joined_member_count": undefined,
+                            "m.invited_member_count": undefined,
+                        },
+                        timeline: {
+                            events: [msg("alice", "hi")],
+                            prev_batch: "something",
+                        },
+                    },
+                },
+            },
+        };
+        sa.accumulate(res);
+        const output = sa.getJSON();
+        expect(output.nextBatch).toEqual(res.next_batch);
+        expect(output.roomsData).toEqual(res.rooms);
+    });
+
+    it("should prune the timeline to the oldest prev_batch within the limit", () => {
+        // maxTimelineEntries is 10 so we should get back all
+        // 10 timeline messages with a prev_batch of "pinned_to_1"
+        sa.accumulate(syncSkeleton({
+            state: { events: [member("alice", "join")] },
+            timeline: {
+                events: [
+                    msg("alice", "1"),
+                    msg("alice", "2"),
+                    msg("alice", "3"),
+                    msg("alice", "4"),
+                    msg("alice", "5"),
+                    msg("alice", "6"),
+                    msg("alice", "7"),
+                ],
+                prev_batch: "pinned_to_1",
+            },
+        }));
+        sa.accumulate(syncSkeleton({
+            state: { events: [] },
+            timeline: {
+                events: [
+                    msg("alice", "8"),
+                ],
+                prev_batch: "pinned_to_8",
+            },
+        }));
+        sa.accumulate(syncSkeleton({
+            state: { events: [] },
+            timeline: {
+                events: [
+                    msg("alice", "9"),
+                    msg("alice", "10"),
+                ],
+                prev_batch: "pinned_to_10",
+            },
+        }));
+
+        let output = sa.getJSON().roomsData.join["!foo:bar"];
+
+        expect(output.timeline.events.length).toEqual(10);
+        output.timeline.events.forEach((e, i) => {
+            expect(e.content.body).toEqual(""+(i+1));
+        });
+        expect(output.timeline.prev_batch).toEqual("pinned_to_1");
+
+        // accumulate more messages. Now it can't have a prev_batch of "pinned to 1"
+        // AND give us <= 10 messages without losing messages in-between.
+        // It should try to find the oldest prev_batch which still fits into 10
+        // messages, which is "pinned to 8".
+        sa.accumulate(syncSkeleton({
+            state: { events: [] },
+            timeline: {
+                events: [
+                    msg("alice", "11"),
+                    msg("alice", "12"),
+                    msg("alice", "13"),
+                    msg("alice", "14"),
+                    msg("alice", "15"),
+                    msg("alice", "16"),
+                    msg("alice", "17"),
+                ],
+                prev_batch: "pinned_to_11",
+            },
+        }));
+
+        output = sa.getJSON().roomsData.join["!foo:bar"];
+
+        expect(output.timeline.events.length).toEqual(10);
+        output.timeline.events.forEach((e, i) => {
+            expect(e.content.body).toEqual(""+(i+8));
+        });
+        expect(output.timeline.prev_batch).toEqual("pinned_to_8");
+    });
+
+    it("should remove the stored timeline on limited syncs", () => {
+        sa.accumulate(syncSkeleton({
+            state: { events: [member("alice", "join")] },
+            timeline: {
+                events: [
+                    msg("alice", "1"),
+                    msg("alice", "2"),
+                    msg("alice", "3"),
+                ],
+                prev_batch: "pinned_to_1",
+            },
+        }));
+        // some time passes and now we get a limited sync
+        sa.accumulate(syncSkeleton({
+            state: { events: [] },
+            timeline: {
+                limited: true,
+                events: [
+                    msg("alice", "51"),
+                    msg("alice", "52"),
+                    msg("alice", "53"),
+                ],
+                prev_batch: "pinned_to_51",
+            },
+        }));
+
+        const output = sa.getJSON().roomsData.join["!foo:bar"];
+
+        expect(output.timeline.events.length).toEqual(3);
+        output.timeline.events.forEach((e, i) => {
+            expect(e.content.body).toEqual(""+(i+51));
+        });
+        expect(output.timeline.prev_batch).toEqual("pinned_to_51");
+    });
+
+    it("should drop typing notifications", () => {
+        const res = syncSkeleton({
+            ephemeral: {
+                events: [{
+                    type: "m.typing",
+                    content: {
+                        user_ids: ["@alice:localhost"],
+                    },
+                    room_id: "!foo:bar",
+                }],
+            },
+        });
+        sa.accumulate(res);
+        expect(
+            sa.getJSON().roomsData.join["!foo:bar"].ephemeral.events.length,
+        ).toEqual(0);
+    });
+
+    it("should clobber account data based on event type", () => {
+        const acc1 = {
+            type: "favourite.food",
+            content: {
+                food: "banana",
+            },
+        };
+        const acc2 = {
+            type: "favourite.food",
+            content: {
+                food: "apple",
+            },
+        };
+        sa.accumulate(syncSkeleton({
+            account_data: {
+                events: [acc1],
+            },
+        }));
+        sa.accumulate(syncSkeleton({
+            account_data: {
+                events: [acc2],
+            },
+        }));
+        expect(
+            sa.getJSON().roomsData.join["!foo:bar"].account_data.events.length,
+        ).toEqual(1);
+        expect(
+            sa.getJSON().roomsData.join["!foo:bar"].account_data.events[0],
+        ).toEqual(acc2);
+    });
+
+    it("should clobber global account data based on event type", () => {
+        const acc1 = {
+            type: "favourite.food",
+            content: {
+                food: "banana",
+            },
+        };
+        const acc2 = {
+            type: "favourite.food",
+            content: {
+                food: "apple",
+            },
+        };
+        sa.accumulate({
+            account_data: {
+                events: [acc1],
+            },
+        });
+        sa.accumulate({
+            account_data: {
+                events: [acc2],
+            },
+        });
+        expect(
+            sa.getJSON().accountData.length,
+        ).toEqual(1);
+        expect(
+            sa.getJSON().accountData[0],
+        ).toEqual(acc2);
+    });
+
+    it("should accumulate read receipts", () => {
+        const receipt1 = {
+            type: "m.receipt",
+            room_id: "!foo:bar",
+            content: {
+                "$event1:localhost": {
+                    "m.read": {
+                        "@alice:localhost": { ts: 1 },
+                        "@bob:localhost": { ts: 2 },
+                    },
+                    "some.other.receipt.type": {
+                        "@should_be_ignored:localhost": { key: "val" },
+                    },
+                },
+            },
+        };
+        const receipt2 = {
+            type: "m.receipt",
+            room_id: "!foo:bar",
+            content: {
+                "$event2:localhost": {
+                    "m.read": {
+                        "@bob:localhost": { ts: 2 }, // clobbers event1 receipt
+                        "@charlie:localhost": { ts: 3 },
+                    },
+                },
+            },
+        };
+        sa.accumulate(syncSkeleton({
+            ephemeral: {
+                events: [receipt1],
+            },
+        }));
+        sa.accumulate(syncSkeleton({
+            ephemeral: {
+                events: [receipt2],
+            },
+        }));
+
+        expect(
+            sa.getJSON().roomsData.join["!foo:bar"].ephemeral.events.length,
+        ).toEqual(1);
+        expect(
+            sa.getJSON().roomsData.join["!foo:bar"].ephemeral.events[0],
+        ).toEqual({
+            type: "m.receipt",
+            room_id: "!foo:bar",
+            content: {
+                "$event1:localhost": {
+                    "m.read": {
+                        "@alice:localhost": { ts: 1 },
+                    },
+                },
+                "$event2:localhost": {
+                    "m.read": {
+                        "@bob:localhost": { ts: 2 },
+                        "@charlie:localhost": { ts: 3 },
+                    },
+                },
+            },
+        });
+    });
+
+    describe("summary field", function() {
+        function createSyncResponseWithSummary(summary) {
+            return {
+                next_batch: "abc",
+                rooms: {
+                    invite: {},
+                    leave: {},
+                    join: {
+                        "!foo:bar": {
+                            account_data: { events: [] },
+                            ephemeral: { events: [] },
+                            unread_notifications: {},
+                            state: {
+                                events: [],
+                            },
+                            summary: summary,
+                            timeline: {
+                                events: [],
+                                prev_batch: "something",
+                            },
+                        },
+                    },
+                },
+            };
+        }
+
+        it("should copy summary properties", function() {
+            sa.accumulate(createSyncResponseWithSummary({
+                "m.heroes": ["@alice:bar"],
+                "m.invited_member_count": 2,
+            }));
+            const summary = sa.getJSON().roomsData.join["!foo:bar"].summary;
+            expect(summary["m.invited_member_count"]).toEqual(2);
+            expect(summary["m.heroes"]).toEqual(["@alice:bar"]);
+        });
+
+        it("should accumulate summary properties", function() {
+            sa.accumulate(createSyncResponseWithSummary({
+                "m.heroes": ["@alice:bar"],
+                "m.invited_member_count": 2,
+            }));
+            sa.accumulate(createSyncResponseWithSummary({
+                "m.heroes": ["@bob:bar"],
+                "m.joined_member_count": 5,
+            }));
+            const summary = sa.getJSON().roomsData.join["!foo:bar"].summary;
+            expect(summary["m.invited_member_count"]).toEqual(2);
+            expect(summary["m.joined_member_count"]).toEqual(5);
+            expect(summary["m.heroes"]).toEqual(["@bob:bar"]);
+        });
+    });
+});
+
+function syncSkeleton(joinObj) {
+    joinObj = joinObj || {};
+    return {
+        next_batch: "abc",
+        rooms: {
+            join: {
+                "!foo:bar": joinObj,
+            },
+        },
+    };
+}
+
+function msg(localpart, text) {
+    return {
+        content: {
+            body: text,
+        },
+        origin_server_ts: 123456789,
+        sender: "@" + localpart + ":localhost",
+        type: "m.room.message",
+    };
+}
+
+function member(localpart, membership) {
+    return {
+        content: {
+            membership: membership,
+        },
+        origin_server_ts: 123456789,
+        state_key: "@" + localpart + ":localhost",
+        sender: "@" + localpart + ":localhost",
+        type: "m.room.member",
+    };
+}

spec/unit/timeline-window.spec.js

@@ -0,0 +1,477 @@
+"use strict";
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const EventTimeline = sdk.EventTimeline;
+const TimelineWindow = sdk.TimelineWindow;
+const TimelineIndex = require("../../lib/timeline-window").TimelineIndex;
+
+const utils = require("../test-utils");
+import expect from 'expect';
+
+const ROOM_ID = "roomId";
+const USER_ID = "userId";
+
+/*
+ * create a timeline with a bunch (default 3) events.
+ * baseIndex is 1 by default.
+ */
+function createTimeline(numEvents, baseIndex) {
+    if (numEvents === undefined) {
+        numEvents = 3;
+    }
+    if (baseIndex === undefined) {
+        baseIndex = 1;
+    }
+
+    // XXX: this is a horrid hack
+    const timelineSet = { room: { roomId: ROOM_ID }};
+    timelineSet.room.getUnfilteredTimelineSet = function() {
+        return timelineSet;
+    };
+
+    const timeline = new EventTimeline(timelineSet);
+
+    // add the events after the baseIndex first
+    addEventsToTimeline(timeline, numEvents - baseIndex, false);
+
+    // then add those before the baseIndex
+    addEventsToTimeline(timeline, baseIndex, true);
+
+    expect(timeline.getBaseIndex()).toEqual(baseIndex);
+    return timeline;
+}
+
+function addEventsToTimeline(timeline, numEvents, atStart) {
+    for (let i = 0; i < numEvents; i++) {
+        timeline.addEvent(
+            utils.mkMessage({
+                room: ROOM_ID, user: USER_ID,
+                event: true,
+            }), atStart,
+        );
+    }
+}
+
+
+/*
+ * create a pair of linked timelines
+ */
+function createLinkedTimelines() {
+    const tl1 = createTimeline();
+    const tl2 = createTimeline();
+    tl1.setNeighbouringTimeline(tl2, EventTimeline.FORWARDS);
+    tl2.setNeighbouringTimeline(tl1, EventTimeline.BACKWARDS);
+    return [tl1, tl2];
+}
+
+
+describe("TimelineIndex", function() {
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+    });
+
+    describe("minIndex", function() {
+        it("should return the min index relative to BaseIndex", function() {
+            const timelineIndex = new TimelineIndex(createTimeline(), 0);
+            expect(timelineIndex.minIndex()).toEqual(-1);
+        });
+    });
+
+    describe("maxIndex", function() {
+        it("should return the max index relative to BaseIndex", function() {
+            const timelineIndex = new TimelineIndex(createTimeline(), 0);
+            expect(timelineIndex.maxIndex()).toEqual(2);
+        });
+    });
+
+    describe("advance", function() {
+        it("should advance up to the end of the timeline", function() {
+            const timelineIndex = new TimelineIndex(createTimeline(), 0);
+            const result = timelineIndex.advance(3);
+            expect(result).toEqual(2);
+            expect(timelineIndex.index).toEqual(2);
+        });
+
+        it("should retreat back to the start of the timeline", function() {
+            const timelineIndex = new TimelineIndex(createTimeline(), 0);
+            const result = timelineIndex.advance(-2);
+            expect(result).toEqual(-1);
+            expect(timelineIndex.index).toEqual(-1);
+        });
+
+        it("should advance into the next timeline", function() {
+            const timelines = createLinkedTimelines();
+            const tl1 = timelines[0];
+            const tl2 = timelines[1];
+
+            // initialise the index pointing at the end of the first timeline
+            const timelineIndex = new TimelineIndex(tl1, 2);
+
+            const result = timelineIndex.advance(1);
+            expect(result).toEqual(1);
+            expect(timelineIndex.timeline).toBe(tl2);
+
+            // we expect the index to be the zero (ie, the same as the
+            // BaseIndex), because the BaseIndex points at the second event,
+            // and we've advanced past the first.
+            expect(timelineIndex.index).toEqual(0);
+        });
+
+        it("should retreat into the previous timeline", function() {
+            const timelines = createLinkedTimelines();
+            const tl1 = timelines[0];
+            const tl2 = timelines[1];
+
+            // initialise the index pointing at the start of the second
+            // timeline
+            const timelineIndex = new TimelineIndex(tl2, -1);
+
+            const result = timelineIndex.advance(-1);
+            expect(result).toEqual(-1);
+            expect(timelineIndex.timeline).toBe(tl1);
+            expect(timelineIndex.index).toEqual(1);
+        });
+    });
+
+    describe("retreat", function() {
+        it("should retreat up to the start of the timeline", function() {
+            const timelineIndex = new TimelineIndex(createTimeline(), 0);
+            const result = timelineIndex.retreat(2);
+            expect(result).toEqual(1);
+            expect(timelineIndex.index).toEqual(-1);
+        });
+    });
+});
+
+
+describe("TimelineWindow", function() {
+    /**
+     * create a dummy eventTimelineSet and client, and a TimelineWindow
+     * attached to them.
+     */
+    let timelineSet;
+    let client;
+    function createWindow(timeline, opts) {
+        timelineSet = {};
+        client = {};
+        client.getEventTimeline = function(timelineSet0, eventId0) {
+            expect(timelineSet0).toBe(timelineSet);
+            return Promise.resolve(timeline);
+        };
+
+        return new TimelineWindow(client, timelineSet, opts);
+    }
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+    });
+
+    describe("load", function() {
+        it("should initialise from the live timeline", function(done) {
+            const liveTimeline = createTimeline();
+            const room = {};
+            room.getLiveTimeline = function() {
+                return liveTimeline;
+            };
+
+            const timelineWindow = new TimelineWindow(undefined, room);
+            timelineWindow.load(undefined, 2).then(function() {
+                const expectedEvents = liveTimeline.getEvents().slice(1);
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+            }).nodeify(done);
+        });
+
+        it("should initialise from a specific event", function(done) {
+            const timeline = createTimeline();
+            const eventId = timeline.getEvents()[1].getId();
+
+            const timelineSet = {};
+            const client = {};
+            client.getEventTimeline = function(timelineSet0, eventId0) {
+                expect(timelineSet0).toBe(timelineSet);
+                expect(eventId0).toEqual(eventId);
+                return Promise.resolve(timeline);
+            };
+
+            const timelineWindow = new TimelineWindow(client, timelineSet);
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = timeline.getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+            }).nodeify(done);
+        });
+
+        it("canPaginate should return false until load has returned",
+           function(done) {
+            const timeline = createTimeline();
+            timeline.setPaginationToken("toktok1", EventTimeline.BACKWARDS);
+            timeline.setPaginationToken("toktok2", EventTimeline.FORWARDS);
+
+            const eventId = timeline.getEvents()[1].getId();
+
+            const timelineSet = {};
+            const client = {};
+
+            const timelineWindow = new TimelineWindow(client, timelineSet);
+
+            client.getEventTimeline = function(timelineSet0, eventId0) {
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+                return Promise.resolve(timeline);
+            };
+
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = timeline.getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+            }).nodeify(done);
+        });
+    });
+
+    describe("pagination", function() {
+        it("should be able to advance across the initial timeline",
+           function(done) {
+            const timeline = createTimeline();
+            const eventId = timeline.getEvents()[1].getId();
+            const timelineWindow = createWindow(timeline);
+
+            timelineWindow.load(eventId, 1).then(function() {
+                const expectedEvents = [timeline.getEvents()[1]];
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                const expectedEvents = timeline.getEvents().slice(1);
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(false);
+
+                return timelineWindow.paginate(EventTimeline.BACKWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                const expectedEvents = timeline.getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+                return timelineWindow.paginate(EventTimeline.BACKWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(false);
+            }).nodeify(done);
+        });
+
+        it("should advance into next timeline", function(done) {
+            const tls = createLinkedTimelines();
+            const eventId = tls[0].getEvents()[1].getId();
+            const timelineWindow = createWindow(tls[0], {windowLimit: 5});
+
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = tls[0].getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                const expectedEvents = tls[0].getEvents()
+                    .concat(tls[1].getEvents().slice(0, 2));
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                // the windowLimit should have made us drop an event from
+                // tls[0]
+                const expectedEvents = tls[0].getEvents().slice(1)
+                    .concat(tls[1].getEvents());
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(false);
+            }).nodeify(done);
+        });
+
+        it("should retreat into previous timeline", function(done) {
+            const tls = createLinkedTimelines();
+            const eventId = tls[1].getEvents()[1].getId();
+            const timelineWindow = createWindow(tls[1], {windowLimit: 5});
+
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = tls[1].getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+
+                return timelineWindow.paginate(EventTimeline.BACKWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                const expectedEvents = tls[0].getEvents().slice(1, 3)
+                    .concat(tls[1].getEvents());
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+
+                return timelineWindow.paginate(EventTimeline.BACKWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                // the windowLimit should have made us drop an event from
+                // tls[1]
+                const expectedEvents = tls[0].getEvents()
+                    .concat(tls[1].getEvents().slice(0, 2));
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+                return timelineWindow.paginate(EventTimeline.BACKWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(false);
+            }).nodeify(done);
+        });
+
+        it("should make forward pagination requests", function(done) {
+            const timeline = createTimeline();
+            timeline.setPaginationToken("toktok", EventTimeline.FORWARDS);
+
+            const timelineWindow = createWindow(timeline, {windowLimit: 5});
+            const eventId = timeline.getEvents()[1].getId();
+
+            client.paginateEventTimeline = function(timeline0, opts) {
+                expect(timeline0).toBe(timeline);
+                expect(opts.backwards).toBe(false);
+                expect(opts.limit).toEqual(2);
+
+                addEventsToTimeline(timeline, 3, false);
+                return Promise.resolve(true);
+            };
+
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = timeline.getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                const expectedEvents = timeline.getEvents().slice(0, 5);
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+            }).nodeify(done);
+        });
+
+
+        it("should make backward pagination requests", function(done) {
+            const timeline = createTimeline();
+            timeline.setPaginationToken("toktok", EventTimeline.BACKWARDS);
+
+            const timelineWindow = createWindow(timeline, {windowLimit: 5});
+            const eventId = timeline.getEvents()[1].getId();
+
+            client.paginateEventTimeline = function(timeline0, opts) {
+                expect(timeline0).toBe(timeline);
+                expect(opts.backwards).toBe(true);
+                expect(opts.limit).toEqual(2);
+
+                addEventsToTimeline(timeline, 3, true);
+                return Promise.resolve(true);
+            };
+
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = timeline.getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(true);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(false);
+                return timelineWindow.paginate(EventTimeline.BACKWARDS, 2);
+            }).then(function(success) {
+                expect(success).toBe(true);
+                const expectedEvents = timeline.getEvents().slice(1, 6);
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+            }).nodeify(done);
+        });
+
+        it("should limit the number of unsuccessful pagination requests",
+        function(done) {
+            const timeline = createTimeline();
+            timeline.setPaginationToken("toktok", EventTimeline.FORWARDS);
+
+            const timelineWindow = createWindow(timeline, {windowLimit: 5});
+            const eventId = timeline.getEvents()[1].getId();
+
+            let paginateCount = 0;
+            client.paginateEventTimeline = function(timeline0, opts) {
+                expect(timeline0).toBe(timeline);
+                expect(opts.backwards).toBe(false);
+                expect(opts.limit).toEqual(2);
+                paginateCount += 1;
+                return Promise.resolve(true);
+            };
+
+            timelineWindow.load(eventId, 3).then(function() {
+                const expectedEvents = timeline.getEvents();
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+                return timelineWindow.paginate(EventTimeline.FORWARDS, 2, true, 3);
+            }).then(function(success) {
+                expect(success).toBe(false);
+                expect(paginateCount).toEqual(3);
+                const expectedEvents = timeline.getEvents().slice(0, 3);
+                expect(timelineWindow.getEvents()).toEqual(expectedEvents);
+
+                expect(timelineWindow.canPaginate(EventTimeline.BACKWARDS))
+                    .toBe(false);
+                expect(timelineWindow.canPaginate(EventTimeline.FORWARDS))
+                    .toBe(true);
+            }).nodeify(done);
+        });
+    });
+});

spec/unit/user.spec.js

@@ -0,0 +1,87 @@
+"use strict";
+import 'source-map-support/register';
+const sdk = require("../..");
+const User = sdk.User;
+const utils = require("../test-utils");
+
+import expect from 'expect';
+
+describe("User", function() {
+    const userId = "@alice:bar";
+    let user;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        user = new User(userId);
+    });
+
+    describe("setPresenceEvent", function() {
+        const event = utils.mkEvent({
+            type: "m.presence", content: {
+                presence: "online",
+                user_id: userId,
+                displayname: "Alice",
+                last_active_ago: 1085,
+                avatar_url: "mxc://foo/bar",
+            }, event: true,
+        });
+
+        it("should emit 'User.displayName' if the display name changes", function() {
+            let emitCount = 0;
+            user.on("User.displayName", function(ev, usr) {
+                emitCount += 1;
+            });
+            user.setPresenceEvent(event);
+            expect(emitCount).toEqual(1);
+            user.setPresenceEvent(event); // no-op
+            expect(emitCount).toEqual(1);
+        });
+
+        it("should emit 'User.avatarUrl' if the avatar URL changes", function() {
+            let emitCount = 0;
+            user.on("User.avatarUrl", function(ev, usr) {
+                emitCount += 1;
+            });
+            user.setPresenceEvent(event);
+            expect(emitCount).toEqual(1);
+            user.setPresenceEvent(event); // no-op
+            expect(emitCount).toEqual(1);
+        });
+
+        it("should emit 'User.presence' if the presence changes", function() {
+            let emitCount = 0;
+            user.on("User.presence", function(ev, usr) {
+                emitCount += 1;
+            });
+            user.setPresenceEvent(event);
+            expect(emitCount).toEqual(1);
+            user.setPresenceEvent(event); // no-op
+            expect(emitCount).toEqual(1);
+        });
+
+        it("should set User.displayName", function() {
+            user.setPresenceEvent(event);
+            expect(user.displayName).toEqual("Alice");
+        });
+
+        it("should set User.avatarUrl", function() {
+            user.setPresenceEvent(event);
+            expect(user.avatarUrl).toEqual("mxc://foo/bar");
+        });
+
+        it("should set User.presence", function() {
+            user.setPresenceEvent(event);
+            expect(user.presence).toEqual("online");
+        });
+
+        it("should set User.lastActiveAgo", function() {
+            user.setPresenceEvent(event);
+            expect(user.lastActiveAgo).toEqual(1085);
+        });
+
+        it("should set User.events.presence", function() {
+            user.setPresenceEvent(event);
+            expect(user.events.presence).toEqual(event);
+        });
+    });
+});

spec/unit/utils.spec.js

@@ -0,0 +1,294 @@
+"use strict";
+import 'source-map-support/register';
+const utils = require("../../lib/utils");
+const testUtils = require("../test-utils");
+
+import expect from 'expect';
+
+describe("utils", function() {
+    beforeEach(function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+    });
+
+    describe("encodeParams", function() {
+        it("should url encode and concat with &s", function() {
+            const params = {
+                foo: "bar",
+                baz: "beer@",
+            };
+            expect(utils.encodeParams(params)).toEqual(
+                "foo=bar&baz=beer%40",
+            );
+        });
+    });
+
+    describe("encodeUri", function() {
+        it("should replace based on object keys and url encode", function() {
+            const path = "foo/bar/%something/%here";
+            const vals = {
+                "%something": "baz",
+                "%here": "beer@",
+            };
+            expect(utils.encodeUri(path, vals)).toEqual(
+                "foo/bar/baz/beer%40",
+            );
+        });
+    });
+
+    describe("forEach", function() {
+        it("should be invoked for each element", function() {
+            const arr = [];
+            utils.forEach([55, 66, 77], function(element) {
+                arr.push(element);
+            });
+            expect(arr).toEqual([55, 66, 77]);
+        });
+    });
+
+    describe("findElement", function() {
+        it("should find only 1 element if there is a match", function() {
+            const matchFn = function() {
+                return true;
+            };
+            const arr = [55, 66, 77];
+            expect(utils.findElement(arr, matchFn)).toEqual(55);
+        });
+        it("should be able to find in reverse order", function() {
+            const matchFn = function() {
+                return true;
+            };
+            const arr = [55, 66, 77];
+            expect(utils.findElement(arr, matchFn, true)).toEqual(77);
+        });
+        it("should find nothing if the function never returns true", function() {
+            const matchFn = function() {
+                return false;
+            };
+            const arr = [55, 66, 77];
+            expect(utils.findElement(arr, matchFn)).toBeFalsy();
+        });
+    });
+
+    describe("removeElement", function() {
+        it("should remove only 1 element if there is a match", function() {
+            const matchFn = function() {
+                return true;
+            };
+            const arr = [55, 66, 77];
+            utils.removeElement(arr, matchFn);
+            expect(arr).toEqual([66, 77]);
+        });
+        it("should be able to remove in reverse order", function() {
+            const matchFn = function() {
+                return true;
+            };
+            const arr = [55, 66, 77];
+            utils.removeElement(arr, matchFn, true);
+            expect(arr).toEqual([55, 66]);
+        });
+        it("should remove nothing if the function never returns true", function() {
+            const matchFn = function() {
+                return false;
+            };
+            const arr = [55, 66, 77];
+            utils.removeElement(arr, matchFn);
+            expect(arr).toEqual(arr);
+        });
+    });
+
+    describe("isFunction", function() {
+        it("should return true for functions", function() {
+            expect(utils.isFunction([])).toBe(false);
+            expect(utils.isFunction([5, 3, 7])).toBe(false);
+            expect(utils.isFunction()).toBe(false);
+            expect(utils.isFunction(null)).toBe(false);
+            expect(utils.isFunction({})).toBe(false);
+            expect(utils.isFunction("foo")).toBe(false);
+            expect(utils.isFunction(555)).toBe(false);
+
+            expect(utils.isFunction(function() {})).toBe(true);
+            const s = { foo: function() {} };
+            expect(utils.isFunction(s.foo)).toBe(true);
+        });
+    });
+
+    describe("isArray", function() {
+        it("should return true for arrays", function() {
+            expect(utils.isArray([])).toBe(true);
+            expect(utils.isArray([5, 3, 7])).toBe(true);
+
+            expect(utils.isArray()).toBe(false);
+            expect(utils.isArray(null)).toBe(false);
+            expect(utils.isArray({})).toBe(false);
+            expect(utils.isArray("foo")).toBe(false);
+            expect(utils.isArray(555)).toBe(false);
+            expect(utils.isArray(function() {})).toBe(false);
+        });
+    });
+
+    describe("checkObjectHasKeys", function() {
+        it("should throw for missing keys", function() {
+            expect(function() {
+                utils.checkObjectHasKeys({}, ["foo"]);
+            }).toThrow();
+            expect(function() {
+                utils.checkObjectHasKeys({
+                    foo: "bar",
+                }, ["foo"]);
+            }).toNotThrow();
+        });
+    });
+
+    describe("checkObjectHasNoAdditionalKeys", function() {
+        it("should throw for extra keys", function() {
+            expect(function() {
+                utils.checkObjectHasNoAdditionalKeys({
+                            foo: "bar",
+                            baz: 4,
+                        }, ["foo"]);
+            }).toThrow();
+
+            expect(function() {
+                utils.checkObjectHasNoAdditionalKeys({
+                            foo: "bar",
+                        }, ["foo"]);
+            }).toNotThrow();
+        });
+    });
+
+    describe("deepCompare", function() {
+        const assert = {
+            isTrue: function(x) {
+                expect(x).toBe(true);
+            },
+            isFalse: function(x) {
+                expect(x).toBe(false);
+            },
+        };
+
+        it("should handle primitives", function() {
+            assert.isTrue(utils.deepCompare(null, null));
+            assert.isFalse(utils.deepCompare(null, undefined));
+            assert.isTrue(utils.deepCompare("hi", "hi"));
+            assert.isTrue(utils.deepCompare(5, 5));
+            assert.isFalse(utils.deepCompare(5, 10));
+        });
+
+        it("should handle regexps", function() {
+            assert.isTrue(utils.deepCompare(/abc/, /abc/));
+            assert.isFalse(utils.deepCompare(/abc/, /123/));
+            const r = /abc/;
+            assert.isTrue(utils.deepCompare(r, r));
+        });
+
+        it("should handle dates", function() {
+            assert.isTrue(utils.deepCompare(new Date("2011-03-31"),
+                                            new Date("2011-03-31")));
+            assert.isFalse(utils.deepCompare(new Date("2011-03-31"),
+                                             new Date("1970-01-01")));
+        });
+
+        it("should handle arrays", function() {
+            assert.isTrue(utils.deepCompare([], []));
+            assert.isTrue(utils.deepCompare([1, 2], [1, 2]));
+            assert.isFalse(utils.deepCompare([1, 2], [2, 1]));
+            assert.isFalse(utils.deepCompare([1, 2], [1, 2, 3]));
+        });
+
+        it("should handle simple objects", function() {
+            assert.isTrue(utils.deepCompare({}, {}));
+            assert.isTrue(utils.deepCompare({a: 1, b: 2}, {a: 1, b: 2}));
+            assert.isTrue(utils.deepCompare({a: 1, b: 2}, {b: 2, a: 1}));
+            assert.isFalse(utils.deepCompare({a: 1, b: 2}, {a: 1, b: 3}));
+
+            assert.isTrue(utils.deepCompare({1: {name: "mhc", age: 28},
+                                             2: {name: "arb", age: 26}},
+                                            {1: {name: "mhc", age: 28},
+                                             2: {name: "arb", age: 26}}));
+
+            assert.isFalse(utils.deepCompare({1: {name: "mhc", age: 28},
+                                              2: {name: "arb", age: 26}},
+                                             {1: {name: "mhc", age: 28},
+                                              2: {name: "arb", age: 27}}));
+
+            assert.isFalse(utils.deepCompare({}, null));
+            assert.isFalse(utils.deepCompare({}, undefined));
+        });
+
+        it("should handle functions", function() {
+            // no two different function is equal really, they capture their
+            // context variables so even if they have same toString(), they
+            // won't have same functionality
+            const func = function(x) {
+                return true;
+            };
+            const func2 = function(x) {
+                return true;
+            };
+            assert.isTrue(utils.deepCompare(func, func));
+            assert.isFalse(utils.deepCompare(func, func2));
+            assert.isTrue(utils.deepCompare({ a: { b: func } }, { a: { b: func } }));
+            assert.isFalse(utils.deepCompare({ a: { b: func } }, { a: { b: func2 } }));
+        });
+    });
+
+
+    describe("extend", function() {
+        const SOURCE = { "prop2": 1, "string2": "x", "newprop": "new" };
+
+        it("should extend", function() {
+            const target = {
+                "prop1": 5, "prop2": 7, "string1": "baz", "string2": "foo",
+            };
+            const merged = {
+                "prop1": 5, "prop2": 1, "string1": "baz", "string2": "x",
+                "newprop": "new",
+            };
+            const sourceOrig = JSON.stringify(SOURCE);
+
+            utils.extend(target, SOURCE);
+            expect(JSON.stringify(target)).toEqual(JSON.stringify(merged));
+
+            // check the originial wasn't modified
+            expect(JSON.stringify(SOURCE)).toEqual(sourceOrig);
+        });
+
+        it("should ignore null", function() {
+            const target = {
+                "prop1": 5, "prop2": 7, "string1": "baz", "string2": "foo",
+            };
+            const merged = {
+                "prop1": 5, "prop2": 1, "string1": "baz", "string2": "x",
+                "newprop": "new",
+            };
+            const sourceOrig = JSON.stringify(SOURCE);
+
+            utils.extend(target, null, SOURCE);
+            expect(JSON.stringify(target)).toEqual(JSON.stringify(merged));
+
+            // check the originial wasn't modified
+            expect(JSON.stringify(SOURCE)).toEqual(sourceOrig);
+        });
+
+        it("should handle properties created with defineProperties", function() {
+            const source = Object.defineProperties({}, {
+                "enumerableProp": {
+                    get: function() {
+                        return true;
+                    },
+                    enumerable: true,
+                },
+                "nonenumerableProp": {
+                    get: function() {
+                        return true;
+                    },
+                },
+            });
+
+            const target = {};
+            utils.extend(target, source);
+            expect(target.enumerableProp).toBe(true);
+            expect(target.nonenumerableProp).toBe(undefined);
+        });
+    });
+});

src/ReEmitter.js

@@ -0,0 +1,52 @@
+/*
+Copyright 2015, 2016 OpenMarket Ltd
+Copyright 2017 Vector Creations Ltd
+Copyright 2017 New Vector 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.
+*/
+
+/**
+ * @module
+ */
+
+export default class Reemitter {
+    constructor(target) {
+        this.target = target;
+
+        // We keep one bound event handler for each event name so we know
+        // what event is arriving
+        this.boundHandlers = {};
+    }
+
+    _handleEvent(eventName, ...args) {
+        this.target.emit(eventName, ...args);
+    }
+
+    reEmit(source, eventNames) {
+        // We include the source as the last argument for event handlers which may need it,
+        // such as read receipt listeners on the client class which won't have the context
+        // of the room.
+        const forSource = (handler, ...args) => {
+            handler(...args, source);
+        };
+        for (const eventName of eventNames) {
+            if (this.boundHandlers[eventName] === undefined) {
+                this.boundHandlers[eventName] = this._handleEvent.bind(this, eventName);
+            }
+
+            const boundHandler = forSource.bind(this, this.boundHandlers[eventName]);
+            source.on(eventName, boundHandler);
+        }
+    }
+}

src/autodiscovery.js

@@ -0,0 +1,524 @@
+/*
+Copyright 2018 New Vector 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.
+*/
+
+/** @module auto-discovery */
+
+import Promise from 'bluebird';
+import logger from './logger';
+import { URL as NodeURL } from "url";
+
+// Dev note: Auto discovery is part of the spec.
+// See: https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery
+
+/**
+ * Description for what an automatically discovered client configuration
+ * would look like. Although this is a class, it is recommended that it
+ * be treated as an interface definition rather than as a class.
+ *
+ * Additional properties than those defined here may be present, and
+ * should follow the Java package naming convention.
+ */
+class DiscoveredClientConfig { // eslint-disable-line no-unused-vars
+    // Dev note: this is basically a copy/paste of the .well-known response
+    // object as defined in the spec. It does have additional information,
+    // however. Overall, this exists to serve as a place for documentation
+    // and not functionality.
+    // See https://matrix.org/docs/spec/client_server/r0.4.0.html#get-well-known-matrix-client
+
+    constructor() {
+        /**
+         * The homeserver configuration the client should use. This will
+         * always be present on the object.
+         * @type {{state: string, base_url: string}} The configuration.
+         */
+        this["m.homeserver"] = {
+            /**
+             * The lookup result state. If this is anything other than
+             * AutoDiscovery.SUCCESS then base_url may be falsey. Additionally,
+             * if this is not AutoDiscovery.SUCCESS then the client should
+             * assume the other properties in the client config (such as
+             * the identity server configuration) are not valid.
+             */
+            state: AutoDiscovery.PROMPT,
+
+            /**
+             * If the state is AutoDiscovery.FAIL_ERROR or .FAIL_PROMPT
+             * then this will contain a human-readable (English) message
+             * for what went wrong. If the state is none of those previously
+             * mentioned, this will be falsey.
+             */
+            error: "Something went wrong",
+
+            /**
+             * The base URL clients should use to talk to the homeserver,
+             * particularly for the login process. May be falsey if the
+             * state is not AutoDiscovery.SUCCESS.
+             */
+            base_url: "https://matrix.org",
+        };
+
+        /**
+         * The identity server configuration the client should use. This
+         * will always be present on teh object.
+         * @type {{state: string, base_url: string}} The configuration.
+         */
+        this["m.identity_server"] = {
+            /**
+             * The lookup result state. If this is anything other than
+             * AutoDiscovery.SUCCESS then base_url may be falsey.
+             */
+            state: AutoDiscovery.PROMPT,
+
+            /**
+             * The base URL clients should use for interacting with the
+             * identity server. May be falsey if the state is not
+             * AutoDiscovery.SUCCESS.
+             */
+            base_url: "https://vector.im",
+        };
+    }
+}
+
+/**
+ * Utilities for automatically discovery resources, such as homeservers
+ * for users to log in to.
+ */
+export class AutoDiscovery {
+    // Dev note: the constants defined here are related to but not
+    // exactly the same as those in the spec. This is to hopefully
+    // translate the meaning of the states in the spec, but also
+    // support our own if needed.
+
+    static get ERROR_INVALID() {
+        return "Invalid homeserver discovery response";
+    }
+
+    static get ERROR_GENERIC_FAILURE() {
+        return "Failed to get autodiscovery configuration from server";
+    }
+
+    static get ERROR_INVALID_HS_BASE_URL() {
+        return "Invalid base_url for m.homeserver";
+    }
+
+    static get ERROR_INVALID_HOMESERVER() {
+        return "Homeserver URL does not appear to be a valid Matrix homeserver";
+    }
+
+    static get ERROR_INVALID_IS_BASE_URL() {
+        return "Invalid base_url for m.identity_server";
+    }
+
+    static get ERROR_INVALID_IDENTITY_SERVER() {
+        return "Identity server URL does not appear to be a valid identity server";
+    }
+
+    static get ERROR_INVALID_IS() {
+        return "Invalid identity server discovery response";
+    }
+
+    static get ERROR_MISSING_WELLKNOWN() {
+        return "No .well-known JSON file found";
+    }
+
+    static get ERROR_INVALID_JSON() {
+        return "Invalid JSON";
+    }
+
+    static get ALL_ERRORS() {
+        return [
+            AutoDiscovery.ERROR_INVALID,
+            AutoDiscovery.ERROR_GENERIC_FAILURE,
+            AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+            AutoDiscovery.ERROR_INVALID_HOMESERVER,
+            AutoDiscovery.ERROR_INVALID_IS_BASE_URL,
+            AutoDiscovery.ERROR_INVALID_IDENTITY_SERVER,
+            AutoDiscovery.ERROR_INVALID_IS,
+            AutoDiscovery.ERROR_MISSING_WELLKNOWN,
+            AutoDiscovery.ERROR_INVALID_JSON,
+        ];
+    }
+
+    /**
+     * The auto discovery failed. The client is expected to communicate
+     * the error to the user and refuse logging in.
+     * @return {string}
+     * @constructor
+     */
+    static get FAIL_ERROR() { return "FAIL_ERROR"; }
+
+    /**
+     * The auto discovery failed, however the client may still recover
+     * from the problem. The client is recommended to that the same
+     * action it would for PROMPT while also warning the user about
+     * what went wrong. The client may also treat this the same as
+     * a FAIL_ERROR state.
+     * @return {string}
+     * @constructor
+     */
+    static get FAIL_PROMPT() { return "FAIL_PROMPT"; }
+
+    /**
+     * The auto discovery didn't fail but did not find anything of
+     * interest. The client is expected to prompt the user for more
+     * information, or fail if it prefers.
+     * @return {string}
+     * @constructor
+     */
+    static get PROMPT() { return "PROMPT"; }
+
+    /**
+     * The auto discovery was successful.
+     * @return {string}
+     * @constructor
+     */
+    static get SUCCESS() { return "SUCCESS"; }
+
+    /**
+     * Validates and verifies client configuration information for purposes
+     * of logging in. Such information includes the homeserver URL
+     * and identity server URL the client would want. Additional details
+     * may also be included, and will be transparently brought into the
+     * response object unaltered.
+     * @param {string} wellknown The configuration object itself, as returned
+     * by the .well-known auto-discovery endpoint.
+     * @return {Promise<DiscoveredClientConfig>} Resolves to the verified
+     * configuration, which may include error states. Rejects on unexpected
+     * failure, not when verification fails.
+     */
+    static async fromDiscoveryConfig(wellknown) {
+        // Step 1 is to get the config, which is provided to us here.
+
+        // We default to an error state to make the first few checks easier to
+        // write. We'll update the properties of this object over the duration
+        // of this function.
+        const clientConfig = {
+            "m.homeserver": {
+                state: AutoDiscovery.FAIL_ERROR,
+                error: AutoDiscovery.ERROR_INVALID,
+                base_url: null,
+            },
+            "m.identity_server": {
+                // Technically, we don't have a problem with the identity server
+                // config at this point.
+                state: AutoDiscovery.PROMPT,
+                error: null,
+                base_url: null,
+            },
+        };
+
+        if (!wellknown || !wellknown["m.homeserver"]) {
+            logger.error("No m.homeserver key in config");
+
+            clientConfig["m.homeserver"].state = AutoDiscovery.FAIL_PROMPT;
+            clientConfig["m.homeserver"].error = AutoDiscovery.ERROR_INVALID;
+
+            return Promise.resolve(clientConfig);
+        }
+
+        if (!wellknown["m.homeserver"]["base_url"]) {
+            logger.error("No m.homeserver base_url in config");
+
+            clientConfig["m.homeserver"].state = AutoDiscovery.FAIL_PROMPT;
+            clientConfig["m.homeserver"].error = AutoDiscovery.ERROR_INVALID_HS_BASE_URL;
+
+            return Promise.resolve(clientConfig);
+        }
+
+        // Step 2: Make sure the homeserver URL is valid *looking*. We'll make
+        // sure it points to a homeserver in Step 3.
+        const hsUrl = this._sanitizeWellKnownUrl(
+            wellknown["m.homeserver"]["base_url"],
+        );
+        if (!hsUrl) {
+            logger.error("Invalid base_url for m.homeserver");
+            clientConfig["m.homeserver"].error = AutoDiscovery.ERROR_INVALID_HS_BASE_URL;
+            return Promise.resolve(clientConfig);
+        }
+
+        // Step 3: Make sure the homeserver URL points to a homeserver.
+        const hsVersions = await this._fetchWellKnownObject(
+            `${hsUrl}/_matrix/client/versions`,
+        );
+        if (!hsVersions || !hsVersions.raw["versions"]) {
+            logger.error("Invalid /versions response");
+            clientConfig["m.homeserver"].error = AutoDiscovery.ERROR_INVALID_HOMESERVER;
+
+            // Supply the base_url to the caller because they may be ignoring liveliness
+            // errors, like this one.
+            clientConfig["m.homeserver"].base_url = hsUrl;
+
+            return Promise.resolve(clientConfig);
+        }
+
+        // Step 4: Now that the homeserver looks valid, update our client config.
+        clientConfig["m.homeserver"] = {
+            state: AutoDiscovery.SUCCESS,
+            error: null,
+            base_url: hsUrl,
+        };
+
+        // Step 5: Try to pull out the identity server configuration
+        let isUrl = "";
+        if (wellknown["m.identity_server"]) {
+            // We prepare a failing identity server response to save lines later
+            // in this branch. Note that we also fail the homeserver check in the
+            // object because according to the spec we're supposed to FAIL_ERROR
+            // if *anything* goes wrong with the IS validation, including invalid
+            // format. This means we're supposed to stop discovery completely.
+            const failingClientConfig = {
+                "m.homeserver": {
+                    state: AutoDiscovery.FAIL_ERROR,
+                    error: AutoDiscovery.ERROR_INVALID_IS,
+
+                    // We'll provide the base_url that was previously valid for
+                    // debugging purposes.
+                    base_url: clientConfig["m.homeserver"].base_url,
+                },
+                "m.identity_server": {
+                    state: AutoDiscovery.FAIL_ERROR,
+                    error: AutoDiscovery.ERROR_INVALID_IS,
+                    base_url: null,
+                },
+            };
+
+            // Step 5a: Make sure the URL is valid *looking*. We'll make sure it
+            // points to an identity server in Step 5b.
+            isUrl = this._sanitizeWellKnownUrl(
+                wellknown["m.identity_server"]["base_url"],
+            );
+            if (!isUrl) {
+                logger.error("Invalid base_url for m.identity_server");
+                failingClientConfig["m.identity_server"].error =
+                    AutoDiscovery.ERROR_INVALID_IS_BASE_URL;
+                return Promise.resolve(failingClientConfig);
+            }
+
+            // Step 5b: Verify there is an identity server listening on the provided
+            // URL.
+            const isResponse = await this._fetchWellKnownObject(
+                `${isUrl}/_matrix/identity/api/v1`,
+            );
+            if (!isResponse || !isResponse.raw || isResponse.action !== "SUCCESS") {
+                logger.error("Invalid /api/v1 response");
+                failingClientConfig["m.identity_server"].error =
+                    AutoDiscovery.ERROR_INVALID_IDENTITY_SERVER;
+
+                // Supply the base_url to the caller because they may be ignoring
+                // liveliness errors, like this one.
+                failingClientConfig["m.identity_server"].base_url = isUrl;
+
+                return Promise.resolve(failingClientConfig);
+            }
+        }
+
+        // Step 6: Now that the identity server is valid, or never existed,
+        // populate the IS section.
+        if (isUrl && isUrl.length > 0) {
+            clientConfig["m.identity_server"] = {
+                state: AutoDiscovery.SUCCESS,
+                error: null,
+                base_url: isUrl,
+            };
+        }
+
+        // Step 7: Copy any other keys directly into the clientConfig. This is for
+        // things like custom configuration of services.
+        Object.keys(wellknown)
+            .map((k) => {
+                if (k === "m.homeserver" || k === "m.identity_server") {
+                    // Only copy selected parts of the config to avoid overwriting
+                    // properties computed by the validation logic above.
+                    const notProps = ["error", "state", "base_url"];
+                    for (const prop of Object.keys(wellknown[k])) {
+                        if (notProps.includes(prop)) continue;
+                        clientConfig[k][prop] = wellknown[k][prop];
+                    }
+                } else {
+                    // Just copy the whole thing over otherwise
+                    clientConfig[k] = wellknown[k];
+                }
+            });
+
+        // Step 8: Give the config to the caller (finally)
+        return Promise.resolve(clientConfig);
+    }
+
+    /**
+     * Attempts to automatically discover client configuration information
+     * prior to logging in. Such information includes the homeserver URL
+     * and identity server URL the client would want. Additional details
+     * may also be discovered, and will be transparently included in the
+     * response object unaltered.
+     * @param {string} domain The homeserver domain to perform discovery
+     * on. For example, "matrix.org".
+     * @return {Promise<DiscoveredClientConfig>} Resolves to the discovered
+     * configuration, which may include error states. Rejects on unexpected
+     * failure, not when discovery fails.
+     */
+    static async findClientConfig(domain) {
+        if (!domain || typeof(domain) !== "string" || domain.length === 0) {
+            throw new Error("'domain' must be a string of non-zero length");
+        }
+
+        // We use a .well-known lookup for all cases. According to the spec, we
+        // can do other discovery mechanisms if we want such as custom lookups
+        // however we won't bother with that here (mostly because the spec only
+        // supports .well-known right now).
+        //
+        // By using .well-known, we need to ensure we at least pull out a URL
+        // for the homeserver. We don't really need an identity server configuration
+        // but will return one anyways (with state PROMPT) to make development
+        // easier for clients. If we can't get a homeserver URL, all bets are
+        // off on the rest of the config and we'll assume it is invalid too.
+
+        // We default to an error state to make the first few checks easier to
+        // write. We'll update the properties of this object over the duration
+        // of this function.
+        const clientConfig = {
+            "m.homeserver": {
+                state: AutoDiscovery.FAIL_ERROR,
+                error: AutoDiscovery.ERROR_INVALID,
+                base_url: null,
+            },
+            "m.identity_server": {
+                // Technically, we don't have a problem with the identity server
+                // config at this point.
+                state: AutoDiscovery.PROMPT,
+                error: null,
+                base_url: null,
+            },
+        };
+
+        // Step 1: Actually request the .well-known JSON file and make sure it
+        // at least has a homeserver definition.
+        const wellknown = await this._fetchWellKnownObject(
+            `https://${domain}/.well-known/matrix/client`,
+        );
+        if (!wellknown || wellknown.action !== "SUCCESS") {
+            logger.error("No response or error when parsing .well-known");
+            if (wellknown.reason) logger.error(wellknown.reason);
+            if (wellknown.action === "IGNORE") {
+                clientConfig["m.homeserver"] = {
+                    state: AutoDiscovery.PROMPT,
+                    error: null,
+                    base_url: null,
+                };
+            } else {
+                // this can only ever be FAIL_PROMPT at this point.
+                clientConfig["m.homeserver"].state = AutoDiscovery.FAIL_PROMPT;
+                clientConfig["m.homeserver"].error = AutoDiscovery.ERROR_INVALID;
+            }
+            return Promise.resolve(clientConfig);
+        }
+
+        // Step 2: Validate and parse the config
+        return AutoDiscovery.fromDiscoveryConfig(wellknown.raw);
+    }
+
+    /**
+     * Sanitizes a given URL to ensure it is either an HTTP or HTTP URL and
+     * is suitable for the requirements laid out by .well-known auto discovery.
+     * If valid, the URL will also be stripped of any trailing slashes.
+     * @param {string} url The potentially invalid URL to sanitize.
+     * @return {string|boolean} The sanitized URL or a falsey value if the URL is invalid.
+     * @private
+     */
+    static _sanitizeWellKnownUrl(url) {
+        if (!url) return false;
+
+        try {
+            // We have to try and parse the URL using the NodeJS URL
+            // library if we're on NodeJS and use the browser's URL
+            // library when we're in a browser. To accomplish this, we
+            // try the NodeJS version first and fall back to the browser.
+            let parsed = null;
+            try {
+                if (NodeURL) parsed = new NodeURL(url);
+                else parsed = new URL(url);
+            } catch (e) {
+                parsed = new URL(url);
+            }
+
+            if (!parsed || !parsed.hostname) return false;
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+
+            const port = parsed.port ? `:${parsed.port}` : "";
+            const path = parsed.pathname ? parsed.pathname : "";
+            let saferUrl = `${parsed.protocol}//${parsed.hostname}${port}${path}`;
+            if (saferUrl.endsWith("/")) {
+                saferUrl = saferUrl.substring(0, saferUrl.length - 1);
+            }
+            return saferUrl;
+        } catch (e) {
+            logger.error(e);
+            return false;
+        }
+    }
+
+    /**
+     * Fetches a JSON object from a given URL, as expected by all .well-known
+     * related lookups. If the server gives a 404 then the `action` will be
+     * IGNORE. If the server returns something that isn't JSON, the `action`
+     * will be FAIL_PROMPT. For any other failure the `action` will be FAIL_PROMPT.
+     *
+     * The returned object will be a result of the call in object form with
+     * the following properties:
+     *   raw: The JSON object returned by the server.
+     *   action: One of SUCCESS, IGNORE, or FAIL_PROMPT.
+     *   reason: Relatively human readable description of what went wrong.
+     *   error: The actual Error, if one exists.
+     * @param {string} url The URL to fetch a JSON object from.
+     * @return {Promise<object>} Resolves to the returned state.
+     * @private
+     */
+    static async _fetchWellKnownObject(url) {
+        return new Promise(function(resolve, reject) {
+            const request = require("./matrix").getRequest();
+            if (!request) throw new Error("No request library available");
+            request(
+                { method: "GET", uri: url, timeout: 5000 },
+                (err, response, body) => {
+                    if (err || response.statusCode < 200 || response.statusCode >= 300) {
+                        let action = "FAIL_PROMPT";
+                        let reason = (err ? err.message : null) || "General failure";
+                        if (response.statusCode === 404) {
+                            action = "IGNORE";
+                            reason = AutoDiscovery.ERROR_MISSING_WELLKNOWN;
+                        }
+                        resolve({raw: {}, action: action, reason: reason, error: err});
+                        return;
+                    }
+
+                    try {
+                        resolve({raw: JSON.parse(body), action: "SUCCESS"});
+                    } catch (e) {
+                        let reason = AutoDiscovery.ERROR_INVALID;
+                        if (e.name === "SyntaxError") {
+                            reason = AutoDiscovery.ERROR_INVALID_JSON;
+                        }
+                        resolve({
+                            raw: {},
+                            action: "FAIL_PROMPT",
+                            reason: reason,
+                            error: e,
+                        });
+                    }
+                },
+            );
+        });
+    }
+}

src/content-helpers.js

@@ -0,0 +1,100 @@
+/*
+Copyright 2018 New Vector 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.
+*/
+"use strict";
+
+/** @module ContentHelpers */
+module.exports = {
+    /**
+     * 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}}
+     */
+    makeHtmlMessage: function(body, htmlBody) {
+        return {
+            msgtype: "m.text",
+            format: "org.matrix.custom.html",
+            body: body,
+            formatted_body: htmlBody,
+        };
+    },
+
+    /**
+     * Generates the content for a HTML Notice event
+     * @param {string} body the plaintext body of the notice
+     * @param {string} htmlBody the HTML representation of the notice
+     * @returns {{msgtype: string, format: string, body: string, formatted_body: string}}
+     */
+    makeHtmlNotice: function(body, htmlBody) {
+        return {
+            msgtype: "m.notice",
+            format: "org.matrix.custom.html",
+            body: body,
+            formatted_body: htmlBody,
+        };
+    },
+
+    /**
+     * Generates the content for a HTML Emote event
+     * @param {string} body the plaintext body of the emote
+     * @param {string} htmlBody the HTML representation of the emote
+     * @returns {{msgtype: string, format: string, body: string, formatted_body: string}}
+     */
+    makeHtmlEmote: function(body, htmlBody) {
+        return {
+            msgtype: "m.emote",
+            format: "org.matrix.custom.html",
+            body: body,
+            formatted_body: htmlBody,
+        };
+    },
+
+    /**
+     * Generates the content for a Plaintext Message event
+     * @param {string} body the plaintext body of the emote
+     * @returns {{msgtype: string, body: string}}
+     */
+    makeTextMessage: function(body) {
+        return {
+            msgtype: "m.text",
+            body: body,
+        };
+    },
+
+    /**
+     * Generates the content for a Plaintext Notice event
+     * @param {string} body the plaintext body of the notice
+     * @returns {{msgtype: string, body: string}}
+     */
+    makeNotice: function(body) {
+        return {
+            msgtype: "m.notice",
+            body: body,
+        };
+    },
+
+    /**
+     * Generates the content for a Plaintext Emote event
+     * @param {string} body the plaintext body of the emote
+     * @returns {{msgtype: string, body: string}}
+     */
+    makeEmoteMessage: function(body) {
+        return {
+            msgtype: "m.emote",
+            body: body,
+        };
+    },
+};

src/content-repo.js

@@ -0,0 +1,110 @@
+/*
+Copyright 2015, 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.
+*/
+/**
+ * @module content-repo
+ */
+const utils = require("./utils");
+
+/** Content Repo utility functions */
+module.exports = {
+    /**
+     * Get the HTTP URL for an MXC URI.
+     * @param {string} baseUrl The base homeserver url which has a content repo.
+     * @param {string} mxc The mxc:// URI.
+     * @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} allowDirectLinks If true, return any non-mxc URLs
+     * directly. Fetching such URLs will leak information about the user to
+     * anyone they share a room with. If false, will return the emptry string
+     * for such URLs.
+     * @return {string} The complete URL to the content.
+     */
+    getHttpUriForMxc: function(baseUrl, mxc, width, height,
+                               resizeMethod, allowDirectLinks) {
+        if (typeof mxc !== "string" || !mxc) {
+            return '';
+        }
+        if (mxc.indexOf("mxc://") !== 0) {
+            if (allowDirectLinks) {
+                return mxc;
+            } else {
+                return '';
+            }
+        }
+        let serverAndMediaId = mxc.slice(6); // strips mxc://
+        let prefix = "/_matrix/media/r0/download/";
+        const params = {};
+
+        if (width) {
+            params.width = Math.round(width);
+        }
+        if (height) {
+            params.height = Math.round(height);
+        }
+        if (resizeMethod) {
+            params.method = resizeMethod;
+        }
+        if (utils.keys(params).length > 0) {
+            // these are thumbnailing params so they probably want the
+            // thumbnailing API...
+            prefix = "/_matrix/media/r0/thumbnail/";
+        }
+
+        const fragmentOffset = serverAndMediaId.indexOf("#");
+        let fragment = "";
+        if (fragmentOffset >= 0) {
+            fragment = serverAndMediaId.substr(fragmentOffset);
+            serverAndMediaId = serverAndMediaId.substr(0, fragmentOffset);
+        }
+        return baseUrl + prefix + serverAndMediaId +
+            (utils.keys(params).length === 0 ? "" :
+            ("?" + utils.encodeParams(params))) + fragment;
+    },
+
+    /**
+     * Get an identicon URL from an arbitrary string.
+     * @param {string} baseUrl The base homeserver url which has a content repo.
+     * @param {string} identiconString The string to create an identicon for.
+     * @param {Number} width The desired width of the image in pixels. Default: 96.
+     * @param {Number} height The desired height of the image in pixels. Default: 96.
+     * @return {string} The complete URL to the identicon.
+     * @deprecated This is no longer in the specification.
+     */
+    getIdenticonUri: function(baseUrl, identiconString, width, height) {
+        if (!identiconString) {
+            return null;
+        }
+        if (!width) {
+            width = 96;
+        }
+        if (!height) {
+            height = 96;
+        }
+        const params = {
+            width: width,
+            height: height,
+        };
+
+        const path = utils.encodeUri("/_matrix/media/unstable/identicon/$ident", {
+            $ident: identiconString,
+        });
+        return baseUrl + path +
+            (utils.keys(params).length === 0 ? "" :
+                ("?" + utils.encodeParams(params)));
+    },
+};

src/crypto/DeviceList.js

@@ -0,0 +1,890 @@
+/*
+Copyright 2017 Vector Creations Ltd
+Copyright 2018, 2019 New Vector 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.
+*/
+"use strict";
+
+/**
+ * @module crypto/DeviceList
+ *
+ * Manages the list of other users' devices
+ */
+
+import Promise from 'bluebird';
+
+import logger from '../logger';
+import DeviceInfo from './deviceinfo';
+import olmlib from './olmlib';
+import IndexedDBCryptoStore from './store/indexeddb-crypto-store';
+
+
+/* State transition diagram for DeviceList._deviceTrackingStatus
+ *
+ *                                |
+ *     stopTrackingDeviceList     V
+ *   +---------------------> NOT_TRACKED
+ *   |                            |
+ *   +<--------------------+      | startTrackingDeviceList
+ *   |                     |      V
+ *   |   +-------------> PENDING_DOWNLOAD <--------------------+-+
+ *   |   |                      ^ |                            | |
+ *   |   | restart     download | |  start download            | | invalidateUserDeviceList
+ *   |   | client        failed | |                            | |
+ *   |   |                      | V                            | |
+ *   |   +------------ DOWNLOAD_IN_PROGRESS -------------------+ |
+ *   |                    |       |                              |
+ *   +<-------------------+       |  download successful         |
+ *   ^                            V                              |
+ *   +----------------------- UP_TO_DATE ------------------------+
+ */
+
+
+// constants for DeviceList._deviceTrackingStatus
+const TRACKING_STATUS_NOT_TRACKED = 0;
+const TRACKING_STATUS_PENDING_DOWNLOAD = 1;
+const TRACKING_STATUS_DOWNLOAD_IN_PROGRESS = 2;
+const TRACKING_STATUS_UP_TO_DATE = 3;
+
+/**
+ * @alias module:crypto/DeviceList
+ */
+export default class DeviceList {
+    constructor(baseApis, cryptoStore, olmDevice) {
+        this._cryptoStore = cryptoStore;
+
+        // userId -> {
+        //     deviceId -> {
+        //         [device info]
+        //     }
+        // }
+        this._devices = {};
+
+        // map of identity keys to the user who owns it
+        this._userByIdentityKey = {};
+
+        // which users we are tracking device status for.
+        // userId -> TRACKING_STATUS_*
+        this._deviceTrackingStatus = {}; // loaded from storage in load()
+
+        // The 'next_batch' sync token at the point the data was writen,
+        // ie. a token representing the point immediately after the
+        // moment represented by the snapshot in the db.
+        this._syncToken = null;
+
+        this._serialiser = new DeviceListUpdateSerialiser(
+            baseApis, olmDevice, this,
+        );
+
+        // userId -> promise
+        this._keyDownloadsInProgressByUser = {};
+
+        // Set whenever changes are made other than setting the sync token
+        this._dirty = false;
+
+        // Promise resolved when device data is saved
+        this._savePromise = null;
+        // Function that resolves the save promise
+        this._resolveSavePromise = null;
+        // The time the save is scheduled for
+        this._savePromiseTime = null;
+        // The timer used to delay the save
+        this._saveTimer = null;
+    }
+
+    /**
+     * Load the device tracking state from storage
+     */
+    async load() {
+        await this._cryptoStore.doTxn(
+            'readonly', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
+                this._cryptoStore.getEndToEndDeviceData(txn, (deviceData) => {
+                    this._devices = deviceData ? deviceData.devices : {},
+                    this._deviceTrackingStatus = deviceData ?
+                        deviceData.trackingStatus : {};
+                    this._syncToken = deviceData ? deviceData.syncToken : null;
+                    this._userByIdentityKey = {};
+                    for (const user of Object.keys(this._devices)) {
+                        const userDevices = this._devices[user];
+                        for (const device of Object.keys(userDevices)) {
+                            const idKey = userDevices[device].keys['curve25519:'+device];
+                            if (idKey !== undefined) {
+                                this._userByIdentityKey[idKey] = user;
+                            }
+                        }
+                    }
+                });
+            },
+        );
+
+        for (const u of Object.keys(this._deviceTrackingStatus)) {
+            // if a download was in progress when we got shut down, it isn't any more.
+            if (this._deviceTrackingStatus[u] == TRACKING_STATUS_DOWNLOAD_IN_PROGRESS) {
+                this._deviceTrackingStatus[u] = TRACKING_STATUS_PENDING_DOWNLOAD;
+            }
+        }
+    }
+
+    stop() {
+        if (this._saveTimer !== null) {
+            clearTimeout(this._saveTimer);
+        }
+    }
+
+    /**
+     * Save the device tracking state to storage, if any changes are
+     * pending other than updating the sync token
+     *
+     * The actual save will be delayed by a short amount of time to
+     * aggregate multiple writes to the database.
+     *
+     * @param {integer} delay Time in ms before which the save actually happens.
+     *     By default, the save is delayed for a short period in order to batch
+     *     multiple writes, but this behaviour can be disabled by passing 0.
+     *
+     * @return {Promise<bool>} true if the data was saved, false if
+     *     it was not (eg. because no changes were pending). The promise
+     *     will only resolve once the data is saved, so may take some time
+     *     to resolve.
+     */
+    async saveIfDirty(delay) {
+        if (!this._dirty) return Promise.resolve(false);
+        // Delay saves for a bit so we can aggregate multiple saves that happen
+        // in quick succession (eg. when a whole room's devices are marked as known)
+        if (delay === undefined) delay = 500;
+
+        const targetTime = Date.now + delay;
+        if (this._savePromiseTime && targetTime < this._savePromiseTime) {
+            // There's a save scheduled but for after we would like: cancel
+            // it & schedule one for the time we want
+            clearTimeout(this._saveTimer);
+            this._saveTimer = null;
+            this._savePromiseTime = null;
+            // (but keep the save promise since whatever called save before
+            // will still want to know when the save is done)
+        }
+
+        let savePromise = this._savePromise;
+        if (savePromise === null) {
+            savePromise = new Promise((resolve, reject) => {
+                this._resolveSavePromise = resolve;
+            });
+            this._savePromise = savePromise;
+        }
+
+        if (this._saveTimer === null) {
+            const resolveSavePromise = this._resolveSavePromise;
+            this._savePromiseTime = targetTime;
+            this._saveTimer = setTimeout(() => {
+                logger.log('Saving device tracking data at token ' + this._syncToken);
+                // null out savePromise now (after the delay but before the write),
+                // otherwise we could return the existing promise when the save has
+                // actually already happened. Likewise for the dirty flag.
+                this._savePromiseTime = null;
+                this._saveTimer = null;
+                this._savePromise = null;
+                this._resolveSavePromise = null;
+
+                this._dirty = false;
+                this._cryptoStore.doTxn(
+                    'readwrite', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
+                        this._cryptoStore.storeEndToEndDeviceData({
+                            devices: this._devices,
+                            trackingStatus: this._deviceTrackingStatus,
+                            syncToken: this._syncToken,
+                        }, txn);
+                    },
+                ).then(() => {
+                    resolveSavePromise();
+                });
+            }, delay);
+        }
+        return savePromise;
+    }
+
+    /**
+     * Gets the sync token last set with setSyncToken
+     *
+     * @return {string} The sync token
+     */
+    getSyncToken() {
+        return this._syncToken;
+    }
+
+    /**
+     * Sets the sync token that the app will pass as the 'since' to the /sync
+     * endpoint next time it syncs.
+     * The sync token must always be set after any changes made as a result of
+     * data in that sync since setting the sync token to a newer one will mean
+     * those changed will not be synced from the server if a new client starts
+     * up with that data.
+     *
+     * @param {string} st The sync token
+     */
+    setSyncToken(st) {
+        this._syncToken = st;
+    }
+
+    /**
+     * Ensures up to date keys for a list of users are stored in the session store,
+     * downloading and storing them if they're not (or if forceDownload is
+     * true).
+     * @param {Array} userIds The users to fetch.
+     * @param {bool} forceDownload Always download the keys even if cached.
+     *
+     * @return {Promise} A promise which resolves to a map userId->deviceId->{@link
+     * module:crypto/deviceinfo|DeviceInfo}.
+     */
+    downloadKeys(userIds, forceDownload) {
+        const usersToDownload = [];
+        const promises = [];
+
+        userIds.forEach((u) => {
+            const trackingStatus = this._deviceTrackingStatus[u];
+            if (this._keyDownloadsInProgressByUser[u]) {
+                // already a key download in progress/queued for this user; its results
+                // will be good enough for us.
+                logger.log(
+                    `downloadKeys: already have a download in progress for ` +
+                    `${u}: awaiting its result`,
+                );
+                promises.push(this._keyDownloadsInProgressByUser[u]);
+            } else if (forceDownload || trackingStatus != TRACKING_STATUS_UP_TO_DATE) {
+                usersToDownload.push(u);
+            }
+        });
+
+        if (usersToDownload.length != 0) {
+            logger.log("downloadKeys: downloading for", usersToDownload);
+            const downloadPromise = this._doKeyDownload(usersToDownload);
+            promises.push(downloadPromise);
+        }
+
+        if (promises.length === 0) {
+            logger.log("downloadKeys: already have all necessary keys");
+        }
+
+        return Promise.all(promises).then(() => {
+            return this._getDevicesFromStore(userIds);
+        });
+    }
+
+    /**
+     * Get the stored device keys for a list of user ids
+     *
+     * @param {string[]} userIds the list of users to list keys for.
+     *
+     * @return {Object} userId->deviceId->{@link module:crypto/deviceinfo|DeviceInfo}.
+     */
+    _getDevicesFromStore(userIds) {
+        const stored = {};
+        const self = this;
+        userIds.map(function(u) {
+            stored[u] = {};
+            const devices = self.getStoredDevicesForUser(u) || [];
+            devices.map(function(dev) {
+                stored[u][dev.deviceId] = dev;
+            });
+        });
+        return stored;
+    }
+
+    /**
+     * Get the stored device keys for a user id
+     *
+     * @param {string} userId the user to list keys for.
+     *
+     * @return {module:crypto/deviceinfo[]|null} list of devices, or null if we haven't
+     * managed to get a list of devices for this user yet.
+     */
+    getStoredDevicesForUser(userId) {
+        const devs = this._devices[userId];
+        if (!devs) {
+            return null;
+        }
+        const res = [];
+        for (const deviceId in devs) {
+            if (devs.hasOwnProperty(deviceId)) {
+                res.push(DeviceInfo.fromStorage(devs[deviceId], deviceId));
+            }
+        }
+        return res;
+    }
+
+    /**
+     * Get the stored device data for a user, in raw object form
+     *
+     * @param {string} userId the user to get data for
+     *
+     * @return {Object} deviceId->{object} devices, or undefined if
+     * there is no data for this user.
+     */
+    getRawStoredDevicesForUser(userId) {
+        return this._devices[userId];
+    }
+
+    /**
+     * Get the stored keys for a single device
+     *
+     * @param {string} userId
+     * @param {string} deviceId
+     *
+     * @return {module:crypto/deviceinfo?} device, or undefined
+     * if we don't know about this device
+     */
+    getStoredDevice(userId, deviceId) {
+        const devs = this._devices[userId];
+        if (!devs || !devs[deviceId]) {
+            return undefined;
+        }
+        return DeviceInfo.fromStorage(devs[deviceId], deviceId);
+    }
+
+    /**
+     * Find a device by curve25519 identity key
+     *
+     * @param {string} algorithm  encryption algorithm
+     * @param {string} senderKey  curve25519 key to match
+     *
+     * @return {module:crypto/deviceinfo?}
+     */
+    getDeviceByIdentityKey(algorithm, senderKey) {
+        const userId = this._userByIdentityKey[senderKey];
+        if (!userId) {
+            return null;
+        }
+
+        if (
+            algorithm !== olmlib.OLM_ALGORITHM &&
+            algorithm !== olmlib.MEGOLM_ALGORITHM
+        ) {
+            // we only deal in olm keys
+            return null;
+        }
+
+        const devices = this._devices[userId];
+        if (!devices) {
+            return null;
+        }
+
+        for (const deviceId in devices) {
+            if (!devices.hasOwnProperty(deviceId)) {
+                continue;
+            }
+
+            const device = devices[deviceId];
+            for (const keyId in device.keys) {
+                if (!device.keys.hasOwnProperty(keyId)) {
+                    continue;
+                }
+                if (keyId.indexOf("curve25519:") !== 0) {
+                    continue;
+                }
+                const deviceKey = device.keys[keyId];
+                if (deviceKey == senderKey) {
+                    return DeviceInfo.fromStorage(device, deviceId);
+                }
+            }
+        }
+
+        // doesn't match a known device
+        return null;
+    }
+
+    /**
+     * Replaces the list of devices for a user with the given device list
+     *
+     * @param {string} u The user ID
+     * @param {Object} devs New device info for user
+     */
+    storeDevicesForUser(u, devs) {
+        // remove previous devices from _userByIdentityKey
+        if (this._devices[u] !== undefined) {
+            for (const [deviceId, dev] of Object.entries(this._devices[u])) {
+                const identityKey = dev.keys['curve25519:'+deviceId];
+
+                delete this._userByIdentityKey[identityKey];
+            }
+        }
+
+        this._devices[u] = devs;
+
+        // add new ones
+        for (const [deviceId, dev] of Object.entries(devs)) {
+            const identityKey = dev.keys['curve25519:'+deviceId];
+
+            this._userByIdentityKey[identityKey] = u;
+        }
+        this._dirty = true;
+    }
+
+    /**
+     * flag the given user for device-list tracking, if they are not already.
+     *
+     * This will mean that a subsequent call to refreshOutdatedDeviceLists()
+     * will download the device list for the user, and that subsequent calls to
+     * invalidateUserDeviceList will trigger more updates.
+     *
+     * @param {String} userId
+     */
+    startTrackingDeviceList(userId) {
+        // sanity-check the userId. This is mostly paranoia, but if synapse
+        // can't parse the userId we give it as an mxid, it 500s the whole
+        // request and we can never update the device lists again (because
+        // the broken userId is always 'invalid' and always included in any
+        // refresh request).
+        // By checking it is at least a string, we can eliminate a class of
+        // silly errors.
+        if (typeof userId !== 'string') {
+            throw new Error('userId must be a string; was '+userId);
+        }
+        if (!this._deviceTrackingStatus[userId]) {
+            logger.log('Now tracking device list for ' + userId);
+            this._deviceTrackingStatus[userId] = TRACKING_STATUS_PENDING_DOWNLOAD;
+            // we don't yet persist the tracking status, since there may be a lot
+            // of calls; we save all data together once the sync is done
+            this._dirty = true;
+        }
+    }
+
+    /**
+     * Mark the given user as no longer being tracked for device-list updates.
+     *
+     * This won't affect any in-progress downloads, which will still go on to
+     * complete; it will just mean that we don't think that we have an up-to-date
+     * list for future calls to downloadKeys.
+     *
+     * @param {String} userId
+     */
+    stopTrackingDeviceList(userId) {
+        if (this._deviceTrackingStatus[userId]) {
+            logger.log('No longer tracking device list for ' + userId);
+            this._deviceTrackingStatus[userId] = TRACKING_STATUS_NOT_TRACKED;
+
+            // we don't yet persist the tracking status, since there may be a lot
+            // of calls; we save all data together once the sync is done
+            this._dirty = true;
+        }
+    }
+
+    /**
+     * Set all users we're currently tracking to untracked
+     *
+     * This will flag each user whose devices we are tracking as in need of an
+     * update.
+     */
+    stopTrackingAllDeviceLists() {
+        for (const userId of Object.keys(this._deviceTrackingStatus)) {
+            this._deviceTrackingStatus[userId] = TRACKING_STATUS_NOT_TRACKED;
+        }
+        this._dirty = true;
+    }
+
+    /**
+     * Mark the cached device list for the given user outdated.
+     *
+     * If we are not tracking this user's devices, we'll do nothing. Otherwise
+     * we flag the user as needing an update.
+     *
+     * This doesn't actually set off an update, so that several users can be
+     * batched together. Call refreshOutdatedDeviceLists() for that.
+     *
+     * @param {String} userId
+     */
+    invalidateUserDeviceList(userId) {
+        if (this._deviceTrackingStatus[userId]) {
+            logger.log("Marking device list outdated for", userId);
+            this._deviceTrackingStatus[userId] = TRACKING_STATUS_PENDING_DOWNLOAD;
+
+            // we don't yet persist the tracking status, since there may be a lot
+            // of calls; we save all data together once the sync is done
+            this._dirty = true;
+        }
+    }
+
+    /**
+     * If we have users who have outdated device lists, start key downloads for them
+     *
+     * @returns {Promise} which completes when the download completes; normally there
+     *    is no need to wait for this (it's mostly for the unit tests).
+     */
+    refreshOutdatedDeviceLists() {
+        this.saveIfDirty();
+
+        const usersToDownload = [];
+        for (const userId of Object.keys(this._deviceTrackingStatus)) {
+            const stat = this._deviceTrackingStatus[userId];
+            if (stat == TRACKING_STATUS_PENDING_DOWNLOAD) {
+                usersToDownload.push(userId);
+            }
+        }
+
+        return this._doKeyDownload(usersToDownload);
+    }
+
+    /**
+     * Set the stored device data for a user, in raw object form
+     * Used only by internal class DeviceListUpdateSerialiser
+     *
+     * @param {string} userId the user to get data for
+     *
+     * @param {Object} devices deviceId->{object} the new devices
+     */
+    _setRawStoredDevicesForUser(userId, devices) {
+        // remove old devices from _userByIdentityKey
+        if (this._devices[userId] !== undefined) {
+            for (const [deviceId, dev] of Object.entries(this._devices[userId])) {
+                const identityKey = dev.keys['curve25519:'+deviceId];
+
+                delete this._userByIdentityKey[identityKey];
+            }
+        }
+
+        this._devices[userId] = devices;
+
+        // add new devices into _userByIdentityKey
+        for (const [deviceId, dev] of Object.entries(devices)) {
+            const identityKey = dev.keys['curve25519:'+deviceId];
+
+            this._userByIdentityKey[identityKey] = userId;
+        }
+    }
+
+    /**
+     * Fire off download update requests for the given users, and update the
+     * device list tracking status for them, and the
+     * _keyDownloadsInProgressByUser map for them.
+     *
+     * @param {String[]} users  list of userIds
+     *
+     * @return {module:client.Promise} resolves when all the users listed have
+     *     been updated. rejects if there was a problem updating any of the
+     *     users.
+     */
+    _doKeyDownload(users) {
+        if (users.length === 0) {
+            // nothing to do
+            return Promise.resolve();
+        }
+
+        const prom = this._serialiser.updateDevicesForUsers(
+            users, this._syncToken,
+        ).then(() => {
+            finished(true);
+        }, (e) => {
+            logger.error(
+                'Error downloading keys for ' + users + ":", e,
+            );
+            finished(false);
+            throw e;
+        });
+
+        users.forEach((u) => {
+            this._keyDownloadsInProgressByUser[u] = prom;
+            const stat = this._deviceTrackingStatus[u];
+            if (stat == TRACKING_STATUS_PENDING_DOWNLOAD) {
+                this._deviceTrackingStatus[u] = TRACKING_STATUS_DOWNLOAD_IN_PROGRESS;
+            }
+        });
+
+        const finished = (success) => {
+            users.forEach((u) => {
+                this._dirty = true;
+
+                // we may have queued up another download request for this user
+                // since we started this request. If that happens, we should
+                // ignore the completion of the first one.
+                if (this._keyDownloadsInProgressByUser[u] !== prom) {
+                    logger.log('Another update in the queue for', u,
+                                '- not marking up-to-date');
+                    return;
+                }
+                delete this._keyDownloadsInProgressByUser[u];
+                const stat = this._deviceTrackingStatus[u];
+                if (stat == TRACKING_STATUS_DOWNLOAD_IN_PROGRESS) {
+                    if (success) {
+                        // we didn't get any new invalidations since this download started:
+                        // this user's device list is now up to date.
+                        this._deviceTrackingStatus[u] = TRACKING_STATUS_UP_TO_DATE;
+                        logger.log("Device list for", u, "now up to date");
+                    } else {
+                        this._deviceTrackingStatus[u] = TRACKING_STATUS_PENDING_DOWNLOAD;
+                    }
+                }
+            });
+            this.saveIfDirty();
+        };
+
+        return prom;
+    }
+}
+
+/**
+ * Serialises updates to device lists
+ *
+ * Ensures that results from /keys/query are not overwritten if a second call
+ * completes *before* an earlier one.
+ *
+ * It currently does this by ensuring only one call to /keys/query happens at a
+ * time (and queuing other requests up).
+ */
+class DeviceListUpdateSerialiser {
+    /*
+     * @param {object} baseApis Base API object
+     * @param {object} olmDevice The Olm Device
+     * @param {object} deviceList The device list object
+     */
+    constructor(baseApis, olmDevice, deviceList) {
+        this._baseApis = baseApis;
+        this._olmDevice = olmDevice;
+        this._deviceList = deviceList; // the device list to be updated
+
+        this._downloadInProgress = false;
+
+        // users which are queued for download
+        // userId -> true
+        this._keyDownloadsQueuedByUser = {};
+
+        // deferred which is resolved when the queued users are downloaded.
+        //
+        // non-null indicates that we have users queued for download.
+        this._queuedQueryDeferred = null;
+
+        this._syncToken = null; // The sync token we send with the requests
+    }
+
+    /**
+     * Make a key query request for the given users
+     *
+     * @param {String[]} users list of user ids
+     *
+     * @param {String} syncToken sync token to pass in the query request, to
+     *     help the HS give the most recent results
+     *
+     * @return {module:client.Promise} resolves when all the users listed have
+     *     been updated. rejects if there was a problem updating any of the
+     *     users.
+     */
+    updateDevicesForUsers(users, syncToken) {
+        users.forEach((u) => {
+            this._keyDownloadsQueuedByUser[u] = true;
+        });
+
+        if (!this._queuedQueryDeferred) {
+            this._queuedQueryDeferred = Promise.defer();
+        }
+
+        // We always take the new sync token and just use the latest one we've
+        // been given, since it just needs to be at least as recent as the
+        // sync response the device invalidation message arrived in
+        this._syncToken = syncToken;
+
+        if (this._downloadInProgress) {
+            // just queue up these users
+            logger.log('Queued key download for', users);
+            return this._queuedQueryDeferred.promise;
+        }
+
+        // start a new download.
+        return this._doQueuedQueries();
+    }
+
+    _doQueuedQueries() {
+        if (this._downloadInProgress) {
+            throw new Error(
+                "DeviceListUpdateSerialiser._doQueuedQueries called with request active",
+            );
+        }
+
+        const downloadUsers = Object.keys(this._keyDownloadsQueuedByUser);
+        this._keyDownloadsQueuedByUser = {};
+        const deferred = this._queuedQueryDeferred;
+        this._queuedQueryDeferred = null;
+
+        logger.log('Starting key download for', downloadUsers);
+        this._downloadInProgress = true;
+
+        const opts = {};
+        if (this._syncToken) {
+            opts.token = this._syncToken;
+        }
+
+        this._baseApis.downloadKeysForUsers(
+            downloadUsers, opts,
+        ).then((res) => {
+            const dk = res.device_keys || {};
+
+            // do each user in a separate promise, to avoid wedging the CPU
+            // (https://github.com/vector-im/riot-web/issues/3158)
+            //
+            // of course we ought to do this in a web worker or similar, but
+            // this serves as an easy solution for now.
+            let prom = Promise.resolve();
+            for (const userId of downloadUsers) {
+                prom = prom.delay(5).then(() => {
+                    return this._processQueryResponseForUser(userId, dk[userId]);
+                });
+            }
+
+            return prom;
+        }).done(() => {
+            logger.log('Completed key download for ' + downloadUsers);
+
+            this._downloadInProgress = false;
+            deferred.resolve();
+
+            // if we have queued users, fire off another request.
+            if (this._queuedQueryDeferred) {
+                this._doQueuedQueries();
+            }
+        }, (e) => {
+            logger.warn('Error downloading keys for ' + downloadUsers + ':', e);
+            this._downloadInProgress = false;
+            deferred.reject(e);
+        });
+
+        return deferred.promise;
+    }
+
+    async _processQueryResponseForUser(userId, response) {
+        logger.log('got keys for ' + userId + ':', response);
+
+        // map from deviceid -> deviceinfo for this user
+        const userStore = {};
+        const devs = this._deviceList.getRawStoredDevicesForUser(userId);
+        if (devs) {
+            Object.keys(devs).forEach((deviceId) => {
+                const d = DeviceInfo.fromStorage(devs[deviceId], deviceId);
+                userStore[deviceId] = d;
+            });
+        }
+
+        await _updateStoredDeviceKeysForUser(
+            this._olmDevice, userId, userStore, response || {},
+        );
+
+        // put the updates into thr object that will be returned as our results
+        const storage = {};
+        Object.keys(userStore).forEach((deviceId) => {
+            storage[deviceId] = userStore[deviceId].toStorage();
+        });
+
+        this._deviceList._setRawStoredDevicesForUser(userId, storage);
+    }
+}
+
+
+async function _updateStoredDeviceKeysForUser(_olmDevice, userId, userStore,
+        userResult) {
+    let updated = false;
+
+    // remove any devices in the store which aren't in the response
+    for (const deviceId in userStore) {
+        if (!userStore.hasOwnProperty(deviceId)) {
+            continue;
+        }
+
+        if (!(deviceId in userResult)) {
+            logger.log("Device " + userId + ":" + deviceId +
+                " has been removed");
+            delete userStore[deviceId];
+            updated = true;
+        }
+    }
+
+    for (const deviceId in userResult) {
+        if (!userResult.hasOwnProperty(deviceId)) {
+            continue;
+        }
+
+        const deviceResult = userResult[deviceId];
+
+        // check that the user_id and device_id in the response object are
+        // correct
+        if (deviceResult.user_id !== userId) {
+            logger.warn("Mismatched user_id " + deviceResult.user_id +
+               " in keys from " + userId + ":" + deviceId);
+            continue;
+        }
+        if (deviceResult.device_id !== deviceId) {
+            logger.warn("Mismatched device_id " + deviceResult.device_id +
+               " in keys from " + userId + ":" + deviceId);
+            continue;
+        }
+
+        if (await _storeDeviceKeys(_olmDevice, userStore, deviceResult)) {
+            updated = true;
+        }
+    }
+
+    return updated;
+}
+
+/*
+ * Process a device in a /query response, and add it to the userStore
+ *
+ * returns (a promise for) true if a change was made, else false
+ */
+async function _storeDeviceKeys(_olmDevice, userStore, deviceResult) {
+    if (!deviceResult.keys) {
+        // no keys?
+        return false;
+    }
+
+    const deviceId = deviceResult.device_id;
+    const userId = deviceResult.user_id;
+
+    const signKeyId = "ed25519:" + deviceId;
+    const signKey = deviceResult.keys[signKeyId];
+    if (!signKey) {
+        logger.warn("Device " + userId + ":" + deviceId +
+            " has no ed25519 key");
+        return false;
+    }
+
+    const unsigned = deviceResult.unsigned || {};
+
+    try {
+        await olmlib.verifySignature(_olmDevice, deviceResult, userId, deviceId, signKey);
+    } catch (e) {
+        logger.warn("Unable to verify signature on device " +
+            userId + ":" + deviceId + ":" + e);
+        return false;
+    }
+
+    // DeviceInfo
+    let deviceStore;
+
+    if (deviceId in userStore) {
+        // already have this device.
+        deviceStore = userStore[deviceId];
+
+        if (deviceStore.getFingerprint() != signKey) {
+            // this should only happen if the list has been MITMed; we are
+            // best off sticking with the original keys.
+            //
+            // Should we warn the user about it somehow?
+            logger.warn("Ed25519 key for device " + userId + ":" +
+               deviceId + " has changed");
+            return false;
+        }
+    } else {
+        userStore[deviceId] = deviceStore = new DeviceInfo(deviceId);
+    }
+
+    deviceStore.keys = deviceResult.keys || {};
+    deviceStore.algorithms = deviceResult.algorithms || [];
+    deviceStore.unsigned = unsigned;
+    return true;
+}

src/crypto/OutgoingRoomKeyRequestManager.js

@@ -0,0 +1,493 @@
+/*
+Copyright 2017 Vector Creations 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.
+*/
+
+import Promise from 'bluebird';
+
+import logger from '../logger';
+import utils from '../utils';
+
+/**
+ * Internal module. Management of outgoing room key requests.
+ *
+ * See https://docs.google.com/document/d/1m4gQkcnJkxNuBmb5NoFCIadIY-DyqqNAS3lloE73BlQ
+ * for draft documentation on what we're supposed to be implementing here.
+ *
+ * @module
+ */
+
+// delay between deciding we want some keys, and sending out the request, to
+// allow for (a) it turning up anyway, (b) grouping requests together
+const SEND_KEY_REQUESTS_DELAY_MS = 500;
+
+/** possible states for a room key request
+ *
+ * The state machine looks like:
+ *
+ *     |         (cancellation sent)
+ *     | .-------------------------------------------------.
+ *     | |                                                 |
+ *     V V       (cancellation requested)                  |
+ *   UNSENT  -----------------------------+                |
+ *     |                                  |                |
+ *     |                                  |                |
+ *     | (send successful)                |  CANCELLATION_PENDING_AND_WILL_RESEND
+ *     V                                  |                Λ
+ *    SENT                                |                |
+ *     |--------------------------------  |  --------------'
+ *     |                                  |  (cancellation requested with intent
+ *     |                                  |   to resend the original request)
+ *     |                                  |
+ *     | (cancellation requested)         |
+ *     V                                  |
+ * CANCELLATION_PENDING                   |
+ *     |                                  |
+ *     | (cancellation sent)              |
+ *     V                                  |
+ * (deleted)  <---------------------------+
+ *
+ * @enum {number}
+ */
+const ROOM_KEY_REQUEST_STATES = {
+    /** request not yet sent */
+    UNSENT: 0,
+
+    /** request sent, awaiting reply */
+    SENT: 1,
+
+    /** reply received, cancellation not yet sent */
+    CANCELLATION_PENDING: 2,
+
+    /**
+     * 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,
+};
+
+export default 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.
+        this._sendOutgoingRoomKeyRequestsTimer = null;
+
+        // sanity check to ensure that we don't end up with two concurrent runs
+        // of _sendOutgoingRoomKeyRequests
+        this._sendOutgoingRoomKeyRequestsRunning = false;
+
+        this._clientRunning = false;
+    }
+
+    /**
+     * Called when the client is started. Sets background processes running.
+     */
+    start() {
+        this._clientRunning = true;
+
+        // set the timer going, to handle any requests which didn't get sent
+        // on the previous run of the client.
+        this._startTimer();
+    }
+
+    /**
+     * Called when the client is stopped. Stops any running background processes.
+     */
+    stop() {
+        logger.log('stopping OutgoingRoomKeyRequestManager');
+        // stop the timer on the next run
+        this._clientRunning = false;
+    }
+
+    /**
+     * Send off a room key request, if we haven't already done so.
+     *
+     * The `requestBody` is compared (with a deep-equality check) against
+     * previous queued or sent requests and if it matches, no change is made.
+     * Otherwise, a request is added to the pending list, and a job is started
+     * in the background to send it.
+     *
+     * @param {module:crypto~RoomKeyRequestBody} requestBody
+     * @param {Array<{userId: string, deviceId: string}>} recipients
+     * @param {boolean} resend whether to resend the key request if there is
+     *    already one
+     *
+     * @returns {Promise} resolves when the request has been added to the
+     *    pending list (or we have established that a similar request already
+     *    exists)
+     */
+    async sendRoomKeyRequest(requestBody, recipients, resend=false) {
+        const req = await this._cryptoStore.getOutgoingRoomKeyRequest(
+            requestBody,
+        );
+        if (!req) {
+            await this._cryptoStore.getOrAddOutgoingRoomKeyRequest({
+                requestBody: requestBody,
+                recipients: recipients,
+                requestId: this._baseApis.makeTxnId(),
+                state: ROOM_KEY_REQUEST_STATES.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 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.sendRoomKeyRequest(
+                            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);
+            }
+        }
+        // some of the branches require the timer to be started.  Just start it
+        // all the time, because it doesn't hurt to start it.
+        this._startTimer();
+    }
+
+    /**
+     * Cancel room key requests, if any match the given requestBody
+     *
+     * @param {module:crypto~RoomKeyRequestBody} requestBody
+     *
+     * @returns {Promise} resolves when the request has been updated in our
+     *    pending list.
+     */
+    cancelRoomKeyRequest(requestBody) {
+        return this._cryptoStore.getOutgoingRoomKeyRequest(
+            requestBody,
+        ).then((req) => {
+            if (!req) {
+                // no request was made for this key
+                return;
+            }
+            switch (req.state) {
+                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING:
+                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND:
+                    // nothing to do here
+                    return;
+
+                case ROOM_KEY_REQUEST_STATES.UNSENT:
+                    // just delete it
+
+                    // FIXME: ghahah we may have attempted to send it, and
+                    // not yet got a successful response. So the server
+                    // may have seen it, so we still need to send a cancellation
+                    // in that case :/
+
+                    logger.log(
+                        'deleting unnecessary room key request for ' +
+                        stringifyRequestBody(requestBody),
+                    );
+                    return this._cryptoStore.deleteOutgoingRoomKeyRequest(
+                        req.requestId, ROOM_KEY_REQUEST_STATES.UNSENT,
+                    );
+
+                case ROOM_KEY_REQUEST_STATES.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(),
+                        },
+                    ).then((updatedReq) => {
+                        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. There is no point in
+                            // sending another cancellation since the other tab
+                            // will do it.
+                            logger.log(
+                                'Tried to cancel room key request for ' +
+                                stringifyRequestBody(requestBody) +
+                                ' but it was already cancelled in another tab',
+                            );
+                            return;
+                        }
+
+                        // 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.)
+                        this._sendOutgoingRoomKeyRequestCancellation(
+                            updatedReq,
+                        ).catch((e) => {
+                            logger.error(
+                                "Error sending room key request cancellation;"
+                                + " will retry later.", e,
+                            );
+                            this._startTimer();
+                        });
+                    });
+                }
+                default:
+                    throw new Error('unhandled state: ' + req.state);
+            }
+        });
+    }
+
+    /**
+     * Look for room key requests by target device and state
+     *
+     * @param {string} userId Target user ID
+     * @param {string} deviceId Target device ID
+     *
+     * @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],
+        );
+    }
+
+    // start the background timer to send queued requests, if the timer isn't
+    // already running
+    _startTimer() {
+        if (this._sendOutgoingRoomKeyRequestsTimer) {
+            return;
+        }
+
+        const startSendingOutgoingRoomKeyRequests = () => {
+            if (this._sendOutgoingRoomKeyRequestsRunning) {
+                throw new Error("RoomKeyRequestSend already in progress!");
+            }
+            this._sendOutgoingRoomKeyRequestsRunning = true;
+
+            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.
+                logger.warn(
+                    `error in OutgoingRoomKeyRequestManager: ${e}`,
+                );
+            });
+        };
+
+        this._sendOutgoingRoomKeyRequestsTimer = global.setTimeout(
+            startSendingOutgoingRoomKeyRequests,
+            SEND_KEY_REQUESTS_DELAY_MS,
+        );
+    }
+
+    // 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;
+            return Promise.resolve();
+        }
+
+        logger.log("Looking for queued outgoing room key requests");
+
+        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) => {
+            if (!req) {
+                logger.log("No more outgoing room key requests");
+                this._sendOutgoingRoomKeyRequestsTimer = null;
+                return;
+            }
+
+            let prom;
+            switch (req.state) {
+                case ROOM_KEY_REQUEST_STATES.UNSENT:
+                    prom = this._sendOutgoingRoomKeyRequest(req);
+                    break;
+                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING:
+                    prom = this._sendOutgoingRoomKeyRequestCancellation(req);
+                    break;
+                case ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND:
+                    prom = this._sendOutgoingRoomKeyRequestCancellation(req, true);
+                    break;
+            }
+
+            return prom.then(() => {
+                // go around the loop again
+                return this._sendOutgoingRoomKeyRequests();
+            }).catch((e) => {
+                logger.error("Error sending room key request; will retry later.", e);
+                this._sendOutgoingRoomKeyRequestsTimer = null;
+                this._startTimer();
+            });
+        });
+    }
+
+    // given a RoomKeyRequest, send it and update the request record
+    _sendOutgoingRoomKeyRequest(req) {
+        logger.log(
+            `Requesting keys for ${stringifyRequestBody(req.requestBody)}` +
+            ` from ${stringifyRecipientList(req.recipients)}` +
+            `(id ${req.requestId})`,
+        );
+
+        const requestMessage = {
+            action: "request",
+            requesting_device_id: this._deviceId,
+            request_id: req.requestId,
+            body: req.requestBody,
+        };
+
+        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 },
+            );
+        });
+    }
+
+    // Given a RoomKeyRequest, cancel it and delete the request record unless
+    // andResend is set, in which case transition to UNSENT.
+    _sendOutgoingRoomKeyRequestCancellation(req, andResend) {
+        logger.log(
+            `Sending cancellation for key request for ` +
+            `${stringifyRequestBody(req.requestBody)} to ` +
+            `${stringifyRecipientList(req.recipients)} ` +
+            `(cancellation id ${req.cancellationTxnId})`,
+        );
+
+        const requestMessage = {
+            action: "request_cancellation",
+            requesting_device_id: this._deviceId,
+            request_id: req.requestId,
+        };
+
+        return this._sendMessageToDevices(
+            requestMessage, req.recipients, req.cancellationTxnId,
+        ).then(() => {
+            if (andResend) {
+                // We want to resend, so transition to UNSENT
+                return this._cryptoStore.updateOutgoingRoomKeyRequest(
+                    req.requestId,
+                    ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND,
+                    { state: ROOM_KEY_REQUEST_STATES.UNSENT },
+                );
+            }
+            return this._cryptoStore.deleteOutgoingRoomKeyRequest(
+                req.requestId, ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING,
+            );
+        });
+    }
+
+    // send a RoomKeyRequest to a list of recipients
+    _sendMessageToDevices(message, recipients, txnId) {
+        const contentMap = {};
+        for (const recip of recipients) {
+            if (!contentMap[recip.userId]) {
+                contentMap[recip.userId] = {};
+            }
+            contentMap[recip.userId][recip.deviceId] = message;
+        }
+
+        return this._baseApis.sendToDevice(
+            'm.room_key_request', contentMap, txnId,
+        );
+    }
+}
+
+function stringifyRequestBody(requestBody) {
+    // we assume that the request is for megolm keys, which are identified by
+    // room id and session id
+    return requestBody.room_id + " / " + requestBody.session_id;
+}
+
+function stringifyRecipientList(recipients) {
+    return '['
+        + utils.map(recipients, (r) => `${r.userId}:${r.deviceId}`).join(",")
+        + ']';
+}
+

src/crypto/RoomList.js

@@ -0,0 +1,65 @@
+/*
+Copyright 2018, 2019 New Vector 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.
+*/
+
+/**
+ * @module crypto/RoomList
+ *
+ * Manages the list of encrypted rooms
+ */
+
+import IndexedDBCryptoStore from './store/indexeddb-crypto-store';
+
+/**
+ * @alias module:crypto/RoomList
+ */
+export default class RoomList {
+    constructor(cryptoStore) {
+        this._cryptoStore = cryptoStore;
+
+        // Object of roomId -> room e2e info object (body of the m.room.encryption event)
+        this._roomEncryption = {};
+    }
+
+    async init() {
+        await this._cryptoStore.doTxn(
+            'readwrite', [IndexedDBCryptoStore.STORE_ROOMS], (txn) => {
+                this._cryptoStore.getEndToEndRooms(txn, (result) => {
+                    this._roomEncryption = result;
+                });
+            },
+        );
+    }
+
+    getRoomEncryption(roomId) {
+        return this._roomEncryption[roomId] || null;
+    }
+
+    isRoomEncrypted(roomId) {
+        return Boolean(this.getRoomEncryption(roomId));
+    }
+
+    async setRoomEncryption(roomId, roomInfo) {
+        // 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(
+            'readwrite', [IndexedDBCryptoStore.STORE_ROOMS], (txn) => {
+                this._cryptoStore.storeEndToEndRoom(roomId, roomInfo, txn);
+            },
+        );
+    }
+}

src/crypto/algorithms/base.js

@@ -0,0 +1,236 @@
+/*
+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.
+*/
+
+/**
+ * Internal module. Defines the base classes of the encryption implementations
+ *
+ * @module
+ */
+
+import Promise from 'bluebird';
+
+/**
+ * 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 = {};
+
+/**
+ * map of registered encryption algorithm classes. Map from string to {@link
+ * module:crypto/algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm} class
+ *
+ * @type {Object.<string, function(new: module:crypto/algorithms/base.DecryptionAlgorithm)>}
+ */
+export const DECRYPTION_CLASSES = {};
+
+/**
+ * base type for encryption implementations
+ *
+ * @alias module:crypto/algorithms/base.EncryptionAlgorithm
+ *
+ * @param {object} params parameters
+ * @param {string} params.userId  The UserID for the local user
+ * @param {string} params.deviceId The identifier for this device.
+ * @param {module:crypto} params.crypto crypto core
+ * @param {module:crypto/OlmDevice} params.olmDevice olm.js wrapper
+ * @param {module:base-apis~MatrixBaseApis} baseApis base matrix api interface
+ * @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
+ */
+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;
+    }
+
+    /**
+     * Encrypt a message event
+     *
+     * @method module:crypto/algorithms/base.EncryptionAlgorithm.encryptMessage
+     * @abstract
+     *
+     * @param {module:models/room} room
+     * @param {string} eventType
+     * @param {object} plaintext event content
+     *
+     * @return {module:client.Promise} Promise which resolves to the new event body
+     */
+
+    /**
+     * Called when the membership of a member of the room changes.
+     *
+     * @param {module:models/event.MatrixEvent} event  event causing the change
+     * @param {module:models/room-member} member  user whose membership changed
+     * @param {string=} oldMembership  previous membership
+     * @public
+     */
+     onRoomMembership(event, member, oldMembership) {
+     }
+}
+export {EncryptionAlgorithm}; // https://github.com/jsdoc3/jsdoc/issues/1272
+
+/**
+ * base type for decryption implementations
+ *
+ * @alias module:crypto/algorithms/base.DecryptionAlgorithm
+ * @param {object} params parameters
+ * @param {string} params.userId  The UserID for the local user
+ * @param {module:crypto} params.crypto crypto core
+ * @param {module:crypto/OlmDevice} params.olmDevice olm.js wrapper
+ * @param {module:base-apis~MatrixBaseApis} baseApis base matrix api interface
+ * @param {string=} params.roomId The ID of the room we will be receiving
+ *     from. Null for to-device events.
+ */
+class DecryptionAlgorithm {
+    constructor(params) {
+        this._userId = params.userId;
+        this._crypto = params.crypto;
+        this._olmDevice = params.olmDevice;
+        this._baseApis = params.baseApis;
+        this._roomId = params.roomId;
+    }
+
+    /**
+     * Decrypt an event
+     *
+     * @method module:crypto/algorithms/base.DecryptionAlgorithm#decryptEvent
+     * @abstract
+     *
+     * @param {MatrixEvent} event undecrypted event
+     *
+     * @return {Promise<module:crypto~EventDecryptionResult>} promise which
+     * resolves once we have finished decrypting. Rejects with an
+     * `algorithms.DecryptionError` if there is a problem decrypting the event.
+     */
+
+    /**
+     * Handle a key event
+     *
+     * @method module:crypto/algorithms/base.DecryptionAlgorithm#onRoomKeyEvent
+     *
+     * @param {module:models/event.MatrixEvent} params event key event
+     */
+    onRoomKeyEvent(params) {
+        // ignore by default
+    }
+
+    /**
+     * Import a room key
+     *
+     * @param {module:crypto/OlmDevice.MegolmSessionData} session
+     */
+    importRoomKey(session) {
+        // ignore by default
+    }
+
+    /**
+     * Determine if we have the keys necessary to respond to a room key request
+     *
+     * @param {module:crypto~IncomingRoomKeyRequest} keyRequest
+     * @return {Promise<boolean>} true if we have the keys and could (theoretically) share
+     *  them; else false.
+     */
+    hasKeysForKeyRequest(keyRequest) {
+        return Promise.resolve(false);
+    }
+
+    /**
+     * Send the response to a room key request
+     *
+     * @param {module:crypto~IncomingRoomKeyRequest} keyRequest
+     */
+    shareKeysWithDevice(keyRequest) {
+        throw new Error("shareKeysWithDevice not supported for this DecryptionAlgorithm");
+    }
+}
+export {DecryptionAlgorithm}; // https://github.com/jsdoc3/jsdoc/issues/1272
+
+/**
+ * Exception thrown when decryption fails
+ *
+ * @alias module:crypto/algorithms/base.DecryptionError
+ * @param {string} msg user-visible message describing the problem
+ *
+ * @param {Object=} details key/value pairs reported in the logs but not shown
+ *   to the user.
+ *
+ * @extends Error
+ */
+class DecryptionError extends Error {
+    constructor(code, msg, details) {
+        super(msg);
+        this.code = code;
+        this.name = 'DecryptionError';
+        this.detailedString = _detailedStringForDecryptionError(this, details);
+    }
+}
+export {DecryptionError}; // https://github.com/jsdoc3/jsdoc/issues/1272
+
+function _detailedStringForDecryptionError(err, details) {
+    let result = err.name + '[msg: ' + err.message;
+
+    if (details) {
+        result += ', ' +
+            Object.keys(details).map(
+                (k) => k + ': ' + details[k],
+            ).join(', ');
+    }
+
+    result += ']';
+
+    return result;
+}
+
+/**
+ * Exception thrown specifically when we want to warn the user to consider
+ * the security of their conversation before continuing
+ *
+ * @param {string} msg message describing the problem
+ * @param {Object} devices userId -> {deviceId -> object}
+ *      set of unknown devices per user we're warning about
+ * @extends Error
+ */
+export class UnknownDeviceError extends Error {
+    constructor(msg, devices) {
+        super(msg);
+        this.name = "UnknownDeviceError";
+        this.devices = devices;
+    }
+}
+
+/**
+ * Registers an encryption/decryption class for a particular algorithm
+ *
+ * @param {string} algorithm algorithm tag to register for
+ *
+ * @param {class} encryptor {@link
+ *     module:crypto/algorithms/base.EncryptionAlgorithm|EncryptionAlgorithm}
+ *     implementation
+ *
+ * @param {class} decryptor {@link
+ *     module:crypto/algorithms/base.DecryptionAlgorithm|DecryptionAlgorithm}
+ *     implementation
+ */
+export function registerAlgorithm(algorithm, encryptor, decryptor) {
+    ENCRYPTION_CLASSES[algorithm] = encryptor;
+    DECRYPTION_CLASSES[algorithm] = decryptor;
+}

src/crypto/algorithms/index.js

@@ -0,0 +1,40 @@
+/*
+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.
+*/
+"use strict";
+
+/**
+ * @module crypto/algorithms
+ */
+
+const base = require("./base");
+
+require("./olm");
+require("./megolm");
+
+/**
+ * @see module:crypto/algorithms/base.ENCRYPTION_CLASSES
+ */
+module.exports.ENCRYPTION_CLASSES = base.ENCRYPTION_CLASSES;
+
+/**
+ * @see module:crypto/algorithms/base.DECRYPTION_CLASSES
+ */
+module.exports.DECRYPTION_CLASSES = base.DECRYPTION_CLASSES;
+
+/**
+ * @see module:crypto/algorithms/base.DecryptionError
+ */
+module.exports.DecryptionError = base.DecryptionError;

src/crypto/algorithms/olm.js

@@ -0,0 +1,340 @@
+/*
+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.
+*/
+"use strict";
+
+/**
+ * Defines m.olm encryption/decryption
+ *
+ * @module crypto/algorithms/olm
+ */
+import Promise from 'bluebird';
+
+import logger from '../../logger';
+const utils = require("../../utils");
+const olmlib = require("../olmlib");
+const DeviceInfo = require("../deviceinfo");
+const DeviceVerification = DeviceInfo.DeviceVerification;
+
+
+const base = require("./base");
+
+/**
+ * Olm encryption implementation
+ *
+ * @constructor
+ * @extends {module:crypto/algorithms/base.EncryptionAlgorithm}
+ *
+ * @param {object} params parameters, as per
+ *     {@link module:crypto/algorithms/base.EncryptionAlgorithm}
+ */
+function OlmEncryption(params) {
+    base.EncryptionAlgorithm.call(this, params);
+    this._sessionPrepared = false;
+    this._prepPromise = null;
+}
+utils.inherits(OlmEncryption, base.EncryptionAlgorithm);
+
+/**
+ * @private
+
+ * @param {string[]} roomMembers list of currently-joined users in the room
+ * @return {module:client.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 {module:client.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 = utils.map(members, 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).return(encryptedContent);
+};
+
+/**
+ * Olm decryption implementation
+ *
+ * @constructor
+ * @extends {module:crypto/algorithms/base.DecryptionAlgorithm}
+ * @param {object} params parameters, as per
+ *     {@link module:crypto/algorithms/base.DecryptionAlgorithm}
+ */
+function OlmDecryption(params) {
+    base.DecryptionAlgorithm.call(this, params);
+}
+utils.inherits(OlmDecryption, base.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 base.DecryptionError(
+            "OLM_MISSING_CIPHERTEXT",
+            "Missing ciphertext",
+        );
+    }
+
+    if (!(this._olmDevice.deviceCurve25519Key in ciphertext)) {
+        throw new base.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 base.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 base.DecryptionError(
+            "OLM_BAD_RECIPIENT",
+            "Message was intented for " + payload.recipient,
+        );
+    }
+
+    if (payload.recipient_keys.ed25519 != this._olmDevice.deviceEd25519Key) {
+        throw new base.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 base.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 base.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,
+) {
+    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;
+};
+
+
+base.registerAlgorithm(olmlib.OLM_ALGORITHM, OlmEncryption, OlmDecryption);

src/crypto/backup_password.js

@@ -0,0 +1,81 @@
+/*
+Copyright 2018 New Vector 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.
+*/
+
+import { randomString } from '../randomstring';
+
+const DEFAULT_ITERATIONS = 500000;
+
+export async function keyForExistingBackup(backupData, password) {
+    if (!global.Olm) {
+        throw new Error("Olm is not available");
+    }
+
+    const authData = backupData.auth_data;
+
+    if (!authData.private_key_salt || !authData.private_key_iterations) {
+        throw new Error(
+            "Salt and/or iterations not found: " +
+            "this backup cannot be restored with a passphrase",
+        );
+    }
+
+    return await deriveKey(
+        password, backupData.auth_data.private_key_salt,
+        backupData.auth_data.private_key_iterations,
+    );
+}
+
+export async function keyForNewBackup(password) {
+    if (!global.Olm) {
+        throw new Error("Olm is not available");
+    }
+
+    const salt = randomString(32);
+
+    const key = await deriveKey(password, salt, DEFAULT_ITERATIONS);
+
+    return { key, salt, iterations: DEFAULT_ITERATIONS };
+}
+
+async function deriveKey(password, salt, iterations) {
+    const subtleCrypto = global.crypto.subtle;
+    const TextEncoder = global.TextEncoder;
+    if (!subtleCrypto || !TextEncoder) {
+        // TODO: Implement this for node
+        throw new Error("Password-based backup is not avaiable on this platform");
+    }
+
+    const key = await subtleCrypto.importKey(
+        'raw',
+        new TextEncoder().encode(password),
+        {name: 'PBKDF2'},
+        false,
+        ['deriveBits'],
+    );
+
+    const keybits = await subtleCrypto.deriveBits(
+        {
+            name: 'PBKDF2',
+            salt: new TextEncoder().encode(salt),
+            iterations: iterations,
+            hash: 'SHA-512',
+        },
+        key,
+        global.Olm.PRIVATE_KEY_LENGTH * 8,
+    );
+
+    return new Uint8Array(keybits);
+}

src/crypto/deviceinfo.js

@@ -0,0 +1,169 @@
+/*
+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.
+*/
+"use strict";
+
+
+/**
+ * @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
+  */
+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 = {};
+}
+
+/**
+ * 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,
+    };
+};
+
+/**
+ * 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;
+
+/** */
+module.exports = DeviceInfo;