v1.0.2

Prepare changelog for v1.0.2
v1.0.2-rc.1
2019-03-18 13:47:54 +00:00 · 2019-03-18 13:47:53 +00:00 · 2019-03-13 14:24:57 +00:00 · 2019-03-13 14:24:26 +00:00 · 2019-03-13 14:23:51 +00:00 · 2019-03-13 14:20:18 +00:00
71 changed files with 11844 additions and 468 deletions
@@ -1,7 +1,6 @@
 module.exports = {
-    parser: "babel-eslint",
+    parser: "babel-eslint", // now needed for class properties
    parserOptions: {
-        ecmaVersion: 6,
        sourceType: "module",
        ecmaFeatures: {
        }
@@ -67,5 +66,12 @@ module.exports = {
        "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",
    }
 }
@@ -2,6 +2,7 @@
 /.jsdoc

 node_modules
+/.npmrc
 .lock-wscript
 build/Release
 coverage
@@ -12,6 +13,6 @@ reports
 /lib
 /specbuild

-# version file and tarball created by 'npm pack'
+# version file and tarball created by `npm pack` / `yarn pack`
 /git-revision.txt
 /matrix-js-sdk-*.tgz
@@ -1,5 +1,8 @@
 language: node_js
 node_js:
-    - node # Latest stable version of nodejs.
+    - "10.11.0"
+before_install:
+    - curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.13.0
+    - export PATH=$HOME/.yarn/bin:$PATH
 script:
    - ./travis.sh
@@ -1,3 +1,252 @@
+Changes in [1.0.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.2) (2019-03-18)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.2-rc.1...v1.0.2)
+
+ * No changes since rc.1
+
+Changes in [1.0.2-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.2-rc.1) (2019-03-13)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.1...v1.0.2-rc.1)
+
+ * Use modern Yarn version on Travis CI
+   [\#858](https://github.com/matrix-org/matrix-js-sdk/pull/858)
+ * Switch to `yarn` for dependency management
+   [\#856](https://github.com/matrix-org/matrix-js-sdk/pull/856)
+ * More key request fixes
+   [\#855](https://github.com/matrix-org/matrix-js-sdk/pull/855)
+ * Calculate encrypted notification counts
+   [\#851](https://github.com/matrix-org/matrix-js-sdk/pull/851)
+ * Update dependencies
+   [\#854](https://github.com/matrix-org/matrix-js-sdk/pull/854)
+ * make sure key requests get sent
+   [\#850](https://github.com/matrix-org/matrix-js-sdk/pull/850)
+ * Use 'ideal' rather than 'exact' for deviceid
+   [\#852](https://github.com/matrix-org/matrix-js-sdk/pull/852)
+ * handle partially-shared sessions better
+   [\#848](https://github.com/matrix-org/matrix-js-sdk/pull/848)
+
+Changes in [1.0.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.1) (2019-03-06)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.1-rc.2...v1.0.1)
+
+ * No changes since rc.2
+
+Changes in [1.0.1-rc.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.1-rc.2) (2019-03-05)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.1-rc.1...v1.0.1-rc.2)
+
+ * dont swallow txn errors in crypto store
+   [\#853](https://github.com/matrix-org/matrix-js-sdk/pull/853)
+ * Don't swallow txn errors in crypto store
+   [\#849](https://github.com/matrix-org/matrix-js-sdk/pull/849)
+
+Changes in [1.0.1-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.1-rc.1) (2019-02-28)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.0...v1.0.1-rc.1)
+
+ * Fix "e is undefined" masking the original error in MegolmDecryption
+   [\#847](https://github.com/matrix-org/matrix-js-sdk/pull/847)
+
+Changes in [1.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.0) (2019-02-14)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.0-rc.2...v1.0.0)
+
+ * Try again to commit package-lock.json
+   [\#841](https://github.com/matrix-org/matrix-js-sdk/pull/841)
+
+Changes in [1.0.0-rc.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.0-rc.2) (2019-02-14)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.0-rc.1...v1.0.0-rc.2)
+
+ * Release script: commit package-lock.json
+   [\#839](https://github.com/matrix-org/matrix-js-sdk/pull/839)
+ * Add method to force re-check of key backup
+   [\#840](https://github.com/matrix-org/matrix-js-sdk/pull/840)
+ * Fix: dont check for unverified devices in left members
+   [\#838](https://github.com/matrix-org/matrix-js-sdk/pull/838)
+
+Changes in [1.0.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.0-rc.1) (2019-02-08)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.3...v1.0.0-rc.1)
+
+ * change hex SAS verification to decimal and emoji
+   [\#837](https://github.com/matrix-org/matrix-js-sdk/pull/837)
+ * Trust on decrypt
+   [\#836](https://github.com/matrix-org/matrix-js-sdk/pull/836)
+ * Always track our own devices
+   [\#835](https://github.com/matrix-org/matrix-js-sdk/pull/835)
+ * Make linting rules more consistent
+   [\#834](https://github.com/matrix-org/matrix-js-sdk/pull/834)
+ * add method to room to check for unverified devices
+   [\#833](https://github.com/matrix-org/matrix-js-sdk/pull/833)
+ * Merge redesign into develop
+   [\#831](https://github.com/matrix-org/matrix-js-sdk/pull/831)
+ * Supporting infrastructure for educated decisions on when to upgrade rooms
+   [\#830](https://github.com/matrix-org/matrix-js-sdk/pull/830)
+ * Include signature info for unknown devices
+   [\#826](https://github.com/matrix-org/matrix-js-sdk/pull/826)
+ * Flag v2 rooms as "safe"
+   [\#828](https://github.com/matrix-org/matrix-js-sdk/pull/828)
+ * Update ESLint
+   [\#821](https://github.com/matrix-org/matrix-js-sdk/pull/821)
+
+Changes in [0.14.3](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.3) (2019-01-22)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.3-rc.1...v0.14.3)
+
+ * No changes since rc.1
+
+Changes in [0.14.3-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.3-rc.1) (2019-01-17)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.2...v0.14.3-rc.1)
+
+ * Merge develop into experimental
+   [\#815](https://github.com/matrix-org/matrix-js-sdk/pull/815)
+ * Add a getAllEndToEndSessions to crypto store
+   [\#812](https://github.com/matrix-org/matrix-js-sdk/pull/812)
+ * T3chguy/fix displayname logic
+   [\#668](https://github.com/matrix-org/matrix-js-sdk/pull/668)
+ * Contributing: Note that rebase lets you mass signoff commits
+   [\#814](https://github.com/matrix-org/matrix-js-sdk/pull/814)
+ * take into account homoglyphs when calculating similar display names
+   [\#672](https://github.com/matrix-org/matrix-js-sdk/pull/672)
+ * Emit for key backup failures
+   [\#809](https://github.com/matrix-org/matrix-js-sdk/pull/809)
+ * emit oldEventId on "updatePendingEvent"
+   [\#646](https://github.com/matrix-org/matrix-js-sdk/pull/646)
+ * Add getThirdpartyUser to base api
+   [\#589](https://github.com/matrix-org/matrix-js-sdk/pull/589)
+ * Support custom status messages
+   [\#805](https://github.com/matrix-org/matrix-js-sdk/pull/805)
+ * Extra checks to avoid release script blowing up mid-process.
+   [\#749](https://github.com/matrix-org/matrix-js-sdk/pull/749)
+ * Move glob regex utilities out of the pushprocessor and into a more generic
+   place
+   [\#800](https://github.com/matrix-org/matrix-js-sdk/pull/800)
+
+Changes in [0.14.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.2) (2018-12-10)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.2-rc.1...v0.14.2)
+
+ * No changes since rc.1
+
+Changes in [0.14.2-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.2-rc.1) (2018-12-06)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.1...v0.14.2-rc.1)
+
+ * fix some assertions in e2e backup unit test
+   [\#794](https://github.com/matrix-org/matrix-js-sdk/pull/794)
+ * Config should be called with auth
+   [\#798](https://github.com/matrix-org/matrix-js-sdk/pull/798)
+ * Don't re-establish sessions with unknown devices
+   [\#792](https://github.com/matrix-org/matrix-js-sdk/pull/792)
+ * e2e key backups
+   [\#684](https://github.com/matrix-org/matrix-js-sdk/pull/684)
+ * WIP: online incremental megolm backups
+   [\#595](https://github.com/matrix-org/matrix-js-sdk/pull/595)
+ * Support for e2e key backups
+   [\#736](https://github.com/matrix-org/matrix-js-sdk/pull/736)
+ * Passphrase Support for e2e backups
+   [\#786](https://github.com/matrix-org/matrix-js-sdk/pull/786)
+ * Add 'getSsoLoginUrl' function
+   [\#783](https://github.com/matrix-org/matrix-js-sdk/pull/783)
+ * Fix: don't set the room name to null when heroes are missing.
+   [\#784](https://github.com/matrix-org/matrix-js-sdk/pull/784)
+ * Handle crypto db version upgrades
+   [\#785](https://github.com/matrix-org/matrix-js-sdk/pull/785)
+ * Restart broken Olm sessions
+   [\#780](https://github.com/matrix-org/matrix-js-sdk/pull/780)
+ * Use the last olm session that got a message
+   [\#776](https://github.com/matrix-org/matrix-js-sdk/pull/776)
+
+Changes in [0.14.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.1) (2018-11-22)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.0...v0.14.1)
+
+ * Warning when crypto DB is too new to use.
+
+Changes in [0.14.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.0) (2018-11-19)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.14.0-rc.1...v0.14.0)
+
+ * No changes since rc.1
+
+Changes in [0.14.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.14.0-rc.1) (2018-11-15)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.13.1...v0.14.0-rc.1)
+
+BREAKING CHANGE
+----------------
+ 
+ * js-sdk now uses Olm 3.0. Apps using Olm must update to 3.0 to
+   continue using Olm with the js-sdk. The js-sdk will call Olm's
+   init() method when the client is started.
+
+All Changes
+-----------
+
+ * Prevent messages from being sent if other messages have failed to send
+   [\#781](https://github.com/matrix-org/matrix-js-sdk/pull/781)
+ * A unit test for olm
+   [\#777](https://github.com/matrix-org/matrix-js-sdk/pull/777)
+ * Set access_token and user_id after login in with username and password.
+   [\#778](https://github.com/matrix-org/matrix-js-sdk/pull/778)
+ * Add function to get currently joined rooms.
+   [\#779](https://github.com/matrix-org/matrix-js-sdk/pull/779)
+ * Remove the request-only stuff we don't need anymore
+   [\#775](https://github.com/matrix-org/matrix-js-sdk/pull/775)
+ * Manually construct query strings for browser-request instances
+   [\#770](https://github.com/matrix-org/matrix-js-sdk/pull/770)
+ * Fix: correctly check for crypto being present
+   [\#769](https://github.com/matrix-org/matrix-js-sdk/pull/769)
+ * Update babel-eslint to 8.1.1
+   [\#768](https://github.com/matrix-org/matrix-js-sdk/pull/768)
+ * Support `request` in the browser and support supplying servers to try in
+   joinRoom()
+   [\#764](https://github.com/matrix-org/matrix-js-sdk/pull/764)
+ * loglevel should be a normal dependency
+   [\#767](https://github.com/matrix-org/matrix-js-sdk/pull/767)
+ * Stop devicelist when client is stopped
+   [\#766](https://github.com/matrix-org/matrix-js-sdk/pull/766)
+ * Update to WebAssembly-powered Olm
+   [\#743](https://github.com/matrix-org/matrix-js-sdk/pull/743)
+ * Logging lib. Fixes #332
+   [\#763](https://github.com/matrix-org/matrix-js-sdk/pull/763)
+ * Use new stop() method on matrix-mock-request
+   [\#765](https://github.com/matrix-org/matrix-js-sdk/pull/765)
+
+Changes in [0.13.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.13.1) (2018-11-14)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.13.0...v0.13.1)
+
+ * Add function to get currently joined rooms.
+   [\#779](https://github.com/matrix-org/matrix-js-sdk/pull/779)
+
+Changes in [0.13.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.13.0) (2018-11-15)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.12.1...v0.13.0)
+
+BREAKING CHANGE
+----------------
+ * `MatrixClient::login` now sets client `access_token` and `user_id` following successful login with username and password.
+
+Changes in [0.12.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.12.1) (2018-10-29)
+==================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.12.1-rc.1...v0.12.1)
+
+ * No changes since rc.1
+
+Changes in [0.12.1-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.12.1-rc.1) (2018-10-24)
+============================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.12.0...v0.12.1-rc.1)
+
+ * Add repository type to package.json to make it valid
+   [\#762](https://github.com/matrix-org/matrix-js-sdk/pull/762)
+ * Add getMediaConfig()
+   [\#761](https://github.com/matrix-org/matrix-js-sdk/pull/761)
+ * add new examples, to be expanded into a post
+   [\#739](https://github.com/matrix-org/matrix-js-sdk/pull/739)
+
 Changes in [0.12.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v0.12.0) (2018-10-16)
 ==================================================================================================
 [Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v0.12.0-rc.1...v0.12.0)
@@ -113,3 +113,8 @@ include the line in your commit or pull request comment::
 can't be accepted. Git makes this trivial - just use the -s flag when you do
 ``git commit``, having first set ``user.name`` and ``user.email`` git configs
 (which you should have done anyway :)
+
+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
@@ -21,7 +21,11 @@ Please check [the working browser example](examples/browser) for more informatio
 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");
@@ -30,9 +34,61 @@ In Node.js
    console.log("Public Rooms: %s", JSON.stringify(data));
  });
 ```
+
 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 `MatrixInMemoryStore` 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?
 ----------------------
@@ -231,7 +287,7 @@ This SDK uses JSDoc3 style comments. You can manually build and
 host the API reference from the source files like this:

 ```
-  $ npm run gendoc
+  $ yarn gendoc
  $ cd .jsdoc
  $ python -m SimpleHTTPServer 8005
 ```
@@ -267,15 +323,15 @@ To provide the Olm library in a browser application:
 
 To provide the Olm library in a node.js application:

- * ``npm install https://matrix.org/packages/npm/olm/olm-2.2.2.tgz``
+ * ``yarn add https://matrix.org/packages/npm/olm/olm-3.0.0.tgz``
   (replace the URL with the latest version you want to use from
    https://matrix.org/packages/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 ``npm install https://matrix.org/packages/npm/olm/olm-2.2.2.tgz 
--save-optional`` (if your application also works without e2e crypto enabled)
-or ``--save`` (if it doesn't) to do so.
+If you want to package Olm as dependency for your node.js application, you can
+use ``yarn add https://matrix.org/packages/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
@@ -285,7 +341,7 @@ want to use this SDK, skip this section.*

 First, you need to pull in the right build tools:
 ```
- $ npm install
+ $ yarn install
 ```

 Building
@@ -293,20 +349,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 linting:
 ```
- $ npm run lint
+ $ yarn lint
 ```
@@ -1,5 +1,17 @@
 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.
@@ -21,4 +21,4 @@ export PATH="$rootdir/node_modules/.bin:$PATH"

 # now run our checks
 cd "$tmpdir"
-npm run lint
+yarn lint
@@ -5,8 +5,8 @@ set -x
 export NVM_DIR="$HOME/.nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

-nvm use 6 || exit $?
-npm install || exit $?
+nvm use 10 || exit $?
+yarn install || exit $?

 RC=0

@@ -18,17 +18,19 @@ function fail {
 # don't use last time's test reports
 rm -rf reports coverage || exit $?

-npm test || fail "npm test finished with return code $?"
+yarn test || fail "yarn test finished with return code $?"

-npm run -s lint -- -f checkstyle > eslint.xml ||
+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

-npm pack ||
-    fail "npm pack finished with return code $?"
+# `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 $?"

-npm run gendoc || fail "JSDoc failed with code $?"
+yarn gendoc || fail "JSDoc failed with code $?"

 exit $RC
@@ -1,26 +1,27 @@
 {
  "name": "matrix-js-sdk",
-  "version": "0.12.0",
+  "version": "1.0.2",
  "description": "Matrix Client-Server SDK for Javascript",
  "main": "index.js",
  "scripts": {
    "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": "npm run test:build && npm run test:run",
-    "check": "npm run test:build && _mocha --recursive specbuild --colors",
+    "test": "yarn test:build && yarn test:run",
+    "check": "yarn test:build && _mocha --recursive specbuild --colors",
    "gendoc": "babel --no-babelrc -d .jsdocbuild src && jsdoc -r .jsdocbuild -P package.json -R README.md -d .jsdoc",
-    "start": "npm run start:init && npm run start:watch",
+    "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 && uglifyjs -c -m -o dist/browser-matrix.min.js --source-map dist/browser-matrix.min.js.map --in-source-map dist/browser-matrix.js.map dist/browser-matrix.js",
-    "dist": "npm run build",
+    "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 102 src spec",
-    "prepublish": "npm run clean && npm run build && git rev-parse HEAD > git-revision.txt"
+    "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": [
@@ -53,34 +54,40 @@
  "dependencies": {
    "another-json": "^0.2.0",
    "babel-runtime": "^6.26.0",
+    "base-x": "3.0.4",
    "bluebird": "^3.5.0",
    "browser-request": "^0.3.3",
+    "bs58": "^4.0.1",
    "content-type": "^1.0.2",
-    "request": "^2.53.0"
+    "loglevel": "1.6.1",
+    "qs": "^6.5.2",
+    "request": "^2.88.0",
+    "unhomoglyph": "^1.0.2"
  },
  "devDependencies": {
    "babel-cli": "^6.18.0",
-    "babel-eslint": "^7.1.1",
+    "babel-eslint": "^10.0.1",
    "babel-plugin-transform-async-to-bluebird": "^1.1.1",
    "babel-plugin-transform-runtime": "^6.23.0",
    "babel-preset-es2015": "^6.18.0",
-    "browserify": "^14.0.0",
+    "browserify": "^16.2.3",
    "browserify-shim": "^3.8.13",
-    "eslint": "^3.13.1",
+    "eslint": "^5.12.0",
    "eslint-config-google": "^0.7.1",
    "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.0",
+    "matrix-mock-request": "^1.2.2",
    "mocha": "^5.2.0",
    "mocha-jenkins-reporter": "^0.4.0",
+    "olm": "https://matrix.org/packages/npm/olm/olm-3.1.0-pre1.tgz",
    "rimraf": "^2.5.4",
    "source-map-support": "^0.4.11",
    "sourceify": "^0.1.0",
    "uglify-js": "^2.8.26",
-    "watchify": "^3.2.1"
+    "watchify": "^3.11.1"
  },
  "browserify": {
    "transform": [
@@ -6,12 +6,26 @@
 #   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 (OSX) or source/pre-compiled binaries (debian) (https://github.com/github/hub) - Tested on v2.2.9
+#   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 $$)
-hub --version > /dev/null || (echo "hub 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"

@@ -45,7 +59,8 @@ fi
 skip_changelog=
 skip_jsdoc=
 changelog_file="CHANGELOG.md"
-while getopts hc:xz f; do
+expected_npm_user="matrixdotorg"
+while getopts hc:u:xz f; do
    case $f in
        h)
            help
@@ -60,6 +75,9 @@ while getopts hc:xz f; do
        z)
            skip_jsdoc=1
            ;;
+        u)
+            expected_npm_user="$OPTARG"
+            ;;
    esac
 done
 shift `expr $OPTIND - 1`
@@ -74,6 +92,14 @@ if [ -z "$skip_changelog" ]; then
    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}"
@@ -127,14 +153,22 @@ cat "${changelog_file}" | `dirname $0`/scripts/changelog_head.py > "${latest_cha
 set -x

 # Bump package.json and build the dist
-echo "npm version"
-# npm version will automatically commit its modification
+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.
-npm version --no-git-tag-version "$release"
-git commit package.json -m "$tag"
+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
@@ -150,7 +184,7 @@ fi
 # 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 npm link)
+# (rather than whatever we're pulling in from yarn link)
 assets=''
 dodist=0
 jq -e .scripts.dist package.json 2> /dev/null || dodist=$?
@@ -161,10 +195,10 @@ if [ $dodist -eq 0 ]; then
    pushd "$builddir"
    git clone "$projdir" .
    git checkout "$rel_branch"
-    npm install
+    yarn install
    # We haven't tagged yet, so tell the dist script what version
    # it's building
-    DIST_VERSION="$tag" npm run dist
+    DIST_VERSION="$tag" yarn dist

    popd

@@ -253,12 +287,13 @@ fi
 rm "${release_text}"
 rm "${latest_changes}"

-# publish to npmjs
+# 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"
-    npm run gendoc
+    yarn gendoc

    echo "copying jsdocs to gh-pages branch"
    git checkout gh-pages
@@ -283,7 +318,7 @@ git checkout master
 git pull
 git merge "$rel_branch"

-# push master  and docs (if generated) to github
+# push master and docs (if generated) to github
 git push origin master
 if [ -z "$skip_jsdoc" ]; then
    git push origin gh-pages
@@ -1,7 +1,7 @@
 /*
 Copyright 2016 OpenMarket Ltd
 Copyright 2017 Vector Creations Ltd
-Copyright 2018 New Vector 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.
@@ -38,9 +38,10 @@ import LocalStorageCryptoStore from '../lib/crypto/store/localStorage-crypto-sto
 *
 * @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,
+    userId, deviceId, accessToken, sessionStoreBackend, options,
 ) {
    this.userId = userId;
    this.deviceId = deviceId;
@@ -50,19 +51,22 @@ export default function TestClient(
    }
    const sessionStore = new sdk.WebStorageSessionStore(sessionStoreBackend);

-    // expose this so the tests can get to it
-    this.cryptoStore = new LocalStorageCryptoStore(sessionStoreBackend);
-
    this.httpBackend = new MockHttpBackend();
-    this.client = sdk.createClient({
+
+    options = Object.assign({
        baseUrl: "http://" + userId + ".test.server",
        userId: userId,
        accessToken: accessToken,
        deviceId: deviceId,
        sessionStore: sessionStore,
-        cryptoStore: this.cryptoStore,
        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 = {};
@@ -102,9 +106,11 @@ TestClient.prototype.start = function() {

 /**
 * 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();
 };

 /**
@@ -179,7 +185,11 @@ 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({});
+                expect(content.device_keys[userId]).toEqual(
+                    {},
+                    "Expected key query for " + userId + ", got " +
+                    Object.keys(content.device_keys),
+                );
            });
            return response;
        });
@@ -97,10 +97,11 @@ describe("DeviceList management:", function() {
    });

    afterEach(function() {
-        aliceTestClient.stop();
+        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);
@@ -143,6 +144,7 @@ describe("DeviceList management:", function() {
    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']));
@@ -72,7 +72,11 @@ function expectAliQueryKeys() {
    bobKeys[bobDeviceId] = bobTestClient.deviceKeys;
    aliTestClient.httpBackend.when("POST", "/keys/query")
            .respond(200, function(path, content) {
-        expect(content.device_keys[bobUserId]).toEqual({});
+        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};
@@ -96,7 +100,11 @@ function expectBobQueryKeys() {
    bobTestClient.httpBackend.when(
        "POST", "/keys/query",
    ).respond(200, function(path, content) {
-        expect(content.device_keys[aliUserId]).toEqual({});
+        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};
@@ -410,10 +418,10 @@ describe("MatrixClient crypto", function() {
    });

    afterEach(function() {
-        aliTestClient.stop();
        aliTestClient.httpBackend.verifyNoOutstandingExpectation();
-        bobTestClient.stop();
        bobTestClient.httpBackend.verifyNoOutstandingExpectation();
+
+        return Promise.all([aliTestClient.stop(), bobTestClient.stop()]);
    });

    it("Bob uploads device keys", function() {
@@ -544,6 +552,7 @@ describe("MatrixClient crypto", function() {
    });

    it("Ali sends a message", function(done) {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
        Promise.resolve()
            .then(() => aliTestClient.start())
            .then(() => bobTestClient.start())
@@ -554,6 +563,7 @@ describe("MatrixClient crypto", function() {
    });

    it("Bob receives a message", function() {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
        return Promise.resolve()
            .then(() => aliTestClient.start())
            .then(() => bobTestClient.start())
@@ -564,6 +574,7 @@ describe("MatrixClient crypto", function() {
    });

    it("Bob receives a message with a bogus sender", function() {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
        return Promise.resolve()
            .then(() => aliTestClient.start())
            .then(() => bobTestClient.start())
@@ -617,6 +628,7 @@ describe("MatrixClient crypto", function() {
    });

    it("Ali blocks Bob's device", function(done) {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
        Promise.resolve()
            .then(() => aliTestClient.start())
            .then(() => bobTestClient.start())
@@ -636,6 +648,7 @@ describe("MatrixClient crypto", function() {
    });

    it("Bob receives two pre-key messages", function(done) {
+        aliTestClient.expectKeyQuery({device_keys: {[aliUserId]: {}}});
        Promise.resolve()
            .then(() => aliTestClient.start())
            .then(() => bobTestClient.start())
@@ -649,6 +662,8 @@ describe("MatrixClient crypto", function() {
    });

    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())
@@ -659,13 +674,14 @@ describe("MatrixClient crypto", function() {
            .then(bobRecvMessage)
            .then(bobEnablesEncryption)
            .then(bobSendsReplyMessage).then(function(ciphertext) {
-                expect(ciphertext.type).toEqual(1);
+                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))
@@ -696,7 +712,6 @@ describe("MatrixClient crypto", function() {
            }).then(() => {
                aliTestClient.expectKeyQuery({
                    device_keys: {
-                        [aliUserId]: {},
                        [bobUserId]: {},
                    },
                });
@@ -30,6 +30,7 @@ describe("MatrixClient events", function() {
    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
        client.stopClient();
+        return httpBackend.stop();
    });

    describe("emissions", function() {
@@ -111,6 +111,7 @@ describe("getEventTimeline support", function() {
        if (client) {
            client.stopClient();
        }
+        return httpBackend.stop();
    });

    it("timeline support must be enabled to work", function(done) {
@@ -41,6 +41,7 @@ describe("MatrixClient", function() {

    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
+        return httpBackend.stop();
    });

    describe("uploadContent", function() {
@@ -64,6 +64,7 @@ describe("MatrixClient opts", function() {

    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
+        return httpBackend.stop();
    });

    describe("without opts.store", function() {
@@ -36,6 +36,7 @@ describe("MatrixClient retrying", function() {

    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
+        return httpBackend.stop();
    });

    xit("should retry according to MatrixScheduler.retryFn", function() {
@@ -130,6 +130,7 @@ describe("MatrixClient room timelines", function() {
    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
        client.stopClient();
+        return httpBackend.stop();
    });

    describe("local echo events", function() {
@@ -38,6 +38,7 @@ describe("MatrixClient syncing", function() {
    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
        client.stopClient();
+        return httpBackend.stop();
    });

    describe("startClient", function() {
@@ -296,7 +296,7 @@ describe("megolm", function() {
    });

    afterEach(function() {
-        aliceTestClient.stop();
+        return aliceTestClient.stop();
    });

    it("Alice receives a megolm message", function() {
@@ -499,6 +499,7 @@ describe("megolm", function() {
    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);
@@ -581,6 +582,7 @@ describe("megolm", function() {
    });

    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);
@@ -634,6 +636,7 @@ describe("megolm", 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);
@@ -817,8 +820,14 @@ describe("megolm", function() {
                };
            });

+            // 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.sendTextMessage(ROOM_ID, 'test'),
+                aliceTestClient.client.resendEvent(unsentEvent, room),

                // the crypto stuff can take a while, so give the requests a whole second.
                aliceTestClient.httpBackend.flushAllExpected({
@@ -837,6 +846,7 @@ describe("megolm", 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);
@@ -880,6 +890,7 @@ describe("megolm", function() {
    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);
@@ -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 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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: "Invalid homeserver discovery response",
+                        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: 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: "Invalid homeserver discovery response",
+                        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: 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: "Invalid homeserver discovery response",
+                        base_url: null,
+                    },
+                    "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: "Invalid identity server discovery response",
+
+                        // 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: "Invalid identity server discovery response",
+                        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: "Invalid identity server discovery response",
+
+                        // 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: "Invalid identity server discovery response",
+                        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: "Invalid identity server discovery response",
+
+                        // 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: "Invalid identity server discovery response",
+                        base_url: null,
+                    },
+                };
+
+                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: "Invalid identity server discovery response",
+
+                        // 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: "Invalid identity server discovery response",
+                        base_url: null,
+                    },
+                };
+
+                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);
+            }),
+        ]);
+    });
+});
@@ -1,20 +1,366 @@
-
-"use strict";
 import 'source-map-support/register';

-const sdk = require("../..");
-let Crypto;
-if (sdk.CRYPTO_ENABLED) {
-    Crypto = require("../../lib/crypto");
-}
+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(2);
+        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();
+            }
+        });
    });
 });
@@ -59,16 +59,25 @@ describe('DeviceList', function() {
    let downloadSpy;
    let sessionStore;
    let cryptoStore;
+    let deviceLists = [];

    beforeEach(function() {
        testUtils.beforeEach(this); // eslint-disable-line no-invalid-this

+        deviceLists = [];
+
        downloadSpy = expect.createSpy();
        const mockStorage = new MockStorageApi();
        sessionStore = new WebStorageSessionStore(mockStorage);
        cryptoStore = new MemoryCryptoStore();
    });

+    afterEach(function() {
+        for (const dl of deviceLists) {
+            dl.stop();
+        }
+    });
+
    function createTestDeviceList() {
        const baseApis = {
            downloadKeysForUsers: downloadSpy,
@@ -76,7 +85,9 @@ describe('DeviceList', function() {
        const mockOlm = {
            verifySignature: function(key, message, signature) {},
        };
-        return new DeviceList(baseApis, cryptoStore, sessionStore, mockOlm);
+        const dl = new DeviceList(baseApis, cryptoStore, sessionStore, mockOlm);
+        deviceLists.push(dl);
+        return dl;
    }

    it("should successfully download and store device keys", function() {
@@ -1,8 +1,4 @@
-try {
-    global.Olm = require('olm');
-} catch (e) {
-    console.warn("unable to run megolm tests: libolm not available");
-}
+import '../../../olm-loader';

 import expect from 'expect';
 import Promise from 'bluebird';
@@ -13,20 +9,17 @@ 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';
-
-// Crypto and OlmDevice won't import unless we have global.Olm
-let OlmDevice;
-let Crypto;
-if (global.Olm) {
-    OlmDevice = require('../../../../lib/crypto/OlmDevice');
-    Crypto = require('../../../../lib/crypto');
-}
+import OlmDevice from '../../../../lib/crypto/OlmDevice';
+import Crypto from '../../../../lib/crypto';

 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) {
        console.warn('Not running megolm unit tests: libolm not present');
@@ -38,9 +31,11 @@ describe("MegolmDecryption", function() {
    let mockCrypto;
    let mockBaseApis;

-    beforeEach(function() {
+    beforeEach(async function() {
        testUtils.beforeEach(this); // eslint-disable-line no-invalid-this

+        await Olm.init();
+
        mockCrypto = testUtils.mock(Crypto, 'Crypto');
        mockBaseApis = {};

@@ -69,7 +64,7 @@ describe("MegolmDecryption", function() {

    describe('receives some keys:', function() {
        let groupSession;
-        beforeEach(function() {
+        beforeEach(async function() {
            groupSession = new global.Olm.OutboundGroupSession();
            groupSession.create();

@@ -98,7 +93,7 @@ describe("MegolmDecryption", function() {
                },
            };

-            return event.attemptDecryption(mockCrypto).then(() => {
+            await event.attemptDecryption(mockCrypto).then(() => {
                megolmDecryption.onRoomKeyEvent(event);
            });
        });
@@ -266,5 +261,92 @@ describe("MegolmDecryption", function() {
                // test is successful if no exception is thrown
            });
        });
+
+        it("re-uses sessions for sequential messages", async function() {
+            const mockStorage = new MockStorageApi();
+            const sessionStore = new WebStorageSessionStore(mockStorage);
+            const cryptoStore = new MemoryCryptoStore(mockStorage);
+
+            const olmDevice = new OlmDevice(sessionStore, 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);
+        });
    });
 });
@@ -0,0 +1,86 @@
+/*
+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 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';
+
+function makeOlmDevice() {
+    const mockStorage = new MockStorageApi();
+    const sessionStore = new WebStorageSessionStore(mockStorage);
+    const cryptoStore = new MemoryCryptoStore(mockStorage);
+    const olmDevice = new OlmDevice(sessionStore, 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) {
+        console.warn('Not running megolm unit tests: libolm not present');
+        return;
+    }
+
+    let aliceOlmDevice;
+    let bobOlmDevice;
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line 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",
+            );
+        });
+    });
+});
@@ -0,0 +1,471 @@
+/*
+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';
+
+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) {
+        console.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 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(sessionStore, 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');
+            });
+        });
+    });
+});
@@ -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.
+*/
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    console.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) {
+        console.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();
+        });
+    });
+});
@@ -0,0 +1,75 @@
+/*
+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.
+*/
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    console.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) {
+        console.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();
+        });
+        const aliceVerifier = await alice.requestVerification("@bob:example.com");
+        expect(aliceVerifier).toBeAn(SAS);
+    });
+});
@@ -0,0 +1,207 @@
+/*
+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.
+*/
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    console.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) {
+        console.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();
+    });
+
+    it("should verify a key", 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.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();
+        };
+
+        let aliceSasEvent;
+        let bobSasEvent;
+
+        const 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);
+            });
+        });
+
+        const 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();
+                }
+            }
+        });
+        await Promise.all([
+            aliceVerifier.verify(),
+            bobPromise.then((verifier) => verifier.verify()),
+        ]);
+        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();
+    });
+});
@@ -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 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;
+}
@@ -285,5 +285,52 @@ describe("RoomMember", function() {
            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);
+        });
    });
 });
@@ -0,0 +1,389 @@
+/*
+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';
+const logger = require("./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.
+
+    /**
+     * 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"; }
+
+    /**
+     * 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: "Invalid homeserver discovery response",
+                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"
+            || !wellknown.raw["m.homeserver"]
+            || !wellknown.raw["m.homeserver"]["base_url"]) {
+            logger.error("No m.homeserver key in well-known response");
+            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;
+            }
+            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.raw["m.homeserver"]["base_url"],
+        );
+        if (!hsUrl) {
+            logger.error("Invalid base_url for m.homeserver");
+            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");
+            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.raw["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: "Invalid identity server discovery response",
+
+                    // 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: "Invalid identity server discovery response",
+                    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.raw["m.identity_server"]["base_url"],
+            );
+            if (!isUrl) {
+                logger.error("Invalid base_url for m.identity_server");
+                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");
+                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.raw)
+            .filter((k) => k !== "m.homeserver" && k !== "m.identity_server")
+            .map((k) => clientConfig[k] = wellknown.raw[k]);
+
+        // Step 8: Give the config to the caller (finally)
+        return Promise.resolve(clientConfig);
+    }
+
+    /**
+     * 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 },
+                (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 = "No .well-known JSON file found";
+                        }
+                        resolve({raw: {}, action: action, reason: reason, error: err});
+                        return;
+                    }
+
+                    try {
+                        resolve({raw: JSON.parse(body), action: "SUCCESS"});
+                    } catch (e) {
+                        let reason = "General failure";
+                        if (e.name === "SyntaxError") reason = "Invalid JSON";
+                        resolve({
+                            raw: {},
+                            action: "FAIL_PROMPT",
+                            reason: reason, error: e,
+                        });
+                    }
+                },
+            );
+        });
+    }
+}
@@ -262,7 +262,19 @@ MatrixBaseApis.prototype.login = function(loginType, data, callback) {
    utils.extend(login_data, data);

    return this._http.authedRequest(
-        callback, "POST", "/login", undefined, login_data,
+        (error, response) => {
+            if (loginType === "m.login.password" && response &&
+                response.access_token && response.user_id) {
+                this._http.opts.accessToken = response.access_token;
+                this.credentials = {
+                    userId: response.user_id,
+                };
+            }
+
+            if (callback) {
+                callback(error, response);
+            }
+        }, "POST", "/login", undefined, login_data,
    );
 };

@@ -298,9 +310,23 @@ MatrixBaseApis.prototype.loginWithSAML2 = function(relayState, callback) {
 * @return {string} The HS URL to hit to begin the CAS login process.
 */
 MatrixBaseApis.prototype.getCasLoginUrl = function(redirectUrl) {
-    return this._http.getUrl("/login/cas/redirect", {
+    return this.getSsoLoginUrl(redirectUrl, "cas");
+};
+
+/**
+ * @param {string} redirectUrl The URL to redirect to after the HS
+ *     authenticates with the SSO.
+ * @param {string} loginType The type of SSO login we are doing (sso or cas).
+ *     Defaults to 'sso'.
+ * @return {string} The HS URL to hit to begin the SSO login process.
+ */
+MatrixBaseApis.prototype.getSsoLoginUrl = function(redirectUrl, loginType) {
+    if (loginType === undefined) {
+        loginType = "sso";
+    }
+    return this._http.getUrl("/login/"+loginType+"/redirect", {
        "redirectUrl": redirectUrl,
-    }, httpApi.PREFIX_UNSTABLE);
+    }, httpApi.PREFIX_R0);
 };

 /**
@@ -927,6 +953,28 @@ MatrixBaseApis.prototype.setRoomReadMarkersHttpRequest =
    );
 };

+/**
+ * @return {module:client.Promise} Resolves: A list of the user's current rooms
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixBaseApis.prototype.getJoinedRooms = function() {
+    const path = utils.encodeUri("/joined_rooms");
+    return this._http.authedRequest(undefined, "GET", path);
+};
+
+/**
+ * Retrieve membership info. for a room.
+ * @param {string} roomId ID of the room to get membership for
+ * @return {module:client.Promise} Resolves: A list of currently joined users
+ *                                 and their profile data.
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixBaseApis.prototype.getJoinedRoomMembers = function(roomId) {
+    const path = utils.encodeUri("/rooms/$roomId/joined_members", {
+        $roomId: roomId,
+    });
+    return this._http.authedRequest(undefined, "GET", path);
+};

 // Room Directory operations
 // =========================
@@ -1785,7 +1833,7 @@ MatrixBaseApis.prototype.getThirdpartyProtocols = function() {
 * Get information on how a specific place on a third party protocol
 * may be reached.
 * @param {string} protocol The protocol given in getThirdpartyProtocols()
- * @param {object} params Protocol-specific parameters, as given in th
+ * @param {object} params Protocol-specific parameters, as given in the
 *                        response to getThirdpartyProtocols()
 * @return {module:client.Promise} Resolves to the result object
 */
@@ -1800,6 +1848,25 @@ MatrixBaseApis.prototype.getThirdpartyLocation = function(protocol, params) {
    );
 };

+/**
+ * Get information on how a specific user on a third party protocol
+ * may be reached.
+ * @param {string} protocol The protocol given in getThirdpartyProtocols()
+ * @param {object} params Protocol-specific parameters, as given in the
+ *                        response to getThirdpartyProtocols()
+ * @return {module:client.Promise} Resolves to the result object
+ */
+MatrixBaseApis.prototype.getThirdpartyUser = function(protocol, params) {
+    const path = utils.encodeUri("/thirdparty/user/$protocol", {
+        $protocol: protocol,
+    });
+
+    return this._http.authedRequestWithPrefix(
+        undefined, "GET", path, params, undefined,
+        httpApi.PREFIX_UNSTABLE,
+    );
+};
+
 /**
 * MatrixBaseApis object
 */
@@ -1,7 +1,7 @@
 /*
 Copyright 2015, 2016 OpenMarket Ltd
 Copyright 2017 Vector Creations Ltd
-Copyright 2018 New Vector 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.
@@ -41,23 +41,47 @@ const SyncApi = require("./sync");
 const MatrixBaseApis = require("./base-apis");
 const MatrixError = httpApi.MatrixError;
 const ContentHelpers = require("./content-helpers");
+const olmlib = require("./crypto/olmlib");

 import ReEmitter from './ReEmitter';
 import RoomList from './crypto/RoomList';

+import Crypto from './crypto';
+import { isCryptoAvailable } from './crypto';
+import { encodeRecoveryKey, decodeRecoveryKey } from './crypto/recoverykey';
+import { keyForNewBackup, keyForExistingBackup } from './crypto/backup_password';
+import { randomString } from './randomstring';
+
 // Disable warnings for now: we use deprecated bluebird functions
 // and need to migrate, but they spam the console with warnings.
 Promise.config({warnings: false});


 const SCROLLBACK_DELAY_MS = 3000;
-let CRYPTO_ENABLED = false;
+const CRYPTO_ENABLED = isCryptoAvailable();
+const CAPABILITIES_CACHE_MS = 21600000; // 6 hours - an arbitrary value

-try {
-    var Crypto = require("./crypto");
-    CRYPTO_ENABLED = true;
-} catch (e) {
-    console.warn("Unable to load crypto module: crypto will be disabled: " + e);
+function keysFromRecoverySession(sessions, decryptionKey, roomId) {
+    const keys = [];
+    for (const [sessionId, sessionData] of Object.entries(sessions)) {
+        try {
+            const decrypted = keyFromRecoverySession(sessionData, decryptionKey);
+            decrypted.session_id = sessionId;
+            decrypted.room_id = roomId;
+            keys.push(decrypted);
+        } catch (e) {
+            console.log("Failed to decrypt session from backup");
+        }
+    }
+    return keys;
+}
+
+function keyFromRecoverySession(session, decryptionKey) {
+    return JSON.parse(decryptionKey.decrypt(
+        session.session_data.ephemeral,
+        session.session_data.mac,
+        session.session_data.ciphertext,
+    ));
 }

 /**
@@ -119,6 +143,11 @@ try {
 *
 * @param {module:crypto.store.base~CryptoStore} opts.cryptoStore
 *    crypto store implementation.
+ *
+ * @param {Array} [opts.verificationMethods] Optional. The verification method
+ * that the application can handle.  Each element should be an item from {@link
+ * module:crypto~verificationMethods verificationMethods}, or a class that
+ * implements the {$link module:crypto/verification/Base verifier interface}.
 */
 function MatrixClient(opts) {
    // Allow trailing slash in HS url
@@ -133,6 +162,8 @@ function MatrixClient(opts) {

    MatrixBaseApis.call(this, opts);

+    this.olmVersion = null; // Populated after initCrypto is done
+
    this.reEmitter = new ReEmitter(this);

    this.store = opts.store || new StubStore();
@@ -182,13 +213,10 @@ function MatrixClient(opts) {
    this._crypto = null;
    this._cryptoStore = opts.cryptoStore;
    this._sessionStore = opts.sessionStore;
+    this._verificationMethods = opts.verificationMethods;

    this._forceTURN = opts.forceTURN || false;

-    if (CRYPTO_ENABLED) {
-        this.olmVersion = Crypto.getOlmVersion();
-    }
-
    // List of which rooms have encryption enabled: separate from crypto because
    // we still want to know which rooms are encrypted even if crypto is disabled:
    // we don't want to start sending unencrypted events to them.
@@ -198,6 +226,34 @@ function MatrixClient(opts) {
    this._pushProcessor = new PushProcessor(this);

    this._serverSupportsLazyLoading = null;
+
+    this._cachedCapabilities = null; // { capabilities: {}, lastUpdated: timestamp }
+
+    // The SDK doesn't really provide a clean way for events to recalculate the push
+    // actions for themselves, so we have to kinda help them out when they are encrypted.
+    // We do this so that push rules are correctly executed on events in their decrypted
+    // state, such as highlights when the user's name is mentioned.
+    this.on("Event.decrypted", (event) => {
+        const oldActions = event.getPushActions();
+        const actions = this._pushProcessor.actionsForEvent(event);
+        event.setPushActions(actions); // Might as well while we're here
+
+        // Ensure the unread counts are kept up to date if the event is encrypted
+        const oldHighlight = oldActions && oldActions.tweaks
+            ? !!oldActions.tweaks.highlight : false;
+        const newHighlight = actions && actions.tweaks
+            ? !!actions.tweaks.highlight : false;
+        if (oldHighlight !== newHighlight) {
+            const room = this.getRoom(event.getRoomId());
+            // TODO: Handle mentions received while the client is offline
+            // See also https://github.com/vector-im/riot-web/issues/9069
+            if (room && !room.hasUserReadEvent(this.getUserId(), event.getId())) {
+                const current = room.getUnreadNotificationCount("highlight");
+                const newCount = newHighlight ? current + 1 : current - 1;
+                room.setUnreadNotificationCount("highlight", newCount);
+            }
+        }
+    });
 }
 utils.inherits(MatrixClient, EventEmitter);
 utils.extend(MatrixClient.prototype, MatrixBaseApis.prototype);
@@ -365,6 +421,34 @@ MatrixClient.prototype.setNotifTimelineSet = function(notifTimelineSet) {
    this._notifTimelineSet = notifTimelineSet;
 };

+/**
+ * Gets the capabilities of the homeserver. Always returns an object of
+ * capability keys and their options, which may be empty.
+ * @return {module:client.Promise} Resolves to the capabilities of the homeserver
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype.getCapabilities = function() {
+    if (this._cachedCapabilities) {
+        const now = new Date().getTime();
+        if (now - this._cachedCapabilities.lastUpdated <= CAPABILITIES_CACHE_MS) {
+            return Promise.resolve(this._cachedCapabilities.capabilities);
+        }
+    }
+
+    // We swallow errors because we need a default object anyhow
+    return this._http.authedRequest(
+        undefined, "GET", "/capabilities",
+    ).catch(() => null).then((r) => {
+        if (!r) r = {};
+        const capabilities = r["capabilities"] || {};
+        this._cachedCapabilities = {
+            capabilities: capabilities,
+            lastUpdated: new Date().getTime(),
+        };
+        return capabilities;
+    });
+};
+
 // Crypto bits
 // ===========

@@ -378,6 +462,13 @@ MatrixClient.prototype.setNotifTimelineSet = function(notifTimelineSet) {
 * successfully initialised.
 */
 MatrixClient.prototype.initCrypto = async function() {
+    if (!isCryptoAvailable()) {
+        throw new Error(
+            `End-to-end encryption not supported in this js-sdk build: did ` +
+                `you remember to load the olm library?`,
+        );
+    }
+
    if (this._crypto) {
        console.warn("Attempt to re-initialise e2e encryption on MatrixClient");
        return;
@@ -395,13 +486,6 @@ MatrixClient.prototype.initCrypto = async function() {
    // initialise the list of encrypted rooms (whether or not crypto is enabled)
    await this._roomList.init();

-    if (!CRYPTO_ENABLED) {
-        throw new Error(
-            `End-to-end encryption not supported in this js-sdk build: did ` +
-                `you remember to load the olm library?`,
-        );
-    }
-
    const userId = this.getUserId();
    if (userId === null) {
        throw new Error(
@@ -423,9 +507,12 @@ MatrixClient.prototype.initCrypto = async function() {
        this.store,
        this._cryptoStore,
        this._roomList,
+        this._verificationMethods,
    );

    this.reEmitter.reEmit(crypto, [
+        "crypto.keyBackupFailed",
+        "crypto.keyBackupSessionsRemaining",
        "crypto.roomKeyRequest",
        "crypto.roomKeyRequestCancellation",
        "crypto.warning",
@@ -433,6 +520,9 @@ MatrixClient.prototype.initCrypto = async function() {

    await crypto.init();

+    this.olmVersion = Crypto.getOlmVersion();
+
+
    // if crypto initialisation was successful, tell it to attach its event
    // handlers.
    crypto.registerEventHandlers(this);
@@ -536,7 +626,15 @@ MatrixClient.prototype.setDeviceVerified = function(userId, deviceId, verified)
    if (verified === undefined) {
        verified = true;
    }
-    return _setDeviceVerification(this, userId, deviceId, verified, null);
+    const prom = _setDeviceVerification(this, userId, deviceId, verified, null);
+
+    // if one of the user's own devices is being marked as verified / unverified,
+    // check the key backup status, since whether or not we use this depends on
+    // whether it has a signature from a verified device
+    if (userId == this.credentials.userId) {
+        this._crypto.checkKeyBackup();
+    }
+    return prom;
 };

 /**
@@ -591,6 +689,43 @@ async function _setDeviceVerification(
    client.emit("deviceVerificationChanged", userId, deviceId, dev);
 }

+/**
+ * Request a key verification from another user.
+ *
+ * @param {string} userId the user to request verification with
+ * @param {Array} devices array of device IDs to send requests to.  Defaults to
+ *    all devices owned by the user
+ * @param {Array} methods array of verification methods to use.  Defaults to
+ *    all known methods
+ *
+ * @returns {Promise<module:crypto/verification/Base>} resolves to a verifier
+ *    when the request is accepted by the other user
+ */
+MatrixClient.prototype.requestVerification = function(userId, devices, methods) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+    return this._crypto.requestVerification(userId, devices);
+};
+
+/**
+ * Begin a key verification.
+ *
+ * @param {string} method the verification method to use
+ * @param {string} userId the user to verify keys with
+ * @param {string} deviceId the device to verify
+ *
+ * @returns {module:crypto/verification/Base} a verification object
+ */
+MatrixClient.prototype.beginKeyVerification = function(
+    method, userId, deviceId,
+) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+    return this._crypto.beginKeyVerification(method, userId, deviceId);
+};
+
 /**
 * Set the global override for whether the client should ever send encrypted
 * messages to unverified devices.  This provides the default for rooms which
@@ -651,9 +786,10 @@ MatrixClient.prototype.isEventSenderVerified = async function(event) {
 * request.
 * @param  {MatrixEvent} event event of which to cancel and resend the room
 *                            key request.
+ * @return {Promise} A promise that will resolve when the key request is queued
 */
 MatrixClient.prototype.cancelAndResendEventRoomKeyRequest = function(event) {
-    event.cancelAndResendKeyRequest(this._crypto);
+    return event.cancelAndResendKeyRequest(this._crypto, this.getUserId());
 };

 /**
@@ -740,6 +876,366 @@ MatrixClient.prototype.importRoomKeys = function(keys) {
    return this._crypto.importRoomKeys(keys);
 };

+/**
+ * Force a re-check of the local key backup status against
+ * what's on the server.
+ *
+ * @returns {Object} Object with backup info (as returned by
+ *     getKeyBackupVersion) in backupInfo and
+ *     trust information (as returned by isKeyBackupTrusted)
+ *     in trustInfo.
+ */
+MatrixClient.prototype.checkKeyBackup = function() {
+    return this._crypto.checkKeyBackup();
+};
+
+/**
+ * Get information about the current key backup.
+ * @returns {Promise} Information object from API or null
+ */
+MatrixClient.prototype.getKeyBackupVersion = function() {
+    return this._http.authedRequest(
+        undefined, "GET", "/room_keys/version",
+    ).then((res) => {
+        if (res.algorithm !== olmlib.MEGOLM_BACKUP_ALGORITHM) {
+            const err = "Unknown backup algorithm: " + res.algorithm;
+            return Promise.reject(err);
+        } else if (!(typeof res.auth_data === "object")
+                   || !res.auth_data.public_key) {
+            const err = "Invalid backup data returned";
+            return Promise.reject(err);
+        } else {
+            return res;
+        }
+    }).catch((e) => {
+        if (e.errcode === 'M_NOT_FOUND') {
+            return null;
+        } else {
+            throw e;
+        }
+    });
+};
+
+/**
+ * @param {object} info key backup info dict from getKeyBackupVersion()
+ * @return {object} {
+ *     usable: [bool], // is the backup trusted, true iff there is a sig that is valid & from a trusted device
+ *     sigs: [
+ *         valid: [bool],
+ *         device: [DeviceInfo],
+ *     ]
+ * }
+ */
+MatrixClient.prototype.isKeyBackupTrusted = function(info) {
+    return this._crypto.isKeyBackupTrusted(info);
+};
+
+/**
+ * @returns {bool} true if the client is configured to back up keys to
+ *     the server, otherwise false.
+ */
+MatrixClient.prototype.getKeyBackupEnabled = function() {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+    return Boolean(this._crypto.backupKey);
+};
+
+/**
+ * Enable backing up of keys, using data previously returned from
+ * getKeyBackupVersion.
+ *
+ * @param {object} info Backup information object as returned by getKeyBackupVersion
+ */
+MatrixClient.prototype.enableKeyBackup = function(info) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    this._crypto.backupInfo = info;
+    if (this._crypto.backupKey) this._crypto.backupKey.free();
+    this._crypto.backupKey = new global.Olm.PkEncryption();
+    this._crypto.backupKey.set_recipient_key(info.auth_data.public_key);
+
+    this.emit('crypto.keyBackupStatus', true);
+
+    // There may be keys left over from a partially completed backup, so
+    // schedule a send to check.
+    this._crypto.scheduleKeyBackupSend();
+};
+
+/**
+ * Disable backing up of keys.
+ */
+MatrixClient.prototype.disableKeyBackup = function() {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    this._crypto.backupInfo = null;
+    if (this._crypto.backupKey) this._crypto.backupKey.free();
+    this._crypto.backupKey = null;
+
+    this.emit('crypto.keyBackupStatus', false);
+};
+
+/**
+ * Set up the data required to create a new backup version.  The backup version
+ * will not be created and enabled until createKeyBackupVersion is called.
+ *
+ * @param {string} password Passphrase string that can be entered by the user
+ *     when restoring the backup as an alternative to entering the recovery key.
+ *     Optional.
+ *
+ * @returns {Promise<object>} Object that can be passed to createKeyBackupVersion and
+ *     additionally has a 'recovery_key' member with the user-facing recovery key string.
+ */
+MatrixClient.prototype.prepareKeyBackupVersion = async function(password) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    const decryption = new global.Olm.PkDecryption();
+    try {
+        let publicKey;
+        const authData = {};
+        if (password) {
+            const keyInfo = await keyForNewBackup(password);
+            publicKey = decryption.init_with_private_key(keyInfo.key);
+            authData.private_key_salt = keyInfo.salt;
+            authData.private_key_iterations = keyInfo.iterations;
+        } else {
+            publicKey = decryption.generate_key();
+        }
+
+        authData.public_key = publicKey;
+
+        return {
+            algorithm: olmlib.MEGOLM_BACKUP_ALGORITHM,
+            auth_data: authData,
+            recovery_key: encodeRecoveryKey(decryption.get_private_key()),
+        };
+    } finally {
+        decryption.free();
+    }
+};
+
+/**
+ * Create a new key backup version and enable it, using the information return
+ * from prepareKeyBackupVersion.
+ *
+ * @param {object} info Info object from prepareKeyBackupVersion
+ * @returns {Promise<object>} Object with 'version' param indicating the version created
+ */
+MatrixClient.prototype.createKeyBackupVersion = function(info) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    const data = {
+        algorithm: info.algorithm,
+        auth_data: info.auth_data,
+    };
+    return this._crypto._signObject(data.auth_data).then(() => {
+        return this._http.authedRequest(
+            undefined, "POST", "/room_keys/version", undefined, data,
+        );
+    }).then((res) => {
+        this.enableKeyBackup({
+            algorithm: info.algorithm,
+            auth_data: info.auth_data,
+            version: res.version,
+        });
+        return res;
+    });
+};
+
+MatrixClient.prototype.deleteKeyBackupVersion = function(version) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    // If we're currently backing up to this backup... stop.
+    // (We start using it automatically in createKeyBackupVersion
+    // so this is symmetrical).
+    if (this._crypto.backupInfo && this._crypto.backupInfo.version === version) {
+        this.disableKeyBackup();
+    }
+
+    const path = utils.encodeUri("/room_keys/version/$version", {
+        $version: version,
+    });
+
+    return this._http.authedRequest(
+        undefined, "DELETE", path, undefined, undefined,
+    );
+};
+
+MatrixClient.prototype._makeKeyBackupPath = function(roomId, sessionId, version) {
+    let path;
+    if (sessionId !== undefined) {
+        path = utils.encodeUri("/room_keys/keys/$roomId/$sessionId", {
+            $roomId: roomId,
+            $sessionId: sessionId,
+        });
+    } else if (roomId !== undefined) {
+        path = utils.encodeUri("/room_keys/keys/$roomId", {
+            $roomId: roomId,
+        });
+    } else {
+        path = "/room_keys/keys";
+    }
+    const queryData = version === undefined ? undefined : { version: version };
+    return {
+        path: path,
+        queryData: queryData,
+    };
+};
+
+/**
+ * Back up session keys to the homeserver.
+ * @param {string} roomId ID of the room that the keys are for Optional.
+ * @param {string} sessionId ID of the session that the keys are for Optional.
+ * @param {integer} version backup version Optional.
+ * @param {object} data Object keys to send
+ * @return {module:client.Promise} a promise that will resolve when the keys
+ * are uploaded
+ */
+MatrixClient.prototype.sendKeyBackup = function(roomId, sessionId, version, data) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    const path = this._makeKeyBackupPath(roomId, sessionId, version);
+    return this._http.authedRequest(
+        undefined, "PUT", path.path, path.queryData, data,
+    );
+};
+
+/**
+ * Marks all group sessions as needing to be backed up and schedules them to
+ * upload in the background as soon as possible.
+ */
+MatrixClient.prototype.scheduleAllGroupSessionsForBackup = async function() {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    await this._crypto.scheduleAllGroupSessionsForBackup();
+};
+
+MatrixClient.prototype.isValidRecoveryKey = function(recoveryKey) {
+    try {
+        decodeRecoveryKey(recoveryKey);
+        return true;
+    } catch (e) {
+        return false;
+    }
+};
+
+MatrixClient.RESTORE_BACKUP_ERROR_BAD_KEY = 'RESTORE_BACKUP_ERROR_BAD_KEY';
+
+MatrixClient.prototype.restoreKeyBackupWithPassword = async function(
+    password, targetRoomId, targetSessionId, backupInfo,
+) {
+    const privKey = await keyForExistingBackup(backupInfo, password);
+    return this._restoreKeyBackup(
+        privKey, targetRoomId, targetSessionId, backupInfo,
+    );
+};
+
+MatrixClient.prototype.restoreKeyBackupWithRecoveryKey = function(
+    recoveryKey, targetRoomId, targetSessionId, backupInfo,
+) {
+    const privKey = decodeRecoveryKey(recoveryKey);
+    return this._restoreKeyBackup(
+        privKey, targetRoomId, targetSessionId, backupInfo,
+    );
+};
+
+MatrixClient.prototype._restoreKeyBackup = function(
+    privKey, targetRoomId, targetSessionId, backupInfo,
+) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+    let totalKeyCount = 0;
+    let keys = [];
+
+    const path = this._makeKeyBackupPath(
+        targetRoomId, targetSessionId, backupInfo.version,
+    );
+
+    const decryption = new global.Olm.PkDecryption();
+    let backupPubKey;
+    try {
+        backupPubKey = decryption.init_with_private_key(privKey);
+    } catch(e) {
+        decryption.free();
+        throw e;
+    }
+
+    // If the pubkey computed from the private data we've been given
+    // doesn't match the one in the auth_data, the user has enetered
+    // a different recovery key / the wrong passphrase.
+    if (backupPubKey !== backupInfo.auth_data.public_key) {
+        return Promise.reject({errcode: MatrixClient.RESTORE_BACKUP_ERROR_BAD_KEY});
+    }
+
+    return this._http.authedRequest(
+        undefined, "GET", path.path, path.queryData,
+    ).then((res) => {
+        if (res.rooms) {
+            for (const [roomId, roomData] of Object.entries(res.rooms)) {
+                if (!roomData.sessions) continue;
+
+                totalKeyCount += Object.keys(roomData.sessions).length;
+                const roomKeys = keysFromRecoverySession(
+                    roomData.sessions, decryption, roomId, roomKeys,
+                );
+                for (const k of roomKeys) {
+                    k.room_id = roomId;
+                    keys.push(k);
+                }
+            }
+        } else if (res.sessions) {
+            totalKeyCount = Object.keys(res.sessions).length;
+            keys = keysFromRecoverySession(
+                res.sessions, decryption, targetRoomId, keys,
+            );
+        } else {
+            totalKeyCount = 1;
+            try {
+                const key = keyFromRecoverySession(res, decryption);
+                key.room_id = targetRoomId;
+                key.session_id = targetSessionId;
+                keys.push(key);
+            } catch (e) {
+                console.log("Failed to decrypt session from backup");
+            }
+        }
+
+        return this.importRoomKeys(keys);
+    }).then(() => {
+        return this._crypto.setTrustedBackupPubKey(backupPubKey);
+    }).then(() => {
+        return {total: totalKeyCount, imported: keys.length};
+    }).finally(() => {
+        decryption.free();
+    });
+};
+
+MatrixClient.prototype.deleteKeysFromBackup = function(roomId, sessionId, version) {
+    if (this._crypto === null) {
+        throw new Error("End-to-end encryption disabled");
+    }
+
+    const path = this._makeKeyBackupPath(roomId, sessionId, version);
+    return this._http.authedRequest(
+        undefined, "DELETE", path.path, path.queryData,
+    );
+};
+
 // Group ops
 // =========
 // Operations on groups that come down the sync stream (ie. ones the
@@ -764,6 +1260,17 @@ MatrixClient.prototype.getGroups = function() {
    return this.store.getGroups();
 };

+/**
+ * Get the config for the media repository.
+ * @param {module:client.callback} callback Optional.
+ * @return {module:client.Promise} Resolves with an object containing the config.
+ */
+MatrixClient.prototype.getMediaConfig = function(callback) {
+    return this._http.authedRequestWithPrefix(
+        callback, "GET", "/config", undefined, undefined, httpApi.PREFIX_MEDIA_R0,
+    );
+};
+
 // Room ops
 // ========

@@ -910,6 +1417,8 @@ MatrixClient.prototype.isUserIgnored = function(userId) {
 * </strong> Default: true.
 * @param {boolean} opts.inviteSignUrl If the caller has a keypair 3pid invite,
 *                                     the signing URL is passed in this parameter.
+ * @param {string[]} opts.viaServers The server names to try and join through in
+ *                                   addition to those that are automatically chosen.
 * @param {module:client.callback} callback Optional.
 * @return {module:client.Promise} Resolves: Room object.
 * @return {module:http-api.MatrixError} Rejects: with an error response.
@@ -938,6 +1447,13 @@ MatrixClient.prototype.joinRoom = function(roomIdOrAlias, opts, callback) {
        );
    }

+    const queryString = {};
+    if (opts.viaServers) {
+        queryString["server_name"] = opts.viaServers;
+    }
+
+    const reqOpts = {qsStringifyOptions: {arrayFormat: 'repeat'}};
+
    const defer = Promise.defer();

    const self = this;
@@ -948,7 +1464,8 @@ MatrixClient.prototype.joinRoom = function(roomIdOrAlias, opts, callback) {
        }

        const path = utils.encodeUri("/join/$roomid", { $roomid: roomIdOrAlias});
-        return self._http.authedRequest(undefined, "POST", path, undefined, data);
+        return self._http.authedRequest(
+            undefined, "POST", path, queryString, data, reqOpts);
    }).then(function(res) {
        const roomId = res.room_id;
        const syncApi = new SyncApi(self, self._clientOpts);
@@ -1168,6 +1685,13 @@ MatrixClient.prototype.sendEvent = function(roomId, eventType, content, txnId,
        room.addPendingEvent(localEvent, txnId);
    }

+    // addPendingEvent can change the state to NOT_SENT if it believes
+    // that there's other events that have failed. We won't bother to
+    // try sending the event if the state has changed as such.
+    if (localEvent.status === EventStatus.NOT_SENT) {
+        return Promise.reject(new Error("Event blocked by other events not yet sent"));
+    }
+
    return _sendEvent(this, room, localEvent, callback);
 };

@@ -1875,6 +2399,32 @@ MatrixClient.prototype.mxcUrlToHttp =
    );
 };

+/**
+ * Sets a new status message for the user. The message may be null/falsey
+ * to clear the message.
+ * @param {string} newMessage The new message to set.
+ * @return {module:client.Promise} Resolves: to nothing
+ * @return {module:http-api.MatrixError} Rejects: with an error response.
+ */
+MatrixClient.prototype._unstable_setStatusMessage = function(newMessage) {
+    const type = "im.vector.user_status";
+    return Promise.all(this.getRooms().map((room) => {
+        const isJoined = room.getMyMembership() === "join";
+        const looksLikeDm = room.getInvitedAndJoinedMemberCount() === 2;
+        if (!isJoined || !looksLikeDm) {
+            return Promise.resolve();
+        }
+        // Check power level separately as it's a bit more expensive.
+        const maySend = room.currentState.mayClientSendStateEvent(type, this);
+        if (!maySend) {
+            return Promise.resolve();
+        }
+        return this.sendStateEvent(room.roomId, type, {
+            status: newMessage,
+        }, this.getUserId());
+    }));
+};
+
 /**
 * @param {Object} opts Options to apply
 * @param {string} opts.presence One of "online", "offline" or "unavailable"
@@ -3476,14 +4026,7 @@ MatrixClient.prototype.getEventMapper = function() {
 * @return {string} A new client secret
 */
 MatrixClient.prototype.generateClientSecret = function() {
-    let ret = "";
-    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-
-    for (let i = 0; i < 32; i++) {
-        ret += chars.charAt(Math.floor(Math.random() * chars.length));
-    }
-
-    return ret;
+    return randomString(32);
 };

 /** */
@@ -3727,6 +4270,52 @@ module.exports.CRYPTO_ENABLED = CRYPTO_ENABLED;
 * });
 */

+/**
+ * Fires whenever the status of e2e key backup changes, as returned by getKeyBackupEnabled()
+ * @event module:client~MatrixClient#"crypto.keyBackupStatus"
+ * @param {bool} enabled true if key backup has been enabled, otherwise false
+ * @example
+ * matrixClient.on("crypto.keyBackupStatus", function(enabled){
+ *   if (enabled) {
+ *     [...]
+ *   }
+ * });
+ */
+
+/**
+ * Fires when we want to suggest to the user that they restore their megolm keys
+ * from backup or by cross-signing the device.
+ *
+ * @event module:client~MatrixClient#"crypto.suggestKeyRestore"
+ */
+
+/**
+ * Fires when a key verification is requested.
+ * @event module:client~MatrixClient#"crypto.verification.request"
+ * @param {object} data
+ * @param {MatrixEvent} data.event the original verification request message
+ * @param {Array} data.methods the verification methods that can be used
+ * @param {Function} data.beginKeyVerification a function to call if a key
+ *     verification should be performed.  The function takes one argument: the
+ *     name of the key verification method (taken from data.methods) to use.
+ * @param {Function} data.cancel a function to call if the key verification is
+ *     rejected.
+ */
+
+/**
+ * Fires when a key verification is requested with an unknown method.
+ * @event module:client~MatrixClient#"crypto.verification.request.unknown"
+ * @param {string} userId the user ID who requested the key verification
+ * @param {Function} cancel a function that will send a cancellation message to
+ *     reject the key verification.
+ */
+
+/**
+ * Fires when a key verification started message is received.
+ * @event module:client~MatrixClient#"crypto.verification.start"
+ * @param {module:crypto/verification/Base} verifier a verifier object to
+ *     perform the key verification
+ */

 // EventEmitter JSDocs

@@ -24,6 +24,7 @@ limitations under the License.

 import Promise from 'bluebird';

+import logger from '../logger';
 import DeviceInfo from './deviceinfo';
 import olmlib from './olmlib';
 import IndexedDBCryptoStore from './store/indexeddb-crypto-store';
@@ -71,6 +72,9 @@ export default class DeviceList {
        // }
        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()
@@ -110,7 +114,7 @@ export default class DeviceList {
            'readwrite', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
                this._cryptoStore.getEndToEndDeviceData(txn, (deviceData) => {
                    if (deviceData === null) {
-                        console.log("Migrating e2e device data...");
+                        logger.log("Migrating e2e device data...");
                        this._devices = this._sessionStore.getAllEndToEndDevices() || {};
                        this._deviceTrackingStatus = (
                            this._sessionStore.getEndToEndDeviceTrackingStatus() || {}
@@ -128,6 +132,16 @@ export default class DeviceList {
                            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;
+                            }
+                        }
+                    }
                });
            },
        );
@@ -145,6 +159,12 @@ export default class DeviceList {
        }
    }

+    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
@@ -190,7 +210,7 @@ export default class DeviceList {
            const resolveSavePromise = this._resolveSavePromise;
            this._savePromiseTime = targetTime;
            this._saveTimer = setTimeout(() => {
-                console.log('Saving device tracking data at token ' + this._syncToken);
+                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.
@@ -258,7 +278,7 @@ export default class DeviceList {
            if (this._keyDownloadsInProgressByUser[u]) {
                // already a key download in progress/queued for this user; its results
                // will be good enough for us.
-                console.log(
+                logger.log(
                    `downloadKeys: already have a download in progress for ` +
                    `${u}: awaiting its result`,
                );
@@ -269,13 +289,13 @@ export default class DeviceList {
        });

        if (usersToDownload.length != 0) {
-            console.log("downloadKeys: downloading for", usersToDownload);
+            logger.log("downloadKeys: downloading for", usersToDownload);
            const downloadPromise = this._doKeyDownload(usersToDownload);
            promises.push(downloadPromise);
        }

        if (promises.length === 0) {
-            console.log("downloadKeys: already have all necessary keys");
+            logger.log("downloadKeys: already have all necessary keys");
        }

        return Promise.all(promises).then(() => {
@@ -357,13 +377,17 @@ export default class DeviceList {
    /**
     * Find a device by curve25519 identity key
     *
-     * @param {string} userId     owner of the device
     * @param {string} algorithm  encryption algorithm
     * @param {string} senderKey  curve25519 key to match
     *
     * @return {module:crypto/deviceinfo?}
     */
-    getDeviceByIdentityKey(userId, algorithm, senderKey) {
+    getDeviceByIdentityKey(algorithm, senderKey) {
+        const userId = this._userByIdentityKey[senderKey];
+        if (!userId) {
+            return null;
+        }
+
        if (
            algorithm !== olmlib.OLM_ALGORITHM &&
            algorithm !== olmlib.MEGOLM_ALGORITHM
@@ -408,7 +432,23 @@ export default class DeviceList {
     * @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;
    }

@@ -433,12 +473,12 @@ export default class DeviceList {
            throw new Error('userId must be a string; was '+userId);
        }
        if (!this._deviceTrackingStatus[userId]) {
-            console.log('Now tracking device list for ' + 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;
        }
-        // 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;
    }

    /**
@@ -452,7 +492,7 @@ export default class DeviceList {
     */
    stopTrackingDeviceList(userId) {
        if (this._deviceTrackingStatus[userId]) {
-            console.log('No longer tracking device list for ' + 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
@@ -487,7 +527,7 @@ export default class DeviceList {
     */
    invalidateUserDeviceList(userId) {
        if (this._deviceTrackingStatus[userId]) {
-            console.log("Marking device list outdated for", 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
@@ -525,7 +565,23 @@ export default class DeviceList {
     * @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;
+        }
    }

    /**
@@ -550,7 +606,7 @@ export default class DeviceList {
        ).then(() => {
            finished(true);
        }, (e) => {
-            console.error(
+            logger.error(
                'Error downloading keys for ' + users + ":", e,
            );
            finished(false);
@@ -573,7 +629,7 @@ export default class DeviceList {
                // since we started this request. If that happens, we should
                // ignore the completion of the first one.
                if (this._keyDownloadsInProgressByUser[u] !== prom) {
-                    console.log('Another update in the queue for', u,
+                    logger.log('Another update in the queue for', u,
                                '- not marking up-to-date');
                    return;
                }
@@ -584,7 +640,7 @@ export default class DeviceList {
                        // 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;
-                        console.log("Device list for", u, "now up to date");
+                        logger.log("Device list for", u, "now up to date");
                    } else {
                        this._deviceTrackingStatus[u] = TRACKING_STATUS_PENDING_DOWNLOAD;
                    }
@@ -659,7 +715,7 @@ class DeviceListUpdateSerialiser {

        if (this._downloadInProgress) {
            // just queue up these users
-            console.log('Queued key download for', users);
+            logger.log('Queued key download for', users);
            return this._queuedQueryDeferred.promise;
        }

@@ -679,7 +735,7 @@ class DeviceListUpdateSerialiser {
        const deferred = this._queuedQueryDeferred;
        this._queuedQueryDeferred = null;

-        console.log('Starting key download for', downloadUsers);
+        logger.log('Starting key download for', downloadUsers);
        this._downloadInProgress = true;

        const opts = {};
@@ -706,7 +762,7 @@ class DeviceListUpdateSerialiser {

            return prom;
        }).done(() => {
-            console.log('Completed key download for ' + downloadUsers);
+            logger.log('Completed key download for ' + downloadUsers);

            this._downloadInProgress = false;
            deferred.resolve();
@@ -716,7 +772,7 @@ class DeviceListUpdateSerialiser {
                this._doQueuedQueries();
            }
        }, (e) => {
-            console.warn('Error downloading keys for ' + downloadUsers + ':', e);
+            logger.warn('Error downloading keys for ' + downloadUsers + ':', e);
            this._downloadInProgress = false;
            deferred.reject(e);
        });
@@ -725,7 +781,7 @@ class DeviceListUpdateSerialiser {
    }

    async _processQueryResponseForUser(userId, response) {
-        console.log('got keys for ' + userId + ':', response);
+        logger.log('got keys for ' + userId + ':', response);

        // map from deviceid -> deviceinfo for this user
        const userStore = {};
@@ -763,7 +819,7 @@ async function _updateStoredDeviceKeysForUser(_olmDevice, userId, userStore,
        }

        if (!(deviceId in userResult)) {
-            console.log("Device " + userId + ":" + deviceId +
+            logger.log("Device " + userId + ":" + deviceId +
                " has been removed");
            delete userStore[deviceId];
            updated = true;
@@ -780,12 +836,12 @@ async function _updateStoredDeviceKeysForUser(_olmDevice, userId, userStore,
        // check that the user_id and device_id in the response object are
        // correct
        if (deviceResult.user_id !== userId) {
-            console.warn("Mismatched user_id " + deviceResult.user_id +
+            logger.warn("Mismatched user_id " + deviceResult.user_id +
               " in keys from " + userId + ":" + deviceId);
            continue;
        }
        if (deviceResult.device_id !== deviceId) {
-            console.warn("Mismatched device_id " + deviceResult.device_id +
+            logger.warn("Mismatched device_id " + deviceResult.device_id +
               " in keys from " + userId + ":" + deviceId);
            continue;
        }
@@ -815,7 +871,7 @@ async function _storeDeviceKeys(_olmDevice, userStore, deviceResult) {
    const signKeyId = "ed25519:" + deviceId;
    const signKey = deviceResult.keys[signKeyId];
    if (!signKey) {
-        console.warn("Device " + userId + ":" + deviceId +
+        logger.warn("Device " + userId + ":" + deviceId +
            " has no ed25519 key");
        return false;
    }
@@ -825,7 +881,7 @@ async function _storeDeviceKeys(_olmDevice, userStore, deviceResult) {
    try {
        await olmlib.verifySignature(_olmDevice, deviceResult, userId, deviceId, signKey);
    } catch (e) {
-        console.warn("Unable to verify signature on device " +
+        logger.warn("Unable to verify signature on device " +
            userId + ":" + deviceId + ":" + e);
        return false;
    }
@@ -842,7 +898,7 @@ async function _storeDeviceKeys(_olmDevice, userStore, deviceResult) {
            // best off sticking with the original keys.
            //
            // Should we warn the user about it somehow?
-            console.warn("Ed25519 key for device " + userId + ":" +
+            logger.warn("Ed25519 key for device " + userId + ":" +
               deviceId + " has changed");
            return false;
        }
@@ -15,19 +15,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */

+import logger from '../logger';
 import IndexedDBCryptoStore from './store/indexeddb-crypto-store';

-/**
- * olm.js wrapper
- *
- * @module crypto/OlmDevice
- */
-const Olm = global.Olm;
-if (!Olm) {
-    throw new Error("global.Olm is not defined");
-}
-
-
 // The maximum size of an event is 65K, and we base64 the content, so this is a
 // reasonable approximation to the biggest plaintext we can encrypt.
 const MAX_PLAINTEXT_LENGTH = 65536 * 3 / 4;
@@ -127,7 +117,7 @@ OlmDevice.prototype.init = async function() {
    await this._migrateFromSessionStore();

    let e2eKeys;
-    const account = new Olm.Account();
+    const account = new global.Olm.Account();
    try {
        await _initialiseAccount(
            this._sessionStore, this._cryptoStore, this._pickleKey, account,
@@ -161,7 +151,7 @@ async function _initialiseAccount(sessionStore, cryptoStore, pickleKey, account)
 * @return {array} The version of Olm.
 */
 OlmDevice.getOlmVersion = function() {
-    return Olm.get_library_version();
+    return global.Olm.get_library_version();
 };

 OlmDevice.prototype._migrateFromSessionStore = async function() {
@@ -173,7 +163,7 @@ OlmDevice.prototype._migrateFromSessionStore = async function() {
                    // Migrate from sessionStore
                    pickledAccount = this._sessionStore.getEndToEndAccount();
                    if (pickledAccount !== null) {
-                        console.log("Migrating account from session store");
+                        logger.log("Migrating account from session store");
                        this._cryptoStore.storeAccount(txn, pickledAccount);
                    }
                }
@@ -195,7 +185,7 @@ OlmDevice.prototype._migrateFromSessionStore = async function() {
                // has run against the same localstorage and created some spurious sessions.
                this._cryptoStore.countEndToEndSessions(txn, (count) => {
                    if (count) {
-                        console.log("Crypto store already has sessions: not migrating");
+                        logger.log("Crypto store already has sessions: not migrating");
                        return;
                    }
                    let numSessions = 0;
@@ -207,7 +197,7 @@ OlmDevice.prototype._migrateFromSessionStore = async function() {
                            );
                        }
                    }
-                    console.log(
+                    logger.log(
                        "Migrating " + numSessions + " sessions from session store",
                    );
                });
@@ -236,14 +226,14 @@ OlmDevice.prototype._migrateFromSessionStore = async function() {
                            ), txn,
                        );
                    } catch (e) {
-                        console.warn(
+                        logger.warn(
                            "Failed to migrate session " + s.senderKey + "/" +
                            s.sessionId + ": " + e.stack || e,
                        );
                    }
                    ++numIbSessions;
                }
-                console.log(
+                logger.log(
                    "Migrated " + numIbSessions +
                    " inbound group sessions from session store",
                );
@@ -268,7 +258,7 @@ OlmDevice.prototype._migrateFromSessionStore = async function() {
 */
 OlmDevice.prototype._getAccount = function(txn, func) {
    this._cryptoStore.getAccount(txn, (pickledAccount) => {
-        const account = new Olm.Account();
+        const account = new global.Olm.Account();
        try {
            account.unpickle(this._pickleKey, pickledAccount);
            func(account);
@@ -305,8 +295,8 @@ OlmDevice.prototype._storeAccount = function(txn, account) {
 */
 OlmDevice.prototype._getSession = function(deviceKey, sessionId, txn, func) {
    this._cryptoStore.getEndToEndSession(
-        deviceKey, sessionId, txn, (pickledSession) => {
-            this._unpickleSession(pickledSession, func);
+        deviceKey, sessionId, txn, (sessionInfo) => {
+            this._unpickleSession(sessionInfo, func);
        },
    );
 };
@@ -316,15 +306,17 @@ OlmDevice.prototype._getSession = function(deviceKey, sessionId, txn, func) {
 * function with it. The session object is destroyed once the function
 * returns.
 *
- * @param {string} pickledSession
+ * @param {object} sessionInfo
 * @param {function} func
 * @private
 */
-OlmDevice.prototype._unpickleSession = function(pickledSession, func) {
-    const session = new Olm.Session();
+OlmDevice.prototype._unpickleSession = function(sessionInfo, func) {
+    const session = new global.Olm.Session();
    try {
-        session.unpickle(this._pickleKey, pickledSession);
-        func(session);
+        session.unpickle(this._pickleKey, sessionInfo.session);
+        const unpickledSessInfo = Object.assign({}, sessionInfo, {session});
+
+        func(unpickledSessInfo);
    } finally {
        session.free();
    }
@@ -334,14 +326,17 @@ OlmDevice.prototype._unpickleSession = function(pickledSession, func) {
 * store our OlmSession in the session store
 *
 * @param {string} deviceKey
- * @param {OlmSession} session
+ * @param {object} sessionInfo {session: OlmSession, lastReceivedMessageTs: int}
 * @param {*} txn Opaque transaction object from cryptoStore.doTxn()
 * @private
 */
-OlmDevice.prototype._saveSession = function(deviceKey, session, txn) {
-    const pickledSession = session.pickle(this._pickleKey);
+OlmDevice.prototype._saveSession = function(deviceKey, sessionInfo, txn) {
+    const sessionId = sessionInfo.session.session_id();
+    const pickledSessionInfo = Object.assign(sessionInfo, {
+        session: sessionInfo.session.pickle(this._pickleKey),
+    });
    this._cryptoStore.storeEndToEndSession(
-        deviceKey, session.session_id(), pickledSession, txn,
+        deviceKey, sessionId, pickledSessionInfo, txn,
    );
 };

@@ -354,7 +349,7 @@ OlmDevice.prototype._saveSession = function(deviceKey, session, txn) {
 * @private
 */
 OlmDevice.prototype._getUtility = function(func) {
-    const utility = new Olm.Utility();
+    const utility = new global.Olm.Utility();
    try {
        return func(utility);
    } finally {
@@ -466,12 +461,19 @@ OlmDevice.prototype.createOutboundSession = async function(
        ],
        (txn) => {
            this._getAccount(txn, (account) => {
-                const session = new Olm.Session();
+                const session = new global.Olm.Session();
                try {
                    session.create_outbound(account, theirIdentityKey, theirOneTimeKey);
                    newSessionId = session.session_id();
                    this._storeAccount(txn, account);
-                    this._saveSession(theirIdentityKey, session, txn);
+                    const sessionInfo = {
+                        session,
+                        // Pretend we've received a message at this point, otherwise
+                        // if we try to send a message to the device, it won't use
+                        // this session
+                        lastReceivedMessageTs: Date.now(),
+                    };
+                    this._saveSession(theirIdentityKey, sessionInfo, txn);
                } finally {
                    session.free();
                }
@@ -510,7 +512,7 @@ OlmDevice.prototype.createInboundSession = async function(
        ],
        (txn) => {
            this._getAccount(txn, (account) => {
-                const session = new Olm.Session();
+                const session = new global.Olm.Session();
                try {
                    session.create_inbound_from(
                        account, theirDeviceIdentityKey, ciphertext,
@@ -520,7 +522,13 @@ OlmDevice.prototype.createInboundSession = async function(

                    const payloadString = session.decrypt(messageType, ciphertext);

-                    this._saveSession(theirDeviceIdentityKey, session, txn);
+                    const sessionInfo = {
+                        session,
+                        // this counts as a received message: set last received message time
+                        // to now
+                        lastReceivedMessageTs: Date.now(),
+                    };
+                    this._saveSession(theirDeviceIdentityKey, sessionInfo, txn);

                    result = {
                        payload: payloadString,
@@ -568,13 +576,30 @@ OlmDevice.prototype.getSessionIdsForDevice = async function(theirDeviceIdentityK
 * @return {Promise<?string>}  session id, or null if no established session
 */
 OlmDevice.prototype.getSessionIdForDevice = async function(theirDeviceIdentityKey) {
-    const sessionIds = await this.getSessionIdsForDevice(theirDeviceIdentityKey);
-    if (sessionIds.length === 0) {
+    const sessionInfos = await this.getSessionInfoForDevice(theirDeviceIdentityKey);
+    if (sessionInfos.length === 0) {
        return null;
    }
-    // Use the session with the lowest ID.
-    sessionIds.sort();
-    return sessionIds[0];
+    // Use the session that has most recently received a message
+    let idxOfBest = 0;
+    for (let i = 1; i < sessionInfos.length; i++) {
+        const thisSessInfo = sessionInfos[i];
+        const thisLastReceived = thisSessInfo.lastReceivedMessageTs === undefined ?
+            0 : thisSessInfo.lastReceivedMessageTs;
+
+        const bestSessInfo = sessionInfos[idxOfBest];
+        const bestLastReceived = bestSessInfo.lastReceivedMessageTs === undefined ?
+            0 : bestSessInfo.lastReceivedMessageTs;
+        if (
+            thisLastReceived > bestLastReceived || (
+                thisLastReceived === bestLastReceived &&
+                thisSessInfo.sessionId < bestSessInfo.sessionId
+            )
+        ) {
+            idxOfBest = i;
+        }
+    }
+    return sessionInfos[idxOfBest].sessionId;
 };

 /**
@@ -597,9 +622,10 @@ OlmDevice.prototype.getSessionInfoForDevice = async function(deviceIdentityKey)
            this._cryptoStore.getEndToEndSessions(deviceIdentityKey, txn, (sessions) => {
                const sessionIds = Object.keys(sessions).sort();
                for (const sessionId of sessionIds) {
-                    this._unpickleSession(sessions[sessionId], (session) => {
+                    this._unpickleSession(sessions[sessionId], (sessInfo) => {
                        info.push({
-                            hasReceivedMessage: session.has_received_message(),
+                            lastReceivedMessageTs: sessInfo.lastReceivedMessageTs,
+                            hasReceivedMessage: sessInfo.session.has_received_message(),
                            sessionId: sessionId,
                        });
                    });
@@ -630,9 +656,9 @@ OlmDevice.prototype.encryptMessage = async function(
    await this._cryptoStore.doTxn(
        'readwrite', [IndexedDBCryptoStore.STORE_SESSIONS],
        (txn) => {
-            this._getSession(theirDeviceIdentityKey, sessionId, txn, (session) => {
-                res = session.encrypt(payloadString);
-                this._saveSession(theirDeviceIdentityKey, session, txn);
+            this._getSession(theirDeviceIdentityKey, sessionId, txn, (sessionInfo) => {
+                res = sessionInfo.session.encrypt(payloadString);
+                this._saveSession(theirDeviceIdentityKey, sessionInfo, txn);
            });
        },
    );
@@ -657,9 +683,10 @@ OlmDevice.prototype.decryptMessage = async function(
    await this._cryptoStore.doTxn(
        'readwrite', [IndexedDBCryptoStore.STORE_SESSIONS],
        (txn) => {
-            this._getSession(theirDeviceIdentityKey, sessionId, txn, (session) => {
-                payloadString = session.decrypt(messageType, ciphertext);
-                this._saveSession(theirDeviceIdentityKey, session, txn);
+            this._getSession(theirDeviceIdentityKey, sessionId, txn, (sessionInfo) => {
+                payloadString = sessionInfo.session.decrypt(messageType, ciphertext);
+                sessionInfo.lastReceivedMessageTs = Date.now();
+                this._saveSession(theirDeviceIdentityKey, sessionInfo, txn);
            });
        },
    );
@@ -689,8 +716,8 @@ OlmDevice.prototype.matchesSession = async function(
    await this._cryptoStore.doTxn(
        'readonly', [IndexedDBCryptoStore.STORE_SESSIONS],
        (txn) => {
-            this._getSession(theirDeviceIdentityKey, sessionId, txn, (session) => {
-                matches = session.matches_inbound(ciphertext);
+            this._getSession(theirDeviceIdentityKey, sessionId, txn, (sessionInfo) => {
+                matches = sessionInfo.session.matches_inbound(ciphertext);
            });
        },
    );
@@ -724,11 +751,11 @@ OlmDevice.prototype._saveOutboundGroupSession = function(session) {
 */
 OlmDevice.prototype._getOutboundGroupSession = function(sessionId, func) {
    const pickled = this._outboundGroupSessionStore[sessionId];
-    if (pickled === null) {
+    if (pickled === undefined) {
        throw new Error("Unknown outbound group session " + sessionId);
    }

-    const session = new Olm.OutboundGroupSession();
+    const session = new global.Olm.OutboundGroupSession();
    try {
        session.unpickle(this._pickleKey, pickled);
        return func(session);
@@ -744,7 +771,7 @@ OlmDevice.prototype._getOutboundGroupSession = function(sessionId, func) {
 * @return {string} sessionId for the outbound session.
 */
 OlmDevice.prototype.createOutboundGroupSession = function() {
-    const session = new Olm.OutboundGroupSession();
+    const session = new global.Olm.OutboundGroupSession();
    try {
        session.create();
        this._saveOutboundGroupSession(session);
@@ -816,7 +843,7 @@ OlmDevice.prototype.getOutboundGroupSessionKey = function(sessionId) {
 * @return {*} result of func
 */
 OlmDevice.prototype._unpickleInboundGroupSession = function(sessionData, func) {
-    const session = new Olm.InboundGroupSession();
+    const session = new global.Olm.InboundGroupSession();
    try {
        session.unpickle(this._pickleKey, sessionData.session);
        return func(session);
@@ -888,16 +915,8 @@ OlmDevice.prototype.addInboundGroupSession = async function(
            this._getInboundGroupSession(
                roomId, senderKey, sessionId, txn,
                (existingSession, existingSessionData) => {
-                    if (existingSession) {
-                        console.log(
-                            "Update for megolm session " + senderKey + "/" + sessionId,
-                        );
-                        // for now we just ignore updates. TODO: implement something here
-                        return;
-                    }
-
                    // new session.
-                    const session = new Olm.InboundGroupSession();
+                    const session = new global.Olm.InboundGroupSession();
                    try {
                        if (exportFormat) {
                            session.import_session(sessionKey);
@@ -911,6 +930,20 @@ OlmDevice.prototype.addInboundGroupSession = async function(
                            );
                        }

+                        if (existingSession) {
+                            logger.log(
+                                "Update for megolm session "
+                                    + senderKey + "/" + sessionId,
+                            );
+                            if (existingSession.first_known_index()
+                                <= session.first_known_index()) {
+                                // existing session has lower index (i.e. can
+                                // decrypt more), so keep it
+                                logger.log("Keeping existing session");
+                                return;
+                            }
+                        }
+
                        const sessionData = {
                            room_id: roomId,
                            session: session.pickle(this._pickleKey),
@@ -918,7 +951,7 @@ OlmDevice.prototype.addInboundGroupSession = async function(
                            forwardingCurve25519KeyChain: forwardingCurve25519KeyChain,
                        };

-                        this._cryptoStore.addEndToEndInboundGroupSession(
+                        this._cryptoStore.storeEndToEndInboundGroupSession(
                            senderKey, sessionId, sessionData, txn,
                        );
                    } finally {
@@ -1034,7 +1067,7 @@ OlmDevice.prototype.hasInboundSessionKeys = async function(roomId, senderKey, se
                    }

                    if (roomId !== sessionData.room_id) {
-                        console.warn(
+                        logger.warn(
                            `requested keys for inbound group session ${senderKey}|` +
                            `${sessionId}, with incorrect room_id ` +
                            `(expected ${sessionData.room_id}, ` +
@@ -1058,6 +1091,8 @@ OlmDevice.prototype.hasInboundSessionKeys = async function(roomId, senderKey, se
 * @param {string} roomId    room in which the message was received
 * @param {string} senderKey base64-encoded curve25519 key of the sender
 * @param {string} sessionId session identifier
+ * @param {integer} chainIndex The chain index at which to export the session.
+ *     If omitted, export at the first index we know about.
 *
 * @returns {Promise<{chain_index: number, key: string,
 *        forwarding_curve25519_key_chain: Array<string>,
@@ -1065,9 +1100,12 @@ OlmDevice.prototype.hasInboundSessionKeys = async function(roomId, senderKey, se
 *    }>}
 *    details of the session key. The key is a base64-encoded megolm key in
 *    export format.
+ *
+ * @throws Error If the given chain index could not be obtained from the known
+ *     index (ie. the given chain index is before the first we have).
 */
 OlmDevice.prototype.getInboundGroupSessionKey = async function(
-    roomId, senderKey, sessionId,
+    roomId, senderKey, sessionId, chainIndex,
 ) {
    let result;
    await this._cryptoStore.doTxn(
@@ -1078,14 +1116,19 @@ OlmDevice.prototype.getInboundGroupSessionKey = async function(
                        result = null;
                        return;
                    }
-                    const messageIndex = session.first_known_index();
+
+                    if (chainIndex === undefined) {
+                        chainIndex = session.first_known_index();
+                    }
+
+                    const exportedSession = session.export_session(chainIndex);

                    const claimedKeys = sessionData.keysClaimed || {};
                    const senderEd25519Key = claimedKeys.ed25519 || null;

                    result = {
-                        "chain_index": messageIndex,
-                        "key": session.export_session(messageIndex),
+                        "chain_index": chainIndex,
+                        "key": exportedSession,
                        "forwarding_curve25519_key_chain":
                            sessionData.forwardingCurve25519KeyChain || [],
                        "sender_claimed_ed25519_key": senderEd25519Key,
@@ -1119,6 +1162,7 @@ OlmDevice.prototype.exportInboundGroupSession = function(
            "session_id": sessionId,
            "session_key": session.export_session(messageIndex),
            "forwarding_curve25519_key_chain": session.forwardingCurve25519KeyChain || [],
+            "first_known_index": session.first_known_index(),
        };
    });
 };
@@ -16,6 +16,7 @@ limitations under the License.

 import Promise from 'bluebird';

+import logger from '../logger';
 import utils from '../utils';

 /**
@@ -108,7 +109,7 @@ export default class OutgoingRoomKeyRequestManager {
     * Called when the client is stopped. Stops any running background processes.
     */
    stop() {
-        console.log('stopping OutgoingRoomKeyRequestManager');
+        logger.log('stopping OutgoingRoomKeyRequestManager');
        // stop the timer on the next run
        this._clientRunning = false;
    }
@@ -123,35 +124,118 @@ export default class OutgoingRoomKeyRequestManager {
     *
     * @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)
     */
-    sendRoomKeyRequest(requestBody, recipients) {
-        return this._cryptoStore.getOrAddOutgoingRoomKeyRequest({
-            requestBody: requestBody,
-            recipients: recipients,
-            requestId: this._baseApis.makeTxnId(),
-            state: ROOM_KEY_REQUEST_STATES.UNSENT,
-        }).then((req) => {
-            if (req.state === ROOM_KEY_REQUEST_STATES.UNSENT) {
-                this._startTimer();
+    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
-     * @param {boolean} andResend if true, transition to UNSENT instead of
-     *                            deleting after sending cancellation.
     *
     * @returns {Promise} resolves when the request has been updated in our
     *    pending list.
     */
-    cancelRoomKeyRequest(requestBody, andResend=false) {
+    cancelRoomKeyRequest(requestBody) {
        return this._cryptoStore.getOutgoingRoomKeyRequest(
            requestBody,
        ).then((req) => {
@@ -173,7 +257,7 @@ export default class OutgoingRoomKeyRequestManager {
                    // may have seen it, so we still need to send a cancellation
                    // in that case :/

-                    console.log(
+                    logger.log(
                        'deleting unnecessary room key request for ' +
                        stringifyRequestBody(requestBody),
                    );
@@ -182,15 +266,10 @@ export default class OutgoingRoomKeyRequestManager {
                    );

                case ROOM_KEY_REQUEST_STATES.SENT: {
-                    // If `andResend` is set, transition to UNSENT once the
-                    // cancellation has successfully been sent.
-                    const state = andResend ?
-                        ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING_AND_WILL_RESEND :
-                        ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING;
                    // send a cancellation.
                    return this._cryptoStore.updateOutgoingRoomKeyRequest(
                        req.requestId, ROOM_KEY_REQUEST_STATES.SENT, {
-                            state,
+                            state: ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING,
                            cancellationTxnId: this._baseApis.makeTxnId(),
                        },
                    ).then((updatedReq) => {
@@ -201,7 +280,7 @@ export default class OutgoingRoomKeyRequestManager {
                            // the request cancelled. There is no point in
                            // sending another cancellation since the other tab
                            // will do it.
-                            console.log(
+                            logger.log(
                                'Tried to cancel room key request for ' +
                                stringifyRequestBody(requestBody) +
                                ' but it was already cancelled in another tab',
@@ -220,20 +299,12 @@ export default class OutgoingRoomKeyRequestManager {
                        // do.)
                        this._sendOutgoingRoomKeyRequestCancellation(
                            updatedReq,
-                            andResend,
                        ).catch((e) => {
-                            console.error(
+                            logger.error(
                                "Error sending room key request cancellation;"
                                + " will retry later.", e,
                            );
                            this._startTimer();
-                        }).then(() => {
-                            if (!andResend) return;
-                            // 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.
-                            this._startTimer();
                        });
                    });
                }
@@ -243,6 +314,21 @@ export default class OutgoingRoomKeyRequestManager {
        });
    }

+    /**
+     * 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() {
@@ -261,10 +347,10 @@ export default class OutgoingRoomKeyRequestManager {
            }).catch((e) => {
                // this should only happen if there is an indexeddb error,
                // in which case we're a bit stuffed anyway.
-                console.warn(
+                logger.warn(
                    `error in OutgoingRoomKeyRequestManager: ${e}`,
                );
-            }).done();
+            });
        };

        this._sendOutgoingRoomKeyRequestsTimer = global.setTimeout(
@@ -282,7 +368,7 @@ export default class OutgoingRoomKeyRequestManager {
            return Promise.resolve();
        }

-        console.log("Looking for queued outgoing room key requests");
+        logger.log("Looking for queued outgoing room key requests");

        return this._cryptoStore.getOutgoingRoomKeyRequestByState([
            ROOM_KEY_REQUEST_STATES.CANCELLATION_PENDING,
@@ -290,7 +376,7 @@ export default class OutgoingRoomKeyRequestManager {
            ROOM_KEY_REQUEST_STATES.UNSENT,
        ]).then((req) => {
            if (!req) {
-                console.log("No more outgoing room key requests");
+                logger.log("No more outgoing room key requests");
                this._sendOutgoingRoomKeyRequestsTimer = null;
                return;
            }
@@ -312,16 +398,16 @@ export default class OutgoingRoomKeyRequestManager {
                // go around the loop again
                return this._sendOutgoingRoomKeyRequests();
            }).catch((e) => {
-                console.error("Error sending room key request; will retry later.", e);
+                logger.error("Error sending room key request; will retry later.", e);
                this._sendOutgoingRoomKeyRequestsTimer = null;
                this._startTimer();
-            }).done();
+            });
        });
    }

    // given a RoomKeyRequest, send it and update the request record
    _sendOutgoingRoomKeyRequest(req) {
-        console.log(
+        logger.log(
            `Requesting keys for ${stringifyRequestBody(req.requestBody)}` +
            ` from ${stringifyRecipientList(req.recipients)}` +
            `(id ${req.requestId})`,
@@ -335,7 +421,7 @@ export default class OutgoingRoomKeyRequestManager {
        };

        return this._sendMessageToDevices(
-            requestMessage, req.recipients, req.requestId,
+            requestMessage, req.recipients, req.requestTxnId || req.requestId,
        ).then(() => {
            return this._cryptoStore.updateOutgoingRoomKeyRequest(
                req.requestId, ROOM_KEY_REQUEST_STATES.UNSENT,
@@ -347,7 +433,7 @@ export default class OutgoingRoomKeyRequestManager {
    // Given a RoomKeyRequest, cancel it and delete the request record unless
    // andResend is set, in which case transition to UNSENT.
    _sendOutgoingRoomKeyRequestCancellation(req, andResend) {
-        console.log(
+        logger.log(
            `Sending cancellation for key request for ` +
            `${stringifyRequestBody(req.requestBody)} to ` +
            `${stringifyRecipientList(req.recipients)} ` +
@@ -24,6 +24,7 @@ limitations under the License.

 import Promise from 'bluebird';

+const logger = require("../../logger");
 const utils = require("../../utils");
 const olmlib = require("../olmlib");
 const base = require("./base");
@@ -65,7 +66,7 @@ OutboundSessionInfo.prototype.needsRotation = function(
    if (this.useCount >= rotationPeriodMsgs ||
        sessionLifetime >= rotationPeriodMs
       ) {
-        console.log(
+        logger.log(
            "Rotating megolm session after " + this.useCount +
                " messages, " + sessionLifetime + "ms",
        );
@@ -103,7 +104,7 @@ OutboundSessionInfo.prototype.sharedWithTooManyDevices = function(
        }

        if (!devicesInRoom.hasOwnProperty(userId)) {
-            console.log("Starting new session because we shared with " + userId);
+            logger.log("Starting new session because we shared with " + userId);
            return true;
        }

@@ -113,7 +114,7 @@ OutboundSessionInfo.prototype.sharedWithTooManyDevices = function(
            }

            if (!devicesInRoom[userId].hasOwnProperty(deviceId)) {
-                console.log(
+                logger.log(
                    "Starting new session because we shared with " +
                        userId + ":" + deviceId,
                );
@@ -143,6 +144,11 @@ function MegolmEncryption(params) {
    // room).
    this._setupPromise = Promise.resolve();

+    // Map of outbound sessions by sessions ID. Used if we need a particular
+    // session (the session we're currently using to send is always obtained
+    // using _setupPromise).
+    this._outboundSessions = {};
+
    // default rotation periods
    this._sessionRotationPeriodMsgs = 100;
    this._sessionRotationPeriodMs = 7 * 24 * 3600 * 1000;
@@ -182,7 +188,7 @@ MegolmEncryption.prototype._ensureOutboundSession = function(devicesInRoom) {
        if (session && session.needsRotation(self._sessionRotationPeriodMsgs,
                                             self._sessionRotationPeriodMs)
           ) {
-            console.log("Starting new megolm session because we need to rotate.");
+            logger.log("Starting new megolm session because we need to rotate.");
            session = null;
        }

@@ -192,8 +198,9 @@ MegolmEncryption.prototype._ensureOutboundSession = function(devicesInRoom) {
        }

        if (!session) {
-            console.log(`Starting new megolm session for room ${self._roomId}`);
+            logger.log(`Starting new megolm session for room ${self._roomId}`);
            session = await self._prepareNewSession();
+            self._outboundSessions[session.sessionId] = session;
        }

        // now check if we need to share with any devices
@@ -263,6 +270,18 @@ MegolmEncryption.prototype._prepareNewSession = async function() {
        key.key, {ed25519: this._olmDevice.deviceEd25519Key},
    );

+    if (this._crypto.backupInfo) {
+        // don't wait for it to complete
+        this._crypto.backupGroupSession(
+            this._roomId, this._olmDevice.deviceCurve25519Key, [],
+            sessionId, key.key,
+        ).catch((e) => {
+            // This throws if the upload failed, but this is fine
+            // since it will have written it to the db and will retry.
+            console.log("Failed to back up group session", e);
+        });
+    }
+
    return new OutboundSessionInfo(sessionId);
 };

@@ -319,7 +338,7 @@ MegolmEncryption.prototype._splitUserDeviceMap = function(
                continue;
            }

-            console.log(
+            logger.log(
                "share keys with device " + userId + ":" + deviceId,
            );

@@ -408,8 +427,98 @@ MegolmEncryption.prototype._encryptAndSendKeysToDevices = function(
 };

 /**
- * @private
+ * Re-shares a megolm session key with devices if the key has already been
+ * sent to them.
 *
+ * @param {string} senderKey The key of the originating device for the session
+ * @param {string} sessionId ID of the outbound session to share
+ * @param {string} userId ID of the user who owns the target device
+ * @param {module:crypto/deviceinfo} device The target device
+ */
+MegolmEncryption.prototype.reshareKeyWithDevice = async function(
+    senderKey, sessionId, userId, device,
+) {
+    const obSessionInfo = this._outboundSessions[sessionId];
+    if (!obSessionInfo) {
+        logger.debug("Session ID " + sessionId + " not found: not re-sharing keys");
+        return;
+    }
+
+    // The chain index of the key we previously sent this device
+    if (obSessionInfo.sharedWithDevices[userId] === undefined) {
+        logger.debug("Session ID " + sessionId + " never shared with user " + userId);
+        return;
+    }
+    const sentChainIndex = obSessionInfo.sharedWithDevices[userId][device.deviceId];
+    if (sentChainIndex === undefined) {
+        logger.debug(
+            "Session ID " + sessionId + " never shared with device " +
+            userId + ":" + device.deviceId,
+        );
+        return;
+    }
+
+    // get the key from the inbound session: the outbound one will already
+    // have been ratcheted to the next chain index.
+    const key = await this._olmDevice.getInboundGroupSessionKey(
+        this._roomId, senderKey, sessionId, sentChainIndex,
+    );
+
+    if (!key) {
+        logger.warn(
+            "No outbound session key found for " + sessionId + ": not re-sharing keys",
+        );
+        return;
+    }
+
+    await olmlib.ensureOlmSessionsForDevices(
+        this._olmDevice, this._baseApis, {
+            [userId]: {
+                [device.deviceId]: device,
+            },
+        },
+    );
+
+    const payload = {
+        type: "m.forwarded_room_key",
+        content: {
+            algorithm: olmlib.MEGOLM_ALGORITHM,
+            room_id: this._roomId,
+            session_id: sessionId,
+            session_key: key.key,
+            chain_index: key.chain_index,
+            sender_key: senderKey,
+            sender_claimed_ed25519_key: key.sender_claimed_ed25519_key,
+            forwarding_curve25519_key_chain: key.forwarding_curve25519_key_chain,
+        },
+    };
+
+    const encryptedContent = {
+        algorithm: olmlib.OLM_ALGORITHM,
+        sender_key: this._olmDevice.deviceCurve25519Key,
+        ciphertext: {},
+    };
+    await olmlib.encryptMessageForDevice(
+        encryptedContent.ciphertext,
+        this._userId,
+        this._deviceId,
+        this._olmDevice,
+        userId,
+        device,
+        payload,
+    ),
+
+    await this._baseApis.sendToDevice("m.room.encrypted", {
+        [userId]: {
+            [device.deviceId]: encryptedContent,
+        },
+    });
+    logger.debug(
+        `Re-shared key for session ${sessionId}  with ${userId}:${device.deviceId}`,
+    );
+};
+
+/**
 * @param {module:crypto/algorithms/megolm.OutboundSessionInfo} session
 *
 * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
@@ -441,10 +550,10 @@ MegolmEncryption.prototype._shareKeyWithDevices = async function(session, device
            await this._encryptAndSendKeysToDevices(
                session, key.chain_index, userDeviceMaps[i], payload,
            );
-            console.log(`Completed megolm keyshare in ${this._roomId} `
+            logger.log(`Completed megolm keyshare in ${this._roomId} `
                + `(slice ${i + 1}/${userDeviceMaps.length})`);
        } catch (e) {
-            console.log(`megolm keyshare in ${this._roomId} `
+            logger.log(`megolm keyshare in ${this._roomId} `
                + `(slice ${i + 1}/${userDeviceMaps.length}) failed`);

            throw e;
@@ -463,7 +572,7 @@ MegolmEncryption.prototype._shareKeyWithDevices = async function(session, device
 */
 MegolmEncryption.prototype.encryptMessage = function(room, eventType, content) {
    const self = this;
-    console.log(`Starting to encrypt event for ${this._roomId}`);
+    logger.log(`Starting to encrypt event for ${this._roomId}`);

    return this._getDevicesInRoom(room).then(function(devicesInRoom) {
        // check if any of these devices are not yet known to the user.
@@ -649,7 +758,7 @@ MegolmDecryption.prototype.decryptEvent = async function(event) {
    } catch (e) {
        let errorCode = "OLM_DECRYPT_GROUP_MESSAGE_ERROR";

-        if (e.message === 'OLM.UNKNOWN_MESSAGE_INDEX') {
+        if (e && e.message === 'OLM.UNKNOWN_MESSAGE_INDEX') {
            this._requestKeysForEvent(event);

            errorCode = 'OLM_UNKNOWN_MESSAGE_INDEX';
@@ -657,7 +766,7 @@ MegolmDecryption.prototype.decryptEvent = async function(event) {

        throw new base.DecryptionError(
            errorCode,
-            e.toString(), {
+            e ? e.toString() : "Unknown Error: Error is undefined", {
                session: content.sender_key + '|' + content.session_id,
            },
        );
@@ -706,19 +815,9 @@ MegolmDecryption.prototype.decryptEvent = async function(event) {
 };

 MegolmDecryption.prototype._requestKeysForEvent = function(event) {
-    const sender = event.getSender();
    const wireContent = event.getWireContent();

-    // send the request to all of our own devices, and the
-    // original sending device if it wasn't us.
-    const recipients = [{
-        userId: this._userId, deviceId: '*',
-    }];
-    if (sender != this._userId) {
-        recipients.push({
-            userId: sender, deviceId: wireContent.device_id,
-        });
-    }
+    const recipients = event.getKeyRequestRecipients(this._userId);

    this._crypto.requestRoomKey({
        room_id: event.getRoomId(),
@@ -782,12 +881,12 @@ MegolmDecryption.prototype.onRoomKeyEvent = function(event) {
        !sessionId ||
        !content.session_key
       ) {
-        console.error("key event is missing fields");
+        logger.error("key event is missing fields");
        return;
    }

    if (!senderKey) {
-        console.error("key event has no sender key (not encrypted?)");
+        logger.error("key event has no sender key (not encrypted?)");
        return;
    }

@@ -804,13 +903,13 @@ MegolmDecryption.prototype.onRoomKeyEvent = function(event) {

        senderKey = content.sender_key;
        if (!senderKey) {
-            console.error("forwarded_room_key event is missing sender_key field");
+            logger.error("forwarded_room_key event is missing sender_key field");
            return;
        }

        const ed25519Key = content.sender_claimed_ed25519_key;
        if (!ed25519Key) {
-            console.error(
+            logger.error(
                `forwarded_room_key_event is missing sender_claimed_ed25519_key field`,
            );
            return;
@@ -823,24 +922,44 @@ MegolmDecryption.prototype.onRoomKeyEvent = function(event) {
        keysClaimed = event.getKeysClaimed();
    }

-    console.log(`Adding key for megolm session ${senderKey}|${sessionId}`);
-    this._olmDevice.addInboundGroupSession(
+    logger.log(`Adding key for megolm session ${senderKey}|${sessionId}`);
+    return this._olmDevice.addInboundGroupSession(
        content.room_id, senderKey, forwardingKeyChain, sessionId,
        content.session_key, keysClaimed,
        exportFormat,
    ).then(() => {
-        // cancel any outstanding room key requests for this session
-        this._crypto.cancelRoomKeyRequest({
-            algorithm: content.algorithm,
-            room_id: content.room_id,
-            session_id: content.session_id,
-            sender_key: senderKey,
-        });
-
        // have another go at decrypting events sent with this session.
-        this._retryDecryption(senderKey, sessionId);
+        this._retryDecryption(senderKey, sessionId)
+            .then((success) => {
+                // cancel any outstanding room key requests for this session.
+                // Only do this if we managed to decrypt every message in the
+                // session, because if we didn't, we leave the other key
+                // requests in the hopes that someone sends us a key that
+                // includes an earlier index.
+                if (success) {
+                    this._crypto.cancelRoomKeyRequest({
+                        algorithm: content.algorithm,
+                        room_id: content.room_id,
+                        session_id: content.session_id,
+                        sender_key: senderKey,
+                    });
+                }
+            });
+    }).then(() => {
+        if (this._crypto.backupInfo) {
+            // don't wait for the keys to be backed up for the server
+            this._crypto.backupGroupSession(
+                content.room_id, senderKey, forwardingKeyChain,
+                content.session_id, content.session_key, keysClaimed,
+                exportFormat,
+            ).catch((e) => {
+                // This throws if the upload failed, but this is fine
+                // since it will have written it to the db and will retry.
+                console.log("Failed to back up group session", e);
+            });
+        }
    }).catch((e) => {
-        console.error(`Error handling m.room_key_event: ${e}`);
+        logger.error(`Error handling m.room_key_event: ${e}`);
    });
 };

@@ -882,7 +1001,7 @@ MegolmDecryption.prototype.shareKeysWithDevice = function(keyRequest) {
            return null;
        }

-        console.log(
+        logger.log(
            "sharing keys for session " + body.sender_key + "|"
            + body.session_id + " with device "
            + userId + ":" + deviceId,
@@ -956,6 +1075,22 @@ MegolmDecryption.prototype.importRoomKey = function(session) {
        session.sender_claimed_keys,
        true,
    ).then(() => {
+        if (this._crypto.backupInfo) {
+            // don't wait for it to complete
+            this._crypto.backupGroupSession(
+                session.room_id,
+                session.sender_key,
+                session.forwarding_curve25519_key_chain,
+                session.session_id,
+                session.session_key,
+                session.sender_claimed_keys,
+                true,
+            ).catch((e) => {
+                // This throws if the upload failed, but this is fine
+                // since it will have written it to the db and will retry.
+                console.log("Failed to back up group session", e);
+            });
+        }
        // have another go at decrypting events sent with this session.
        this._retryDecryption(session.sender_key, session.session_id);
    });
@@ -967,19 +1102,27 @@ MegolmDecryption.prototype.importRoomKey = function(session) {
 * @private
 * @param {String} senderKey
 * @param {String} sessionId
+ *
+ * @return {Boolean} whether all messages were successfully decrypted
 */
-MegolmDecryption.prototype._retryDecryption = function(senderKey, sessionId) {
+MegolmDecryption.prototype._retryDecryption = async function(senderKey, sessionId) {
    const k = senderKey + "|" + sessionId;
    const pending = this._pendingEvents[k];
    if (!pending) {
-        return;
+        return true;
    }

    delete this._pendingEvents[k];

-    for (const ev of pending) {
-        ev.attemptDecryption(this._crypto);
-    }
+    await Promise.all([...pending].map(async (ev) => {
+        try {
+            await ev.attemptDecryption(this._crypto);
+        } catch (e) {
+            // don't die if something goes wrong
+        }
+    }));
+
+    return !this._pendingEvents[k];
 };

 base.registerAlgorithm(
@@ -22,6 +22,7 @@ limitations under the License.
 */
 import Promise from 'bluebird';

+const logger = require("../../logger");
 const utils = require("../../utils");
 const olmlib = require("../olmlib");
 const DeviceInfo = require("../deviceinfo");
@@ -273,7 +274,7 @@ OlmDecryption.prototype._decryptMessage = async function(
            const payload = await this._olmDevice.decryptMessage(
                theirDeviceIdentityKey, sessionId, message.type, message.body,
            );
-            console.log(
+            logger.log(
                "Decrypted Olm message from " + theirDeviceIdentityKey +
                    " with session " + sessionId,
            );
@@ -328,7 +329,7 @@ OlmDecryption.prototype._decryptMessage = async function(
        );
    }

-    console.log(
+    logger.log(
        "created new inbound Olm session ID " +
            res.session_id + " with " + theirDeviceIdentityKey,
    );
@@ -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);
+}
@@ -23,6 +23,7 @@ limitations under the License.
 import Promise from 'bluebird';
 const anotherjson = require('another-json');

+const logger = require("../logger");
 const utils = require("../utils");

 /**
@@ -35,6 +36,11 @@ module.exports.OLM_ALGORITHM = "m.olm.v1.curve25519-aes-sha2";
 */
 module.exports.MEGOLM_ALGORITHM = "m.megolm.v1.aes-sha2";

+/**
+ * matrix algorithm tag for megolm backups
+ */
+module.exports.MEGOLM_BACKUP_ALGORITHM = "m.megolm_backup.v1.curve25519-aes-sha2";
+

 /**
 * Encrypt an event payload for an Olm device
@@ -65,7 +71,7 @@ module.exports.encryptMessageForDevice = async function(
        return;
    }

-    console.log(
+    logger.log(
        "Using sessionid " + sessionId + " for device " +
            recipientUserId + ":" + recipientDevice.deviceId,
    );
@@ -115,14 +121,17 @@ module.exports.encryptMessageForDevice = async function(
 * @param {module:base-apis~MatrixBaseApis} baseApis
 *
 * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
- *    map from userid to list of devices
+ *    map from userid to list of devices to ensure sessions for
+ *
+ * @param {bolean} force If true, establish a new session even if one already exists.
+ *     Optional.
 *
 * @return {module:client.Promise} resolves once the sessions are complete, to
 *    an Object mapping from userId to deviceId to
 *    {@link module:crypto~OlmSessionResult}
 */
 module.exports.ensureOlmSessionsForDevices = async function(
-    olmDevice, baseApis, devicesByUser,
+    olmDevice, baseApis, devicesByUser, force,
 ) {
    const devicesWithoutSession = [
        // [userId, deviceId], ...
@@ -140,7 +149,7 @@ module.exports.ensureOlmSessionsForDevices = async function(
            const deviceId = deviceInfo.deviceId;
            const key = deviceInfo.getIdentityKey();
            const sessionId = await olmDevice.getSessionIdForDevice(key);
-            if (sessionId === null) {
+            if (sessionId === null || force) {
                devicesWithoutSession.push([userId, deviceId]);
            }
            result[userId][deviceId] = {
@@ -176,7 +185,7 @@ module.exports.ensureOlmSessionsForDevices = async function(
        for (let j = 0; j < devices.length; j++) {
            const deviceInfo = devices[j];
            const deviceId = deviceInfo.deviceId;
-            if (result[userId][deviceId].sessionId) {
+            if (result[userId][deviceId].sessionId && !force) {
                // we already have a result for this device
                continue;
            }
@@ -190,7 +199,7 @@ module.exports.ensureOlmSessionsForDevices = async function(
            }

            if (!oneTimeKey) {
-                console.warn(
+                logger.warn(
                    "No one-time keys (alg=" + oneTimeKeyAlgorithm +
                        ") for device " + userId + ":" + deviceId,
                );
@@ -219,7 +228,7 @@ async function _verifyKeyAndStartSession(olmDevice, oneTimeKey, userId, deviceIn
            deviceInfo.getFingerprint(),
        );
    } catch (e) {
-        console.error(
+        logger.error(
            "Unable to verify signature on one-time key for device " +
                userId + ":" + deviceId + ":", e,
        );
@@ -233,12 +242,12 @@ async function _verifyKeyAndStartSession(olmDevice, oneTimeKey, userId, deviceIn
        );
    } catch (e) {
        // possibly a bad key
-        console.error("Error starting session with device " +
+        logger.error("Error starting session with device " +
                      userId + ":" + deviceId + ": " + e);
        return null;
    }

-    console.log("Started new sessionid " + sid +
+    logger.log("Started new sessionid " + sid +
                " for device " + userId + ":" + deviceId);
    return sid;
 }
@@ -0,0 +1,66 @@
+/*
+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 bs58 from 'bs58';
+
+// picked arbitrarily but to try & avoid clashing with any bitcoin ones
+// (which are also base58 encoded, but bitcoin's involve a lot more hashing)
+const OLM_RECOVERY_KEY_PREFIX = [0x8B, 0x01];
+
+export function encodeRecoveryKey(key) {
+    const buf = new Uint8Array(OLM_RECOVERY_KEY_PREFIX.length + key.length + 1);
+    buf.set(OLM_RECOVERY_KEY_PREFIX, 0);
+    buf.set(key, OLM_RECOVERY_KEY_PREFIX.length);
+
+    let parity = 0;
+    for (let i = 0; i < buf.length - 1; ++i) {
+        parity ^= buf[i];
+    }
+    buf[buf.length - 1] = parity;
+    const base58key = bs58.encode(buf);
+
+    return base58key.match(/.{1,4}/g).join(" ");
+}
+
+export function decodeRecoveryKey(recoverykey) {
+    const result = bs58.decode(recoverykey.replace(/ /g, ''));
+
+    let parity = 0;
+    for (const b of result) {
+        parity ^= b;
+    }
+    if (parity !== 0) {
+        throw new Error("Incorrect parity");
+    }
+
+    for (let i = 0; i < OLM_RECOVERY_KEY_PREFIX.length; ++i) {
+        if (result[i] !== OLM_RECOVERY_KEY_PREFIX[i]) {
+            throw new Error("Incorrect prefix");
+        }
+    }
+
+    if (
+        result.length !==
+        OLM_RECOVERY_KEY_PREFIX.length + global.Olm.PRIVATE_KEY_LENGTH + 1
+    ) {
+        throw new Error("Incorrect length");
+    }
+
+    return result.slice(
+        OLM_RECOVERY_KEY_PREFIX.length,
+        OLM_RECOVERY_KEY_PREFIX.length + global.Olm.PRIVATE_KEY_LENGTH,
+    );
+}
@@ -16,9 +16,11 @@ limitations under the License.
 */

 import Promise from 'bluebird';
+
+import logger from '../../logger';
 import utils from '../../utils';

-export const VERSION = 6;
+export const VERSION = 7;

 /**
 * Implementation of a CryptoStore which is backed by an existing
@@ -38,7 +40,7 @@ export class Backend {
        // attempts to delete the database will block (and subsequent
        // attempts to re-create it will also block).
        db.onversionchange = (ev) => {
-            console.log(`versionchange for indexeddb ${this._dbName}: closing`);
+            logger.log(`versionchange for indexeddb ${this._dbName}: closing`);
            db.close();
        };
    }
@@ -64,7 +66,7 @@ export class Backend {
        this._getOutgoingRoomKeyRequest(txn, requestBody, (existing) => {
            if (existing) {
                // this entry matches the request - return it.
-                console.log(
+                logger.log(
                    `already have key request outstanding for ` +
                        `${requestBody.room_id} / ${requestBody.session_id}: ` +
                        `not sending another`,
@@ -75,7 +77,7 @@ export class Backend {

            // we got to the end of the list without finding a match
            // - add the new request.
-            console.log(
+            logger.log(
                `enqueueing key request for ${requestBody.room_id} / ` +
                    requestBody.session_id,
            );
@@ -204,6 +206,42 @@ export class Backend {
        return promiseifyTxn(txn).then(() => result);
    }

+    getOutgoingRoomKeyRequestsByTarget(userId, deviceId, wantedStates) {
+        let stateIndex = 0;
+        const results = [];
+
+        function onsuccess(ev) {
+            const cursor = ev.target.result;
+            if (cursor) {
+                const keyReq = cursor.value;
+                if (keyReq.recipients.includes({userId, deviceId})) {
+                    results.push(keyReq);
+                }
+                cursor.continue();
+            } else {
+                // try the next state in the list
+                stateIndex++;
+                if (stateIndex >= wantedStates.length) {
+                    // no matches
+                    return;
+                }
+
+                const wantedState = wantedStates[stateIndex];
+                const cursorReq = ev.target.source.openCursor(wantedState);
+                cursorReq.onsuccess = onsuccess;
+            }
+        }
+
+        const txn = this._db.transaction("outgoingRoomKeyRequests", "readonly");
+        const store = txn.objectStore("outgoingRoomKeyRequests");
+
+        const wantedState = wantedStates[stateIndex];
+        const cursorReq = store.index("state").openCursor(wantedState);
+        cursorReq.onsuccess = onsuccess;
+
+        return promiseifyTxn(txn).then(() => results);
+    }
+
    /**
     * Look for an existing room key request by id and state, and update it if
     * found
@@ -226,7 +264,7 @@ export class Backend {
            }
            const data = cursor.value;
            if (data.state != expectedState) {
-                console.warn(
+                logger.warn(
                    `Cannot update room key request from ${expectedState} ` +
                    `as it was already updated to ${data.state}`,
                );
@@ -264,7 +302,7 @@ export class Backend {
            }
            const data = cursor.value;
            if (data.state != expectedState) {
-                console.warn(
+                logger.warn(
                    `Cannot delete room key request in state ${data.state} `
                        + `(expected ${expectedState})`,
                );
@@ -312,7 +350,10 @@ export class Backend {
        getReq.onsuccess = function() {
            const cursor = getReq.result;
            if (cursor) {
-                results[cursor.value.sessionId] = cursor.value.session;
+                results[cursor.value.sessionId] = {
+                    session: cursor.value.session,
+                    lastReceivedMessageTs: cursor.value.lastReceivedMessageTs,
+                };
                cursor.continue();
            } else {
                try {
@@ -330,7 +371,10 @@ export class Backend {
        getReq.onsuccess = function() {
            try {
                if (getReq.result) {
-                    func(getReq.result.session);
+                    func({
+                        session: getReq.result.session,
+                        lastReceivedMessageTs: getReq.result.lastReceivedMessageTs,
+                    });
                } else {
                    func(null);
                }
@@ -340,9 +384,32 @@ export class Backend {
        };
    }

-    storeEndToEndSession(deviceKey, sessionId, session, txn) {
+    getAllEndToEndSessions(txn, func) {
        const objectStore = txn.objectStore("sessions");
-        objectStore.put({deviceKey, sessionId, session});
+        const getReq = objectStore.openCursor();
+        getReq.onsuccess = function() {
+            const cursor = getReq.result;
+            if (cursor) {
+                func(cursor.value);
+                cursor.continue();
+            } else {
+                try {
+                    func(null);
+                } catch (e) {
+                    abortWithException(txn, e);
+                }
+            }
+        };
+    }
+
+    storeEndToEndSession(deviceKey, sessionId, sessionInfo, txn) {
+        const objectStore = txn.objectStore("sessions");
+        objectStore.put({
+            deviceKey,
+            sessionId,
+            session: sessionInfo.session,
+            lastReceivedMessageTs: sessionInfo.lastReceivedMessageTs,
+        });
    }

    // Inbound group sessions
@@ -400,7 +467,7 @@ export class Backend {
                ev.stopPropagation();
                // ...and this stops it from aborting the transaction
                ev.preventDefault();
-                console.log(
+                logger.log(
                    "Ignoring duplicate inbound group session: " +
                    senderCurve25519Key + " / " + sessionId,
                );
@@ -460,6 +527,85 @@ export class Backend {
        };
    }

+    // session backups
+
+    getSessionsNeedingBackup(limit) {
+        return new Promise((resolve, reject) => {
+            const sessions = [];
+
+            const txn = this._db.transaction(
+                ["sessions_needing_backup", "inbound_group_sessions"],
+                "readonly",
+            );
+            txn.onerror = reject;
+            txn.oncomplete = function() {
+                resolve(sessions);
+            };
+            const objectStore = txn.objectStore("sessions_needing_backup");
+            const sessionStore = txn.objectStore("inbound_group_sessions");
+            const getReq = objectStore.openCursor();
+            getReq.onsuccess = function() {
+                const cursor = getReq.result;
+                if (cursor) {
+                    const sessionGetReq = sessionStore.get(cursor.key);
+                    sessionGetReq.onsuccess = function() {
+                        sessions.push({
+                            senderKey: sessionGetReq.result.senderCurve25519Key,
+                            sessionId: sessionGetReq.result.sessionId,
+                            sessionData: sessionGetReq.result.session,
+                        });
+                    };
+                    if (!limit || sessions.length < limit) {
+                        cursor.continue();
+                    }
+                }
+            };
+        });
+    }
+
+    countSessionsNeedingBackup(txn) {
+        if (!txn) {
+            txn = this._db.transaction("sessions_needing_backup", "readonly");
+        }
+        const objectStore = txn.objectStore("sessions_needing_backup");
+        return new Promise((resolve, reject) => {
+            const req = objectStore.count();
+            req.onerror = reject;
+            req.onsuccess = () => resolve(req.result);
+        });
+    }
+
+    unmarkSessionsNeedingBackup(sessions, txn) {
+        if (!txn) {
+            txn = this._db.transaction("sessions_needing_backup", "readwrite");
+        }
+        const objectStore = txn.objectStore("sessions_needing_backup");
+        return Promise.all(sessions.map((session) => {
+            return new Promise((resolve, reject) => {
+                const req = objectStore.delete([session.senderKey, session.sessionId]);
+                req.onsuccess = resolve;
+                req.onerror = reject;
+            });
+        }));
+    }
+
+    markSessionsNeedingBackup(sessions, txn) {
+        if (!txn) {
+            txn = this._db.transaction("sessions_needing_backup", "readwrite");
+        }
+        const objectStore = txn.objectStore("sessions_needing_backup");
+        return Promise.all(sessions.map((session) => {
+            return new Promise((resolve, reject) => {
+                const req = objectStore.put({
+                    senderCurve25519Key: session.senderKey,
+                    sessionId: session.sessionId,
+                });
+                req.onsuccess = resolve;
+                req.onerror = reject;
+            });
+        }));
+    }
+
    doTxn(mode, stores, func) {
        const txn = this._db.transaction(stores, mode);
        const promise = promiseifyTxn(txn);
@@ -471,7 +617,7 @@ export class Backend {
 }

 export function upgradeDatabase(db, oldVersion) {
-    console.log(
+    logger.log(
        `Upgrading IndexedDBCryptoStore from version ${oldVersion}`
            + ` to ${VERSION}`,
    );
@@ -498,6 +644,11 @@ export function upgradeDatabase(db, oldVersion) {
    if (oldVersion < 6) {
        db.createObjectStore("rooms");
    }
+    if (oldVersion < 7) {
+        db.createObjectStore("sessions_needing_backup", {
+            keyPath: ["senderCurve25519Key", "sessionId"],
+        });
+    }
    // Expand as needed.
 }

@@ -539,11 +690,12 @@ function promiseifyTxn(txn) {
            }
            resolve();
        };
-        txn.onerror = () => {
+        txn.onerror = (event) => {
            if (txn._mx_abortexception !== undefined) {
                reject(txn._mx_abortexception);
+            } else {
+                reject(event.target.error);
            }
-            reject();
        };
        txn.onabort = () => reject(txn._mx_abortexception);
    });
@@ -17,9 +17,11 @@ limitations under the License.

 import Promise from 'bluebird';

+import logger from '../../logger';
 import LocalStorageCryptoStore from './localStorage-crypto-store';
 import MemoryCryptoStore from './memory-crypto-store';
 import * as IndexedDBCryptoStoreBackend from './indexeddb-crypto-store-backend';
+import {InvalidCryptoStoreError} from '../../errors';

 /**
 * Internal module. indexeddb storage for e2e.
@@ -64,7 +66,7 @@ export default class IndexedDBCryptoStore {
                return;
            }

-            console.log(`connecting to indexeddb ${this._dbName}`);
+            logger.log(`connecting to indexeddb ${this._dbName}`);

            const req = this._indexedDB.open(
                this._dbName, IndexedDBCryptoStoreBackend.VERSION,
@@ -77,7 +79,7 @@ export default class IndexedDBCryptoStore {
            };

            req.onblocked = () => {
-                console.log(
+                logger.log(
                    `can't yet open IndexedDBCryptoStore because it is open elsewhere`,
                );
            };
@@ -89,7 +91,7 @@ export default class IndexedDBCryptoStore {
            req.onsuccess = (r) => {
                const db = r.target.result;

-                console.log(`connected to indexeddb ${this._dbName}`);
+                logger.log(`connected to indexeddb ${this._dbName}`);
                resolve(new IndexedDBCryptoStoreBackend.Backend(db));
            };
        }).then((backend) => {
@@ -106,16 +108,25 @@ export default class IndexedDBCryptoStore {
                },
            );
        }).catch((e) => {
-            console.warn(
+            if (e.name === 'VersionError') {
+                logger.warn("Crypto DB is too new for us to use!", e);
+                // don't fall back to a different store: the user has crypto data
+                // in this db so we should use it or nothing at all.
+                throw new InvalidCryptoStoreError(InvalidCryptoStoreError.TOO_NEW);
+            }
+            logger.warn(
                `unable to connect to indexeddb ${this._dbName}` +
                    `: falling back to localStorage store: ${e}`,
            );
-            return new LocalStorageCryptoStore(global.localStorage);
-        }).catch((e) => {
-            console.warn(
-                `unable to open localStorage: falling back to in-memory store: ${e}`,
-            );
-            return new MemoryCryptoStore();
+
+            try {
+                return new LocalStorageCryptoStore(global.localStorage);
+            } catch (e) {
+                logger.warn(
+                    `unable to open localStorage: falling back to in-memory store: ${e}`,
+                );
+                return new MemoryCryptoStore();
+            }
        });

        return this._backendPromise;
@@ -133,11 +144,11 @@ export default class IndexedDBCryptoStore {
                return;
            }

-            console.log(`Removing indexeddb instance: ${this._dbName}`);
+            logger.log(`Removing indexeddb instance: ${this._dbName}`);
            const req = this._indexedDB.deleteDatabase(this._dbName);

            req.onblocked = () => {
-                console.log(
+                logger.log(
                    `can't yet delete IndexedDBCryptoStore because it is open elsewhere`,
                );
            };
@@ -147,14 +158,14 @@ export default class IndexedDBCryptoStore {
            };

            req.onsuccess = () => {
-                console.log(`Removed indexeddb instance: ${this._dbName}`);
+                logger.log(`Removed indexeddb instance: ${this._dbName}`);
                resolve();
            };
        }).catch((e) => {
            // in firefox, with indexedDB disabled, this fails with a
            // DOMError. We treat this as non-fatal, so that people can
            // still use the app.
-            console.warn(`unable to delete IndexedDBCryptoStore: ${e}`);
+            logger.warn(`unable to delete IndexedDBCryptoStore: ${e}`);
        });
    }

@@ -206,6 +217,24 @@ export default class IndexedDBCryptoStore {
        });
    }

+    /**
+     * Look for room key requests by target device and state
+     *
+     * @param {string} userId Target user ID
+     * @param {string} deviceId Target device ID
+     * @param {Array<Number>} wantedStates list of acceptable states
+     *
+     * @return {Promise} resolves to a list of all the
+     *    {@link module:crypto/store/base~OutgoingRoomKeyRequest}
+     */
+    getOutgoingRoomKeyRequestsByTarget(userId, deviceId, wantedStates) {
+        return this._connect().then((backend) => {
+            return backend.getOutgoingRoomKeyRequestsByTarget(
+                userId, deviceId, wantedStates,
+            );
+        });
+    }
+
    /**
     * Look for an existing room key request by id and state, and update it if
     * found
@@ -283,7 +312,10 @@ export default class IndexedDBCryptoStore {
     * @param {string} sessionId The ID of the session to retrieve
     * @param {*} txn An active transaction. See doTxn().
     * @param {function(object)} func Called with A map from sessionId
-     *     to Base64 end-to-end session.
+     *     to session information object with 'session' key being the
+     *     Base64 end-to-end session and lastReceivedMessageTs being the
+     *     timestamp in milliseconds at which the session last received
+     *     a message.
     */
    getEndToEndSession(deviceKey, sessionId, txn, func) {
        this._backendPromise.value().getEndToEndSession(deviceKey, sessionId, txn, func);
@@ -295,22 +327,36 @@ export default class IndexedDBCryptoStore {
     * @param {string} deviceKey The public key of the other device.
     * @param {*} txn An active transaction. See doTxn().
     * @param {function(object)} func Called with A map from sessionId
-     *     to Base64 end-to-end session.
+     *     to session information object with 'session' key being the
+     *     Base64 end-to-end session and lastReceivedMessageTs being the
+     *     timestamp in milliseconds at which the session last received
+     *     a message.
     */
    getEndToEndSessions(deviceKey, txn, func) {
        this._backendPromise.value().getEndToEndSessions(deviceKey, txn, func);
    }

+    /**
+     * Retrieve all end-to-end sessions
+     * @param {*} txn An active transaction. See doTxn().
+     * @param {function(object)} func Called one for each session with
+     *     an object with, deviceKey, lastReceivedMessageTs, sessionId
+     *     and session keys.
+     */
+    getAllEndToEndSessions(txn, func) {
+        this._backendPromise.value().getAllEndToEndSessions(txn, func);
+    }
+
    /**
     * Store a session between the logged-in user and another device
     * @param {string} deviceKey The public key of the other device.
     * @param {string} sessionId The ID for this end-to-end session.
-     * @param {string} session Base64 encoded end-to-end session.
+     * @param {string} sessionInfo Session information object
     * @param {*} txn An active transaction. See doTxn().
     */
-    storeEndToEndSession(deviceKey, sessionId, session, txn) {
+    storeEndToEndSession(deviceKey, sessionId, sessionInfo, txn) {
        this._backendPromise.value().storeEndToEndSession(
-            deviceKey, sessionId, session, txn,
+            deviceKey, sessionId, sessionInfo, txn,
        );
    }

@@ -420,6 +466,55 @@ export default class IndexedDBCryptoStore {
        this._backendPromise.value().getEndToEndRooms(txn, func);
    }

+    // session backups
+
+    /**
+     * Get the inbound group sessions that need to be backed up.
+     * @param {integer} limit The maximum number of sessions to retrieve.  0
+     * for no limit.
+     * @returns {Promise} resolves to an array of inbound group sessions
+     */
+    getSessionsNeedingBackup(limit) {
+        return this._connect().then((backend) => {
+            return backend.getSessionsNeedingBackup(limit);
+        });
+    }
+
+    /**
+     * Count the inbound group sessions that need to be backed up.
+     * @param {*} txn An active transaction. See doTxn(). (optional)
+     * @returns {Promise} resolves to the number of sessions
+     */
+    countSessionsNeedingBackup(txn) {
+        return this._connect().then((backend) => {
+            return backend.countSessionsNeedingBackup(txn);
+        });
+    }
+
+    /**
+     * Unmark sessions as needing to be backed up.
+     * @param {Array<object>} sessions The sessions that need to be backed up.
+     * @param {*} txn An active transaction. See doTxn(). (optional)
+     * @returns {Promise} resolves when the sessions are unmarked
+     */
+    unmarkSessionsNeedingBackup(sessions, txn) {
+        return this._connect().then((backend) => {
+            return backend.unmarkSessionsNeedingBackup(sessions, txn);
+        });
+    }
+
+    /**
+     * Mark sessions as needing to be backed up.
+     * @param {Array<object>} sessions The sessions that need to be backed up.
+     * @param {*} txn An active transaction. See doTxn(). (optional)
+     * @returns {Promise} resolves when the sessions are marked
+     */
+    markSessionsNeedingBackup(sessions, txn) {
+        return this._connect().then((backend) => {
+            return backend.markSessionsNeedingBackup(sessions, txn);
+        });
+    }
+
    /**
     * Perform a transaction on the crypto store. Any store methods
     * that require a transaction (txn) object to be passed in may
@@ -453,3 +548,4 @@ IndexedDBCryptoStore.STORE_SESSIONS = 'sessions';
 IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS = 'inbound_group_sessions';
 IndexedDBCryptoStore.STORE_DEVICE_DATA = 'device_data';
 IndexedDBCryptoStore.STORE_ROOMS = 'rooms';
+IndexedDBCryptoStore.STORE_BACKUP = 'sessions_needing_backup';
@@ -15,6 +15,8 @@ limitations under the License.
 */

 import Promise from 'bluebird';
+
+import logger from '../../logger';
 import MemoryCryptoStore from './memory-crypto-store.js';

 /**
@@ -32,6 +34,7 @@ const KEY_END_TO_END_ACCOUNT = E2E_PREFIX + "account";
 const KEY_DEVICE_DATA = E2E_PREFIX + "device_data";
 const KEY_INBOUND_SESSION_PREFIX = E2E_PREFIX + "inboundgroupsessions/";
 const KEY_ROOMS_PREFIX = E2E_PREFIX + "rooms/";
+const KEY_SESSIONS_NEEDING_BACKUP = E2E_PREFIX + "sessionsneedingbackup";

 function keyEndToEndSessions(deviceKey) {
    return E2E_PREFIX + "sessions/" + deviceKey;
@@ -65,7 +68,21 @@ export default class LocalStorageCryptoStore extends MemoryCryptoStore {
    }

    _getEndToEndSessions(deviceKey, txn, func) {
-        return getJsonItem(this.store, keyEndToEndSessions(deviceKey));
+        const sessions = getJsonItem(this.store, keyEndToEndSessions(deviceKey));
+        const fixedSessions = {};
+
+        // fix up any old sessions to be objects rather than just the base64 pickle
+        for (const [sid, val] of Object.entries(sessions || {})) {
+            if (typeof val === 'string') {
+                fixedSessions[sid] = {
+                    session: val,
+                };
+            } else {
+                fixedSessions[sid] = val;
+            }
+        }
+
+        return fixedSessions;
    }

    getEndToEndSession(deviceKey, sessionId, txn, func) {
@@ -77,9 +94,20 @@ export default class LocalStorageCryptoStore extends MemoryCryptoStore {
        func(this._getEndToEndSessions(deviceKey) || {});
    }

-    storeEndToEndSession(deviceKey, sessionId, session, txn) {
+    getAllEndToEndSessions(txn, func) {
+        for (let i = 0; i < this.store.length; ++i) {
+            if (this.store.key(i).startsWith(keyEndToEndSessions(''))) {
+                const deviceKey = this.store.key(i).split('/')[1];
+                for (const sess of Object.values(this._getEndToEndSessions(deviceKey))) {
+                    func(sess);
+                }
+            }
+        }
+    }
+
+    storeEndToEndSession(deviceKey, sessionId, sessionInfo, txn) {
        const sessions = this._getEndToEndSessions(deviceKey) || {};
-        sessions[sessionId] = session;
+        sessions[sessionId] = sessionInfo;
        setJsonItem(
            this.store, keyEndToEndSessions(deviceKey), sessions,
        );
@@ -165,6 +193,64 @@ export default class LocalStorageCryptoStore extends MemoryCryptoStore {
        func(result);
    }

+    getSessionsNeedingBackup(limit) {
+        const sessionsNeedingBackup
+              = getJsonItem(this.store, KEY_SESSIONS_NEEDING_BACKUP) || {};
+        const sessions = [];
+
+        for (const session in sessionsNeedingBackup) {
+            if (Object.prototype.hasOwnProperty.call(sessionsNeedingBackup, session)) {
+                // see getAllEndToEndInboundGroupSessions for the magic number explanations
+                const senderKey = session.substr(0, 43);
+                const sessionId = session.substr(44);
+                this.getEndToEndInboundGroupSession(
+                    senderKey, sessionId, null,
+                    (sessionData) => {
+                        sessions.push({
+                            senderKey: senderKey,
+                            sessionId: sessionId,
+                            sessionData: sessionData,
+                        });
+                    },
+                );
+                if (limit && session.length >= limit) {
+                    break;
+                }
+            }
+        }
+        return Promise.resolve(sessions);
+    }
+
+    countSessionsNeedingBackup() {
+        const sessionsNeedingBackup
+              = getJsonItem(this.store, KEY_SESSIONS_NEEDING_BACKUP) || {};
+        return Promise.resolve(Object.keys(sessionsNeedingBackup).length);
+    }
+
+    unmarkSessionsNeedingBackup(sessions) {
+        const sessionsNeedingBackup
+              = getJsonItem(this.store, KEY_SESSIONS_NEEDING_BACKUP) || {};
+        for (const session of sessions) {
+            delete sessionsNeedingBackup[session.senderKey + '/' + session.sessionId];
+        }
+        setJsonItem(
+            this.store, KEY_SESSIONS_NEEDING_BACKUP, sessionsNeedingBackup,
+        );
+        return Promise.resolve();
+    }
+
+    markSessionsNeedingBackup(sessions) {
+        const sessionsNeedingBackup
+              = getJsonItem(this.store, KEY_SESSIONS_NEEDING_BACKUP) || {};
+        for (const session of sessions) {
+            sessionsNeedingBackup[session.senderKey + '/' + session.sessionId] = true;
+        }
+        setJsonItem(
+            this.store, KEY_SESSIONS_NEEDING_BACKUP, sessionsNeedingBackup,
+        );
+        return Promise.resolve();
+    }
+
    /**
     * Delete all data from this store.
     *
@@ -199,8 +285,8 @@ function getJsonItem(store, key) {
        // JSON.parse(null) === null, so this returns null.
        return JSON.parse(store.getItem(key));
    } catch (e) {
-        console.log("Error: Failed to get key %s: %s", key, e.stack || e);
-        console.log(e.stack);
+        logger.log("Error: Failed to get key %s: %s", key, e.stack || e);
+        logger.log(e.stack);
    }
    return null;
 }
@@ -17,6 +17,7 @@ limitations under the License.

 import Promise from 'bluebird';

+import logger from '../../logger';
 import utils from '../../utils';

 /**
@@ -41,6 +42,8 @@ export default class MemoryCryptoStore {
        this._deviceData = null;
        // roomId -> Opaque roomInfo object
        this._rooms = {};
+        // Set of {senderCurve25519Key+'/'+sessionId}
+        this._sessionsNeedingBackup = {};
    }

    /**
@@ -71,7 +74,7 @@ export default class MemoryCryptoStore {

            if (existing) {
                // this entry matches the request - return it.
-                console.log(
+                logger.log(
                    `already have key request outstanding for ` +
                    `${requestBody.room_id} / ${requestBody.session_id}: ` +
                    `not sending another`,
@@ -81,7 +84,7 @@ export default class MemoryCryptoStore {

            // we got to the end of the list without finding a match
            // - add the new request.
-            console.log(
+            logger.log(
                `enqueueing key request for ${requestBody.room_id} / ` +
                requestBody.session_id,
            );
@@ -144,6 +147,19 @@ export default class MemoryCryptoStore {
        return Promise.resolve(null);
    }

+    getOutgoingRoomKeyRequestsByTarget(userId, deviceId, wantedStates) {
+        const results = [];
+
+        for (const req of this._outgoingRoomKeyRequests) {
+            for (const state of wantedStates) {
+                if (req.state === state && req.recipients.includes({userId, deviceId})) {
+                    results.push(req);
+                }
+            }
+        }
+        return Promise.resolve(results);
+    }
+
    /**
     * Look for an existing room key request by id and state, and update it if
     * found
@@ -163,7 +179,7 @@ export default class MemoryCryptoStore {
            }

            if (req.state != expectedState) {
-                console.warn(
+                logger.warn(
                    `Cannot update room key request from ${expectedState} ` +
                    `as it was already updated to ${req.state}`,
                );
@@ -194,7 +210,7 @@ export default class MemoryCryptoStore {
            }

            if (req.state != expectedState) {
-                console.warn(
+                logger.warn(
                    `Cannot delete room key request in state ${req.state} `
                    + `(expected ${expectedState})`,
                );
@@ -233,13 +249,21 @@ export default class MemoryCryptoStore {
        func(this._sessions[deviceKey] || {});
    }

-    storeEndToEndSession(deviceKey, sessionId, session, txn) {
+    getAllEndToEndSessions(txn, func) {
+        for (const deviceSessions of Object.values(this._sessions)) {
+            for (const sess of Object.values(deviceSessions)) {
+                func(sess);
+            }
+        }
+    }
+
+    storeEndToEndSession(deviceKey, sessionId, sessionInfo, txn) {
        let deviceSessions = this._sessions[deviceKey];
        if (deviceSessions === undefined) {
            deviceSessions = {};
            this._sessions[deviceKey] = deviceSessions;
        }
-        deviceSessions[sessionId] = session;
+        deviceSessions[sessionId] = sessionInfo;
    }

    // Inbound Group Sessions
@@ -295,6 +319,45 @@ export default class MemoryCryptoStore {
        func(this._rooms);
    }

+    getSessionsNeedingBackup(limit) {
+        const sessions = [];
+        for (const session in this._sessionsNeedingBackup) {
+            if (this._inboundGroupSessions[session]) {
+                sessions.push({
+                    senderKey: session.substr(0, 43),
+                    sessionId: session.substr(44),
+                    sessionData: this._inboundGroupSessions[session],
+                });
+                if (limit && session.length >= limit) {
+                    break;
+                }
+            }
+        }
+        return Promise.resolve(sessions);
+    }
+
+    countSessionsNeedingBackup() {
+        return Promise.resolve(Object.keys(this._sessionsNeedingBackup).length);
+    }
+
+    unmarkSessionsNeedingBackup(sessions) {
+        for (const session of sessions) {
+            const sessionKey = session.senderKey + '/' + session.sessionId;
+            delete this._sessionsNeedingBackup[sessionKey];
+        }
+        return Promise.resolve();
+    }
+
+    markSessionsNeedingBackup(sessions) {
+        for (const session of sessions) {
+            const sessionKey = session.senderKey + '/' + session.sessionId;
+            this._sessionsNeedingBackup[sessionKey] = true;
+        }
+        return Promise.resolve();
+    }
+
+    // Session key backups
+
    doTxn(mode, stores, func) {
        return Promise.resolve(func(null));
    }
@@ -0,0 +1,200 @@
+/*
+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.
+*/
+
+/**
+ * Base class for verification methods.
+ * @module crypto/verification/Base
+ */
+
+import {MatrixEvent} from '../../models/event';
+import {EventEmitter} from 'events';
+
+export default class VerificationBase extends EventEmitter {
+    /**
+     * Base class for verification methods.
+     *
+     * <p>Once a verifier object is created, the verification can be started by
+     * calling the verify() method, which will return a promise that will
+     * resolve when the verification is completed, or reject if it could not
+     * complete.</p>
+     *
+     * <p>Subclasses must have a NAME class property.</p>
+     *
+     * @class
+     *
+     * @param {module:base-apis~MatrixBaseApis} baseApis base matrix api interface
+     *
+     * @param {string} userId the user ID that is being verified
+     *
+     * @param {string} deviceId the device ID that is being verified
+     *
+     * @param {string} transactionId the transaction ID to be used when sending events
+     *
+     * @param {object} startEvent the m.key.verification.start event that
+     * initiated this verification, if any
+     *
+     * @param {object} request the key verification request object related to
+     * this verification, if any
+     *
+     * @param {object} parent parent verification for this verification, if any
+     */
+    constructor(baseApis, userId, deviceId, transactionId, startEvent, request, parent) {
+        super();
+        this._baseApis = baseApis;
+        this.userId = userId;
+        this.deviceId = deviceId;
+        this.transactionId = transactionId;
+        this.startEvent = startEvent;
+        this.request = request;
+        this._parent = parent;
+        this._done = false;
+        this._promise = null;
+    }
+
+    _sendToDevice(type, content) {
+        if (this._done) {
+            return Promise.reject(new Error("Verification is already done"));
+        }
+        content.transaction_id = this.transactionId;
+        return this._baseApis.sendToDevice(type, {
+            [this.userId]: { [this.deviceId]: content },
+        });
+    }
+
+    _waitForEvent(type) {
+        if (this._done) {
+            return Promise.reject(new Error("Verification is already done"));
+        }
+        this._expectedEvent = type;
+        return new Promise((resolve, reject) => {
+            this._resolveEvent = resolve;
+            this._rejectEvent = reject;
+        });
+    }
+
+    handleEvent(e) {
+        if (this._done) {
+            return;
+        } else if (e.getType() === this._expectedEvent) {
+            this._expectedEvent = undefined;
+            this._rejectEvent = undefined;
+            this._resolveEvent(e);
+        } else {
+            this._expectedEvent = undefined;
+            const exception = new Error(
+                "Unexpected message: expecting " + this._expectedEvent
+                    + " but got " + e.getType(),
+            );
+            if (this._rejectEvent) {
+                const reject = this._rejectEvent;
+                this._rejectEvent = undefined;
+                reject(exception);
+            }
+            this.cancel(exception);
+        }
+    }
+
+    done() {
+        if (!this._done) {
+            this._resolve();
+        }
+    }
+
+    cancel(e) {
+        if (!this._done) {
+            if (this.userId && this.deviceId && this.transactionId) {
+                // send a cancellation to the other user (if it wasn't
+                // cancelled by the other user)
+                if (e instanceof MatrixEvent) {
+                    const sender = e.getSender();
+                    if (sender !== this.userId) {
+                        const content = e.getContent();
+                        if (e.getType() === "m.key.verification.cancel") {
+                            content.code = content.code || "m.unknown";
+                            content.reason = content.reason || content.body
+                                || "Unknown reason";
+                            content.transaction_id = this.transactionId;
+                            this._sendToDevice("m.key.verification.cancel", content);
+                        } else {
+                            this._sendToDevice("m.key.verification.cancel", {
+                                code: "m.unknown",
+                                reason: content.body || "Unknown reason",
+                                transaction_id: this.transactionId,
+                            });
+                        }
+                    }
+                } else {
+                    this._sendToDevice("m.key.verification.cancel", {
+                        code: "m.unknown",
+                        reason: e.toString(),
+                        transaction_id: this.transactionId,
+                    });
+                }
+            }
+            if (this._promise !== null) {
+                this._reject(e);
+            } else {
+                this._promise = Promise.reject(e);
+            }
+            // Also emit a 'cancel' event that the app can listen for to detect cancellation
+            // before calling verify()
+            this.emit('cancel', e);
+        }
+    }
+
+    /**
+     * Begin the key verification
+     *
+     * @returns {Promise} Promise which resolves when the verification has
+     *     completed.
+     */
+    verify() {
+        if (this._promise) return this._promise;
+
+        this._promise = new Promise((resolve, reject) => {
+            this._resolve = (...args) => {
+                this._done = true;
+                resolve(...args);
+            };
+            this._reject = (...args) => {
+                this._done = true;
+                reject(...args);
+            };
+        });
+        if (this._doVerification && !this._started) {
+            this._started = true;
+            Promise.resolve(this._doVerification())
+                .then(this.done.bind(this), this.cancel.bind(this));
+        }
+        return this._promise;
+    }
+
+    async _verifyKeys(userId, keys, verifier) {
+        for (const [keyId, keyInfo] of Object.entries(keys)) {
+            const deviceId = keyId.split(':', 2)[1];
+            const device = await this._baseApis.getStoredDevice(userId, deviceId);
+            if (!device) {
+                throw new Error(`Could not find device ${deviceId}`);
+            } else {
+                await verifier(keyId, device, keyInfo);
+            }
+        }
+        for (const keyId of Object.keys(keys)) {
+            const deviceId = keyId.split(':', 2)[1];
+            await this._baseApis.setDeviceVerified(userId, deviceId);
+        }
+    }
+}
@@ -0,0 +1,87 @@
+/*
+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.
+*/
+
+/**
+ * Error messages.
+ *
+ * @module crypto/verification/Error
+ */
+
+import {MatrixEvent} from "../../models/event";
+
+export function newVerificationError(code, reason, extradata) {
+    extradata = extradata || {};
+    extradata.code = code;
+    extradata.reason = reason;
+    return new MatrixEvent({
+        type: "m.key.verification.cancel",
+        content: extradata,
+    });
+}
+
+export function errorFactory(code, reason) {
+    return function(extradata) {
+        return newVerificationError(code, reason, extradata);
+    };
+}
+
+/**
+ * The verification was cancelled by the user.
+ */
+export const newUserCancelledError = errorFactory("m.user", "Cancelled by user");
+
+/**
+ * The verification timed out.
+ */
+export const newTimeoutError = errorFactory("m.timeout", "Timed out");
+
+/**
+ * The transaction is unknown.
+ */
+export const newUnknownTransactionError = errorFactory(
+    "m.unknown_transaction", "Unknown transaction",
+);
+
+/**
+ * An unknown method was selected.
+ */
+export const newUnknownMethodError = errorFactory("m.unknown_method", "Unknown method");
+
+/**
+ * An unexpected message was sent.
+ */
+export const newUnexpectedMessageError = errorFactory(
+    "m.unexpected_message", "Unexpected message",
+);
+
+/**
+ * The key does not match.
+ */
+export const newKeyMismatchError = errorFactory(
+    "m.key_mismatch", "Key mismatch",
+);
+
+/**
+ * The user does not match.
+ */
+export const newUserMismatchError = errorFactory("m.user_error", "User mismatch");
+
+/**
+ * An invalid message was sent.
+ */
+export const newInvalidMessageError = errorFactory(
+    "m.invalid_message", "Invalid message",
+);
@@ -0,0 +1,123 @@
+/*
+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.
+*/
+
+/**
+ * QR code key verification.
+ * @module crypto/verification/QRCode
+ */
+
+import Base from "./Base";
+import {
+    errorFactory,
+    newUserCancelledError,
+    newKeyMismatchError,
+    newUserMismatchError,
+} from './Error';
+
+const MATRIXTO_REGEXP = /^(?:https?:\/\/)?(?:www\.)?matrix\.to\/#\/([#@!+][^?]+)\?(.+)$/;
+const KEY_REGEXP = /^key_([^:]+:.+)$/;
+
+const newQRCodeError = errorFactory("m.qr_code.invalid", "Invalid QR code");
+
+/**
+ * @class crypto/verification/QRCode/ShowQRCode
+ * @extends {module:crypto/verification/Base}
+ */
+export class ShowQRCode extends Base {
+    _doVerification() {
+        if (!this._done) {
+            const url = "https://matrix.to/#/" + this._baseApis.getUserId()
+                  + "?device=" + encodeURIComponent(this._baseApis.deviceId)
+                  + "&action=verify&key_ed25519%3A"
+                  + encodeURIComponent(this._baseApis.deviceId) + "="
+                  + encodeURIComponent(this._baseApis.getDeviceEd25519Key());
+            this.emit("show_qr_code", {
+                url: url,
+            });
+        }
+    }
+}
+
+ShowQRCode.NAME = "m.qr_code.show.v1";
+
+/**
+ * @class crypto/verification/QRCode/ScanQRCode
+ * @extends {module:crypto/verification/Base}
+ */
+export class ScanQRCode extends Base {
+    static factory(...args) {
+        return new ScanQRCode(...args);
+    }
+
+    async _doVerification() {
+        const code = await new Promise((resolve, reject) => {
+            this.emit("scan", {
+                done: resolve,
+                cancel: () => reject(newUserCancelledError()),
+            });
+        });
+
+        const match = code.match(MATRIXTO_REGEXP);
+        let deviceId;
+        const keys = {};
+        if (!match) {
+            throw newQRCodeError();
+        }
+        const userId = match[1];
+        const params = match[2].split("&").map(
+            (x) => x.split("=", 2).map(decodeURIComponent),
+        );
+        let action;
+        for (const [name, value] of params) {
+            if (name === "device") {
+                deviceId = value;
+            } else if (name === "action") {
+                action = value;
+            } else {
+                const keyMatch = name.match(KEY_REGEXP);
+                if (keyMatch) {
+                    keys[keyMatch[1]] = value;
+                }
+            }
+        }
+        if (!deviceId || action !== "verify" || Object.keys(keys).length === 0) {
+            throw newQRCodeError();
+        }
+
+        if (!this.userId) {
+            await new Promise((resolve, reject) => {
+                this.emit("confirm_user_id", {
+                    userId: userId,
+                    confirm: resolve,
+                    cancel: () => reject(newUserMismatchError()),
+                });
+            });
+        } else if (this.userId !== userId) {
+            throw newUserMismatchError({
+                expected: this.userId,
+                actual: userId,
+            });
+        }
+
+        await this._verifyKeys(userId, keys, (keyId, device, key) => {
+            if (device.keys[keyId] !== key) {
+                throw newKeyMismatchError();
+            }
+        });
+    }
+}
+
+ScanQRCode.NAME = "m.qr_code.scan.v1";
@@ -0,0 +1,368 @@
+/*
+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.
+*/
+
+/**
+ * Short Authentication String (SAS) verification.
+ * @module crypto/verification/SAS
+ */
+
+import Base from "./Base";
+import anotherjson from 'another-json';
+import {
+    errorFactory,
+    newUserCancelledError,
+    newUnknownMethodError,
+    newKeyMismatchError,
+    newInvalidMessageError,
+} from './Error';
+
+const EVENTS = [
+    "m.key.verification.accept",
+    "m.key.verification.key",
+    "m.key.verification.mac",
+];
+
+let olmutil;
+
+const newMismatchedSASError = errorFactory(
+    "m.mismatched_sas", "Mismatched short authentication string",
+);
+
+const newMismatchedCommitmentError = errorFactory(
+    "m.mismatched_commitment", "Mismatched commitment",
+);
+
+function generateDecimalSas(sasBytes) {
+    /**
+     *      +--------+--------+--------+--------+--------+
+     *      | Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 |
+     *      +--------+--------+--------+--------+--------+
+     * bits: 87654321 87654321 87654321 87654321 87654321
+     *       \____________/\_____________/\____________/
+     *         1st number    2nd number     3rd number
+     */
+    return [
+        (sasBytes[0] << 5 | sasBytes[1] >> 3) + 1000,
+        ((sasBytes[1] & 0x7) << 10 | sasBytes[2] << 2 | sasBytes[3] >> 6) + 1000,
+        ((sasBytes[3] & 0x3f) << 7 | sasBytes[4] >> 1) + 1000,
+    ];
+}
+
+const emojiMapping = [
+    ["🐶", "dog"],        //  0
+    ["🐱", "cat"],        //  1
+    ["🦁", "lion"],       //  2
+    ["🐎", "horse"],      //  3
+    ["🦄", "unicorn"],    //  4
+    ["🐷", "pig"],        //  5
+    ["🐘", "elephant"],   //  6
+    ["🐰", "rabbit"],     //  7
+    ["🐼", "panda"],      //  8
+    ["🐓", "rooster"],    //  9
+    ["🐧", "penguin"],    // 10
+    ["🐢", "turtle"],     // 11
+    ["🐟", "fish"],       // 12
+    ["🐙", "octopus"],    // 13
+    ["🦋", "butterfly"],  // 14
+    ["🌷", "flower"],     // 15
+    ["🌳", "tree"],       // 16
+    ["🌵", "cactus"],     // 17
+    ["🍄", "mushroom"],   // 18
+    ["🌏", "globe"],      // 19
+    ["🌙", "moon"],       // 20
+    ["☁️", "cloud"],       // 21
+    ["🔥", "fire"],       // 22
+    ["🍌", "banana"],     // 23
+    ["🍎", "apple"],      // 24
+    ["🍓", "strawberry"], // 25
+    ["🌽", "corn"],       // 26
+    ["🍕", "pizza"],      // 27
+    ["🎂", "cake"],       // 28
+    ["❤️", "heart"],      // 29
+    ["🙂", "smiley"],      // 30
+    ["🤖", "robot"],      // 31
+    ["🎩", "hat"],        // 32
+    ["👓", "glasses"],    // 33
+    ["🔧", "spanner"],     // 34
+    ["🎅", "santa"],      // 35
+    ["👍", "thumbs up"],  // 36
+    ["☂️", "umbrella"],    // 37
+    ["⌛", "hourglass"],   // 38
+    ["⏰", "clock"],      // 39
+    ["🎁", "gift"],       // 40
+    ["💡", "light bulb"], // 41
+    ["📕", "book"],       // 42
+    ["✏️", "pencil"],     // 43
+    ["📎", "paperclip"],  // 44
+    ["✂️", "scissors"],    // 45
+    ["🔒", "padlock"],    // 46
+    ["🔑", "key"],        // 47
+    ["🔨", "hammer"],     // 48
+    ["☎️", "telephone"],  // 49
+    ["🏁", "flag"],       // 50
+    ["🚂", "train"],      // 51
+    ["🚲", "bicycle"],    // 52
+    ["✈️", "aeroplane"],   // 53
+    ["🚀", "rocket"],     // 54
+    ["🏆", "trophy"],     // 55
+    ["⚽", "ball"],       // 56
+    ["🎸", "guitar"],     // 57
+    ["🎺", "trumpet"],    // 58
+    ["🔔", "bell"],       // 59
+    ["⚓️", "anchor"],     // 60
+    ["🎧", "headphones"], // 61
+    ["📁", "folder"],     // 62
+    ["📌", "pin"],        // 63
+];
+
+function generateEmojiSas(sasBytes) {
+    const emojis = [
+        // just like base64 encoding
+        sasBytes[0] >> 2,
+        (sasBytes[0] & 0x3) << 4 | sasBytes[1] >> 4,
+        (sasBytes[1] & 0xf) << 2 | sasBytes[2] >> 6,
+        sasBytes[2] & 0x3f,
+        sasBytes[3] >> 2,
+        (sasBytes[3] & 0x3) << 4 | sasBytes[4] >> 4,
+        (sasBytes[4] & 0xf) << 2 | sasBytes[5] >> 6,
+    ];
+
+    return emojis.map((num) => emojiMapping[num]);
+}
+
+function generateSas(sasBytes, methods) {
+    const sas = {};
+    if (methods.includes("decimal")) {
+        sas["decimal"] = generateDecimalSas(sasBytes);
+    }
+    if (methods.includes("emoji")) {
+        sas["emoji"] = generateEmojiSas(sasBytes);
+    }
+    return sas;
+}
+
+/**
+ * @alias module:crypto/verification/SAS
+ * @extends {module:crypto/verification/Base}
+ */
+export default class SAS extends Base {
+    get events() {
+        return EVENTS;
+    }
+
+    async _doVerification() {
+        await global.Olm.init();
+        olmutil = olmutil || new global.Olm.Utility();
+
+        // make sure user's keys are downloaded
+        await this._baseApis.downloadKeys([this.userId]);
+
+        if (this.startEvent) {
+            return await this._doRespondVerification();
+        } else {
+            return await this._doSendVerification();
+        }
+    }
+
+    async _doSendVerification() {
+        const initialMessage = {
+            method: SAS.NAME,
+            from_device: this._baseApis.deviceId,
+            key_agreement_protocols: ["curve25519"],
+            hashes: ["sha256"],
+            message_authentication_codes: ["hmac-sha256"],
+            // FIXME: allow app to specify what SAS methods can be used
+            short_authentication_string: ["decimal", "emoji"],
+            transaction_id: this.transactionId,
+        };
+        this._sendToDevice("m.key.verification.start", initialMessage);
+
+
+        let e = await this._waitForEvent("m.key.verification.accept");
+        let content = e.getContent();
+        if (!(content.key_agreement_protocol === "curve25519"
+              && content.hash === "sha256"
+              && content.message_authentication_code === "hmac-sha256"
+              && content.short_authentication_string instanceof Array
+              && (content.short_authentication_string.includes("decimal")
+                  || content.short_authentication_string.includes("emoji")))) {
+            throw newUnknownMethodError();
+        }
+        if (typeof content.commitment !== "string") {
+            throw newInvalidMessageError();
+        }
+        const hashCommitment = content.commitment;
+        const sasMethods = content.short_authentication_string;
+        const olmSAS = new global.Olm.SAS();
+        try {
+            this._sendToDevice("m.key.verification.key", {
+                key: olmSAS.get_pubkey(),
+            });
+
+
+            e = await this._waitForEvent("m.key.verification.key");
+            // FIXME: make sure event is properly formed
+            content = e.getContent();
+            const commitmentStr = content.key + anotherjson.stringify(initialMessage);
+            if (olmutil.sha256(commitmentStr) !== hashCommitment) {
+                throw newMismatchedCommitmentError();
+            }
+            olmSAS.set_their_key(content.key);
+
+            const sasInfo = "MATRIX_KEY_VERIFICATION_SAS"
+                  + this._baseApis.getUserId() + this._baseApis.deviceId
+                  + this.userId + this.deviceId
+                  + this.transactionId;
+            const sasBytes = olmSAS.generate_bytes(sasInfo, 6);
+            const verifySAS = new Promise((resolve, reject) => {
+                this.emit("show_sas", {
+                    sas: generateSas(sasBytes, sasMethods),
+                    confirm: () => {
+                        this._sendMAC(olmSAS);
+                        resolve();
+                    },
+                    cancel: () => reject(newUserCancelledError()),
+                    mismatch: () => reject(newMismatchedSASError()),
+                });
+            });
+
+
+            [e] = await Promise.all([
+                this._waitForEvent("m.key.verification.mac"),
+                verifySAS,
+            ]);
+            content = e.getContent();
+            await this._checkMAC(olmSAS, content);
+        } finally {
+            olmSAS.free();
+        }
+    }
+
+    async _doRespondVerification() {
+        let content = this.startEvent.getContent();
+        if (!(content.key_agreement_protocols instanceof Array
+              && content.key_agreement_protocols.includes("curve25519")
+              && content.hashes instanceof Array
+              && content.hashes.includes("sha256")
+              && content.message_authentication_codes instanceof Array
+              && content.message_authentication_codes.includes("hmac-sha256")
+              && content.short_authentication_string instanceof Array
+              && (content.short_authentication_string.includes("decimal")
+                  || content.short_authentication_string.includes("emoji")))) {
+            throw newUnknownMethodError();
+        }
+
+        const olmSAS = new global.Olm.SAS();
+        const sasMethods = [];
+        // FIXME: allow app to specify what SAS methods can be used
+        if (content.short_authentication_string.includes("decimal")) {
+            sasMethods.push("decimal");
+        }
+        if (content.short_authentication_string.includes("emoji")) {
+            sasMethods.push("emoji");
+        }
+        try {
+            const commitmentStr = olmSAS.get_pubkey() + anotherjson.stringify(content);
+            this._sendToDevice("m.key.verification.accept", {
+                key_agreement_protocol: "curve25519",
+                hash: "sha256",
+                message_authentication_code: "hmac-sha256",
+                short_authentication_string: sasMethods,
+                commitment: olmutil.sha256(commitmentStr),
+            });
+
+
+            let e = await this._waitForEvent("m.key.verification.key");
+            // FIXME: make sure event is properly formed
+            content = e.getContent();
+            olmSAS.set_their_key(content.key);
+            this._sendToDevice("m.key.verification.key", {
+                key: olmSAS.get_pubkey(),
+            });
+
+            const sasInfo = "MATRIX_KEY_VERIFICATION_SAS"
+                  + this.userId + this.deviceId
+                  + this._baseApis.getUserId() + this._baseApis.deviceId
+                  + this.transactionId;
+            const sasBytes = olmSAS.generate_bytes(sasInfo, 6);
+            const verifySAS = new Promise((resolve, reject) => {
+                this.emit("show_sas", {
+                    sas: generateSas(sasBytes, sasMethods),
+                    confirm: () => {
+                        this._sendMAC(olmSAS);
+                        resolve();
+                    },
+                    cancel: () => reject(newUserCancelledError()),
+                    mismatch: () => reject(newMismatchedSASError()),
+                });
+            });
+
+
+            [e] = await Promise.all([
+                this._waitForEvent("m.key.verification.mac"),
+                verifySAS,
+            ]);
+            content = e.getContent();
+            await this._checkMAC(olmSAS, content);
+        } finally {
+            olmSAS.free();
+        }
+    }
+
+    _sendMAC(olmSAS) {
+        const keyId = `ed25519:${this._baseApis.deviceId}`;
+        const mac = {};
+        const baseInfo = "MATRIX_KEY_VERIFICATION_MAC"
+              + this._baseApis.getUserId() + this._baseApis.deviceId
+              + this.userId + this.deviceId
+              + this.transactionId;
+
+        mac[keyId] = olmSAS.calculate_mac(
+            this._baseApis.getDeviceEd25519Key(),
+            baseInfo + keyId,
+        );
+        const keys = olmSAS.calculate_mac(
+            keyId,
+            baseInfo + "KEY_IDS",
+        );
+        this._sendToDevice("m.key.verification.mac", { mac, keys });
+    }
+
+    async _checkMAC(olmSAS, content) {
+        const baseInfo = "MATRIX_KEY_VERIFICATION_MAC"
+              + this.userId + this.deviceId
+              + this._baseApis.getUserId() + this._baseApis.deviceId
+              + this.transactionId;
+
+        if (content.keys !== olmSAS.calculate_mac(
+            Object.keys(content.mac).sort().join(","),
+            baseInfo + "KEY_IDS",
+        )) {
+            throw newKeyMismatchError();
+        }
+
+        await this._verifyKeys(this.userId, content.mac, (keyId, device, keyInfo) => {
+            if (keyInfo !== olmSAS.calculate_mac(
+                device.keys[keyId],
+                baseInfo + keyId,
+            )) {
+                throw newKeyMismatchError();
+            }
+        });
+    }
+}
+
+SAS.NAME = "m.sas.v1";
@@ -1,6 +1,6 @@
 // can't just do InvalidStoreError extends Error
 // because of http://babeljs.io/docs/usage/caveats/#classes
-function InvalidStoreError(reason, value) {
+export function InvalidStoreError(reason, value) {
    const message = `Store is invalid because ${reason}, ` +
        `please stop the client, delete all data and start the client again`;
    const instance = Reflect.construct(Error, [message]);
@@ -22,4 +22,25 @@ InvalidStoreError.prototype = Object.create(Error.prototype, {
 });
 Reflect.setPrototypeOf(InvalidStoreError, Error);

-module.exports.InvalidStoreError = InvalidStoreError;
+
+export function InvalidCryptoStoreError(reason) {
+    const message = `Crypto store is invalid because ${reason}, ` +
+        `please stop the client, delete all data and start the client again`;
+    const instance = Reflect.construct(Error, [message]);
+    Reflect.setPrototypeOf(instance, Reflect.getPrototypeOf(this));
+    instance.reason = reason;
+    instance.name = 'InvalidCryptoStoreError';
+    return instance;
+}
+
+InvalidCryptoStoreError.TOO_NEW = "TOO_NEW";
+
+InvalidCryptoStoreError.prototype = Object.create(Error.prototype, {
+  constructor: {
+    value: Error,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  },
+});
+Reflect.setPrototypeOf(InvalidCryptoStoreError, Error);
@@ -752,6 +752,8 @@ module.exports.MatrixHttpApi.prototype = {
                    method: method,
                    withCredentials: false,
                    qs: queryParams,
+                    qsStringifyOptions: opts.qsStringifyOptions,
+                    useQuerystring: true,
                    body: data,
                    json: false,
                    timeout: localTimeoutMs,
@@ -0,0 +1,36 @@
+/*
+Copyright 2018 André Jaenisch
+
+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 logger
+ */
+const log = require("loglevel");
+
+// This is to demonstrate, that you can use any namespace you want.
+// Namespaces allow you to turn on/off the logging for specific parts of the
+// application.
+// An idea would be to control this via an environment variable (on Node.js).
+// See https://www.npmjs.com/package/debug to see how this could be implemented
+// Part of #332 is introducing a logging library in the first place.
+const DEFAULT_NAME_SPACE = "matrix";
+const logger = log.getLogger(DEFAULT_NAME_SPACE);
+logger.setLevel(log.levels.DEBUG);
+
+/**
+ * Drop-in replacement for <code>console</code> using {@link https://www.npmjs.com/package/loglevel|loglevel}.
+ * Can be tailored down to specific use cases if needed.
+*/
+module.exports = logger;
@@ -67,6 +67,8 @@ module.exports.Filter = require("./filter");
 module.exports.TimelineWindow = require("./timeline-window").TimelineWindow;
 /** The {@link module:interactive-auth} class. */
 module.exports.InteractiveAuth = require("./interactive-auth");
+/** The {@link module:auto-discovery|AutoDiscovery} class. */
+module.exports.AutoDiscovery = require("./autodiscovery").AutoDiscovery;


 module.exports.MemoryCryptoStore =
@@ -86,21 +88,21 @@ module.exports.createNewMatrixCall = require("./webrtc/call").createNewMatrixCal


 /**
- * Set an audio output device to use for MatrixCalls
+ * Set a preferred audio output device to use for MatrixCalls
 * @function
 * @param {string=} deviceId the identifier for the device
 * undefined treated as unset
 */
 module.exports.setMatrixCallAudioOutput = require('./webrtc/call').setAudioOutput;
 /**
- * Set an audio input device to use for MatrixCalls
+ * Set a preferred audio input device to use for MatrixCalls
 * @function
 * @param {string=} deviceId the identifier for the device
 * undefined treated as unset
 */
 module.exports.setMatrixCallAudioInput = require('./webrtc/call').setAudioInput;
 /**
- * Set a video input device to use for MatrixCalls
+ * Set a preferred video input device to use for MatrixCalls
 * @function
 * @param {string=} deviceId the identifier for the device
 * undefined treated as unset
@@ -382,15 +382,41 @@ utils.extend(module.exports.MatrixEvent.prototype, {
     * Cancel any room key request for this event and resend another.
     *
     * @param {module:crypto} crypto crypto module
+     * @param {string} userId the user who received this event
+     *
+     * @returns {Promise} a promise that resolves when the request is queued
     */
-    cancelAndResendKeyRequest: function(crypto) {
+    cancelAndResendKeyRequest: function(crypto, userId) {
        const wireContent = this.getWireContent();
-        crypto.cancelRoomKeyRequest({
+        return crypto.requestRoomKey({
            algorithm: wireContent.algorithm,
            room_id: this.getRoomId(),
            session_id: wireContent.session_id,
            sender_key: wireContent.sender_key,
-        }, true);
+        }, this.getKeyRequestRecipients(userId), true);
+    },
+
+    /**
+     * Calculate the recipients for keyshare requests.
+     *
+     * @param {string} userId the user who received this event.
+     *
+     * @returns {Array} array of recipients
+     */
+    getKeyRequestRecipients: function(userId) {
+        // send the request to all of our own devices, and the
+        // original sending device if it wasn't us.
+        const wireContent = this.getWireContent();
+        const recipients = [{
+            userId, deviceId: '*',
+        }];
+        const sender = this.getSender();
+        if (sender !== userId) {
+            recipients.push({
+                userId: sender, deviceId: wireContent.device_id,
+            });
+        }
+        return recipients;
    },

    _decryptionLoop: async function(crypto) {
@@ -471,6 +497,14 @@ utils.extend(module.exports.MatrixEvent.prototype, {
            this._retryDecryption = false;
            this._setClearData(res);

+            // Before we emit the event, clear the push actions so that they can be recalculated
+            // by relevant code. We do this because the clear event has now changed, making it
+            // so that existing rules can be re-run over the applicable properties. Stuff like
+            // highlighting when the user's name is mentioned rely on this happening. We also want
+            // to set the push actions before emitting so that any notification listeners don't
+            // pick up the wrong contents.
+            this.setPushActions(null);
+
            this.emit("Event.decrypted", this, err);

            return;
@@ -511,6 +545,17 @@ utils.extend(module.exports.MatrixEvent.prototype, {
            decryptionResult.forwardingCurve25519KeyChain || [];
    },

+    /**
+     * Gets the cleartext content for this event. If the event is not encrypted,
+     * or encryption has not been completed, this will return null.
+     *
+     * @returns {Object} The cleartext (decrypted) content for the event
+     */
+    getClearContent: function() {
+        const ev = this._clearEvent;
+        return ev && ev.content ? ev.content : null;
+    },
+
    /**
     * Check if the event is encrypted.
     * @return {boolean} True if this event is encrypted.
@@ -298,26 +298,24 @@ function calculateDisplayName(selfUserId, displayName, roomState) {
        return selfUserId;
    }

-    if (!roomState) {
-        return displayName;
-    }
-
    // First check if the displayname is something we consider truthy
    // after stripping it of zero width characters and padding spaces
-    const strippedDisplayName = utils.removeHiddenChars(displayName);
-    if (!strippedDisplayName) {
+    if (!utils.removeHiddenChars(displayName)) {
        return selfUserId;
    }

+    if (!roomState) {
+        return displayName;
+    }
+
    // Next check if the name contains something that look like a mxid
    // If it does, it may be someone trying to impersonate someone else
    // Show full mxid in this case
-    // Also show mxid if there are other people with the same displayname
-    // ignoring any zero width chars (unicode 200B-200D)
-    // if their displayname is made up of just zero width chars, show full mxid
+    // Also show mxid if there are other people with the same or similar
+    // displayname, after hidden character removal.
    let disambiguate = /@.+:.+/.test(displayName);
    if (!disambiguate) {
-        const userIds = roomState.getUserIdsWithDisplayName(strippedDisplayName);
+        const userIds = roomState.getUserIdsWithDisplayName(displayName);
        disambiguate = userIds.some((u) => u !== selfUserId);
    }

@@ -75,6 +75,8 @@ function RoomState(roomId, oobMemberFlags = undefined) {
        // userId: RoomMember
    };
    this._updateModifiedTime();
+
+    // stores fuzzy matches to a list of userIDs (applies utils.removeHiddenChars to keys)
    this._displayNameToUserIds = {};
    this._userIdsToDisplayNames = {};
    this._tokenToInvite = {}; // 3pid invite state_key to m.room.member invite
@@ -154,6 +156,16 @@ RoomState.prototype.getMembers = function() {
    return utils.values(this.members);
 };

+/**
+ * Get all RoomMembers in this room, excluding the user IDs provided.
+ * @param {Array<string>} excludedIds The user IDs to exclude.
+ * @return {Array<RoomMember>} A list of RoomMembers.
+ */
+RoomState.prototype.getMembersExcept = function(excludedIds) {
+    return utils.values(this.members)
+        .filter((m) => !excludedIds.includes(m.userId));
+};
+
 /**
 * Get a room member by their user ID.
 * @param {string} userId The room member's user ID.
@@ -519,12 +531,12 @@ RoomState.prototype.getLastModifiedTime = function() {
 };

 /**
- * Get user IDs with the specified display name.
+ * Get user IDs with the specified or similar display names.
 * @param {string} displayName The display name to get user IDs from.
 * @return {string[]} An array of user IDs or an empty array.
 */
 RoomState.prototype.getUserIdsWithDisplayName = function(displayName) {
-    return this._displayNameToUserIds[displayName] || [];
+    return this._displayNameToUserIds[utils.removeHiddenChars(displayName)] || [];
 };

 /**
@@ -31,7 +31,14 @@ const EventTimelineSet = require("./event-timeline-set");

 import ReEmitter from '../ReEmitter';

-const LATEST_ROOM_VERSION = '1';
+// These constants are used as sane defaults when the homeserver doesn't support
+// the m.room_versions capability. In practice, KNOWN_SAFE_ROOM_VERSION should be
+// the same as the common default room version whereas SAFE_ROOM_VERSIONS are the
+// room versions which are considered okay for people to run without being asked
+// to upgrade (ie: "stable"). Eventually, we should remove these when all homeservers
+// return an m.room_versions capability.
+const KNOWN_SAFE_ROOM_VERSION = '1';
+const SAFE_ROOM_VERSIONS = ['1', '2'];

 function synthesizeReceipt(userId, event, receiptType) {
    // console.log("synthesizing receipt for "+event.getId());
@@ -211,12 +218,74 @@ Room.prototype.getVersion = function() {
 * Determines whether this room needs to be upgraded to a new version
 * @returns {string?} What version the room should be upgraded to, or null if
 *     the room does not require upgrading at this time.
+ * @deprecated Use #getRecommendedVersion() instead
 */
 Room.prototype.shouldUpgradeToVersion = function() {
-    // This almost certainly won't be the way this actually works - this
-    // is essentially a stub method.
-    if (this.getVersion() === LATEST_ROOM_VERSION) return null;
-    return LATEST_ROOM_VERSION;
+    // TODO: Remove this function.
+    // This makes assumptions about which versions are safe, and can easily
+    // be wrong. Instead, people are encouraged to use getRecommendedVersion
+    // which determines a safer value. This function doesn't use that function
+    // because this is not async-capable, and to avoid breaking the contract
+    // we're deprecating this.
+
+    if (!SAFE_ROOM_VERSIONS.includes(this.getVersion())) {
+        return KNOWN_SAFE_ROOM_VERSION;
+    }
+
+    return null;
+};
+
+/**
+ * Determines the recommended room version for the room. This returns an
+ * object with 3 properties: <code>version</code> as the new version the
+ * room should be upgraded to (may be the same as the current version);
+ * <code>needsUpgrade</code> to indicate if the room actually can be
+ * upgraded (ie: does the current version not match?); and <code>urgent</code>
+ * to indicate if the new version patches a vulnerability in a previous
+ * version.
+ * @returns {Promise<{version: string, needsUpgrade: bool, urgent: bool}>}
+ * Resolves to the version the room should be upgraded to.
+ */
+Room.prototype.getRecommendedVersion = async function() {
+    const capabilities = await this._client.getCapabilities();
+    let versionCap = capabilities["m.room_versions"];
+    if (!versionCap) {
+        versionCap = {
+            default: KNOWN_SAFE_ROOM_VERSION,
+            available: {},
+        };
+        for (const safeVer of SAFE_ROOM_VERSIONS) {
+            versionCap.available[safeVer] = "stable";
+        }
+    }
+
+    const currentVersion = this.getVersion();
+
+    const result = {
+        version: currentVersion,
+        needsUpgrade: false,
+        urgent: false,
+    };
+
+    // If the room is on the default version then nothing needs to change
+    if (currentVersion === versionCap.default) return Promise.resolve(result);
+
+    const stableVersions = Object.keys(versionCap.available)
+        .filter((v) => versionCap.available[v] === 'stable');
+
+    // Check if the room is on an unstable version. We determine urgency based
+    // off the version being in the Matrix spec namespace or not (if the version
+    // is in the current namespace and unstable, the room is probably vulnerable).
+    if (!stableVersions.includes(currentVersion)) {
+        result.version = versionCap.default;
+        result.needsUpgrade = true;
+        result.urgent = !!this.getVersion().match(/^[0-9]+[0-9.]*$/g);
+        return Promise.resolve(result);
+    }
+
+    // The room is on a stable, but non-default, version by this point.
+    // No upgrade needed.
+    return Promise.resolve(result);
 };

 /**
@@ -520,6 +589,24 @@ Room.prototype._fixUpLegacyTimelineFields = function() {
                            .getState(EventTimeline.FORWARDS);
 };

+/**
+ * Returns whether there are any devices in the room that are unverified
+ * @return {bool} the result
+ */
+Room.prototype.hasUnverifiedDevices = async function() {
+    if (!this._client.isRoomEncrypted(this.roomId)) {
+        return false;
+    }
+    const e2eMembers = await this.getEncryptionTargetMembers();
+    for (const member of e2eMembers) {
+        const devices = await this._client.getStoredDevicesForUser(member.userId);
+        if (devices.some((device) => device.isUnverified())) {
+            return true;
+        }
+    }
+    return false;
+};
+
 /**
 * Return the timeline sets for this room.
 * @return {EventTimelineSet[]} array of timeline sets for this room
@@ -999,6 +1086,10 @@ Room.prototype.addPendingEvent = function(event, txnId) {
    this._txnToEvent[txnId] = event;

    if (this._opts.pendingEventOrdering == "detached") {
+        if (this._pendingEventList.some((e) => e.status === EventStatus.NOT_SENT)) {
+            console.warn("Setting event as NOT_SENT due to messages in the same state");
+            event.status = EventStatus.NOT_SENT;
+        }
        this._pendingEventList.push(event);
    } else {
        for (let i = 0; i < this._timelineSets.length; i++) {
@@ -1163,7 +1254,7 @@ Room.prototype.updatePendingEvent = function(event, newStatus, newEventId) {
        this.removeEvent(oldEventId);
    }

-    this.emit("Room.localEchoUpdated", event, this, event.getId(), oldStatus);
+    this.emit("Room.localEchoUpdated", event, this, oldEventId, oldStatus);
 };


@@ -1333,6 +1424,40 @@ Room.prototype.getEventReadUpTo = function(userId, ignoreSynthesized) {
    return receipts["m.read"][userId].eventId;
 };

+/**
+ * Determines if the given user has read a particular event ID with the known
+ * history of the room. This is not a definitive check as it relies only on
+ * what is available to the room at the time of execution.
+ * @param {String} userId The user ID to check the read state of.
+ * @param {String} eventId The event ID to check if the user read.
+ * @returns {Boolean} True if the user has read the event, false otherwise.
+ */
+Room.prototype.hasUserReadEvent = function(userId, eventId) {
+    const readUpToId = this.getEventReadUpTo(userId, false);
+    if (readUpToId === eventId) return true;
+
+    if (this.timeline.length
+        && this.timeline[this.timeline.length - 1].getSender()
+        && this.timeline[this.timeline.length - 1].getSender() === userId) {
+        // It doesn't matter where the event is in the timeline, the user has read
+        // it because they've sent the latest event.
+        return true;
+    }
+
+    for (let i = this.timeline.length - 1; i >= 0; --i) {
+        const ev = this.timeline[i];
+
+        // If we encounter the target event first, the user hasn't read it
+        // however if we encounter the readUpToId first then the user has read
+        // it. These rules apply because we're iterating bottom-up.
+        if (ev.getId() === eventId) return false;
+        if (ev.getId() === readUpToId) return true;
+    }
+
+    // We don't know if the user has read it, so assume not.
+    return false;
+};
+
 /**
 * Get a list of receipts for the given event.
 * @param {MatrixEvent} event the event to get receipts for
@@ -1606,7 +1731,7 @@ function calculateRoomName(room, userId, ignoreRoomNameEvent) {
 function memberNamesToRoomName(names, count = (names.length + 1)) {
    const countWithoutMe = count - 1;
    if (!names.length) {
-       return count <= 1 ? "Empty room" : null;
+       return "Empty room";
    } else if (names.length === 1 && countWithoutMe <= 1) {
        return names[0];
    } else if (names.length === 2 && countWithoutMe <= 2) {
@@ -39,6 +39,9 @@ limitations under the License.
 *                when a user was last active.
 * @prop {Boolean} currentlyActive Whether we should consider lastActiveAgo to be
 *               an approximation and that the user should be seen as active 'now'
+ * @prop {string} _unstable_statusMessage The status message for the user, if known. This is
+ *                different from the presenceStatusMsg in that this is not tied to
+ *                the user's presence, and should be represented differently.
 * @prop {Object} events The events describing this user.
 * @prop {MatrixEvent} events.presence The m.presence event for this user.
 */
@@ -46,6 +49,7 @@ function User(userId) {
    this.userId = userId;
    this.presence = "offline";
    this.presenceStatusMsg = null;
+    this._unstable_statusMessage = "";
    this.displayName = userId;
    this.rawDisplayName = userId;
    this.avatarUrl = null;
@@ -179,6 +183,18 @@ User.prototype.getLastActiveTs = function() {
    return this.lastPresenceTs - this.lastActiveAgo;
 };

+/**
+ * Manually set the user's status message.
+ * @param {MatrixEvent} event The <code>im.vector.user_status</code> event.
+ * @fires module:client~MatrixClient#event:"User._unstable_statusMessage"
+ */
+User.prototype._unstable_updateStatusMessage = function(event) {
+    if (!event.getContent()) this._unstable_statusMessage = "";
+    else this._unstable_statusMessage = event.getContent()["status"];
+    this._updateModifiedTime();
+    this.emit("User._unstable_statusMessage", this);
+};
+
 /**
 * The User class.
 */
@@ -14,6 +14,9 @@ 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 {escapeRegExp, globToRegexp} from "./utils";
+
 /**
 * @module pushprocessor
 */
@@ -26,10 +29,6 @@ const RULEKINDS_IN_ORDER = ['override', 'content', 'room', 'sender', 'underride'
 * @param {Object} client The Matrix client object to use
 */
 function PushProcessor(client) {
-    const escapeRegExp = function(string) {
-        return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    };
-
    const cachedGlobToRegex = {
        // $glob: RegExp,
    };
@@ -185,7 +184,10 @@ function PushProcessor(client) {
    };

    const eventFulfillsDisplayNameCondition = function(cond, ev) {
-        const content = ev.getContent();
+        let content = ev.getContent();
+        if (ev.isEncrypted() && ev.getClearContent()) {
+            content = ev.getClearContent();
+        }
        if (!content || !content.body || typeof content.body != 'string') {
            return false;
        }
@@ -244,22 +246,6 @@ function PushProcessor(client) {
        return cachedGlobToRegex[glob];
    };

-    const globToRegexp = function(glob) {
-        // From
-        // https://github.com/matrix-org/synapse/blob/abbee6b29be80a77e05730707602f3bbfc3f38cb/synapse/push/__init__.py#L132
-        // Because micromatch is about 130KB with dependencies,
-        // and minimatch is not much better.
-        let pat = escapeRegExp(glob);
-        pat = pat.replace(/\\\*/g, '.*');
-        pat = pat.replace(/\?/g, '.');
-        pat = pat.replace(/\\\[(!|)(.*)\\]/g, function(match, p1, p2, offset, string) {
-            const first = p1 && '^' || '';
-            const second = p2.replace(/\\\-/, '-');
-            return '[' + first + second + ']';
-        });
-        return pat;
-    };
-
    const valueForDottedKey = function(key, ev) {
        const parts = key.split('.');
        let val;
@@ -0,0 +1,26 @@
+/*
+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.
+*/
+
+export function randomString(len) {
+    let ret = "";
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+    for (let i = 0; i < len; ++i) {
+        ret += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+
+    return ret;
+}
@@ -190,11 +190,22 @@ WebStorageSessionStore.prototype = {
    removeAllEndToEndRooms: function() {
        removeByPrefix(this.store, keyEndToEndRoom(''));
    },
+
+    setLocalTrustedBackupPubKey: function(pubkey) {
+        this.store.setItem(KEY_END_TO_END_TRUSTED_BACKUP_PUBKEY, pubkey);
+    },
+
+    // XXX: This store is deprecated really, but added this as a temporary
+    // thing until cross-signing lands.
+    getLocalTrustedBackupPubKey: function() {
+        return this.store.getItem(KEY_END_TO_END_TRUSTED_BACKUP_PUBKEY);
+    },
 };

 const KEY_END_TO_END_ACCOUNT = E2E_PREFIX + "account";
 const KEY_END_TO_END_DEVICE_SYNC_TOKEN = E2E_PREFIX + "device_sync_token";
 const KEY_END_TO_END_DEVICE_LIST_TRACKING_STATUS = E2E_PREFIX + "device_tracking";
+const KEY_END_TO_END_TRUSTED_BACKUP_PUBKEY = E2E_PREFIX + "trusted_backup_pubkey";

 function keyEndToEndDevicesForUser(userId) {
    return E2E_PREFIX + "devices/" + userId;
@@ -34,7 +34,6 @@ import utils from "./utils";
 * rather than asking the server to do an initial sync on startup.
 */
 class SyncAccumulator {
-
    /**
     * @param {Object} opts
     * @param {Number=} opts.maxTimelineEntries The ideal maximum number of
@@ -516,7 +516,7 @@ SyncApi.prototype.sync = function() {
            console.warn("InvalidStoreError: store is not usable: stopping sync.");
            return;
        }
-        if (this.opts.lazyLoadMembers && this._crypto) {
+        if (this.opts.lazyLoadMembers && this.opts.crypto) {
            this.opts.crypto.enableLazyLoading();
        }
        await this.client._storeClientOptions();
@@ -1172,6 +1172,16 @@ SyncApi.prototype._processSyncResponse = async function(
            if (e.isState() && e.getType() == "m.room.encryption" && self.opts.crypto) {
                await self.opts.crypto.onCryptoEvent(e);
            }
+            if (e.isState() && e.getType() === "im.vector.user_status") {
+                let user = client.store.getUser(e.getStateKey());
+                if (user) {
+                    user._unstable_updateStatusMessage(e);
+                } else {
+                    user = createNewUser(client, e.getStateKey());
+                    user._unstable_updateStatusMessage(e);
+                    client.store.storeUser(user);
+                }
+            }
        }

        await Promise.mapSeries(stateEvents, processRoomEvent);
@@ -19,6 +19,8 @@ limitations under the License.
 * @module utils
 */

+const unhomoglyph = require('unhomoglyph');
+
 /**
 * Encode a dictionary of query parameters.
 * @param {Object} params A dict of key/values to encode e.g.
@@ -328,7 +330,7 @@ const deepCompare = module.exports.deepCompare = function(x, y) {
        }

        // finally, compare each of x's keys with y
-        for (p in y) {
+        for (p in y) { // eslint-disable-line guard-for-in
            if (y.hasOwnProperty(p) !== x.hasOwnProperty(p)) {
                return false;
            }
@@ -665,10 +667,35 @@ module.exports.isNumber = function(value) {

 /**
 * Removes zero width chars, diacritics and whitespace from the string
+ * Also applies an unhomoglyph on the string, to prevent similar looking chars
 * @param {string} str the string to remove hidden characters from
 * @return {string} a string with the hidden characters removed
 */
 module.exports.removeHiddenChars = function(str) {
-    return str.normalize('NFD').replace(removeHiddenCharsRegex, '');
+    return unhomoglyph(str.normalize('NFD').replace(removeHiddenCharsRegex, ''));
 };
 const removeHiddenCharsRegex = /[\u200B-\u200D\u0300-\u036f\uFEFF\s]/g;
+
+function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+module.exports.escapeRegExp = escapeRegExp;
+
+module.exports.globToRegexp = function(glob, extended) {
+    extended = typeof(extended) === 'boolean' ? extended : true;
+    // From
+    // https://github.com/matrix-org/synapse/blob/abbee6b29be80a77e05730707602f3bbfc3f38cb/synapse/push/__init__.py#L132
+    // Because micromatch is about 130KB with dependencies,
+    // and minimatch is not much better.
+    let pat = escapeRegExp(glob);
+    pat = pat.replace(/\\\*/g, '.*');
+    pat = pat.replace(/\?/g, '.');
+    if (extended) {
+        pat = pat.replace(/\\\[(!|)(.*)\\]/g, function(match, p1, p2, offset, string) {
+            const first = p1 && '^' || '';
+            const second = p2.replace(/\\-/, '-');
+            return '[' + first + second + ']';
+        });
+    }
+    return pat;
+};
@@ -583,7 +583,7 @@ MatrixCall.prototype._maybeGotUserMediaForInvite = function(stream) {
            ' Or possibly you are using an insecure domain. Receiving only.');
        this.peerConn = _createPeerConnection(this);
    } else {
-        debuglog('Failed to getUserMedia.');
+        debuglog('Failed to getUserMedia: ' + error.name);
        this._getUserMediaFailed(error);
        return;
    }
@@ -652,7 +652,7 @@ MatrixCall.prototype._maybeGotUserMediaForAnswer = function(stream) {
        debuglog('User denied access to camera/microphone.' +
            ' Or possibly you are using an insecure domain. Receiving only.');
    } else {
-        debuglog('Failed to getUserMedia.');
+        debuglog('Failed to getUserMedia: ' + error.name);
        this._getUserMediaFailed(error);
        return;
    }
@@ -1274,15 +1274,15 @@ const _getUserMediaVideoContraints = function(callType) {
        case 'voice':
            return {
                audio: {
-                    deviceId: audioInput ? {exact: audioInput} : undefined,
+                    deviceId: audioInput ? {ideal: audioInput} : undefined,
                }, video: false,
            };
        case 'video':
            return {
                audio: {
-                    deviceId: audioInput ? {exact: audioInput} : undefined,
+                    deviceId: audioInput ? {ideal: audioInput} : undefined,
                }, video: {
-                    deviceId: videoInput ? {exact: videoInput} : undefined,
+                    deviceId: videoInput ? {ideal: videoInput} : undefined,
                    /* We want 640x360.  Chrome will give it only if we ask exactly,
                       FF refuses entirely if we ask exactly, so have to ask for ideal
                       instead */
@@ -2,12 +2,8 @@

 set -ex

-npm run lint
+yarn lint

-# install Olm so that we can run the crypto tests.
-npm install https://matrix.org/packages/npm/olm/olm-2.2.2.tgz
-
-npm run test
-
-npm run gendoc
+yarn test

+yarn gendoc