v2.4.5

Prepare changelog for v2.4.5
Update tests
2019-11-27 10:17:54 +00:00 · 2019-11-27 10:17:54 +00:00 · 2019-11-26 12:04:14 -07:00 · 2019-11-26 12:04:07 -07:00 · 2019-11-26 12:03:34 -07:00 · 2019-11-26 12:03:28 -07:00
114 changed files with 20511 additions and 1540 deletions
@@ -1,6 +1,8 @@
 {
-    "presets": ["es2015"],
+    "presets": ["es2015", "es2016"],
    "plugins": [
+        "transform-class-properties",
+
        // this transforms async functions into generator functions, which
        // are then made to use the regenerator module by babel's
        // transform-regnerator plugin (which is enabled by es2015).
@@ -0,0 +1,34 @@
+steps:
+  - label: ":eslint: Lint"
+    command:
+      - "yarn install"
+      - "yarn lint"
+    plugins:
+      - docker#v3.0.1:
+          image: "node:10"
+
+  - label: ":karma: Tests"
+    command:
+      - "yarn install"
+      - "yarn test"
+    plugins:
+      - docker#v3.0.1:
+          image: "node:10"
+
+  - label: "📃 Docs"
+    command:
+      - "yarn install"
+      - "yarn gendoc"
+    plugins:
+      - docker#v3.0.1:
+          image: "node:10"
+
+  - wait
+
+  - label: "🐴 Trigger matrix-react-sdk"
+    trigger: "matrix-react-sdk"
+    branches: "develop"
+    build:
+        branch: "develop"
+        message: "[js-sdk] ${BUILDKITE_MESSAGE}"
+    async: true
@@ -1,7 +1,6 @@
 module.exports = {
-    parser: "babel-eslint",
+    parser: "babel-eslint", // now needed for class properties
    parserOptions: {
-        ecmaVersion: 6,
        sourceType: "module",
        ecmaFeatures: {
        }
@@ -15,6 +14,9 @@ module.exports = {
        es6: true,
    },
    extends: ["eslint:recommended", "google"],
+    plugins: [
+        "babel",
+    ],
    rules: {
        // rules we've always adhered to or now do
        "max-len": ["error", {
@@ -51,6 +53,7 @@ module.exports = {
        // rules we do not want from the google styleguide
        "object-curly-spacing": ["off"],
        "spaced-comment": ["off"],
+        "guard-for-in": ["off"],

        // in principle we prefer single quotes, but life is too short
        quotes: ["off"],
@@ -67,5 +70,17 @@ 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",
+
+        // eslint's built in no-invalid-this rule breaks with class properties
+        "no-invalid-this": "off",
+        // so we replace it with a version that is class property aware
+        "babel/no-invalid-this": "error",
    }
 }
@@ -0,0 +1,2 @@
+patreon: matrixdotorg
+liberapay: matrixdotorg
@@ -2,16 +2,18 @@
 /.jsdoc

 node_modules
+/.npmrc
+/*.log
+package-lock.json
 .lock-wscript
 build/Release
 coverage
 lib-cov
 out
-reports
 /dist
 /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 +0,0 @@
-language: node_js
-node_js:
-    - node # Latest stable version of nodejs.
-script:
-    - ./travis.sh
@@ -1,3 +1,735 @@
+Changes in [2.4.5](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.5) (2019-11-27)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.4...v2.4.5)
+
+* Relax identity server discovery checks to FAIL_PROMPT
+* Expand E2EE debug logging to diagnose "unable to decrypt" errors
+
+Changes in [2.4.4](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.4) (2019-11-25)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.4-rc.1...v2.4.4)
+
+ * No changes since rc.1
+
+Changes in [2.4.4-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.4-rc.1) (2019-11-20)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.3...v2.4.4-rc.1)
+
+ * Fix SAS verification in encrypted DMs
+   [\#1077](https://github.com/matrix-org/matrix-js-sdk/pull/1077)
+ * Cross-signing / secret storage tweaks
+   [\#1078](https://github.com/matrix-org/matrix-js-sdk/pull/1078)
+ * Fix local trust for key backups
+   [\#1075](https://github.com/matrix-org/matrix-js-sdk/pull/1075)
+ * Add method to get last active timestamp in room
+   [\#1072](https://github.com/matrix-org/matrix-js-sdk/pull/1072)
+ * Check the right Synapse endpoint for determining admin capabilities
+   [\#1071](https://github.com/matrix-org/matrix-js-sdk/pull/1071)
+ * Cross Signing Support
+   [\#832](https://github.com/matrix-org/matrix-js-sdk/pull/832)
+ * Don't double cancel verification request
+   [\#1064](https://github.com/matrix-org/matrix-js-sdk/pull/1064)
+ * Support for verification requests in the timeline
+   [\#1067](https://github.com/matrix-org/matrix-js-sdk/pull/1067)
+ * Use stable API prefix for 3PID APIs when supported
+   [\#1066](https://github.com/matrix-org/matrix-js-sdk/pull/1066)
+ * Remove Jenkins scripts
+   [\#1063](https://github.com/matrix-org/matrix-js-sdk/pull/1063)
+
+Changes in [2.4.3](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.3) (2019-11-04)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.3-rc.1...v2.4.3)
+
+ * No changes since rc.1
+
+Changes in [2.4.3-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.3-rc.1) (2019-10-30)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.2...v2.4.3-rc.1)
+
+ * fix the path in references to logger.js
+   [\#1056](https://github.com/matrix-org/matrix-js-sdk/pull/1056)
+ * verification in DMs
+   [\#1050](https://github.com/matrix-org/matrix-js-sdk/pull/1050)
+ * Properly documented the function possible returns
+   [\#1054](https://github.com/matrix-org/matrix-js-sdk/pull/1054)
+ * Downgrade to Bluebird 3.5.5 to fix Firefox
+   [\#1055](https://github.com/matrix-org/matrix-js-sdk/pull/1055)
+ * Upgrade safe deps to latest major version
+   [\#1053](https://github.com/matrix-org/matrix-js-sdk/pull/1053)
+ * Don't include .js in the import string.
+   [\#1052](https://github.com/matrix-org/matrix-js-sdk/pull/1052)
+
+Changes in [2.4.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.2) (2019-10-18)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.2-rc.1...v2.4.2)
+
+ * No changes since v2.4.2-rc.1
+
+Changes in [2.4.2-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.2-rc.1) (2019-10-09)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.1...v2.4.2-rc.1)
+
+ * Log state of Olm sessions
+   [\#1047](https://github.com/matrix-org/matrix-js-sdk/pull/1047)
+ * Add method to get access to all timelines
+   [\#1048](https://github.com/matrix-org/matrix-js-sdk/pull/1048)
+
+Changes in [2.4.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.1) (2019-10-01)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.0...v2.4.1)
+
+ * Upgrade deps
+   [\#1046](https://github.com/matrix-org/matrix-js-sdk/pull/1046)
+ * Ignore crypto events with no content
+   [\#1043](https://github.com/matrix-org/matrix-js-sdk/pull/1043)
+
+Changes in [2.4.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.0) (2019-09-27)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.4.0-rc.1...v2.4.0)
+
+ * Clean Yarn cache during release
+   [\#1045](https://github.com/matrix-org/matrix-js-sdk/pull/1045)
+
+Changes in [2.4.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.4.0-rc.1) (2019-09-25)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.3.2...v2.4.0-rc.1)
+
+ * Remove id_server from creds for interactive auth
+   [\#1044](https://github.com/matrix-org/matrix-js-sdk/pull/1044)
+ * Remove IS details from requestToken to HS
+   [\#1041](https://github.com/matrix-org/matrix-js-sdk/pull/1041)
+ * Add support for sending MSISDN tokens to alternate URLs
+   [\#1040](https://github.com/matrix-org/matrix-js-sdk/pull/1040)
+ * Add separate 3PID add and bind APIs
+   [\#1038](https://github.com/matrix-org/matrix-js-sdk/pull/1038)
+ * Bump eslint-utils from 1.4.0 to 1.4.2
+   [\#1037](https://github.com/matrix-org/matrix-js-sdk/pull/1037)
+ * Handle WebRTC security errors as non-fatal
+   [\#1036](https://github.com/matrix-org/matrix-js-sdk/pull/1036)
+ * Check for r0.6.0 support in addition to unstable feature flags
+   [\#1035](https://github.com/matrix-org/matrix-js-sdk/pull/1035)
+ * Update room members on member event redaction
+   [\#1030](https://github.com/matrix-org/matrix-js-sdk/pull/1030)
+ * Support hidden read receipts
+   [\#1028](https://github.com/matrix-org/matrix-js-sdk/pull/1028)
+ * Do 3pid lookups in lowercase
+   [\#1029](https://github.com/matrix-org/matrix-js-sdk/pull/1029)
+ * Add Synapse admin functions for deactivating a user
+   [\#1027](https://github.com/matrix-org/matrix-js-sdk/pull/1027)
+ * Fix addPendingEvent with pending event order == chronological
+   [\#1026](https://github.com/matrix-org/matrix-js-sdk/pull/1026)
+ * Add AutoDiscovery.getRawClientConfig() for easy .well-known lookups
+   [\#1024](https://github.com/matrix-org/matrix-js-sdk/pull/1024)
+ * Don't convert errors to JSON if they are JSON already
+   [\#1025](https://github.com/matrix-org/matrix-js-sdk/pull/1025)
+ * Send id_access_token to HS for use in proxied IS requests
+   [\#1022](https://github.com/matrix-org/matrix-js-sdk/pull/1022)
+ * Clean up JSON handling in identity server requests
+   [\#1023](https://github.com/matrix-org/matrix-js-sdk/pull/1023)
+ * Use the v2 (hashed) lookup for identity server queries
+   [\#1021](https://github.com/matrix-org/matrix-js-sdk/pull/1021)
+ * Add getIdServer() & doesServerRequireIdServerParam()
+   [\#1018](https://github.com/matrix-org/matrix-js-sdk/pull/1018)
+ * Make requestToken endpoints work without ID Server
+   [\#1019](https://github.com/matrix-org/matrix-js-sdk/pull/1019)
+ * Fix setIdentityServer
+   [\#1016](https://github.com/matrix-org/matrix-js-sdk/pull/1016)
+ * Change ICE fallback server and make fallback opt-in
+   [\#1015](https://github.com/matrix-org/matrix-js-sdk/pull/1015)
+ * Throw an exception if trying to do an ID server request with no ID server
+   [\#1014](https://github.com/matrix-org/matrix-js-sdk/pull/1014)
+ * Add setIdentityServerUrl
+   [\#1013](https://github.com/matrix-org/matrix-js-sdk/pull/1013)
+ * Add matrix base API to report an event
+   [\#1011](https://github.com/matrix-org/matrix-js-sdk/pull/1011)
+ * Fix POST body for v2 IS requests
+   [\#1010](https://github.com/matrix-org/matrix-js-sdk/pull/1010)
+ * Add API for bulk lookup on the Identity Server
+   [\#1009](https://github.com/matrix-org/matrix-js-sdk/pull/1009)
+ * Remove deprecated authedRequestWithPrefix and requestWithPrefix
+   [\#1000](https://github.com/matrix-org/matrix-js-sdk/pull/1000)
+ * Add API for checking IS account info
+   [\#1007](https://github.com/matrix-org/matrix-js-sdk/pull/1007)
+ * Support rewriting push rules when our internal defaults change
+   [\#1006](https://github.com/matrix-org/matrix-js-sdk/pull/1006)
+ * Upgrade dependencies
+   [\#1005](https://github.com/matrix-org/matrix-js-sdk/pull/1005)
+
+Changes in [2.3.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.3.2) (2019-09-16)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.3.2-rc.1...v2.3.2)
+
+ * [Release] Fix addPendingEvent with pending event order == chronological
+   [\#1034](https://github.com/matrix-org/matrix-js-sdk/pull/1034)
+
+Changes in [2.3.2-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.3.2-rc.1) (2019-09-13)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.3.1...v2.3.2-rc.1)
+
+ * Synapse admin functions to release
+   [\#1033](https://github.com/matrix-org/matrix-js-sdk/pull/1033)
+ * [To Release] Add matrix base API to report an event
+   [\#1032](https://github.com/matrix-org/matrix-js-sdk/pull/1032)
+
+Changes in [2.3.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.3.1) (2019-09-12)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.3.1-rc.1...v2.3.1)
+
+ * No changes since rc.1
+
+Changes in [2.3.1-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.3.1-rc.1) (2019-09-11)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.3.0...v2.3.1-rc.1)
+
+ * Update room members on member event redaction
+   [\#1031](https://github.com/matrix-org/matrix-js-sdk/pull/1031)
+
+Changes in [2.3.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.3.0) (2019-08-05)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.3.0-rc.1...v2.3.0)
+
+ * [release] Support rewriting push rules when our internal defaults change
+   [\#1008](https://github.com/matrix-org/matrix-js-sdk/pull/1008)
+
+Changes in [2.3.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.3.0-rc.1) (2019-07-31)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.2.0...v2.3.0-rc.1)
+
+ * Add support for IS v2 API with authentication
+   [\#1002](https://github.com/matrix-org/matrix-js-sdk/pull/1002)
+ * Tombstone bugfixes
+   [\#1001](https://github.com/matrix-org/matrix-js-sdk/pull/1001)
+ * Support for MSC2140 (terms of service for IS/IM)
+   [\#988](https://github.com/matrix-org/matrix-js-sdk/pull/988)
+ * Add a request method to /devices
+   [\#994](https://github.com/matrix-org/matrix-js-sdk/pull/994)
+
+Changes in [2.2.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.2.0) (2019-07-18)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.2.0-rc.2...v2.2.0)
+
+ * Upgrade lodash dependencies
+
+Changes in [2.2.0-rc.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.2.0-rc.2) (2019-07-12)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.2.0-rc.1...v2.2.0-rc.2)
+
+ * Fix regression from 2.2.0-rc.1 in request to /devices
+   [\#995](https://github.com/matrix-org/matrix-js-sdk/pull/995)
+
+Changes in [2.2.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.2.0-rc.1) (2019-07-12)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.1.1...v2.2.0-rc.1)
+
+ * End the verification timer when verification is done
+   [\#993](https://github.com/matrix-org/matrix-js-sdk/pull/993)
+ * Stabilize usage of stably stable APIs (in a stable way)
+   [\#990](https://github.com/matrix-org/matrix-js-sdk/pull/990)
+ * Expose original_event for /relations
+   [\#987](https://github.com/matrix-org/matrix-js-sdk/pull/987)
+ * Process ephemeral events outside timeline handling
+   [\#989](https://github.com/matrix-org/matrix-js-sdk/pull/989)
+ * Don't accept any locally known edits earlier than the last known server-side
+   aggregated edit
+   [\#986](https://github.com/matrix-org/matrix-js-sdk/pull/986)
+ * Get edit date transparently from server aggregations or local echo
+   [\#984](https://github.com/matrix-org/matrix-js-sdk/pull/984)
+ * Add a function to flag keys for backup without scheduling a backup
+   [\#982](https://github.com/matrix-org/matrix-js-sdk/pull/982)
+ * Block read marker and read receipt from advancing into pending events
+   [\#981](https://github.com/matrix-org/matrix-js-sdk/pull/981)
+ * Upgrade dependencies
+   [\#977](https://github.com/matrix-org/matrix-js-sdk/pull/977)
+ * Add default push rule to ignore reactions
+   [\#976](https://github.com/matrix-org/matrix-js-sdk/pull/976)
+ * Fix exception whilst syncing
+   [\#979](https://github.com/matrix-org/matrix-js-sdk/pull/979)
+ * Include the error object when raising Session.logged_out
+   [\#975](https://github.com/matrix-org/matrix-js-sdk/pull/975)
+
+Changes in [2.1.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.1.1) (2019-07-11)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.1.0...v2.1.1)
+
+ * Process emphemeral events outside timeline handling
+   [\#989](https://github.com/matrix-org/matrix-js-sdk/pull/989)
+
+Changes in [2.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.1.0) (2019-07-08)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.1.0-rc.1...v2.1.0)
+
+ * Fix exception whilst syncing
+   [\#979](https://github.com/matrix-org/matrix-js-sdk/pull/979)
+
+Changes in [2.1.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.1.0-rc.1) (2019-07-03)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.0.1...v2.1.0-rc.1)
+
+ * Handle self read receipts for fixing e2e notification counts
+   [\#974](https://github.com/matrix-org/matrix-js-sdk/pull/974)
+ * Add redacts field to event.toJSON
+   [\#973](https://github.com/matrix-org/matrix-js-sdk/pull/973)
+ * Handle associated event send failures
+   [\#972](https://github.com/matrix-org/matrix-js-sdk/pull/972)
+ * Remove irrelevant debug line from timeline handling
+   [\#971](https://github.com/matrix-org/matrix-js-sdk/pull/971)
+ * Handle relations in encrypted rooms
+   [\#969](https://github.com/matrix-org/matrix-js-sdk/pull/969)
+ * Relations endpoint support
+   [\#967](https://github.com/matrix-org/matrix-js-sdk/pull/967)
+ * Disable event encryption for reactions
+   [\#968](https://github.com/matrix-org/matrix-js-sdk/pull/968)
+ * Change the known safe room version to version 4
+   [\#966](https://github.com/matrix-org/matrix-js-sdk/pull/966)
+ * Check for lazy-loading support in the spec versions instead
+   [\#965](https://github.com/matrix-org/matrix-js-sdk/pull/965)
+ * Use camelCase instead of underscore
+   [\#963](https://github.com/matrix-org/matrix-js-sdk/pull/963)
+ * Time out verification attempts after 10 minutes of inactivity
+   [\#961](https://github.com/matrix-org/matrix-js-sdk/pull/961)
+ * Don't handle key verification requests which are immediately cancelled
+   [\#962](https://github.com/matrix-org/matrix-js-sdk/pull/962)
+
+Changes in [2.0.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.0.1) (2019-06-19)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.0.1-rc.2...v2.0.1)
+
+ No changes since rc.2
+
+Changes in [2.0.1-rc.2](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.0.1-rc.2) (2019-06-18)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.0.1-rc.1...v2.0.1-rc.2)
+
+ * return 'sending' status for an event that is only locally redacted
+   [\#960](https://github.com/matrix-org/matrix-js-sdk/pull/960)
+ * Key verification request fixes
+   [\#954](https://github.com/matrix-org/matrix-js-sdk/pull/954)
+ * Add flag to force saving sync store
+   [\#956](https://github.com/matrix-org/matrix-js-sdk/pull/956)
+ * Expose the inhibit_login flag to register
+   [\#953](https://github.com/matrix-org/matrix-js-sdk/pull/953)
+ *  Support redactions and relations of/with unsent events.
+   [\#947](https://github.com/matrix-org/matrix-js-sdk/pull/947)
+
+Changes in [2.0.1-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.0.1-rc.1) (2019-06-12)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v2.0.0...v2.0.1-rc.1)
+
+ * Fix content uploads for modern browsers
+   [\#952](https://github.com/matrix-org/matrix-js-sdk/pull/952)
+ * Don't overlap auth submissions with polls
+   [\#951](https://github.com/matrix-org/matrix-js-sdk/pull/951)
+ * Add funding details for GitHub sponsor button
+   [\#945](https://github.com/matrix-org/matrix-js-sdk/pull/945)
+ * Fix backup sig validation with multiple sigs
+   [\#944](https://github.com/matrix-org/matrix-js-sdk/pull/944)
+ * Don't send another token request while one's in flight
+   [\#943](https://github.com/matrix-org/matrix-js-sdk/pull/943)
+ * Don't poll UI auth again until current poll finishes
+   [\#942](https://github.com/matrix-org/matrix-js-sdk/pull/942)
+ * Provide the discovered URLs when a liveliness error occurs
+   [\#938](https://github.com/matrix-org/matrix-js-sdk/pull/938)
+ * Encode event IDs when redacting events
+   [\#941](https://github.com/matrix-org/matrix-js-sdk/pull/941)
+ * add missing logger
+   [\#940](https://github.com/matrix-org/matrix-js-sdk/pull/940)
+ * verification: don't error if we don't know about some keys
+   [\#939](https://github.com/matrix-org/matrix-js-sdk/pull/939)
+ * Local echo for redactions
+   [\#937](https://github.com/matrix-org/matrix-js-sdk/pull/937)
+ * Refresh safe room versions when the server looks more modern than us
+   [\#934](https://github.com/matrix-org/matrix-js-sdk/pull/934)
+ * Add v4 as a safe room version
+   [\#935](https://github.com/matrix-org/matrix-js-sdk/pull/935)
+ * Disable guard-for-in rule
+   [\#933](https://github.com/matrix-org/matrix-js-sdk/pull/933)
+ * Extend loglevel logging for the whole project
+   [\#924](https://github.com/matrix-org/matrix-js-sdk/pull/924)
+ * fix(login): saves access_token and user_id after login for all login types
+   [\#930](https://github.com/matrix-org/matrix-js-sdk/pull/930)
+ * Do not try to request thumbnails with non-integer sizes
+   [\#929](https://github.com/matrix-org/matrix-js-sdk/pull/929)
+ * Revert "Add a bunch of debugging to .well-known IS validation"
+   [\#928](https://github.com/matrix-org/matrix-js-sdk/pull/928)
+ * Add a bunch of debugging to .well-known IS validation
+   [\#927](https://github.com/matrix-org/matrix-js-sdk/pull/927)
+
+Changes in [2.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v2.0.0) (2019-05-31)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.2.0...v2.0.0)
+
+BREAKING CHANGES
+----------------
+
+ * This package now publishes in ES6 / ES2015 syntax to NPM
+ * Saves access_token and user_id after login for all login types
+   [\#932](https://github.com/matrix-org/matrix-js-sdk/pull/932)
+ * Fix recovery key encoding for base-x 3.0.5
+   [\#931](https://github.com/matrix-org/matrix-js-sdk/pull/931)
+
+Changes in [1.2.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.2.0) (2019-05-29)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.2.0-rc.1...v1.2.0)
+
+
+Changes in [1.2.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.2.0-rc.1) (2019-05-23)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.1.0...v1.2.0-rc.1)
+
+ * interactive-auth now handles requesting email tokens
+   [\#926](https://github.com/matrix-org/matrix-js-sdk/pull/926)
+ * allow access to unreplaced message content
+   [\#923](https://github.com/matrix-org/matrix-js-sdk/pull/923)
+ * Add method to retrieve replacing event
+   [\#922](https://github.com/matrix-org/matrix-js-sdk/pull/922)
+ * More logging when signature verification fails
+   [\#921](https://github.com/matrix-org/matrix-js-sdk/pull/921)
+ * Local echo for m.replace relations
+   [\#920](https://github.com/matrix-org/matrix-js-sdk/pull/920)
+ * Track relations as pending and remove when cancelled
+   [\#919](https://github.com/matrix-org/matrix-js-sdk/pull/919)
+ * Add stringify helper to summarise events when debugging
+   [\#916](https://github.com/matrix-org/matrix-js-sdk/pull/916)
+ * Message editing: filter out replacements for senders that are not the
+   original sender
+   [\#918](https://github.com/matrix-org/matrix-js-sdk/pull/918)
+ * Wait until decrypt before aggregating
+   [\#917](https://github.com/matrix-org/matrix-js-sdk/pull/917)
+ * Message editing: mark original event as replaced instead of replacing the
+   event object
+   [\#914](https://github.com/matrix-org/matrix-js-sdk/pull/914)
+ * Support for replacing message through m.replace relationship.
+   [\#913](https://github.com/matrix-org/matrix-js-sdk/pull/913)
+ * Use a short timeout for .well-known requests
+   [\#912](https://github.com/matrix-org/matrix-js-sdk/pull/912)
+ * Redaction and change events for relations
+   [\#911](https://github.com/matrix-org/matrix-js-sdk/pull/911)
+ * Add basic read path for relations
+   [\#910](https://github.com/matrix-org/matrix-js-sdk/pull/910)
+ * Add a concept of default push rules, using it for tombstone notifications
+   [\#860](https://github.com/matrix-org/matrix-js-sdk/pull/860)
+ * yarn upgrade
+   [\#907](https://github.com/matrix-org/matrix-js-sdk/pull/907)
+
+Changes in [1.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.1.0) (2019-05-07)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.1.0-rc.1...v1.1.0)
+
+ * No Changes since rc.1
+
+Changes in [1.1.0-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.1.0-rc.1) (2019-04-30)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.4...v1.1.0-rc.1)
+
+ * use the release version of olm 3.1.0
+   [\#903](https://github.com/matrix-org/matrix-js-sdk/pull/903)
+ * Use new Olm repo link in README
+   [\#901](https://github.com/matrix-org/matrix-js-sdk/pull/901)
+ * Support being fed a .well-known config object for validation
+   [\#897](https://github.com/matrix-org/matrix-js-sdk/pull/897)
+ * emit self-membership event at end of handling sync update
+   [\#900](https://github.com/matrix-org/matrix-js-sdk/pull/900)
+ * Use packages.matrix.org for Olm
+   [\#898](https://github.com/matrix-org/matrix-js-sdk/pull/898)
+ * Fix tests on develop
+   [\#899](https://github.com/matrix-org/matrix-js-sdk/pull/899)
+ * Stop syncing when the token is invalid
+   [\#895](https://github.com/matrix-org/matrix-js-sdk/pull/895)
+ * change event redact,  POST request to PUT request
+   [\#887](https://github.com/matrix-org/matrix-js-sdk/pull/887)
+ * Expose better autodiscovery error messages
+   [\#894](https://github.com/matrix-org/matrix-js-sdk/pull/894)
+ * Explicitly guard store usage during sync startup
+   [\#892](https://github.com/matrix-org/matrix-js-sdk/pull/892)
+ * Flag v3 rooms as safe
+   [\#893](https://github.com/matrix-org/matrix-js-sdk/pull/893)
+ * Cache failed capabilities lookups for shorter amounts of time
+   [\#890](https://github.com/matrix-org/matrix-js-sdk/pull/890)
+ * Fix highlight notifications for unencrypted rooms
+   [\#891](https://github.com/matrix-org/matrix-js-sdk/pull/891)
+ * Document checking crypto state before using `hasUnverifiedDevices`
+   [\#889](https://github.com/matrix-org/matrix-js-sdk/pull/889)
+ * Add logging to sync startup path
+   [\#888](https://github.com/matrix-org/matrix-js-sdk/pull/888)
+ * Track e2e highlights better, particularly in 'Mentions Only' rooms
+   [\#886](https://github.com/matrix-org/matrix-js-sdk/pull/886)
+ * support both the incorrect and correct MAC methods
+   [\#882](https://github.com/matrix-org/matrix-js-sdk/pull/882)
+ * Refuse to set forwards pagination token on live timeline
+   [\#885](https://github.com/matrix-org/matrix-js-sdk/pull/885)
+ * Degrade `IndexedDBStore` back to memory only on failure
+   [\#884](https://github.com/matrix-org/matrix-js-sdk/pull/884)
+ * Refuse to link live timelines into the forwards/backwards position when
+   either is invalid
+   [\#877](https://github.com/matrix-org/matrix-js-sdk/pull/877)
+ * Key backup logging improvements
+   [\#883](https://github.com/matrix-org/matrix-js-sdk/pull/883)
+ * Don't assume aborts are always from txn.abort()
+   [\#880](https://github.com/matrix-org/matrix-js-sdk/pull/880)
+ * Add a bunch of logging
+   [\#878](https://github.com/matrix-org/matrix-js-sdk/pull/878)
+ * Refuse splicing the live timeline into a broken position
+   [\#873](https://github.com/matrix-org/matrix-js-sdk/pull/873)
+ * Add existence check to local storage based crypto store
+   [\#872](https://github.com/matrix-org/matrix-js-sdk/pull/872)
+
+Changes in [1.0.4](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.4) (2019-04-08)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.3...v1.0.4)
+
+ * Hotfix: more logging and potential fixes for timeline corruption issue, see ticket https://github.com/vector-im/riot-web/issues/8593.
+
+Changes in [1.0.3](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.3) (2019-04-01)
+================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.3-rc.1...v1.0.3)
+
+ * Add existence check to local storage based crypto store
+   [\#874](https://github.com/matrix-org/matrix-js-sdk/pull/874)
+
+Changes in [1.0.3-rc.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v1.0.3-rc.1) (2019-03-27)
+==========================================================================================================
+[Full Changelog](https://github.com/matrix-org/matrix-js-sdk/compare/v1.0.2...v1.0.3-rc.1)
+
+ * Add IndexedDB existence checks
+   [\#871](https://github.com/matrix-org/matrix-js-sdk/pull/871)
+ * Emit sync errors for capturing by clients
+   [\#869](https://github.com/matrix-org/matrix-js-sdk/pull/869)
+ * Add functions for getting room upgrade history and leaving those rooms
+   [\#868](https://github.com/matrix-org/matrix-js-sdk/pull/868)
+ * Clarify the meaning of 'real name' for contribution
+   [\#867](https://github.com/matrix-org/matrix-js-sdk/pull/867)
+ * Remove `sessionStore` to `cryptoStore` migration path
+   [\#865](https://github.com/matrix-org/matrix-js-sdk/pull/865)
+ * Add debugging for spurious room version warnings
+   [\#866](https://github.com/matrix-org/matrix-js-sdk/pull/866)
+ * Add investigation notes for browser storage
+   [\#864](https://github.com/matrix-org/matrix-js-sdk/pull/864)
+ * make sure resolve object is defined before calling it
+   [\#862](https://github.com/matrix-org/matrix-js-sdk/pull/862)
+ * Rename `MatrixInMemoryStore` to `MemoryStore`
+   [\#861](https://github.com/matrix-org/matrix-js-sdk/pull/861)
+ * Use Buildkite for CI
+   [\#859](https://github.com/matrix-org/matrix-js-sdk/pull/859)
+ * only create one session at a time per device
+   [\#857](https://github.com/matrix-org/matrix-js-sdk/pull/857)
+
+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)
@@ -24,7 +24,7 @@ works. Develop is the unstable branch where all the development actually
 happens: the workflow is that contributors should fork the develop branch to
 make a 'feature' branch for a particular contribution, and then make a pull
 request to merge this back into the matrix.org 'official' develop branch. We
-use github's pull request workflow to review the contribution, and either ask
+use GitHub's pull request workflow to review the contribution, and either ask
 you to make any refinements needed or merge it and make them ourselves. The
 changes will then land on master when we next do a release.

@@ -60,8 +60,8 @@ Sign off
 ~~~~~~~~

 In order to have a concrete record that your contribution is intentional
-and you agree to license it under the same terms as the project's license, we've adopted the
-same lightweight approach that the Linux Kernel
+and you agree to license it under the same terms as the project's license, we've
+adopted the same lightweight approach that the Linux Kernel
 (https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker
 (https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
 projects use: the DCO (Developer Certificate of Origin:
@@ -109,7 +109,16 @@ include the line in your commit or pull request comment::

    Signed-off-by: Your Name <your@email.example.org>

-...using your real name; unfortunately pseudonyms and anonymous contributions
-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 :)
+We accept contributions under a legally identifiable name, such as your name on
+government documentation or common-law names (names claimed by legitimate usage
+or repute). Unfortunately, we cannot accept anonymous contributions at this
+time.
+
+Git allows you to add this signoff automatically when using the ``-s`` flag to
+``git commit``, which uses the name and email set in your ``user.name`` and
+``user.email`` git configs.
+
+If you forgot to sign off your commits before making your pull request and are
+on Git 2.17+ you can mass signoff using rebase::
+
+    git rebase --signoff origin/develop
@@ -1,8 +1,7 @@
 Matrix Javascript SDK
 =====================
-[![Build Status](http://matrix.org/jenkins/buildStatus/icon?job=JavascriptSDK)](http://matrix.org/jenkins/job/JavascriptSDK/)

-This is the [Matrix](https://matrix.org) Client-Server v1/v2 alpha SDK for
+This is the [Matrix](https://matrix.org) Client-Server r0 SDK for
 JavaScript. This SDK can be run in a browser or in Node.js.

 Quickstart
@@ -21,7 +20,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");
@@ -76,7 +79,7 @@ client.on("Room.timeline", function(event, room, toStartOfTimeline) {
 });
 ```

-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:
+By default, the `matrix-js-sdk` client uses the `MemoryStore` to store events as they are received. For example to iterate through the currently stored timeline for a room:

 ```javascript
 Object.keys(client.store.rooms).forEach((roomId) => {
@@ -283,7 +286,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
 ```
@@ -294,8 +297,8 @@ End-to-end encryption support
 =============================

 The SDK supports end-to-end encryption via the Olm and Megolm protocols, using
-[libolm](http://matrix.org/git/olm). It is left up to the application to make
-libolm available, via the ``Olm`` global.
+[libolm](https://gitlab.matrix.org/matrix-org/olm). It is left up to the 
+application to make libolm available, via the ``Olm`` global.

 It is also necessry to call ``matrixClient.initCrypto()`` after creating a new
 ``MatrixClient`` (but **before** calling ``matrixClient.startClient()``) to
@@ -314,20 +317,20 @@ specification.

 To provide the Olm library in a browser application:

- * download the transpiled libolm (from https://matrix.org/packages/npm/olm/).
+ * download the transpiled libolm (from https://packages.matrix.org/npm/olm/).
 * load ``olm.js`` as a ``<script>`` *before* ``browser-matrix.js``.
 
 To provide the Olm library in a node.js application:

- * ``npm install https://matrix.org/packages/npm/olm/olm-2.2.2.tgz``
+ * ``yarn add https://packages.matrix.org/npm/olm/olm-3.1.4.tgz``
   (replace the URL with the latest version you want to use from
-    https://matrix.org/packages/npm/olm/)
+    https://packages.matrix.org/npm/olm/)
 * ``global.Olm = require('olm');`` *before* loading ``matrix-js-sdk``.

-If you want to package Olm as dependency for your node.js application, you
-can use ``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://packages.matrix.org/npm/olm/olm-3.1.4.tgz``. If your
+application also works without e2e crypto enabled, add ``--optional`` to mark it
+as an optional dependency.


 Contributing
@@ -337,7 +340,7 @@ want to use this SDK, skip this section.*

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

 Building
@@ -345,20 +348,20 @@ Building

 To build a browser version from scratch when developing::
 ```
- $ npm run build
+ $ yarn build
 ```

 To constantly do builds when files are modified (using ``watchify``)::
 ```
- $ npm run watch
+ $ yarn watch
 ```

 To run tests (Jasmine)::
 ```
- $ npm test
+ $ yarn test
 ```

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

 # now run our checks
 cd "$tmpdir"
-npm run lint
+yarn lint
@@ -1,34 +0,0 @@
-#!/bin/bash -l
-
-set -x
-
-export NVM_DIR="$HOME/.nvm"
-[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
-
-nvm use 6 || exit $?
-npm install || exit $?
-
-RC=0
-
-function fail {
-    echo $@ >&2
-    RC=1
-}
-
-# don't use last time's test reports
-rm -rf reports coverage || exit $?
-
-npm test || fail "npm test finished with return code $?"
-
-npm run -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 $?"
-
-npm run gendoc || fail "JSDoc failed with code $?"
-
-exit $RC
@@ -1,24 +1,24 @@
 {
  "name": "matrix-js-sdk",
-  "version": "0.13.1",
+  "version": "2.4.5",
  "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:run": "istanbul cover --report text --report cobertura --config .istanbul.yml -i \"lib/**/*.js\" node_modules/mocha/bin/_mocha -- --recursive specbuild --colors",
    "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",
-    "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",
+    "test": "yarn test:build && yarn test:run",
+    "check": "yarn test:build && _mocha --recursive specbuild --colors",
+    "gendoc": "babel --no-babelrc --plugins transform-class-properties -d .jsdocbuild src && jsdoc -r .jsdocbuild -P package.json -R README.md -d .jsdoc",
+    "start": "yarn start:init && yarn start:watch",
    "start:watch": "babel -s -w --skip-initial-build -d lib src",
    "start:init": "babel -s -d lib src",
    "clean": "rimraf lib dist",
-    "build": "babel -s -d lib src && rimraf dist && mkdir dist && browserify -d browser-index.js | exorcist dist/browser-matrix.js.map > dist/browser-matrix.js && 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",
+    "build": "babel -s -d lib src && rimraf dist && mkdir dist && browserify -d browser-index.js | exorcist dist/browser-matrix.js.map > dist/browser-matrix.js && terser -c -m -o dist/browser-matrix.min.js --source-map \"content='dist/browser-matrix.js.map'\" dist/browser-matrix.js",
+    "dist": "yarn build",
    "watch": "watchify -d browser-index.js -o 'exorcist dist/browser-matrix.js.map > dist/browser-matrix.js' -v",
-    "lint": "eslint --max-warnings 102 src spec",
-    "prepublish": "npm run clean && npm run build && git rev-parse HEAD > git-revision.txt"
+    "lint": "eslint --max-warnings 93 src spec",
+    "prepare": "yarn clean && yarn build && git rev-parse HEAD > git-revision.txt"
  },
  "repository": {
    "type": "git",
@@ -44,7 +44,6 @@
    "git-revision.txt",
    "index.js",
    "browser-index.js",
-    "jenkins.sh",
    "lib",
    "package.json",
    "release.sh",
@@ -54,34 +53,41 @@
  "dependencies": {
    "another-json": "^0.2.0",
    "babel-runtime": "^6.26.0",
-    "bluebird": "^3.5.0",
+    "bluebird": "3.5.5",
    "browser-request": "^0.3.3",
+    "bs58": "^4.0.1",
    "content-type": "^1.0.2",
-    "request": "^2.53.0"
+    "loglevel": "^1.6.4",
+    "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-class-properties": "^6.24.1",
    "babel-plugin-transform-runtime": "^6.23.0",
    "babel-preset-es2015": "^6.18.0",
-    "browserify": "^14.0.0",
+    "babel-preset-es2016": "^6.24.1",
+    "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",
+    "eslint-plugin-babel": "^5.3.0",
+    "exorcist": "^1.0.1",
    "expect": "^1.20.2",
    "istanbul": "^0.4.5",
    "jsdoc": "^3.5.5",
    "lolex": "^1.5.2",
-    "matrix-mock-request": "^1.2.0",
-    "mocha": "^5.2.0",
-    "mocha-jenkins-reporter": "^0.4.0",
-    "rimraf": "^2.5.4",
-    "source-map-support": "^0.4.11",
-    "sourceify": "^0.1.0",
-    "uglify-js": "^2.8.26",
-    "watchify": "^3.2.1"
+    "matrix-mock-request": "^1.2.3",
+    "mocha": "^6.2.1",
+    "olm": "https://packages.matrix.org/npm/olm/olm-3.1.4.tgz",
+    "rimraf": "^3.0.0",
+    "source-map-support": "^0.5.13",
+    "sourceify": "^1.0.0",
+    "terser": "^4.3.8",
+    "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,15 @@ if [ $dodist -eq 0 ]; then
    pushd "$builddir"
    git clone "$projdir" .
    git checkout "$rel_branch"
-    npm install
+    # We use Git branch / commit dependencies for some packages, and Yarn seems
+    # to have a hard time getting that right. See also
+    # https://github.com/yarnpkg/yarn/issues/4734. As a workaround, we clean the
+    # global cache here to ensure we get the right thing.
+    yarn cache clean
+    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 +292,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 +323,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.
@@ -27,6 +27,7 @@ import MockHttpBackend from 'matrix-mock-request';
 import expect from 'expect';
 import Promise from 'bluebird';
 import LocalStorageCryptoStore from '../lib/crypto/store/localStorage-crypto-store';
+import logger from '../src/logger';

 /**
 * Wrapper for a MockStorageApi, MockHttpBackend and MatrixClient
@@ -38,9 +39,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 +52,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 = {};
@@ -78,7 +83,7 @@ TestClient.prototype.toString = function() {
 * @return {Promise}
 */
 TestClient.prototype.start = function() {
-    console.log(this + ': starting');
+    logger.log(this + ': starting');
    this.httpBackend.when("GET", "/pushrules").respond(200, {});
    this.httpBackend.when("POST", "/filter").respond(200, { filter_id: "fid" });
    this.expectDeviceKeyUpload();
@@ -96,15 +101,17 @@ TestClient.prototype.start = function() {
        this.httpBackend.flushAllExpected(),
        testUtils.syncPromise(this.client),
    ]).then(() => {
-        console.log(this + ': started');
+        logger.log(this + ': started');
    });
 };

 /**
 * stop the client
+ * @return {Promise} Resolves once the mock http backend has finished all pending flushes
 */
 TestClient.prototype.stop = function() {
    this.client.stopClient();
+    return this.httpBackend.stop();
 };

 /**
@@ -116,7 +123,7 @@ TestClient.prototype.expectDeviceKeyUpload = function() {
        expect(content.one_time_keys).toBe(undefined);
        expect(content.device_keys).toBeTruthy();

-        console.log(self + ': received device keys');
+        logger.log(self + ': received device keys');
        // we expect this to happen before any one-time keys are uploaded.
        expect(Object.keys(self.oneTimeKeys).length).toEqual(0);

@@ -153,7 +160,7 @@ TestClient.prototype.awaitOneTimeKeyUpload = function() {
              expect(content.device_keys).toBe(undefined);
              expect(content.one_time_keys).toBeTruthy();
              expect(content.one_time_keys).toNotEqual({});
-              console.log('%s: received %i one-time keys', this,
+              logger.log('%s: received %i one-time keys', this,
                          Object.keys(content.one_time_keys).length);
              this.oneTimeKeys = content.one_time_keys;
              return {one_time_key_counts: {
@@ -179,7 +186,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;
        });
@@ -213,11 +224,11 @@ TestClient.prototype.getSigningKey = function() {
 * @returns {Promise} promise which completes once the sync has been flushed
 */
 TestClient.prototype.flushSync = function() {
-    console.log(`${this}: flushSync`);
+    logger.log(`${this}: flushSync`);
    return Promise.all([
        this.httpBackend.flush('/sync', 1),
        testUtils.syncPromise(this.client),
    ]).then(() => {
-        console.log(`${this}: flushSync completed`);
+        logger.log(`${this}: flushSync completed`);
    });
 };
@@ -20,6 +20,7 @@ import Promise from 'bluebird';

 import TestClient from '../TestClient';
 import testUtils from '../test-utils';
+import logger from '../../src/logger';

 const ROOM_ID = "!room:id";

@@ -71,7 +72,7 @@ function getSyncResponse(roomMembers) {

 describe("DeviceList management:", function() {
    if (!global.Olm) {
-        console.warn('not running deviceList tests: Olm not present');
+        logger.warn('not running deviceList tests: Olm not present');
        return;
    }

@@ -87,7 +88,7 @@ describe("DeviceList management:", function() {
    }

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

        // we create our own sessionStoreBackend so that we can use it for
        // another TestClient.
@@ -97,17 +98,18 @@ 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);

            return aliceTestClient.flushSync();
        }).then(function() {
-            console.log("Forcing alice to download our device keys");
+            logger.log("Forcing alice to download our device keys");

            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(200, {
                device_keys: {
@@ -120,7 +122,7 @@ describe("DeviceList management:", function() {
                aliceTestClient.httpBackend.flush('/keys/query', 1),
            ]);
        }).then(function() {
-            console.log("Telling alice to send a megolm message");
+            logger.log("Telling alice to send a megolm message");

            aliceTestClient.httpBackend.when(
                'PUT', '/send/',
@@ -143,6 +145,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']));
@@ -36,6 +36,7 @@ import Promise from 'bluebird';
 const utils = require("../../lib/utils");
 const testUtils = require("../test-utils");
 const TestClient = require('../TestClient').default;
+import logger from '../../src/logger';

 let aliTestClient;
 const roomId = "!room:localhost";
@@ -72,7 +73,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};
@@ -91,12 +96,16 @@ function expectBobQueryKeys() {

    const aliKeys = {};
    aliKeys[aliDeviceId] = aliTestClient.deviceKeys;
-    console.log("query result will be", aliKeys);
+    logger.log("query result will be", aliKeys);

    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};
@@ -326,7 +335,7 @@ function recvMessage(httpBackend, client, sender, message) {
            if (event.getType() == "m.room.member") {
                return;
            }
-            console.log(client.credentials.userId + " received event",
+            logger.log(client.credentials.userId + " received event",
                        event);

            client.removeListener("event", onEvent);
@@ -397,7 +406,7 @@ describe("MatrixClient crypto", function() {
    }

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

        aliTestClient = new TestClient(aliUserId, aliDeviceId, aliAccessToken);
        await aliTestClient.client.initCrypto();
@@ -410,10 +419,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 +553,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 +564,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 +575,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())
@@ -596,7 +608,7 @@ describe("MatrixClient crypto", function() {

                const eventPromise = new Promise((resolve, reject) => {
                    const onEvent = function(event) {
-                        console.log(bobUserId + " received event",
+                        logger.log(bobUserId + " received event",
                                    event);
                        resolve(event);
                    };
@@ -617,6 +629,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 +649,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 +663,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 +675,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 +713,6 @@ describe("MatrixClient crypto", function() {
            }).then(() => {
                aliTestClient.expectKeyQuery({
                    device_keys: {
-                        [aliUserId]: {},
                        [bobUserId]: {},
                    },
                });
@@ -719,7 +735,7 @@ describe("MatrixClient crypto", function() {

        return Promise.resolve()
            .then(() => {
-                console.log(aliTestClient + ': starting');
+                logger.log(aliTestClient + ': starting');
                httpBackend.when("GET", "/pushrules").respond(200, {});
                httpBackend.when("POST", "/filter").respond(200, { filter_id: "fid" });
                aliTestClient.expectDeviceKeyUpload();
@@ -731,7 +747,7 @@ describe("MatrixClient crypto", function() {
                aliTestClient.client.startClient({});

                return httpBackend.flushAllExpected().then(() => {
-                    console.log(aliTestClient + ': started');
+                    logger.log(aliTestClient + ': started');
                });
            })
            .then(() => httpBackend.when("POST", "/keys/upload")
@@ -740,7 +756,7 @@ describe("MatrixClient crypto", function() {
                    expect(content.one_time_keys).toNotEqual({});
                    expect(Object.keys(content.one_time_keys).length)
                        .toBeGreaterThanOrEqualTo(1);
-                    console.log('received %i one-time keys',
+                    logger.log('received %i one-time keys',
                                Object.keys(content.one_time_keys).length);
                    // cancel futher calls by telling the client
                    // we have more than we need
@@ -15,7 +15,7 @@ describe("MatrixClient events", function() {
    const selfAccessToken = "aseukfgwef";

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
        sdk.request(httpBackend.requestFn);
        client = sdk.createClient({
@@ -30,6 +30,7 @@ describe("MatrixClient events", function() {
    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
        client.stopClient();
+        return httpBackend.stop();
    });

    describe("emissions", function() {
@@ -156,7 +157,7 @@ describe("MatrixClient events", function() {
                    return;
                }

-                expect(event.event).toEqual(SYNC_DATA.presence.events[0]);
+                expect(event.event).toMatch(SYNC_DATA.presence.events[0]);
                expect(user.presence).toEqual(
                    SYNC_DATA.presence.events[0].content.presence,
                );
@@ -301,11 +302,32 @@ describe("MatrixClient events", function() {
        });

        it("should emit Session.logged_out on M_UNKNOWN_TOKEN", function() {
-            httpBackend.when("GET", "/sync").respond(401, { errcode: 'M_UNKNOWN_TOKEN' });
+            const error = { errcode: 'M_UNKNOWN_TOKEN' };
+            httpBackend.when("GET", "/sync").respond(401, error);

            let sessionLoggedOutCount = 0;
-            client.on("Session.logged_out", function(event, member) {
+            client.on("Session.logged_out", function(errObj) {
                sessionLoggedOutCount++;
+                expect(errObj.data).toEqual(error);
+            });
+
+            client.startClient();
+
+            return httpBackend.flushAllExpected().then(function() {
+                expect(sessionLoggedOutCount).toEqual(
+                    1, "Session.logged_out fired wrong number of times",
+                );
+            });
+        });
+
+        it("should emit Session.logged_out on M_UNKNOWN_TOKEN (soft logout)", function() {
+            const error = { errcode: 'M_UNKNOWN_TOKEN', soft_logout: true };
+            httpBackend.when("GET", "/sync").respond(401, error);
+
+            let sessionLoggedOutCount = 0;
+            client.on("Session.logged_out", function(errObj) {
+                sessionLoggedOutCount++;
+                expect(errObj.data).toEqual(error);
            });

            client.startClient();
@@ -5,6 +5,7 @@ const sdk = require("../..");
 const HttpBackend = require("matrix-mock-request");
 const utils = require("../test-utils");
 const EventTimeline = sdk.EventTimeline;
+import logger from '../../src/logger';

 const baseUrl = "http://localhost.or.something";
 const userId = "@alice:localhost";
@@ -84,7 +85,7 @@ function startClient(httpBackend, client) {
    // set up a promise which will resolve once the client is initialised
    const deferred = Promise.defer();
    client.on("sync", function(state) {
-        console.log("sync", state);
+        logger.log("sync", state);
        if (state != "SYNCING") {
            return;
        }
@@ -102,7 +103,7 @@ describe("getEventTimeline support", function() {
    let client;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
        sdk.request(httpBackend.requestFn);
    });
@@ -111,6 +112,7 @@ describe("getEventTimeline support", function() {
        if (client) {
            client.stopClient();
        }
+        return httpBackend.stop();
    });

    it("timeline support must be enabled to work", function(done) {
@@ -226,7 +228,7 @@ describe("MatrixClient event timelines", function() {
    let httpBackend = null;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
        sdk.request(httpBackend.requestFn);

@@ -668,11 +670,11 @@ describe("MatrixClient event timelines", function() {
                // initiate the send, and set up checks to be done when it completes
                // - but note that it won't complete until after the /sync does, below.
                client.sendTextMessage(roomId, "a body", TXN_ID).then(function(res) {
-                    console.log("sendTextMessage completed");
+                    logger.log("sendTextMessage completed");
                    expect(res.event_id).toEqual(event.event_id);
                    return client.getEventTimeline(timelineSet, event.event_id);
                }).then(function(tl) {
-                    console.log("getEventTimeline completed (2)");
+                    logger.log("getEventTimeline completed (2)");
                    expect(tl.getEvents().length).toEqual(2);
                    expect(tl.getEvents()[1].getContent().body).toEqual("a body");
                }),
@@ -683,7 +685,7 @@ describe("MatrixClient event timelines", function() {
                ]).then(function() {
                    return client.getEventTimeline(timelineSet, event.event_id);
                }).then(function(tl) {
-                    console.log("getEventTimeline completed (1)");
+                    logger.log("getEventTimeline completed (1)");
                    expect(tl.getEvents().length).toEqual(2);
                    expect(tl.getEvents()[1].event).toEqual(event);

@@ -4,7 +4,7 @@ const sdk = require("../..");
 const HttpBackend = require("matrix-mock-request");
 const publicGlobals = require("../../lib/matrix");
 const Room = publicGlobals.Room;
-const MatrixInMemoryStore = publicGlobals.MatrixInMemoryStore;
+const MemoryStore = publicGlobals.MemoryStore;
 const Filter = publicGlobals.Filter;
 const utils = require("../test-utils");
 const MockStorageApi = require("../MockStorageApi");
@@ -21,9 +21,9 @@ describe("MatrixClient", function() {
    const accessToken = "aseukfgwef";

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
-        store = new MatrixInMemoryStore();
+        store = new MemoryStore();

        const mockStorage = new MockStorageApi();
        sessionStore = new sdk.WebStorageSessionStore(mockStorage);
@@ -41,13 +41,14 @@ describe("MatrixClient", function() {

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

    describe("uploadContent", function() {
        const buf = new Buffer('hello world');
        it("should upload the file", function(done) {
            httpBackend.when(
-                "POST", "/_matrix/media/v1/upload",
+                "POST", "/_matrix/media/r0/upload",
            ).check(function(req) {
                expect(req.rawData).toEqual(buf);
                expect(req.queryParams.filename).toEqual("hi.txt");
@@ -86,7 +87,7 @@ describe("MatrixClient", function() {

        it("should parse the response if rawResponse=false", function(done) {
            httpBackend.when(
-                "POST", "/_matrix/media/v1/upload",
+                "POST", "/_matrix/media/r0/upload",
            ).check(function(req) {
                expect(req.opts.json).toBeFalsy();
            }).respond(200, { "content_uri": "uri" });
@@ -106,7 +107,7 @@ describe("MatrixClient", function() {

        it("should parse errors into a MatrixError", function(done) {
            httpBackend.when(
-                "POST", "/_matrix/media/v1/upload",
+                "POST", "/_matrix/media/r0/upload",
            ).check(function(req) {
                expect(req.rawData).toEqual(buf);
                expect(req.opts.json).toBeFalsy();
@@ -354,9 +355,9 @@ describe("MatrixClient", function() {
                return client._crypto._olmDevice.sign(anotherjson.stringify(b));
            };

-            console.log("Ed25519: " + ed25519key);
-            console.log("boris:", sign(borisKeys.dev1));
-            console.log("chaz:", sign(chazKeys.dev2));
+            logger.log("Ed25519: " + ed25519key);
+            logger.log("boris:", sign(borisKeys.dev1));
+            logger.log("chaz:", sign(chazKeys.dev2));
            */

            httpBackend.when("POST", "/keys/query").check(function(req) {
@@ -395,7 +396,7 @@ describe("MatrixClient", function() {
        const auth = {a: 1};
        it("should pass through an auth dict", function(done) {
            httpBackend.when(
-                "DELETE", "/_matrix/client/unstable/devices/my_device",
+                "DELETE", "/_matrix/client/r0/devices/my_device",
            ).check(function(req) {
                expect(req.data).toEqual({auth: auth});
            }).respond(200);
@@ -58,12 +58,13 @@ describe("MatrixClient opts", function() {
    };

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
    });

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

    describe("without opts.store", function() {
@@ -127,7 +128,7 @@ describe("MatrixClient opts", function() {
        beforeEach(function() {
            client = new MatrixClient({
                request: httpBackend.requestFn,
-                store: new sdk.MatrixInMemoryStore(),
+                store: new sdk.MemoryStore(),
                baseUrl: baseUrl,
                userId: userId,
                accessToken: accessToken,
@@ -20,7 +20,7 @@ describe("MatrixClient retrying", function() {
    let room;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
        sdk.request(httpBackend.requestFn);
        scheduler = new sdk.MatrixScheduler();
@@ -36,6 +36,7 @@ describe("MatrixClient retrying", function() {

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

    xit("should retry according to MatrixScheduler.retryFn", function() {
@@ -104,7 +104,7 @@ describe("MatrixClient room timelines", function() {
    }

    beforeEach(function(done) {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
        sdk.request(httpBackend.requestFn);
        client = sdk.createClient({
@@ -130,6 +130,7 @@ describe("MatrixClient room timelines", function() {
    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
        client.stopClient();
+        return httpBackend.stop();
    });

    describe("local echo events", function() {
@@ -23,7 +23,7 @@ describe("MatrixClient syncing", function() {
    const roomTwo = "!bar:localhost";

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        httpBackend = new HttpBackend();
        sdk.request(httpBackend.requestFn);
        client = sdk.createClient({
@@ -38,6 +38,7 @@ describe("MatrixClient syncing", function() {
    afterEach(function() {
        httpBackend.verifyNoOutstandingExpectation();
        client.stopClient();
+        return httpBackend.stop();
    });

    describe("startClient", function() {
@@ -23,6 +23,7 @@ import expect from 'expect';
 const utils = require('../../lib/utils');
 const testUtils = require('../test-utils');
 const TestClient = require('../TestClient').default;
+import logger from '../../src/logger';

 const ROOM_ID = "!room:id";

@@ -203,7 +204,7 @@ function getSyncResponse(roomMembers) {

 describe("megolm", function() {
    if (!global.Olm) {
-        console.warn('not running megolm tests: Olm not present');
+        logger.warn('not running megolm tests: Olm not present');
        return;
    }
    const Olm = global.Olm;
@@ -282,7 +283,7 @@ describe("megolm", function() {
    }

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

        aliceTestClient = new TestClient(
            "@alice:localhost", "xzcvb", "akjgkrgjs",
@@ -296,7 +297,7 @@ describe("megolm", function() {
    });

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

    it("Alice receives a megolm message", function() {
@@ -416,7 +417,7 @@ describe("megolm", function() {

            return new Promise((resolve, reject) => {
                event.once('Event.decrypted', (ev) => {
-                    console.log(`${Date.now()} event ${event.getId()} now decrypted`);
+                    logger.log(`${Date.now()} event ${event.getId()} now decrypted`);
                    resolve(ev);
                });
            });
@@ -499,6 +500,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);
@@ -554,7 +556,7 @@ describe("megolm", function() {
            ).respond(200, function(path, content) {
                const ct = content.ciphertext;
                const r = inboundGroupSession.decrypt(ct);
-                console.log('Decrypted received megolm message', r);
+                logger.log('Decrypted received megolm message', r);

                expect(r.message_index).toEqual(0);
                const decrypted = JSON.parse(r.plaintext);
@@ -581,6 +583,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);
@@ -598,7 +601,7 @@ describe("megolm", function() {

            return aliceTestClient.flushSync();
        }).then(function() {
-            console.log('Forcing alice to download our device keys');
+            logger.log('Forcing alice to download our device keys');

            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
                200, getTestKeysQueryResponse('@bob:xyz'),
@@ -609,10 +612,10 @@ describe("megolm", function() {
                aliceTestClient.httpBackend.flush('/keys/query', 1),
            ]);
        }).then(function() {
-            console.log('Telling alice to block our device');
+            logger.log('Telling alice to block our device');
            aliceTestClient.client.setDeviceBlocked('@bob:xyz', 'DEVICE_ID');

-            console.log('Telling alice to send a megolm message');
+            logger.log('Telling alice to send a megolm message');
            aliceTestClient.httpBackend.when(
                'PUT', '/send/',
            ).respond(200, {
@@ -634,6 +637,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);
@@ -653,7 +657,7 @@ describe("megolm", function() {

            return aliceTestClient.flushSync();
        }).then(function() {
-            console.log("Fetching bob's devices and marking known");
+            logger.log("Fetching bob's devices and marking known");

            aliceTestClient.httpBackend.when('POST', '/keys/query').respond(
                200, getTestKeysQueryResponse('@bob:xyz'),
@@ -666,17 +670,17 @@ describe("megolm", function() {
                aliceTestClient.client.setDeviceKnown('@bob:xyz', 'DEVICE_ID');
            });
        }).then(function() {
-            console.log('Telling alice to send a megolm message');
+            logger.log('Telling alice to send a megolm message');

            aliceTestClient.httpBackend.when(
                'PUT', '/sendToDevice/m.room.encrypted/',
            ).respond(200, function(path, content) {
-                console.log('sendToDevice: ', content);
+                logger.log('sendToDevice: ', content);
                const m = content.messages['@bob:xyz'].DEVICE_ID;
                const ct = m.ciphertext[testSenderKey];
                expect(ct.type).toEqual(1); // normal message
                const decrypted = JSON.parse(p2pSession.decrypt(ct.type, ct.body));
-                console.log('decrypted sendToDevice:', decrypted);
+                logger.log('decrypted sendToDevice:', decrypted);
                expect(decrypted.type).toEqual('m.room_key');
                megolmSessionId = decrypted.content.session_id;
                return {};
@@ -685,7 +689,7 @@ describe("megolm", function() {
            aliceTestClient.httpBackend.when(
                'PUT', '/send/',
            ).respond(200, function(path, content) {
-                console.log('/send:', content);
+                logger.log('/send:', content);
                expect(content.session_id).toEqual(megolmSessionId);
                return {
                    event_id: '$event_id',
@@ -701,14 +705,14 @@ describe("megolm", function() {
                }),
            ]);
        }).then(function() {
-            console.log('Telling alice to block our device');
+            logger.log('Telling alice to block our device');
            aliceTestClient.client.setDeviceBlocked('@bob:xyz', 'DEVICE_ID');

-            console.log('Telling alice to send another megolm message');
+            logger.log('Telling alice to send another megolm message');
            aliceTestClient.httpBackend.when(
                'PUT', '/send/',
            ).respond(200, function(path, content) {
-                console.log('/send:', content);
+                logger.log('/send:', content);
                expect(content.session_id).toNotEqual(megolmSessionId);
                return {
                    event_id: '$event_id',
@@ -789,7 +793,7 @@ describe("megolm", function() {
            aliceTestClient.httpBackend.when(
                'PUT', '/sendToDevice/m.room.encrypted/',
            ).respond(200, function(path, content) {
-                console.log("sendToDevice: ", content);
+                logger.log("sendToDevice: ", content);
                const m = content.messages[aliceTestClient.userId].DEVICE_ID;
                const ct = m.ciphertext[testSenderKey];
                expect(ct.type).toEqual(0); // pre-key message
@@ -809,7 +813,7 @@ describe("megolm", function() {
            ).respond(200, function(path, content) {
                const ct = content.ciphertext;
                const r = inboundGroupSession.decrypt(ct);
-                console.log('Decrypted received megolm message', r);
+                logger.log('Decrypted received megolm message', r);
                decrypted = JSON.parse(r.plaintext);

                return {
@@ -817,8 +821,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 +847,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);
@@ -855,7 +866,7 @@ describe("megolm", function() {
            return aliceTestClient.flushSync();
        }).then(function() {
            // this will block
-            console.log('Forcing alice to download our device keys');
+            logger.log('Forcing alice to download our device keys');
            downloadPromise = aliceTestClient.client.downloadKeys(['@bob:xyz']);

            // so will this.
@@ -880,6 +891,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);
@@ -14,11 +14,12 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */

-// try to load the olm library.
+import logger from '../src/logger';

+// try to load the olm library.
 try {
    global.Olm = require('olm');
-    console.log('loaded libolm');
+    logger.log('loaded libolm');
 } catch (e) {
-    console.warn("unable to run crypto tests: libolm not available");
+    logger.warn("unable to run crypto tests: libolm not available");
 }
@@ -5,6 +5,7 @@ import Promise from 'bluebird';
 // load olm before the sdk if possible
 import './olm-loader';

+import logger from '../src/logger';
 import sdk from '..';
 const MatrixEvent = sdk.MatrixEvent;

@@ -25,7 +26,7 @@ module.exports.syncPromise = function(client, count) {

    const p = new Promise((resolve, reject) => {
        const cb = (state) => {
-            console.log(`${Date.now()} syncPromise(${count}): ${state}`);
+            logger.log(`${Date.now()} syncPromise(${count}): ${state}`);
            if (state == 'SYNCING') {
                resolve();
            } else {
@@ -48,8 +49,8 @@ module.exports.syncPromise = function(client, count) {
 module.exports.beforeEach = function(context) {
    const desc = context.currentTest.fullTitle();

-    console.log(desc);
-    console.log(new Array(1 + desc.length).join("="));
+    logger.log(desc);
+    logger.log(new Array(1 + desc.length).join("="));
 };

 /**
@@ -232,12 +233,153 @@ module.exports.awaitDecryption = function(event) {
        return Promise.resolve(event);
    }

-    console.log(`${Date.now()} event ${event.getId()} is being decrypted; waiting`);
+    logger.log(`${Date.now()} event ${event.getId()} is being decrypted; waiting`);

    return new Promise((resolve, reject) => {
        event.once('Event.decrypted', (ev) => {
-            console.log(`${Date.now()} event ${event.getId()} now decrypted`);
+            logger.log(`${Date.now()} event ${event.getId()} now decrypted`);
            resolve(ev);
        });
    });
 };
+
+
+const HttpResponse = module.exports.HttpResponse = function(
+    httpLookups, acceptKeepalives, ignoreUnhandledSync,
+) {
+    this.httpLookups = httpLookups;
+    this.acceptKeepalives = acceptKeepalives === undefined ? true : acceptKeepalives;
+    this.ignoreUnhandledSync = ignoreUnhandledSync;
+    this.pendingLookup = null;
+};
+
+HttpResponse.prototype.request = function HttpResponse(
+    cb, method, path, qp, data, prefix,
+) {
+    if (path === HttpResponse.KEEP_ALIVE_PATH && this.acceptKeepalives) {
+        return Promise.resolve();
+    }
+    const next = this.httpLookups.shift();
+    const logLine = (
+        "MatrixClient[UT] RECV " + method + " " + path + "  " +
+            "EXPECT " + (next ? next.method : next) + " " + (next ? next.path : next)
+    );
+    logger.log(logLine);
+
+    if (!next) { // no more things to return
+        if (method === "GET" && path === "/sync" && this.ignoreUnhandledSync) {
+            logger.log("MatrixClient[UT] Ignoring.");
+            return Promise.defer().promise;
+        }
+        if (this.pendingLookup) {
+            if (this.pendingLookup.method === method
+                && this.pendingLookup.path === path) {
+                return this.pendingLookup.promise;
+            }
+            // >1 pending thing, and they are different, whine.
+            expect(false).toBe(
+                true, ">1 pending request. You should probably handle them. " +
+                    "PENDING: " + JSON.stringify(this.pendingLookup) + " JUST GOT: " +
+                    method + " " + path,
+            );
+        }
+        this.pendingLookup = {
+            promise: Promise.defer().promise,
+            method: method,
+            path: path,
+        };
+        return this.pendingLookup.promise;
+    }
+    if (next.path === path && next.method === method) {
+        logger.log(
+            "MatrixClient[UT] Matched. Returning " +
+                (next.error ? "BAD" : "GOOD") + " response",
+        );
+        if (next.expectBody) {
+            expect(next.expectBody).toEqual(data);
+        }
+        if (next.expectQueryParams) {
+            Object.keys(next.expectQueryParams).forEach(function(k) {
+                expect(qp[k]).toEqual(next.expectQueryParams[k]);
+            });
+        }
+
+        if (next.thenCall) {
+            process.nextTick(next.thenCall, 0); // next tick so we return first.
+        }
+
+        if (next.error) {
+            return Promise.reject({
+                errcode: next.error.errcode,
+                httpStatus: next.error.httpStatus,
+                name: next.error.errcode,
+                message: "Expected testing error",
+                data: next.error,
+            });
+        }
+        return Promise.resolve(next.data);
+    } else if (method === "GET" && path === "/sync" && this.ignoreUnhandledSync) {
+        logger.log("MatrixClient[UT] Ignoring.");
+        this.httpLookups.unshift(next);
+        return Promise.defer().promise;
+    }
+    expect(true).toBe(false, "Expected different request. " + logLine);
+    return Promise.defer().promise;
+};
+
+HttpResponse.KEEP_ALIVE_PATH = "/_matrix/client/versions";
+
+HttpResponse.PUSH_RULES_RESPONSE = {
+    method: "GET",
+    path: "/pushrules/",
+    data: {},
+};
+
+HttpResponse.USER_ID = "@alice:bar";
+
+HttpResponse.filterResponse = function(userId) {
+    const filterPath = "/user/" + encodeURIComponent(userId) + "/filter";
+    return {
+        method: "POST",
+        path: filterPath,
+        data: { filter_id: "f1lt3r" },
+    };
+};
+
+HttpResponse.SYNC_DATA = {
+    next_batch: "s_5_3",
+    presence: { events: [] },
+    rooms: {},
+};
+
+HttpResponse.SYNC_RESPONSE = {
+    method: "GET",
+    path: "/sync",
+    data: HttpResponse.SYNC_DATA,
+};
+
+HttpResponse.defaultResponses = function(userId) {
+    return [
+        HttpResponse.PUSH_RULES_RESPONSE,
+        HttpResponse.filterResponse(userId),
+        HttpResponse.SYNC_RESPONSE,
+    ];
+};
+
+module.exports.setHttpResponses = function setHttpResponses(
+    client, responses, acceptKeepalives, ignoreUnhandledSyncs,
+) {
+    const httpResponseObj = new HttpResponse(
+        responses, acceptKeepalives, ignoreUnhandledSyncs,
+    );
+
+    const httpReq = httpResponseObj.request.bind(httpResponseObj);
+    client._http = [
+        "authedRequest", "authedRequestWithPrefix", "getContentUri",
+        "request", "requestWithPrefix", "uploadContent",
+    ].reduce((r, k) => {r[k] = expect.createSpy(); return r;}, {});
+    client._http.authedRequest.andCall(httpReq);
+    client._http.authedRequestWithPrefix.andCall(httpReq);
+    client._http.requestWithPrefix.andCall(httpReq);
+    client._http.request.andCall(httpReq);
+};
@@ -0,0 +1,670 @@
+/*
+Copyright 2018 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+"use strict";
+
+import 'source-map-support/register';
+import Promise from 'bluebird';
+const sdk = require("../..");
+const utils = require("../test-utils");
+
+const AutoDiscovery = sdk.AutoDiscovery;
+
+import expect from 'expect';
+import MockHttpBackend from "matrix-mock-request";
+
+
+describe("AutoDiscovery", function() {
+    let httpBackend = null;
+
+    beforeEach(function() {
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+        httpBackend = new MockHttpBackend();
+        sdk.request(httpBackend.requestFn);
+    });
+
+    it("should throw an error when no domain is specified", function() {
+        return Promise.all([
+            AutoDiscovery.findClientConfig(/* no args */).then(() => {
+                throw new Error("Expected a failure, not success with no args");
+            }, () => {
+                return true;
+            }),
+
+            AutoDiscovery.findClientConfig("").then(() => {
+                throw new Error("Expected a failure, not success with an empty string");
+            }, () => {
+                return true;
+            }),
+
+            AutoDiscovery.findClientConfig(null).then(() => {
+                throw new Error("Expected a failure, not success with null");
+            }, () => {
+                return true;
+            }),
+
+            AutoDiscovery.findClientConfig(true).then(() => {
+                throw new Error("Expected a failure, not success with a non-string");
+            }, () => {
+                return true;
+            }),
+        ]);
+    });
+
+    it("should return PROMPT when .well-known 404s", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(404, {});
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns a 500 error", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(500, {});
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns a 400 error", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(400, {});
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns an empty body", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, "");
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known returns not-JSON", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, "abc");
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known does not have a base_url for " +
+        "m.homeserver (empty string)", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_PROMPT when .well-known does not have a base_url for " +
+        "m.homeserver (no property)", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {},
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (disallowed scheme)", function() {
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "mxc://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HS_BASE_URL,
+                        base_url: null,
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (verification failure: 404)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").respond(404, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HOMESERVER,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (verification failure: 500)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").respond(500, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HOMESERVER,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return FAIL_ERROR when .well-known has an invalid base_url for " +
+        "m.homeserver (verification failure: 200 but wrong content)", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").respond(200, {
+            not_matrix_versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "FAIL_ERROR",
+                        error: AutoDiscovery.ERROR_INVALID_HOMESERVER,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS when .well-known has a verifiably accurate base_url for " +
+        "m.homeserver", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri).toEqual("https://example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                base_url: "https://example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS with the right homeserver URL", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "PROMPT",
+                        error: null,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS / FAIL_PROMPT 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: "SUCCESS",
+                        error: null,
+
+                        // We still expect the base_url to be here for debugging purposes.
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_IS_BASE_URL,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS / FAIL_PROMPT 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: "SUCCESS",
+                        error: null,
+
+                        // We still expect the base_url to be here for debugging purposes.
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_IS_BASE_URL,
+                        base_url: null,
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS / FAIL_PROMPT 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: "SUCCESS",
+                        error: null,
+
+                        // We still expect the base_url to be here for debugging purposes.
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_IDENTITY_SERVER,
+                        base_url: "https://identity.example.org",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS / FAIL_PROMPT 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: "SUCCESS",
+                        error: null,
+
+                        // We still expect the base_url to be here for debugging purposes
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "FAIL_PROMPT",
+                        error: AutoDiscovery.ERROR_INVALID_IDENTITY_SERVER,
+                        base_url: "https://identity.example.org",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS when the identity server configuration is " +
+        "verifiably accurate", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/_matrix/identity/api/v1").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://identity.example.org/_matrix/identity/api/v1");
+        }).respond(200, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "https://identity.example.org",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://identity.example.org",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+
+    it("should return SUCCESS and preserve non-standard keys from the " +
+        ".well-known response", function() {
+        httpBackend.when("GET", "/_matrix/client/versions").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://chat.example.org/_matrix/client/versions");
+        }).respond(200, {
+            versions: ["r0.0.1"],
+        });
+        httpBackend.when("GET", "/_matrix/identity/api/v1").check((req) => {
+            expect(req.opts.uri)
+                .toEqual("https://identity.example.org/_matrix/identity/api/v1");
+        }).respond(200, {});
+        httpBackend.when("GET", "/.well-known/matrix/client").respond(200, {
+            "m.homeserver": {
+                // Note: we also expect this test to trim the trailing slash
+                base_url: "https://chat.example.org/",
+            },
+            "m.identity_server": {
+                base_url: "https://identity.example.org",
+            },
+            "org.example.custom.property": {
+                cupcakes: "yes",
+            },
+        });
+        return Promise.all([
+            httpBackend.flushAllExpected(),
+            AutoDiscovery.findClientConfig("example.org").then((conf) => {
+                const expected = {
+                    "m.homeserver": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://chat.example.org",
+                    },
+                    "m.identity_server": {
+                        state: "SUCCESS",
+                        error: null,
+                        base_url: "https://identity.example.org",
+                    },
+                    "org.example.custom.property": {
+                        cupcakes: "yes",
+                    },
+                };
+
+                expect(conf).toEqual(expected);
+            }),
+        ]);
+    });
+});
@@ -9,7 +9,7 @@ describe("ContentRepo", function() {
    const baseUrl = "https://my.home.server";

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

    describe("getHttpUriForMxc", function() {
@@ -31,7 +31,7 @@ describe("ContentRepo", function() {
        function() {
            const mxcUri = "mxc://server.name/resourceid";
            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri)).toEqual(
-                baseUrl + "/_matrix/media/v1/download/server.name/resourceid",
+                baseUrl + "/_matrix/media/r0/download/server.name/resourceid",
            );
        });

@@ -43,7 +43,7 @@ describe("ContentRepo", function() {
        function() {
            const mxcUri = "mxc://server.name/resourceid";
            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri, 32, 64, "crop")).toEqual(
-                baseUrl + "/_matrix/media/v1/thumbnail/server.name/resourceid" +
+                baseUrl + "/_matrix/media/r0/thumbnail/server.name/resourceid" +
                "?width=32&height=64&method=crop",
            );
        });
@@ -52,7 +52,7 @@ describe("ContentRepo", function() {
        function() {
            const mxcUri = "mxc://server.name/resourceid#automade";
            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri, 32)).toEqual(
-                baseUrl + "/_matrix/media/v1/thumbnail/server.name/resourceid" +
+                baseUrl + "/_matrix/media/r0/thumbnail/server.name/resourceid" +
                "?width=32#automade",
            );
        });
@@ -61,7 +61,7 @@ describe("ContentRepo", function() {
        function() {
            const mxcUri = "mxc://server.name/resourceid#automade";
            expect(ContentRepo.getHttpUriForMxc(baseUrl, mxcUri)).toEqual(
-                baseUrl + "/_matrix/media/v1/download/server.name/resourceid#automade",
+                baseUrl + "/_matrix/media/r0/download/server.name/resourceid#automade",
            );
        });
    });
@@ -73,21 +73,21 @@ describe("ContentRepo", function() {

        it("should set w/h by default to 96", function() {
            expect(ContentRepo.getIdenticonUri(baseUrl, "foobar")).toEqual(
-                baseUrl + "/_matrix/media/v1/identicon/foobar" +
+                baseUrl + "/_matrix/media/unstable/identicon/foobar" +
                "?width=96&height=96",
            );
        });

        it("should be able to set custom w/h", function() {
            expect(ContentRepo.getIdenticonUri(baseUrl, "foobar", 32, 64)).toEqual(
-                baseUrl + "/_matrix/media/v1/identicon/foobar" +
+                baseUrl + "/_matrix/media/unstable/identicon/foobar" +
                "?width=32&height=64",
            );
        });

        it("should URL encode the identicon string", function() {
            expect(ContentRepo.getIdenticonUri(baseUrl, "foo#bar", 32, 64)).toEqual(
-                baseUrl + "/_matrix/media/v1/identicon/foo%23bar" +
+                baseUrl + "/_matrix/media/unstable/identicon/foo%23bar" +
                "?width=32&height=64",
            );
        });
@@ -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();
+            }
+        });
    });
 });
@@ -1,6 +1,6 @@
 /*
 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.
@@ -16,11 +16,10 @@ limitations under the License.
 */

 import DeviceList from '../../../lib/crypto/DeviceList';
-import MockStorageApi from '../../MockStorageApi';
-import WebStorageSessionStore from '../../../lib/store/session/webstorage';
 import MemoryCryptoStore from '../../../lib/crypto/store/memory-crypto-store.js';
 import testUtils from '../../test-utils';
 import utils from '../../../lib/utils';
+import logger from '../../../src/logger';

 import expect from 'expect';
 import Promise from 'bluebird';
@@ -57,18 +56,24 @@ const signedDeviceList = {

 describe('DeviceList', function() {
    let downloadSpy;
-    let sessionStore;
    let cryptoStore;
+    let deviceLists = [];

    beforeEach(function() {
-        testUtils.beforeEach(this); // eslint-disable-line no-invalid-this
+        testUtils.beforeEach(this); // eslint-disable-line babel/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 +81,9 @@ describe('DeviceList', function() {
        const mockOlm = {
            verifySignature: function(key, message, signature) {},
        };
-        return new DeviceList(baseApis, cryptoStore, sessionStore, mockOlm);
+        const dl = new DeviceList(baseApis, cryptoStore, mockOlm);
+        deviceLists.push(dl);
+        return dl;
    }

    it("should successfully download and store device keys", function() {
@@ -128,7 +135,7 @@ describe('DeviceList', function() {
        }).then(() => {
            // uh-oh; user restarts before second request completes. The new instance
            // should know we never got a complete device list.
-            console.log("Creating new devicelist to simulate app reload");
+            logger.log("Creating new devicelist to simulate app reload");
            downloadSpy.reset();
            const dl2 = createTestDeviceList();
            const queryDefer3 = Promise.defer();
@@ -1,35 +1,28 @@
-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';

 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';
-
-// 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';
+import logger from '../../../../src/logger';

 const MatrixEvent = sdk.MatrixEvent;
 const MegolmDecryption = algorithms.DECRYPTION_CLASSES['m.megolm.v1.aes-sha2'];
+const MegolmEncryption = algorithms.ENCRYPTION_CLASSES['m.megolm.v1.aes-sha2'];

 const ROOM_ID = '!ROOM:ID';

+const Olm = global.Olm;
+
 describe("MegolmDecryption", function() {
    if (!global.Olm) {
-        console.warn('Not running megolm unit tests: libolm not present');
+        logger.warn('Not running megolm unit tests: libolm not present');
        return;
    }

@@ -38,17 +31,18 @@ describe("MegolmDecryption", function() {
    let mockCrypto;
    let mockBaseApis;

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

        mockCrypto = testUtils.mock(Crypto, 'Crypto');
        mockBaseApis = {};

        const mockStorage = new MockStorageApi();
-        const sessionStore = new WebStorageSessionStore(mockStorage);
        const cryptoStore = new MemoryCryptoStore(mockStorage);

-        const olmDevice = new OlmDevice(sessionStore, cryptoStore);
+        const olmDevice = new OlmDevice(cryptoStore);

        megolmDecryption = new MegolmDecryption({
            userId: '@user:id',
@@ -69,7 +63,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 +92,7 @@ describe("MegolmDecryption", function() {
                },
            };

-            return event.attemptDecryption(mockCrypto).then(() => {
+            await event.attemptDecryption(mockCrypto).then(() => {
                megolmDecryption.onRoomKeyEvent(event);
            });
        });
@@ -266,5 +260,91 @@ 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 cryptoStore = new MemoryCryptoStore(mockStorage);
+
+            const olmDevice = new OlmDevice(cryptoStore);
+            olmDevice.verifySignature = expect.createSpy();
+            await olmDevice.init();
+
+            mockBaseApis.claimOneTimeKeys = expect.createSpy().andReturn(Promise.resolve({
+                one_time_keys: {
+                    '@alice:home.server': {
+                        aliceDevice: {
+                            'signed_curve25519:flooble': {
+                                key: 'YmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmI',
+                                signatures: {
+                                    '@alice:home.server': {
+                                        'ed25519:aliceDevice': 'totally valid',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            }));
+            mockBaseApis.sendToDevice = expect.createSpy().andReturn(Promise.resolve());
+
+            mockCrypto.downloadKeys.andReturn(Promise.resolve({
+                '@alice:home.server': {
+                    aliceDevice: {
+                        deviceId: 'aliceDevice',
+                        isBlocked: expect.createSpy().andReturn(false),
+                        isUnverified: expect.createSpy().andReturn(false),
+                        getIdentityKey: expect.createSpy().andReturn(
+                            'YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE',
+                        ),
+                        getFingerprint: expect.createSpy().andReturn(''),
+                    },
+                },
+            }));
+
+            const megolmEncryption = new MegolmEncryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: mockBaseApis,
+                roomId: ROOM_ID,
+                config: {
+                    rotation_period_ms: 9999999999999,
+                },
+            });
+            const mockRoom = {
+                getEncryptionTargetMembers: expect.createSpy().andReturn(
+                    [{userId: "@alice:home.server"}],
+                ),
+                getBlacklistUnverifiedDevices: expect.createSpy().andReturn(false),
+            };
+            const ct1 = await megolmEncryption.encryptMessage(mockRoom, "a.fake.type", {
+                body: "Some text",
+            });
+            expect(mockRoom.getEncryptionTargetMembers).toHaveBeenCalled();
+
+            // this should have claimed a key for alice as it's starting a new session
+            expect(mockBaseApis.claimOneTimeKeys).toHaveBeenCalled(
+                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519',
+            );
+            expect(mockCrypto.downloadKeys).toHaveBeenCalledWith(
+                ['@alice:home.server'], false,
+            );
+            expect(mockBaseApis.sendToDevice).toHaveBeenCalled();
+            expect(mockBaseApis.claimOneTimeKeys).toHaveBeenCalled(
+                [['@alice:home.server', 'aliceDevice']], 'signed_curve25519',
+            );
+
+            mockBaseApis.claimOneTimeKeys.reset();
+
+            const ct2 = await megolmEncryption.encryptMessage(mockRoom, "a.fake.type", {
+                body: "Some more text",
+            });
+
+            // this should *not* have claimed a key as it should be using the same session
+            expect(mockBaseApis.claimOneTimeKeys).toNotHaveBeenCalled();
+
+            // likewise they should show the same session ID
+            expect(ct2.session_id).toEqual(ct1.session_id);
+        });
    });
 });
@@ -0,0 +1,143 @@
+/*
+Copyright 2018,2019 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import '../../../olm-loader';
+
+import expect from 'expect';
+import MemoryCryptoStore from '../../../../lib/crypto/store/memory-crypto-store.js';
+import MockStorageApi from '../../../MockStorageApi';
+import testUtils from '../../../test-utils';
+import logger from '../../../../src/logger';
+
+import OlmDevice from '../../../../lib/crypto/OlmDevice';
+import olmlib from '../../../../lib/crypto/olmlib';
+import DeviceInfo from '../../../../lib/crypto/deviceinfo';
+
+function makeOlmDevice() {
+    const mockStorage = new MockStorageApi();
+    const cryptoStore = new MemoryCryptoStore(mockStorage);
+    const olmDevice = new OlmDevice(cryptoStore);
+    return olmDevice;
+}
+
+async function setupSession(initiator, opponent) {
+    await opponent.generateOneTimeKeys(1);
+    const keys = await opponent.getOneTimeKeys();
+    const firstKey = Object.values(keys['curve25519'])[0];
+
+    const sid = await initiator.createOutboundSession(
+        opponent.deviceCurve25519Key, firstKey,
+    );
+    return sid;
+}
+
+describe("OlmDecryption", function() {
+    if (!global.Olm) {
+        logger.warn('Not running megolm unit tests: libolm not present');
+        return;
+    }
+
+    let aliceOlmDevice;
+    let bobOlmDevice;
+
+    beforeEach(async function() {
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        await global.Olm.init();
+
+        aliceOlmDevice = makeOlmDevice();
+        bobOlmDevice = makeOlmDevice();
+        await aliceOlmDevice.init();
+        await bobOlmDevice.init();
+    });
+
+    describe('olm', function() {
+        it("can decrypt messages", async function() {
+            const sid = await setupSession(aliceOlmDevice, bobOlmDevice);
+
+            const ciphertext = await aliceOlmDevice.encryptMessage(
+                bobOlmDevice.deviceCurve25519Key,
+                sid,
+                "The olm or proteus is an aquatic salamander in the family Proteidae",
+            );
+
+            const result = await bobOlmDevice.createInboundSession(
+                aliceOlmDevice.deviceCurve25519Key,
+                ciphertext.type,
+                ciphertext.body,
+            );
+            expect(result.payload).toEqual(
+                "The olm or proteus is an aquatic salamander in the family Proteidae",
+            );
+        });
+
+        it("creates only one session at a time", async function() {
+            // if we call ensureOlmSessionsForDevices multiple times, it should
+            // only try to create one session at a time, even if the server is
+            // slow
+            let count = 0;
+            const baseApis = {
+                claimOneTimeKeys: () => {
+                    // simulate a very slow server (.5 seconds to respond)
+                    count++;
+                    return new Promise((resolve, reject) => {
+                        setTimeout(reject, 500);
+                    });
+                },
+            };
+            const devicesByUser = {
+                "@bob:example.com": [
+                    DeviceInfo.fromStorage({
+                        keys: {
+                            "curve25519:ABCDEFG": "akey",
+                        },
+                    }, "ABCDEFG"),
+                ],
+            };
+            function alwaysSucceed(promise) {
+                // swallow any exception thrown by a promise, so that
+                // Promise.all doesn't abort
+                return promise.catch(() => {});
+            }
+
+            // start two tasks that try to ensure that there's an olm session
+            const promises = Promise.all([
+                alwaysSucceed(olmlib.ensureOlmSessionsForDevices(
+                    aliceOlmDevice, baseApis, devicesByUser,
+                )),
+                alwaysSucceed(olmlib.ensureOlmSessionsForDevices(
+                    aliceOlmDevice, baseApis, devicesByUser,
+                )),
+            ]);
+
+            await new Promise((resolve) => {
+                setTimeout(resolve, 200);
+            });
+
+            // after .2s, both tasks should have started, but one should be
+            // waiting on the other before trying to create a session, so
+            // claimOneTimeKeys should have only been called once
+            expect(count).toBe(1);
+
+            await promises;
+
+            // after waiting for both tasks to complete, the first task should
+            // have failed, so the second task should have tried to create a
+            // new session and will have called claimOneTimeKeys
+            expect(count).toBe(2);
+        });
+    });
+});
@@ -0,0 +1,549 @@
+/*
+Copyright 2018 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import '../../olm-loader';
+
+import expect from 'expect';
+import Promise from 'bluebird';
+
+import sdk from '../../..';
+import algorithms from '../../../lib/crypto/algorithms';
+import WebStorageSessionStore from '../../../lib/store/session/webstorage';
+import MemoryCryptoStore from '../../../lib/crypto/store/memory-crypto-store.js';
+import MockStorageApi from '../../MockStorageApi';
+import testUtils from '../../test-utils';
+
+import OlmDevice from '../../../lib/crypto/OlmDevice';
+import Crypto from '../../../lib/crypto';
+import logger from '../../../src/logger';
+import olmlib from '../../../lib/crypto/olmlib';
+
+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",
+    },
+};
+
+const keys = {};
+
+function getCrossSigningKey(type) {
+    return keys[type];
+}
+
+function saveCrossSigningKeys(k) {
+    Object.assign(keys, k);
+}
+
+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,
+        cryptoCallbacks: { getCrossSigningKey, saveCrossSigningKeys },
+    });
+}
+
+describe("MegolmBackup", function() {
+    if (!global.Olm) {
+        logger.warn('Not running megolm backup unit tests: libolm not present');
+        return;
+    }
+
+    let olmDevice;
+    let mockOlmLib;
+    let mockCrypto;
+    let mockStorage;
+    let sessionStore;
+    let cryptoStore;
+    let megolmDecryption;
+    beforeEach(async function() {
+        await Olm.init();
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
+
+        mockCrypto = testUtils.mock(Crypto, 'Crypto');
+        mockCrypto.backupKey = new Olm.PkEncryption();
+        mockCrypto.backupKey.set_recipient_key(
+            "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+        );
+        mockCrypto.backupInfo = BACKUP_INFO;
+
+        mockStorage = new MockStorageApi();
+        sessionStore = new WebStorageSessionStore(mockStorage);
+        cryptoStore = new MemoryCryptoStore(mockStorage);
+
+        olmDevice = new OlmDevice(cryptoStore);
+
+        // we stub out the olm encryption bits
+        mockOlmLib = {};
+        mockOlmLib.ensureOlmSessionsForDevices = expect.createSpy();
+        mockOlmLib.encryptMessageForDevice =
+            expect.createSpy().andReturn(Promise.resolve());
+    });
+
+    describe("backup", function() {
+        let mockBaseApis;
+        let realSetTimeout;
+
+        beforeEach(function() {
+            mockBaseApis = {};
+
+            megolmDecryption = new MegolmDecryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: mockBaseApis,
+                roomId: ROOM_ID,
+            });
+
+            megolmDecryption.olmlib = mockOlmLib;
+
+            // clobber the setTimeout function to run 100x faster.
+            // ideally we would use lolex, but we have no oportunity
+            // to tick the clock between the first try and the retry.
+            realSetTimeout = global.setTimeout;
+            global.setTimeout = function(f, n) {
+                return realSetTimeout(f, n/100);
+            };
+        });
+
+        afterEach(function() {
+            global.setTimeout = realSetTimeout;
+        });
+
+        it('automatically calls the key back up', function() {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+
+            // construct a fake decrypted key event via the use of a mocked
+            // 'crypto' implementation.
+            const event = new MatrixEvent({
+                type: 'm.room.encrypted',
+            });
+            const decryptedData = {
+                clearEvent: {
+                    type: 'm.room_key',
+                    content: {
+                        algorithm: 'm.megolm.v1.aes-sha2',
+                        room_id: ROOM_ID,
+                        session_id: groupSession.session_id(),
+                        session_key: groupSession.session_key(),
+                    },
+                },
+                senderCurve25519Key: "SENDER_CURVE25519",
+                claimedEd25519Key: "SENDER_ED25519",
+            };
+
+            mockCrypto.decryptEvent = function() {
+                return Promise.resolve(decryptedData);
+            };
+            mockCrypto.cancelRoomKeyRequest = function() {};
+
+            mockCrypto.backupGroupSession = expect.createSpy();
+
+            return event.attemptDecryption(mockCrypto).then(() => {
+                return megolmDecryption.onRoomKeyEvent(event);
+            }).then(() => {
+                expect(mockCrypto.backupGroupSession).toHaveBeenCalled();
+            });
+        });
+
+        it('sends backups to the server', function() {
+            const groupSession = new Olm.OutboundGroupSession();
+            groupSession.create();
+            const ibGroupSession = new Olm.InboundGroupSession();
+            ibGroupSession.create(groupSession.session_key());
+
+            const client = makeTestClient(sessionStore, cryptoStore);
+
+            megolmDecryption = new MegolmDecryption({
+                userId: '@user:id',
+                crypto: mockCrypto,
+                olmDevice: olmDevice,
+                baseApis: client,
+                roomId: ROOM_ID,
+            });
+
+            megolmDecryption.olmlib = mockOlmLib;
+
+            return client.initCrypto()
+                .then(() => {
+                    return cryptoStore.doTxn(
+                        "readwrite",
+                        [cryptoStore.STORE_SESSION],
+                        (txn) => {
+                            cryptoStore.addEndToEndInboundGroupSession(
+                                "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
+                                groupSession.session_id(),
+                                {
+                                    forwardingCurve25519KeyChain: undefined,
+                                    keysClaimed: {
+                                        ed25519: "SENDER_ED25519",
+                                    },
+                                    room_id: ROOM_ID,
+                                    session: ibGroupSession.pickle(olmDevice._pickleKey),
+                                },
+                                txn);
+                        });
+                })
+                .then(() => {
+                    client.enableKeyBackup({
+                        algorithm: "m.megolm_backup.v1",
+                        version: 1,
+                        auth_data: {
+                            public_key: "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+                        },
+                    });
+                    let numCalls = 0;
+                    return new Promise((resolve, reject) => {
+                        client._http.authedRequest = function(
+                            callback, method, path, queryParams, data, opts,
+                        ) {
+                            ++numCalls;
+                            expect(numCalls).toBeLessThanOrEqualTo(1);
+                            if (numCalls >= 2) {
+                                // exit out of retry loop if there's something wrong
+                                reject(new Error("authedRequest called too many timmes"));
+                                return Promise.resolve({});
+                            }
+                            expect(method).toBe("PUT");
+                            expect(path).toBe("/room_keys/keys");
+                            expect(queryParams.version).toBe(1);
+                            expect(data.rooms[ROOM_ID].sessions).toExist();
+                            expect(data.rooms[ROOM_ID].sessions).toIncludeKey(
+                                groupSession.session_id(),
+                            );
+                            resolve();
+                            return Promise.resolve({});
+                        };
+                        client._crypto.backupGroupSession(
+                            "roomId",
+                            "F0Q2NmyJNgUVj9DGsb4ZQt3aVxhVcUQhg7+gvW0oyKI",
+                            [],
+                            groupSession.session_id(),
+                            groupSession.session_key(),
+                        );
+                    }).then(() => {
+                        expect(numCalls).toBe(1);
+                    });
+                });
+        });
+
+        it('signs backups with the cross-signing master key', async 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;
+
+            await client.initCrypto();
+            let privateKeys;
+            client.uploadDeviceSigningKeys = async function(e) {return;};
+            client.uploadKeySignatures = async function(e) {return;};
+            client.on("crossSigning.saveCrossSigningKeys", function(e) {
+                privateKeys = e;
+            });
+            client.on("crossSigning.getKey", function(e) {
+                e.done(privateKeys[e.type]);
+            });
+            await client.resetCrossSigningKeys();
+            let numCalls = 0;
+            await new Promise(async (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("POST");
+                    expect(path).toBe("/room_keys/version");
+                    try {
+                        // make sure auth_data is signed by the master key
+                        olmlib.pkVerify(
+                            data.auth_data, client.getCrossSigningId(), "@alice:bar",
+                        );
+                    } catch (e) {
+                        reject(e);
+                        return Promise.resolve({});
+                    }
+                    resolve();
+                    return Promise.resolve({});
+                };
+                await client.createKeyBackupVersion({
+                    algorithm: "m.megolm_backup.v1",
+                    auth_data: {
+                        public_key: "hSDwCYkwp1R0i33ctD73Wg2/Og0mOBr066SpjqqbTmo",
+                    },
+                });
+            });
+            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,800 @@
+/*
+Copyright 2019 New Vector Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import '../../olm-loader';
+
+import expect from 'expect';
+import anotherjson from 'another-json';
+
+import olmlib from '../../../lib/crypto/olmlib';
+
+import TestClient from '../../TestClient';
+
+import {HttpResponse, setHttpResponses} from '../../test-utils';
+
+async function makeTestClient(userInfo, options, keys) {
+    if (!keys) keys = {};
+
+    function getCrossSigningKey(type) {
+        return keys[type];
+    }
+
+    function saveCrossSigningKeys(k) {
+        Object.assign(keys, k);
+    }
+
+    if (!options) options = {};
+    options.cryptoCallbacks = Object.assign(
+        {}, { getCrossSigningKey, saveCrossSigningKeys }, options.cryptoCallbacks || {},
+    );
+    const client = (new TestClient(
+        userInfo.userId, userInfo.deviceId, undefined, undefined, options,
+    )).client;
+
+    await client.initCrypto();
+
+    return client;
+}
+
+describe("Cross Signing", function() {
+    if (!global.Olm) {
+        console.warn('Not running megolm backup unit tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await global.Olm.init();
+    });
+
+    it("should sign the master key with the device key", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+        alice.uploadDeviceSigningKeys = expect.createSpy()
+            .andCall(async (auth, keys) => {
+                await olmlib.verifySignature(
+                    alice._crypto._olmDevice, keys.master_key, "@alice:example.com",
+                    "Osborne2", alice._crypto._olmDevice.deviceEd25519Key,
+                );
+            });
+        alice.uploadKeySignatures = async () => {};
+        // set Alice's cross-signing key
+        await alice.resetCrossSigningKeys();
+        expect(alice.uploadDeviceSigningKeys).toHaveBeenCalled();
+    });
+
+    it("should upload a signature when a user is verified", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+        alice.uploadDeviceSigningKeys = async () => {};
+        alice.uploadKeySignatures = async () => {};
+        // set Alice's cross-signing key
+        await alice.resetCrossSigningKeys();
+        // Alice downloads Bob's device key
+        alice._crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+            keys: {
+                master: {
+                    user_id: "@bob:example.com",
+                    usage: ["master"],
+                    keys: {
+                        "ed25519:bobs+master+pubkey": "bobs+master+pubkey",
+                    },
+                },
+            },
+        });
+        // Alice verifies Bob's key
+        const promise = new Promise((resolve, reject) => {
+            alice.uploadKeySignatures = (...args) => {
+                resolve(...args);
+            };
+        });
+        await alice.setDeviceVerified("@bob:example.com", "bobs+master+pubkey", true);
+        // Alice should send a signature of Bob's key to the server
+        await promise;
+    });
+
+    it("should get cross-signing keys from sync", async function() {
+        const masterKey = new Uint8Array([
+            0xda, 0x5a, 0x27, 0x60, 0xe3, 0x3a, 0xc5, 0x82,
+            0x9d, 0x12, 0xc3, 0xbe, 0xe8, 0xaa, 0xc2, 0xef,
+            0xae, 0xb1, 0x05, 0xc1, 0xe7, 0x62, 0x78, 0xa6,
+            0xd7, 0x1f, 0xf8, 0x2c, 0x51, 0x85, 0xf0, 0x1d,
+        ]);
+        const selfSigningKey = new Uint8Array([
+            0x1e, 0xf4, 0x01, 0x6d, 0x4f, 0xa1, 0x73, 0x66,
+            0x6b, 0xf8, 0x93, 0xf5, 0xb0, 0x4d, 0x17, 0xc0,
+            0x17, 0xb5, 0xa5, 0xf6, 0x59, 0x11, 0x8b, 0x49,
+            0x34, 0xf2, 0x4b, 0x64, 0x9b, 0x52, 0xf8, 0x5f,
+        ]);
+
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+            {
+                cryptoCallbacks: {
+                    // will be called to sign our own device
+                    getCrossSigningKey: type => {
+                        if (type === 'master') {
+                            return masterKey;
+                        } else {
+                            return selfSigningKey;
+                        }
+                    },
+                },
+            },
+        );
+
+        const keyChangePromise = new Promise((resolve, reject) => {
+            alice.once("crossSigning.keysChanged", async (e) => {
+                resolve(e);
+                await alice.checkOwnCrossSigningTrust();
+            });
+        });
+
+        const uploadSigsPromise = new Promise((resolve, reject) => {
+            alice.uploadKeySignatures = expect.createSpy().andCall(async (content) => {
+                await olmlib.verifySignature(
+                    alice._crypto._olmDevice,
+                    content["@alice:example.com"][
+                        "nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk"
+                    ],
+                    "@alice:example.com",
+                    "Osborne2", alice._crypto._olmDevice.deviceEd25519Key,
+                );
+                olmlib.pkVerify(
+                    content["@alice:example.com"]["Osborne2"],
+                    "EmkqvokUn8p+vQAGZitOk4PWjp7Ukp3txV2TbMPEiBQ",
+                    "@alice:example.com",
+                );
+                resolve();
+            });
+        });
+
+        const deviceInfo = alice._crypto._deviceList._devices["@alice:example.com"]
+            .Osborne2;
+        const aliceDevice = {
+            user_id: "@alice:example.com",
+            device_id: "Osborne2",
+        };
+        aliceDevice.keys = deviceInfo.keys;
+        aliceDevice.algorithms = deviceInfo.algorithms;
+        await alice._crypto._signObject(aliceDevice);
+        olmlib.pkSign(aliceDevice, selfSigningKey, "@alice:example.com");
+
+        // feed sync result that includes master key, ssk, device key
+        const responses = [
+            HttpResponse.PUSH_RULES_RESPONSE,
+            {
+                method: "POST",
+                path: "/keys/upload/Osborne2",
+                data: {
+                    one_time_key_counts: {
+                        curve25519: 100,
+                        signed_curve25519: 100,
+                    },
+                },
+            },
+            HttpResponse.filterResponse("@alice:example.com"),
+            {
+                method: "GET",
+                path: "/sync",
+                data: {
+                    next_batch: "abcdefg",
+                    device_lists: {
+                        changed: [
+                            "@alice:example.com",
+                            "@bob:example.com",
+                        ],
+                    },
+                },
+            },
+            {
+                method: "POST",
+                path: "/keys/query",
+                data: {
+                    "failures": {},
+                    "device_keys": {
+                        "@alice:example.com": {
+                            "Osborne2": aliceDevice,
+                        },
+                    },
+                    "master_keys": {
+                        "@alice:example.com": {
+                            user_id: "@alice:example.com",
+                            usage: ["master"],
+                            keys: {
+                                "ed25519:nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk":
+                                "nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk",
+                            },
+                        },
+                    },
+                    "self_signing_keys": {
+                        "@alice:example.com": {
+                            user_id: "@alice:example.com",
+                            usage: ["self-signing"],
+                            keys: {
+                                "ed25519:EmkqvokUn8p+vQAGZitOk4PWjp7Ukp3txV2TbMPEiBQ":
+                                "EmkqvokUn8p+vQAGZitOk4PWjp7Ukp3txV2TbMPEiBQ",
+                            },
+                            signatures: {
+                                "@alice:example.com": {
+                                    "ed25519:nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk":
+                                    "Wqx/HXR851KIi8/u/UX+fbAMtq9Uj8sr8FsOcqrLfVYa6lAmbXs"
+                                    + "Vhfy4AlZ3dnEtjgZx0U0QDrghEn2eYBeOCA",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            {
+                method: "POST",
+                path: "/keys/upload/Osborne2",
+                data: {
+                    one_time_key_counts: {
+                        curve25519: 100,
+                        signed_curve25519: 100,
+                    },
+                },
+            },
+        ];
+        setHttpResponses(alice, responses, true, true);
+
+        await alice.startClient();
+
+        // once ssk is confirmed, device key should be trusted
+        await keyChangePromise;
+        await uploadSigsPromise;
+
+        const aliceTrust = alice.checkUserTrust("@alice:example.com");
+        expect(aliceTrust.isCrossSigningVerified()).toBeTruthy();
+        expect(aliceTrust.isTofu()).toBeTruthy();
+        expect(aliceTrust.isVerified()).toBeTruthy();
+
+        const aliceDeviceTrust = alice.checkDeviceTrust("@alice:example.com", "Osborne2");
+        expect(aliceDeviceTrust.isCrossSigningVerified()).toBeTruthy();
+        expect(aliceDeviceTrust.isLocallyVerified()).toBeTruthy();
+        expect(aliceDeviceTrust.isTofu()).toBeTruthy();
+        expect(aliceDeviceTrust.isVerified()).toBeTruthy();
+    });
+
+    it("should use trust chain to determine device verification", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+        alice.uploadDeviceSigningKeys = async () => {};
+        alice.uploadKeySignatures = async () => {};
+        // set Alice's cross-signing key
+        await alice.resetCrossSigningKeys();
+        // Alice downloads Bob's ssk and device key
+        const bobMasterSigning = new global.Olm.PkSigning();
+        const bobMasterPrivkey = bobMasterSigning.generate_seed();
+        const bobMasterPubkey = bobMasterSigning.init_with_seed(bobMasterPrivkey);
+        const bobSigning = new global.Olm.PkSigning();
+        const bobPrivkey = bobSigning.generate_seed();
+        const bobPubkey = bobSigning.init_with_seed(bobPrivkey);
+        const bobSSK = {
+            user_id: "@bob:example.com",
+            usage: ["self_signing"],
+            keys: {
+                ["ed25519:" + bobPubkey]: bobPubkey,
+            },
+        };
+        const sskSig = bobMasterSigning.sign(anotherjson.stringify(bobSSK));
+        bobSSK.signatures = {
+            "@bob:example.com": {
+                ["ed25519:" + bobMasterPubkey]: sskSig,
+            },
+        };
+        alice._crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+            keys: {
+                master: {
+                    user_id: "@bob:example.com",
+                    usage: ["master"],
+                    keys: {
+                        ["ed25519:" + bobMasterPubkey]: bobMasterPubkey,
+                    },
+                },
+                self_signing: bobSSK,
+            },
+            firstUse: 1,
+            unsigned: {},
+        });
+        const bobDevice = {
+            user_id: "@bob:example.com",
+            device_id: "Dynabook",
+            algorithms: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"],
+            keys: {
+                "curve25519:Dynabook": "somePubkey",
+                "ed25519:Dynabook": "someOtherPubkey",
+            },
+        };
+        const sig = bobSigning.sign(anotherjson.stringify(bobDevice));
+        bobDevice.signatures = {
+            "@bob:example.com": {
+                ["ed25519:" + bobPubkey]: sig,
+            },
+        };
+        alice._crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+            Dynabook: bobDevice,
+        });
+        // Bob's device key should be TOFU
+        const bobTrust = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust.isVerified()).toBeFalsy();
+        expect(bobTrust.isTofu()).toBeTruthy();
+
+        const bobDeviceTrust = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust.isVerified()).toBeFalsy();
+        expect(bobDeviceTrust.isTofu()).toBeTruthy();
+
+        // Alice verifies Bob's SSK
+        alice.uploadKeySignatures = () => {};
+        await alice.setDeviceVerified("@bob:example.com", bobMasterPubkey, true);
+
+        // Bob's device key should be trusted
+        const bobTrust2 = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust2.isCrossSigningVerified()).toBeTruthy();
+        expect(bobTrust2.isTofu()).toBeTruthy();
+
+        const bobDeviceTrust2 = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust2.isCrossSigningVerified()).toBeTruthy();
+        expect(bobDeviceTrust2.isLocallyVerified()).toBeFalsy();
+        expect(bobDeviceTrust2.isTofu()).toBeTruthy();
+    });
+
+    it("should trust signatures received from other devices", async function() {
+        const aliceKeys = {};
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+            null,
+            aliceKeys,
+        );
+        alice._crypto._deviceList.startTrackingDeviceList("@bob:example.com");
+        alice._crypto._deviceList.stopTrackingAllDeviceLists = () => {};
+        alice.uploadDeviceSigningKeys = async () => {};
+        alice.uploadKeySignatures = async () => {};
+
+        // set Alice's cross-signing key
+        await alice.resetCrossSigningKeys();
+
+        const selfSigningKey = new Uint8Array([
+            0x1e, 0xf4, 0x01, 0x6d, 0x4f, 0xa1, 0x73, 0x66,
+            0x6b, 0xf8, 0x93, 0xf5, 0xb0, 0x4d, 0x17, 0xc0,
+            0x17, 0xb5, 0xa5, 0xf6, 0x59, 0x11, 0x8b, 0x49,
+            0x34, 0xf2, 0x4b, 0x64, 0x9b, 0x52, 0xf8, 0x5f,
+        ]);
+
+        const keyChangePromise = new Promise((resolve, reject) => {
+            alice._crypto._deviceList.once("userCrossSigningUpdated", (userId) => {
+                if (userId === "@bob:example.com") {
+                    resolve();
+                }
+            });
+        });
+
+        const deviceInfo = alice._crypto._deviceList._devices["@alice:example.com"]
+            .Osborne2;
+        const aliceDevice = {
+            user_id: "@alice:example.com",
+            device_id: "Osborne2",
+        };
+        aliceDevice.keys = deviceInfo.keys;
+        aliceDevice.algorithms = deviceInfo.algorithms;
+        await alice._crypto._signObject(aliceDevice);
+
+        const bobOlmAccount = new global.Olm.Account();
+        bobOlmAccount.create();
+        const bobKeys = JSON.parse(bobOlmAccount.identity_keys());
+        const bobDevice = {
+            user_id: "@bob:example.com",
+            device_id: "Dynabook",
+            algorithms: [olmlib.OLM_ALGORITHM, olmlib.MEGOLM_ALGORITHM],
+            keys: {
+                "ed25519:Dynabook": bobKeys.ed25519,
+                "curve25519:Dynabook": bobKeys.curve25519,
+            },
+        };
+        const deviceStr = anotherjson.stringify(bobDevice);
+        bobDevice.signatures = {
+            "@bob:example.com": {
+                "ed25519:Dynabook": bobOlmAccount.sign(deviceStr),
+            },
+        };
+        olmlib.pkSign(bobDevice, selfSigningKey, "@bob:example.com");
+
+        const bobMaster = {
+            user_id: "@bob:example.com",
+            usage: ["master"],
+            keys: {
+                "ed25519:nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk":
+                "nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk",
+            },
+        };
+        olmlib.pkSign(bobMaster, aliceKeys.user_signing, "@alice:example.com");
+
+        // Alice downloads Bob's keys
+        // - device key
+        // - ssk
+        // - master key signed by her usk (pretend that it was signed by another
+        //   of Alice's devices)
+        const responses = [
+            HttpResponse.PUSH_RULES_RESPONSE,
+            {
+                method: "POST",
+                path: "/keys/upload/Osborne2",
+                data: {
+                    one_time_key_counts: {
+                        curve25519: 100,
+                        signed_curve25519: 100,
+                    },
+                },
+            },
+            HttpResponse.filterResponse("@alice:example.com"),
+            {
+                method: "GET",
+                path: "/sync",
+                data: {
+                    next_batch: "abcdefg",
+                    device_lists: {
+                        changed: [
+                            "@bob:example.com",
+                        ],
+                    },
+                },
+            },
+            {
+                method: "POST",
+                path: "/keys/query",
+                data: {
+                    "failures": {},
+                    "device_keys": {
+                        "@alice:example.com": {
+                            "Osborne2": aliceDevice,
+                        },
+                        "@bob:example.com": {
+                            "Dynabook": bobDevice,
+                        },
+                    },
+                    "master_keys": {
+                        "@bob:example.com": bobMaster,
+                    },
+                    "self_signing_keys": {
+                        "@bob:example.com": {
+                            user_id: "@bob:example.com",
+                            usage: ["self-signing"],
+                            keys: {
+                                "ed25519:EmkqvokUn8p+vQAGZitOk4PWjp7Ukp3txV2TbMPEiBQ":
+                                "EmkqvokUn8p+vQAGZitOk4PWjp7Ukp3txV2TbMPEiBQ",
+                            },
+                            signatures: {
+                                "@bob:example.com": {
+                                    "ed25519:nqOvzeuGWT/sRx3h7+MHoInYj3Uk2LD/unI9kDYcHwk":
+                                    "2KLiufImvEbfJuAFvsaZD+PsL8ELWl7N1u9yr/9hZvwRghBfQMB"
+                                    + "LAI86b1kDV9+Cq1lt85ykReeCEzmTEPY2BQ",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            {
+                method: "POST",
+                path: "/keys/upload/Osborne2",
+                data: {
+                    one_time_key_counts: {
+                        curve25519: 100,
+                        signed_curve25519: 100,
+                    },
+                },
+            },
+        ];
+        setHttpResponses(alice, responses);
+
+        await alice.startClient();
+
+        await keyChangePromise;
+
+        // Bob's device key should be trusted
+        const bobTrust = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust.isCrossSigningVerified()).toBeTruthy();
+        expect(bobTrust.isTofu()).toBeTruthy();
+
+        const bobDeviceTrust = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust.isCrossSigningVerified()).toBeTruthy();
+        expect(bobDeviceTrust.isLocallyVerified()).toBeFalsy();
+        expect(bobDeviceTrust.isTofu()).toBeTruthy();
+    });
+
+    it("should dis-trust an unsigned device", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+        alice.uploadDeviceSigningKeys = async () => {};
+        alice.uploadKeySignatures = async () => {};
+        // set Alice's cross-signing key
+        await alice.resetCrossSigningKeys();
+        // Alice downloads Bob's ssk and device key
+        // (NOTE: device key is not signed by ssk)
+        const bobMasterSigning = new global.Olm.PkSigning();
+        const bobMasterPrivkey = bobMasterSigning.generate_seed();
+        const bobMasterPubkey = bobMasterSigning.init_with_seed(bobMasterPrivkey);
+        const bobSigning = new global.Olm.PkSigning();
+        const bobPrivkey = bobSigning.generate_seed();
+        const bobPubkey = bobSigning.init_with_seed(bobPrivkey);
+        const bobSSK = {
+            user_id: "@bob:example.com",
+            usage: ["self_signing"],
+            keys: {
+                ["ed25519:" + bobPubkey]: bobPubkey,
+            },
+        };
+        const sskSig = bobMasterSigning.sign(anotherjson.stringify(bobSSK));
+        bobSSK.signatures = {
+            "@bob:example.com": {
+                ["ed25519:" + bobMasterPubkey]: sskSig,
+            },
+        };
+        alice._crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+            keys: {
+                master: {
+                    user_id: "@bob:example.com",
+                    usage: ["master"],
+                    keys: {
+                        ["ed25519:" + bobMasterPubkey]: bobMasterPubkey,
+                    },
+                },
+                self_signing: bobSSK,
+            },
+            firstUse: 1,
+            unsigned: {},
+        });
+        const bobDevice = {
+            user_id: "@bob:example.com",
+            device_id: "Dynabook",
+            algorithms: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"],
+            keys: {
+                "curve25519:Dynabook": "somePubkey",
+                "ed25519:Dynabook": "someOtherPubkey",
+            },
+        };
+        alice._crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+            Dynabook: bobDevice,
+        });
+        // Bob's device key should be untrusted
+        const bobDeviceTrust = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust.isVerified()).toBeFalsy();
+        expect(bobDeviceTrust.isTofu()).toBeFalsy();
+
+        // Alice verifies Bob's SSK
+        await alice.setDeviceVerified("@bob:example.com", bobMasterPubkey, true);
+
+        // Bob's device key should be untrusted
+        const bobDeviceTrust2 = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust2.isVerified()).toBeFalsy();
+        expect(bobDeviceTrust2.isTofu()).toBeFalsy();
+    });
+
+    it("should dis-trust a user when their ssk changes", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+        alice.uploadDeviceSigningKeys = async () => {};
+        alice.uploadKeySignatures = async () => {};
+        await alice.resetCrossSigningKeys();
+        // Alice downloads Bob's keys
+        const bobMasterSigning = new global.Olm.PkSigning();
+        const bobMasterPrivkey = bobMasterSigning.generate_seed();
+        const bobMasterPubkey = bobMasterSigning.init_with_seed(bobMasterPrivkey);
+        const bobSigning = new global.Olm.PkSigning();
+        const bobPrivkey = bobSigning.generate_seed();
+        const bobPubkey = bobSigning.init_with_seed(bobPrivkey);
+        const bobSSK = {
+            user_id: "@bob:example.com",
+            usage: ["self_signing"],
+            keys: {
+                ["ed25519:" + bobPubkey]: bobPubkey,
+            },
+        };
+        const sskSig = bobMasterSigning.sign(anotherjson.stringify(bobSSK));
+        bobSSK.signatures = {
+            "@bob:example.com": {
+                ["ed25519:" + bobMasterPubkey]: sskSig,
+            },
+        };
+        alice._crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+            keys: {
+                master: {
+                    user_id: "@bob:example.com",
+                    usage: ["master"],
+                    keys: {
+                        ["ed25519:" + bobMasterPubkey]: bobMasterPubkey,
+                    },
+                },
+                self_signing: bobSSK,
+            },
+            firstUse: 1,
+            unsigned: {},
+        });
+        const bobDevice = {
+            user_id: "@bob:example.com",
+            device_id: "Dynabook",
+            algorithms: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"],
+            keys: {
+                "curve25519:Dynabook": "somePubkey",
+                "ed25519:Dynabook": "someOtherPubkey",
+            },
+        };
+        const bobDeviceString = anotherjson.stringify(bobDevice);
+        const sig = bobSigning.sign(bobDeviceString);
+        bobDevice.signatures = {};
+        bobDevice.signatures["@bob:example.com"] = {};
+        bobDevice.signatures["@bob:example.com"]["ed25519:" + bobPubkey] = sig;
+        alice._crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+            Dynabook: bobDevice,
+        });
+        // Alice verifies Bob's SSK
+        alice.uploadKeySignatures = () => {};
+        await alice.setDeviceVerified("@bob:example.com", bobMasterPubkey, true);
+
+        // Bob's device key should be trusted
+        const bobDeviceTrust = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust.isVerified()).toBeTruthy();
+        expect(bobDeviceTrust.isTofu()).toBeTruthy();
+
+        // Alice downloads new SSK for Bob
+        const bobMasterSigning2 = new global.Olm.PkSigning();
+        const bobMasterPrivkey2 = bobMasterSigning2.generate_seed();
+        const bobMasterPubkey2 = bobMasterSigning2.init_with_seed(bobMasterPrivkey2);
+        const bobSigning2 = new global.Olm.PkSigning();
+        const bobPrivkey2 = bobSigning2.generate_seed();
+        const bobPubkey2 = bobSigning2.init_with_seed(bobPrivkey2);
+        const bobSSK2 = {
+            user_id: "@bob:example.com",
+            usage: ["self_signing"],
+            keys: {
+                ["ed25519:" + bobPubkey2]: bobPubkey2,
+            },
+        };
+        const sskSig2 = bobMasterSigning2.sign(anotherjson.stringify(bobSSK2));
+        bobSSK2.signatures = {
+            "@bob:example.com": {
+                ["ed25519:" + bobMasterPubkey2]: sskSig2,
+            },
+        };
+        alice._crypto._deviceList.storeCrossSigningForUser("@bob:example.com", {
+            keys: {
+                master: {
+                    user_id: "@bob:example.com",
+                    usage: ["master"],
+                    keys: {
+                        ["ed25519:" + bobMasterPubkey2]: bobMasterPubkey2,
+                    },
+                },
+                self_signing: bobSSK2,
+            },
+            firstUse: 0,
+            unsigned: {},
+        });
+        // Bob's and his device should be untrusted
+        const bobTrust = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust.isVerified()).toBeFalsy();
+        expect(bobTrust.isTofu()).toBeFalsy();
+
+        const bobDeviceTrust2 = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust2.isVerified()).toBeFalsy();
+        expect(bobDeviceTrust2.isTofu()).toBeFalsy();
+
+        // Alice verifies Bob's SSK
+        alice.uploadKeySignatures = () => {};
+        await alice.setDeviceVerified("@bob:example.com", bobMasterPubkey2, true);
+
+        // Bob should be trusted but not his device
+        const bobTrust2 = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust2.isVerified()).toBeTruthy();
+
+        const bobDeviceTrust3 = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust3.isVerified()).toBeFalsy();
+
+        // Alice gets new signature for device
+        const sig2 = bobSigning2.sign(bobDeviceString);
+        bobDevice.signatures["@bob:example.com"]["ed25519:" + bobPubkey2] = sig2;
+        alice._crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+            Dynabook: bobDevice,
+        });
+
+        // Bob's device should be trusted again (but not TOFU)
+        const bobTrust3 = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust3.isVerified()).toBeTruthy();
+
+        const bobDeviceTrust4 = alice.checkDeviceTrust("@bob:example.com", "Dynabook");
+        expect(bobDeviceTrust4.isCrossSigningVerified()).toBeTruthy();
+    });
+
+    it("should offer to upgrade device verifications to cross-signing", async function() {
+        let upgradeResolveFunc;
+
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+            {
+                cryptoCallbacks: {
+                    shouldUpgradeDeviceVerifications: (verifs) => {
+                        expect(verifs.users["@bob:example.com"]).toExist();
+                        upgradeResolveFunc();
+                        return ["@bob:example.com"];
+                    },
+                },
+            },
+        );
+        const bob = await makeTestClient(
+            {userId: "@bob:example.com", deviceId: "Dynabook"},
+        );
+
+        bob.uploadDeviceSigningKeys = async () => {};
+        bob.uploadKeySignatures = async () => {};
+        // set Bob's cross-signing key
+        await bob.resetCrossSigningKeys();
+        alice._crypto._deviceList.storeDevicesForUser("@bob:example.com", {
+            Dynabook: {
+                algorithms: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"],
+                keys: {
+                    "curve25519:Dynabook": bob._crypto._olmDevice.deviceCurve25519Key,
+                    "ed25519:Dynabook": bob._crypto._olmDevice.deviceEd25519Key,
+                },
+                verified: 1,
+                known: true,
+            },
+        });
+        alice._crypto._deviceList.storeCrossSigningForUser(
+            "@bob:example.com",
+            bob._crypto._crossSigningInfo.toStorage(),
+        );
+
+        alice.uploadDeviceSigningKeys = async () => {};
+        alice.uploadKeySignatures = async () => {};
+        // when alice sets up cross-signing, she should notice that bob's
+        // cross-signing key is signed by his Dynabook, which alice has
+        // verified, and ask if the device verification should be upgraded to a
+        // cross-signing verification
+        let upgradePromise = new Promise((resolve) => {
+            upgradeResolveFunc = resolve;
+        });
+        await alice.resetCrossSigningKeys();
+        await upgradePromise;
+
+        const bobTrust = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust.isCrossSigningVerified()).toBeTruthy();
+        expect(bobTrust.isTofu()).toBeTruthy();
+
+        // "forget" that Bob is trusted
+        delete alice._crypto._deviceList._crossSigningInfo["@bob:example.com"]
+            .keys.master.signatures["@alice:example.com"];
+
+        const bobTrust2 = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust2.isCrossSigningVerified()).toBeFalsy();
+        expect(bobTrust2.isTofu()).toBeTruthy();
+
+        upgradePromise = new Promise((resolve) => {
+            upgradeResolveFunc = resolve;
+        });
+        alice._crypto._deviceList.emit("userCrossSigningUpdated", "@bob:example.com");
+        await upgradePromise;
+
+        const bobTrust3 = alice.checkUserTrust("@bob:example.com");
+        expect(bobTrust3.isCrossSigningVerified()).toBeTruthy();
+        expect(bobTrust3.isTofu()).toBeTruthy();
+    });
+});
@@ -0,0 +1,248 @@
+/*
+Copyright 2019 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import '../../olm-loader';
+
+import expect from 'expect';
+import { MatrixEvent } from '../../../lib/models/event';
+import { SECRET_STORAGE_ALGORITHM_V1 } from '../../../lib/crypto/SecretStorage';
+
+import olmlib from '../../../lib/crypto/olmlib';
+
+import TestClient from '../../TestClient';
+import { makeTestClients } from './verification/util';
+
+async function makeTestClient(userInfo, options) {
+    const client = (new TestClient(
+        userInfo.userId, userInfo.deviceId, undefined, undefined, options,
+    )).client;
+
+    await client.initCrypto();
+
+    return client;
+}
+
+describe("Secrets", function() {
+    if (!global.Olm) {
+        console.warn('Not running megolm backup unit tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await global.Olm.init();
+    });
+
+    it("should store and retrieve a secret", async function() {
+        const decryption = new global.Olm.PkDecryption();
+        const pubkey = decryption.generate_key();
+        const privkey = decryption.get_private_key();
+
+        const signing = new global.Olm.PkSigning();
+        const signingKey = signing.generate_seed();
+        const signingPubKey = signing.init_with_seed(signingKey);
+
+        const signingkeyInfo = {
+            user_id: "@alice:example.com",
+            usage: ['master'],
+            keys: {
+                ['ed25519:' + signingPubKey]: signingPubKey,
+            },
+        };
+
+        const getKey = expect.createSpy().andCall(e => {
+            expect(Object.keys(e.keys)).toEqual(["abc"]);
+            return ['abc', privkey];
+        });
+
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+            {
+                cryptoCallbacks: {
+                    getCrossSigningKey: t => signingKey,
+                    getSecretStorageKey: getKey,
+                },
+            },
+        );
+        alice._crypto._crossSigningInfo.setKeys({
+            master: signingkeyInfo,
+        });
+
+        const secretStorage = alice._crypto._secretStorage;
+
+        alice.setAccountData = async function(eventType, contents, callback) {
+            alice.store.storeAccountDataEvents([
+                new MatrixEvent({
+                    type: eventType,
+                    content: contents,
+                }),
+            ]);
+            if (callback) {
+                callback();
+            }
+        };
+
+        const keyAccountData = {
+            algorithm: SECRET_STORAGE_ALGORITHM_V1,
+            pubkey: pubkey,
+        };
+        await alice._crypto._crossSigningInfo.signObject(keyAccountData, 'master');
+
+        alice.store.storeAccountDataEvents([
+            new MatrixEvent({
+                type: "m.secret_storage.key.abc",
+                content: keyAccountData,
+            }),
+        ]);
+
+        expect(secretStorage.isStored("foo")).toBe(false);
+
+        await secretStorage.store("foo", "bar", ["abc"]);
+
+        expect(secretStorage.isStored("foo")).toBe(true);
+        expect(await secretStorage.get("foo")).toBe("bar");
+
+        expect(getKey).toHaveBeenCalled();
+    });
+
+    it("should throw if given a key that doesn't exist", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+
+        try {
+            await alice.storeSecret("foo", "bar", ["this secret does not exist"]);
+            // should be able to use expect(...).toThrow() but mocha still fails
+            // the test even when it throws for reasons I have no inclination to debug
+            expect(true).toBeFalsy();
+        } catch (e) {
+        }
+    });
+
+    it("should refuse to encrypt with zero keys", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+
+        try {
+            await alice.storeSecret("foo", "bar", []);
+            expect(true).toBeFalsy();
+        } catch (e) {
+        }
+    });
+
+    it("should encrypt with default key if keys is null", async function() {
+        let keys = {};
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+            {
+                cryptoCallbacks: {
+                    getCrossSigningKey: t => keys[t],
+                    saveCrossSigningKeys: k => keys = k,
+                },
+            },
+        );
+        alice.setAccountData = async function(eventType, contents, callback) {
+            alice.store.storeAccountDataEvents([
+                new MatrixEvent({
+                    type: eventType,
+                    content: contents,
+                }),
+            ]);
+        };
+        alice.resetCrossSigningKeys();
+
+        const newKeyId = await alice.addSecretKey(
+            SECRET_STORAGE_ALGORITHM_V1,
+        );
+        // we don't await on this because it waits for the event to come down the sync
+        // which won't happen in the test setup
+        alice.setDefaultSecretStorageKeyId(newKeyId);
+        await alice.storeSecret("foo", "bar");
+
+        const accountData = alice.getAccountData('foo');
+        expect(accountData.getContent().encrypted).toBeTruthy();
+    });
+
+    it("should refuse to encrypt if no keys given and no default key", async function() {
+        const alice = await makeTestClient(
+            {userId: "@alice:example.com", deviceId: "Osborne2"},
+        );
+
+        try {
+            await alice.storeSecret("foo", "bar");
+            expect(true).toBeFalsy();
+        } catch (e) {
+        }
+    });
+
+    it("should request secrets from other clients", async function() {
+        const [osborne2, vax] = await makeTestClients(
+            [
+                {userId: "@alice:example.com", deviceId: "Osborne2"},
+                {userId: "@alice:example.com", deviceId: "VAX"},
+            ],
+            {
+                cryptoCallbacks: {
+                    onSecretRequested: e => {
+                        expect(e.name).toBe("foo");
+                        return "bar";
+                    },
+                },
+            },
+        );
+
+        const vaxDevice = vax.client._crypto._olmDevice;
+        const osborne2Device = osborne2.client._crypto._olmDevice;
+        const secretStorage = osborne2.client._crypto._secretStorage;
+
+        osborne2.client._crypto._deviceList.storeDevicesForUser("@alice:example.com", {
+            "VAX": {
+                user_id: "@alice:example.com",
+                device_id: "VAX",
+                algorithms: [olmlib.OLM_ALGORITHM, olmlib.MEGOLM_ALGORITHM],
+                keys: {
+                    "ed25519:VAX": vaxDevice.deviceEd25519Key,
+                    "curve25519:VAX": vaxDevice.deviceCurve25519Key,
+                },
+            },
+        });
+        vax.client._crypto._deviceList.storeDevicesForUser("@alice:example.com", {
+            "Osborne2": {
+                user_id: "@alice:example.com",
+                device_id: "Osborne2",
+                algorithms: [olmlib.OLM_ALGORITHM, olmlib.MEGOLM_ALGORITHM],
+                keys: {
+                    "ed25519:Osborne2": osborne2Device.deviceEd25519Key,
+                    "curve25519:Osborne2": osborne2Device.deviceCurve25519Key,
+                },
+            },
+        });
+
+        await osborne2Device.generateOneTimeKeys(1);
+        const otks = (await osborne2Device.getOneTimeKeys()).curve25519;
+        await osborne2Device.markKeysAsPublished();
+
+        await vax.client._crypto._olmDevice.createOutboundSession(
+            osborne2Device.deviceCurve25519Key,
+            Object.values(otks)[0],
+        );
+
+        const request = await secretStorage.request("foo", ["VAX"]);
+        const secret = await request.promise;
+
+        expect(secret).toBe("bar");
+    });
+});
@@ -0,0 +1,146 @@
+/*
+Copyright 2018-2019 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import logger from '../../../../src/logger';
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    logger.warn("unable to run device verification tests: libolm not available");
+}
+
+import expect from 'expect';
+import DeviceInfo from '../../../../lib/crypto/deviceinfo';
+
+import {ShowQRCode, ScanQRCode} from '../../../../lib/crypto/verification/QRCode';
+
+const Olm = global.Olm;
+
+describe("QR code verification", function() {
+    if (!global.Olm) {
+        logger.warn('Not running device verification tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await Olm.init();
+    });
+
+    describe("showing", function() {
+        it("should emit an event to show a QR code", async function() {
+            const qrCode = new ShowQRCode({
+                getUserId: () => "@alice:example.com",
+                deviceId: "ABCDEFG",
+                getDeviceEd25519Key: function() {
+                    return "device+ed25519+key";
+                },
+            });
+            const spy = expect.createSpy().andCall((e) => {
+                qrCode.done();
+            });
+            qrCode.on("show_qr_code", spy);
+            await qrCode.verify();
+            expect(spy).toHaveBeenCalledWith({
+                url: "https://matrix.to/#/@alice:example.com?device=ABCDEFG"
+                    + "&action=verify&key_ed25519%3AABCDEFG=device%2Bed25519%2Bkey",
+            });
+        });
+    });
+
+    describe("scanning", function() {
+        const QR_CODE_URL = "https://matrix.to/#/@alice:example.com?device=ABCDEFG"
+              + "&action=verify&key_ed25519%3AABCDEFG=device%2Bed25519%2Bkey";
+        it("should verify when a QR code is sent", async function() {
+            const device = DeviceInfo.fromStorage(
+                {
+                    algorithms: [],
+                    keys: {
+                        "curve25519:ABCDEFG": "device+curve25519+key",
+                        "ed25519:ABCDEFG": "device+ed25519+key",
+                    },
+                    verified: false,
+                    known: false,
+                    unsigned: {},
+                },
+                "ABCDEFG",
+            );
+            const client = {
+                getStoredDevice: expect.createSpy().andReturn(device),
+                setDeviceVerified: expect.createSpy(),
+            };
+            const qrCode = new ScanQRCode(client);
+            qrCode.on("confirm_user_id", ({userId, confirm}) => {
+                if (userId === "@alice:example.com") {
+                    confirm();
+                } else {
+                    qrCode.cancel(new Error("Incorrect user"));
+                }
+            });
+            qrCode.on("scan", ({done}) => {
+                done(QR_CODE_URL);
+            });
+            await qrCode.verify();
+            expect(client.getStoredDevice)
+                .toHaveBeenCalledWith("@alice:example.com", "ABCDEFG");
+            expect(client.setDeviceVerified)
+                .toHaveBeenCalledWith("@alice:example.com", "ABCDEFG");
+        });
+
+        it("should error when the user ID doesn't match", async function() {
+            const client = {
+                getStoredDevice: expect.createSpy(),
+                setDeviceVerified: expect.createSpy(),
+            };
+            const qrCode = new ScanQRCode(client, "@bob:example.com", "ABCDEFG");
+            qrCode.on("scan", ({done}) => {
+                done(QR_CODE_URL);
+            });
+            const spy = expect.createSpy();
+            await qrCode.verify().catch(spy);
+            expect(spy).toHaveBeenCalled();
+            expect(client.getStoredDevice).toNotHaveBeenCalled();
+            expect(client.setDeviceVerified).toNotHaveBeenCalled();
+        });
+
+        it("should error if the key doesn't match", async function() {
+            const device = DeviceInfo.fromStorage(
+                {
+                    algorithms: [],
+                    keys: {
+                        "curve25519:ABCDEFG": "device+curve25519+key",
+                        "ed25519:ABCDEFG": "a+different+device+ed25519+key",
+                    },
+                    verified: false,
+                    known: false,
+                    unsigned: {},
+                },
+                "ABCDEFG",
+            );
+            const client = {
+                getStoredDevice: expect.createSpy().andReturn(device),
+                setDeviceVerified: expect.createSpy(),
+            };
+            const qrCode = new ScanQRCode(client, "@alice:example.com", "ABCDEFG");
+            qrCode.on("scan", ({done}) => {
+                done(QR_CODE_URL);
+            });
+            const spy = expect.createSpy();
+            await qrCode.verify().catch(spy);
+            expect(spy).toHaveBeenCalled();
+            expect(client.getStoredDevice).toHaveBeenCalled();
+            expect(client.setDeviceVerified).toNotHaveBeenCalled();
+        });
+    });
+});
@@ -0,0 +1,82 @@
+/*
+Copyright 2019 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import logger from '../../../../src/logger';
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    logger.warn("unable to run device verification tests: libolm not available");
+}
+
+import expect from 'expect';
+
+import {verificationMethods} from '../../../../lib/crypto';
+
+import SAS from '../../../../lib/crypto/verification/SAS';
+
+const Olm = global.Olm;
+
+import {makeTestClients} from './util';
+
+describe("verification request", function() {
+    if (!global.Olm) {
+        logger.warn('Not running device verification unit tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await Olm.init();
+    });
+
+    it("should request and accept a verification", async function() {
+        const [alice, bob] = await makeTestClients(
+            [
+                {userId: "@alice:example.com", deviceId: "Osborne2"},
+                {userId: "@bob:example.com", deviceId: "Dynabook"},
+            ],
+            {
+                verificationMethods: [verificationMethods.SAS],
+            },
+        );
+        alice.client._crypto._deviceList.getRawStoredDevicesForUser = function() {
+            return {
+                Dynabook: {
+                    keys: {
+                        "ed25519:Dynabook": "bob+base64+ed25519+key",
+                    },
+                },
+            };
+        };
+        alice.client.downloadKeys = () => {
+            return Promise.resolve();
+        };
+        bob.client.downloadKeys = () => {
+            return Promise.resolve();
+        };
+        bob.client.on("crypto.verification.request", (request) => {
+            const bobVerifier = request.beginKeyVerification(verificationMethods.SAS);
+            bobVerifier.verify();
+
+            // XXX: Private function access (but it's a test, so we're okay)
+            bobVerifier._endTimer();
+        });
+        const aliceVerifier = await alice.client.requestVerification("@bob:example.com");
+        expect(aliceVerifier).toBeAn(SAS);
+
+        // XXX: Private function access (but it's a test, so we're okay)
+        aliceVerifier._endTimer();
+    });
+});
@@ -0,0 +1,507 @@
+/*
+Copyright 2018-2019 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import logger from '../../../../src/logger';
+
+try {
+    global.Olm = require('olm');
+} catch (e) {
+    logger.warn("unable to run device verification tests: libolm not available");
+}
+
+import expect from 'expect';
+import olmlib from '../../../../lib/crypto/olmlib';
+
+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';
+
+let ALICE_DEVICES;
+let BOB_DEVICES;
+
+describe("SAS verification", function() {
+    if (!global.Olm) {
+        logger.warn('Not running device verification unit tests: libolm not present');
+        return;
+    }
+
+    beforeEach(async function() {
+        await Olm.init();
+    });
+
+    it("should error on an unexpected event", async function() {
+        const sas = new SAS({}, "@alice:example.com", "ABCDEFG");
+        sas.handleEvent(new MatrixEvent({
+            sender: "@alice:example.com",
+            type: "es.inquisition",
+            content: {},
+        }));
+        const spy = expect.createSpy();
+        await sas.verify()
+            .catch(spy);
+        expect(spy).toHaveBeenCalled();
+
+        // Cancel the SAS for cleanup (we started a verification, so abort)
+        sas.cancel();
+    });
+
+    describe("verification", function() {
+        let alice;
+        let bob;
+        let aliceSasEvent;
+        let bobSasEvent;
+        let aliceVerifier;
+        let bobPromise;
+
+        beforeEach(async function() {
+            [alice, bob] = await makeTestClients(
+                [
+                    {userId: "@alice:example.com", deviceId: "Osborne2"},
+                    {userId: "@bob:example.com", deviceId: "Dynabook"},
+                ],
+                {
+                    verificationMethods: [verificationMethods.SAS],
+                },
+            );
+
+            const aliceDevice = alice.client._crypto._olmDevice;
+            const bobDevice = bob.client._crypto._olmDevice;
+
+            ALICE_DEVICES = {
+                Osborne2: {
+                    user_id: "@alice:example.com",
+                    device_id: "Osborne2",
+                    algorithms: [olmlib.OLM_ALGORITHM, olmlib.MEGOLM_ALGORITHM],
+                    keys: {
+                        "ed25519:Osborne2": aliceDevice.deviceEd25519Key,
+                        "curve25519:Osborne2": aliceDevice.deviceCurve25519Key,
+                    },
+                },
+            };
+
+            BOB_DEVICES = {
+                Dynabook: {
+                    user_id: "@bob:example.com",
+                    device_id: "Dynabook",
+                    algorithms: [olmlib.OLM_ALGORITHM, olmlib.MEGOLM_ALGORITHM],
+                    keys: {
+                        "ed25519:Dynabook": bobDevice.deviceEd25519Key,
+                        "curve25519:Dynabook": bobDevice.deviceCurve25519Key,
+                    },
+                },
+            };
+
+            alice.client._crypto._deviceList.storeDevicesForUser(
+                "@bob:example.com", BOB_DEVICES,
+            );
+            alice.downloadKeys = () => {
+                return Promise.resolve();
+            };
+
+            bob.client._crypto._deviceList.storeDevicesForUser(
+                "@alice:example.com", ALICE_DEVICES,
+            );
+            bob.downloadKeys = () => {
+                return Promise.resolve();
+            };
+
+            aliceSasEvent = null;
+            bobSasEvent = null;
+
+            bobPromise = new Promise((resolve, reject) => {
+                bob.client.on("crypto.verification.start", (verifier) => {
+                    verifier.on("show_sas", (e) => {
+                        if (!e.sas.emoji || !e.sas.decimal) {
+                            e.cancel();
+                        } else if (!aliceSasEvent) {
+                            bobSasEvent = e;
+                        } else {
+                            try {
+                                expect(e.sas).toEqual(aliceSasEvent.sas);
+                                e.confirm();
+                                aliceSasEvent.confirm();
+                            } catch (error) {
+                                e.mismatch();
+                                aliceSasEvent.mismatch();
+                            }
+                        }
+                    });
+                    resolve(verifier);
+                });
+            });
+
+            aliceVerifier = alice.client.beginKeyVerification(
+                verificationMethods.SAS, bob.client.getUserId(), bob.deviceId,
+            );
+            aliceVerifier.on("show_sas", (e) => {
+                if (!e.sas.emoji || !e.sas.decimal) {
+                    e.cancel();
+                } else if (!bobSasEvent) {
+                    aliceSasEvent = e;
+                } else {
+                    try {
+                        expect(e.sas).toEqual(bobSasEvent.sas);
+                        e.confirm();
+                        bobSasEvent.confirm();
+                    } catch (error) {
+                        e.mismatch();
+                        bobSasEvent.mismatch();
+                    }
+                }
+            });
+        });
+
+        it("should verify a key", async function() {
+            let macMethod;
+            const origSendToDevice = alice.client.sendToDevice;
+            bob.client.sendToDevice = function(type, map) {
+                if (type === "m.key.verification.accept") {
+                    macMethod = map[alice.client.getUserId()][alice.client.deviceId]
+                        .message_authentication_code;
+                }
+                return origSendToDevice.call(this, type, map);
+            };
+
+            alice.httpBackend.when('POST', '/keys/query').respond(200, {
+                failures: {},
+                device_keys: {
+                    "@bob:example.com": BOB_DEVICES,
+                },
+            });
+            bob.httpBackend.when('POST', '/keys/query').respond(200, {
+                failures: {},
+                device_keys: {
+                    "@alice:example.com": ALICE_DEVICES,
+                },
+            });
+
+            await Promise.all([
+                aliceVerifier.verify(),
+                bobPromise.then((verifier) => verifier.verify()),
+                alice.httpBackend.flush(),
+                bob.httpBackend.flush(),
+            ]);
+
+            // make sure that it uses the preferred method
+            expect(macMethod).toBe("hkdf-hmac-sha256");
+
+            // make sure Alice and Bob verified each other
+            const bobDevice
+                  = await alice.client.getStoredDevice("@bob:example.com", "Dynabook");
+            expect(bobDevice.isVerified()).toBeTruthy();
+            const aliceDevice
+                  = await bob.client.getStoredDevice("@alice:example.com", "Osborne2");
+            expect(aliceDevice.isVerified()).toBeTruthy();
+        });
+
+        it("should be able to verify using the old MAC", async function() {
+            // pretend that Alice can only understand the old (incorrect) MAC,
+            // and make sure that she can still verify with Bob
+            let macMethod;
+            const origSendToDevice = alice.client.sendToDevice;
+            alice.client.sendToDevice = function(type, map) {
+                if (type === "m.key.verification.start") {
+                    // Note: this modifies not only the message that Bob
+                    // receives, but also the copy of the message that Alice
+                    // has, since it is the same object.  If this does not
+                    // happen, the verification will fail due to a hash
+                    // commitment mismatch.
+                    map[bob.client.getUserId()][bob.client.deviceId]
+                        .message_authentication_codes = ['hmac-sha256'];
+                }
+                return origSendToDevice.call(this, type, map);
+            };
+            bob.client.sendToDevice = function(type, map) {
+                if (type === "m.key.verification.accept") {
+                    macMethod = map[alice.client.getUserId()][alice.client.deviceId]
+                        .message_authentication_code;
+                }
+                return origSendToDevice.call(this, type, map);
+            };
+
+            alice.httpBackend.when('POST', '/keys/query').respond(200, {
+                failures: {},
+                device_keys: {
+                    "@bob:example.com": BOB_DEVICES,
+                },
+            });
+            bob.httpBackend.when('POST', '/keys/query').respond(200, {
+                failures: {},
+                device_keys: {
+                    "@alice:example.com": ALICE_DEVICES,
+                },
+            });
+
+            await Promise.all([
+                aliceVerifier.verify(),
+                bobPromise.then((verifier) => verifier.verify()),
+                alice.httpBackend.flush(),
+                bob.httpBackend.flush(),
+            ]);
+
+            expect(macMethod).toBe("hmac-sha256");
+
+            const bobDevice
+                  = await alice.client.getStoredDevice("@bob:example.com", "Dynabook");
+            expect(bobDevice.isVerified()).toBeTruthy();
+            const aliceDevice
+                  = await bob.client.getStoredDevice("@alice:example.com", "Osborne2");
+            expect(aliceDevice.isVerified()).toBeTruthy();
+        });
+
+        it("should verify a cross-signing key", async function() {
+            alice.httpBackend.when('POST', '/keys/device_signing/upload').respond(
+                200, {},
+            );
+            alice.httpBackend.when('POST', '/keys/signatures/upload').respond(200, {});
+            alice.httpBackend.flush(undefined, 2);
+            await alice.client.resetCrossSigningKeys();
+            bob.httpBackend.when('POST', '/keys/device_signing/upload').respond(200, {});
+            bob.httpBackend.when('POST', '/keys/signatures/upload').respond(200, {});
+            bob.httpBackend.flush(undefined, 2);
+
+            await bob.client.resetCrossSigningKeys();
+
+            bob.client._crypto._deviceList.storeCrossSigningForUser(
+                "@alice:example.com", {
+                    keys: alice.client._crypto._crossSigningInfo.keys,
+                },
+            );
+
+            alice.httpBackend.when('POST', '/keys/query').respond(200, {
+                failures: {},
+                device_keys: {
+                    "@bob:example.com": BOB_DEVICES,
+                },
+            });
+            bob.httpBackend.when('POST', '/keys/query').respond(200, {
+                failures: {},
+                device_keys: {
+                    "@alice:example.com": ALICE_DEVICES,
+                },
+            });
+
+            const verifyProm = Promise.all([
+                aliceVerifier.verify(),
+                bobPromise.then((verifier) => {
+                    bob.httpBackend.when(
+                        'POST', '/keys/signatures/upload',
+                    ).respond(200, {});
+                    bob.httpBackend.flush(undefined, 2);
+                    return verifier.verify();
+                }),
+            ]);
+
+            await alice.httpBackend.flush(undefined, 1);
+            console.log("alice reqs flushed");
+
+            await verifyProm;
+
+            const bobDeviceTrust = alice.client.checkDeviceTrust(
+                "@bob:example.com", "Dynabook",
+            );
+            expect(bobDeviceTrust.isLocallyVerified()).toBeTruthy();
+            expect(bobDeviceTrust.isCrossSigningVerified()).toBeFalsy();
+
+            const aliceTrust = bob.client.checkUserTrust("@alice:example.com");
+            expect(aliceTrust.isCrossSigningVerified()).toBeTruthy();
+            expect(aliceTrust.isTofu()).toBeTruthy();
+
+            const aliceDeviceTrust = bob.client.checkDeviceTrust(
+                "@alice:example.com", "Osborne2",
+            );
+            expect(aliceDeviceTrust.isLocallyVerified()).toBeTruthy();
+            expect(aliceDeviceTrust.isCrossSigningVerified()).toBeFalsy();
+        });
+    });
+
+    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.client.setDeviceVerified = expect.createSpy();
+        alice.client.downloadKeys = () => {
+            return Promise.resolve();
+        };
+        bob.client.setDeviceVerified = expect.createSpy();
+        bob.client.downloadKeys = () => {
+            return Promise.resolve();
+        };
+
+        const bobPromise = new Promise((resolve, reject) => {
+            bob.client.on("crypto.verification.start", (verifier) => {
+                verifier.on("show_sas", (e) => {
+                    e.mismatch();
+                });
+                resolve(verifier);
+            });
+        });
+
+        const aliceVerifier = alice.client.beginKeyVerification(
+            verificationMethods.SAS, bob.client.getUserId(), bob.client.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.client.setDeviceVerified)
+            .toNotHaveBeenCalled();
+        expect(bob.client.setDeviceVerified)
+            .toNotHaveBeenCalled();
+    });
+
+    describe("verification in DM", function() {
+        let alice;
+        let bob;
+        let aliceSasEvent;
+        let bobSasEvent;
+        let aliceVerifier;
+        let bobPromise;
+
+        beforeEach(async function() {
+            [alice, bob] = await makeTestClients(
+                [
+                    {userId: "@alice:example.com", deviceId: "Osborne2"},
+                    {userId: "@bob:example.com", deviceId: "Dynabook"},
+                ],
+                {
+                    verificationMethods: [verificationMethods.SAS],
+                },
+            );
+
+            alice.client.setDeviceVerified = expect.createSpy();
+            alice.client.getDeviceEd25519Key = () => {
+                return "alice+base64+ed25519+key";
+            };
+            alice.client.getStoredDevice = () => {
+                return DeviceInfo.fromStorage(
+                    {
+                        keys: {
+                            "ed25519:Dynabook": "bob+base64+ed25519+key",
+                        },
+                    },
+                    "Dynabook",
+                );
+            };
+            alice.client.downloadKeys = () => {
+                return Promise.resolve();
+            };
+
+            bob.client.setDeviceVerified = expect.createSpy();
+            bob.client.getStoredDevice = () => {
+                return DeviceInfo.fromStorage(
+                    {
+                        keys: {
+                            "ed25519:Osborne2": "alice+base64+ed25519+key",
+                        },
+                    },
+                    "Osborne2",
+                );
+            };
+            bob.client.getDeviceEd25519Key = () => {
+                return "bob+base64+ed25519+key";
+            };
+            bob.client.downloadKeys = () => {
+                return Promise.resolve();
+            };
+
+            aliceSasEvent = null;
+            bobSasEvent = null;
+
+            bobPromise = new Promise((resolve, reject) => {
+                bob.client.on("event", async (event) => {
+                    const content = event.getContent();
+                    if (event.getType() === "m.room.message"
+                        && content.msgtype === "m.key.verification.request") {
+                        expect(content.methods).toInclude(SAS.NAME);
+                        expect(content.to).toBe(bob.client.getUserId());
+                        const verifier = bob.client.acceptVerificationDM(event, SAS.NAME);
+                        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();
+                                }
+                            }
+                        });
+                        await verifier.verify();
+                        resolve();
+                    }
+                });
+            });
+
+            aliceVerifier = await alice.client.requestVerificationDM(
+                bob.client.getUserId(), "!room_id", [verificationMethods.SAS],
+            );
+            aliceVerifier.on("show_sas", (e) => {
+                if (!e.sas.emoji || !e.sas.decimal) {
+                    e.cancel();
+                } else if (!bobSasEvent) {
+                    aliceSasEvent = e;
+                } else {
+                    try {
+                        expect(e.sas).toEqual(bobSasEvent.sas);
+                        e.confirm();
+                        bobSasEvent.confirm();
+                    } catch (error) {
+                        e.mismatch();
+                        bobSasEvent.mismatch();
+                    }
+                }
+            });
+        });
+
+        it("should verify a key", async function() {
+            await Promise.all([
+                aliceVerifier.verify(),
+                bobPromise,
+            ]);
+
+            // make sure Alice and Bob verified each other
+            expect(alice.client.setDeviceVerified)
+                .toHaveBeenCalledWith(bob.client.getUserId(), bob.client.deviceId);
+            expect(bob.client.setDeviceVerified)
+                .toHaveBeenCalledWith(alice.client.getUserId(), alice.client.deviceId);
+        });
+    });
+});
@@ -0,0 +1,95 @@
+/*
+Copyright 2019 New Vector Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import TestClient from '../../../TestClient';
+
+import sdk from '../../../..';
+const MatrixEvent = sdk.MatrixEvent;
+
+export async function makeTestClients(userInfos, options) {
+    const clients = [];
+    const clientMap = {};
+    const sendToDevice = function(type, map) {
+        // console.log(this.getUserId(), "sends", type, map);
+        for (const [userId, devMap] of Object.entries(map)) {
+            if (userId in clientMap) {
+                for (const [deviceId, msg] of Object.entries(devMap)) {
+                    if (deviceId in clientMap[userId]) {
+                        const event = new MatrixEvent({
+                            sender: this.getUserId(), // eslint-disable-line babel/no-invalid-this
+                            type: type,
+                            content: msg,
+                        });
+                        const client = clientMap[userId][deviceId];
+                        if (event.isEncrypted()) {
+                            event.attemptDecryption(client._crypto)
+                                .then(() => client.emit("toDeviceEvent", event));
+                        } else {
+                            setTimeout(
+                                () => client.emit("toDeviceEvent", event),
+                                0,
+                            );
+                        }
+                    }
+                }
+            }
+        }
+    };
+    const sendEvent = function(room, type, content) {
+        // make up a unique ID as the event ID
+        const eventId = "$" + this.makeTxnId(); // eslint-disable-line babel/no-invalid-this
+        const event = new MatrixEvent({
+            sender: this.getUserId(), // eslint-disable-line babel/no-invalid-this
+            type: type,
+            content: content,
+            room_id: room,
+            event_id: eventId,
+        });
+        for (const tc of clients) {
+            setTimeout(
+                () => tc.client.emit("event", event),
+                0,
+            );
+        }
+
+        return {event_id: eventId};
+    };
+
+    for (const userInfo of userInfos) {
+        let keys = {};
+        if (!options) options = {};
+        if (!options.cryptoCallbacks) options.cryptoCallbacks = {};
+        if (!options.cryptoCallbacks.saveCrossSigningKeys) {
+            options.cryptoCallbacks.saveCrossSigningKeys = k => { keys = k; };
+            options.cryptoCallbacks.getCrossSigningKey = typ => keys[typ];
+        }
+        const testClient = new TestClient(
+            userInfo.userId, userInfo.deviceId, undefined, undefined,
+            options,
+        );
+        if (!(userInfo.userId in clientMap)) {
+            clientMap[userInfo.userId] = {};
+        }
+        clientMap[userInfo.userId][userInfo.deviceId] = testClient.client;
+        testClient.client.sendToDevice = sendToDevice;
+        testClient.client.sendEvent = sendEvent;
+        clients.push(testClient);
+    }
+
+    await Promise.all(clients.map((testClient) => testClient.client.initCrypto()));
+
+    return clients;
+}
@@ -18,7 +18,7 @@ describe("EventTimeline", function() {
    let timeline;

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

        // XXX: this is a horrid hack; should use sinon or something instead to mock
        const timelineSet = { room: { roomId: roomId }};
@@ -21,10 +21,11 @@ import testUtils from '../test-utils';

 import expect from 'expect';
 import Promise from 'bluebird';
+import logger from '../../src/logger';

 describe("MatrixEvent", () => {
    beforeEach(function() {
-        testUtils.beforeEach(this); // eslint-disable-line no-invalid-this
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
    });

    describe(".attemptDecryption", () => {
@@ -48,7 +49,7 @@ describe("MatrixEvent", () => {
            const crypto = {
                decryptEvent: function() {
                    ++callCount;
-                    console.log(`decrypt: ${callCount}`);
+                    logger.log(`decrypt: ${callCount}`);
                    if (callCount == 1) {
                        // schedule a second decryption attempt while
                        // the first one is still running.
@@ -12,7 +12,7 @@ describe("Filter", function() {
    let filter;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        filter = new Filter(userId);
    });

@@ -24,6 +24,7 @@ const InteractiveAuth = sdk.InteractiveAuth;
 const MatrixError = sdk.MatrixError;

 import expect from 'expect';
+import logger from '../../src/logger';

 // Trivial client object to test interactive auth
 // (we do not need TestClient here)
@@ -35,7 +36,7 @@ class FakeClient {

 describe("InteractiveAuth", function() {
    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
    });

    it("should start an auth stage and complete it", function(done) {
@@ -64,7 +65,7 @@ describe("InteractiveAuth", function() {

        // first we expect a call here
        stateUpdated.andCall(function(stage) {
-            console.log('aaaa');
+            logger.log('aaaa');
            expect(stage).toEqual("logintype");
            ia.submitAuthDict({
                type: "logintype",
@@ -75,7 +76,7 @@ describe("InteractiveAuth", function() {
        // .. which should trigger a call here
        const requestRes = {"a": "b"};
        doRequest.andCall(function(authData) {
-            console.log('cccc');
+            logger.log('cccc');
            expect(authData).toEqual({
                session: "sessionId",
                type: "logintype",
@@ -106,7 +107,7 @@ describe("InteractiveAuth", function() {

        // first we expect a call to doRequest
        doRequest.andCall(function(authData) {
-            console.log("request1", authData);
+            logger.log("request1", authData);
            expect(authData).toEqual({});
            const err = new MatrixError({
                session: "sessionId",
@@ -132,7 +133,7 @@ describe("InteractiveAuth", function() {

            // submitAuthDict should trigger another call to doRequest
            doRequest.andCall(function(authData) {
-                console.log("request2", authData);
+                logger.log("request2", authData);
                expect(authData).toEqual({
                    session: "sessionId",
                    type: "logintype",
@@ -0,0 +1,25 @@
+import expect from 'expect';
+import TestClient from '../TestClient';
+
+describe('Login request', function() {
+    let client;
+
+    beforeEach(function() {
+        client = new TestClient();
+    });
+
+    afterEach(function() {
+        client.stop();
+    });
+
+    it('should store "access_token" and "user_id" if in response', async function() {
+        const response = { user_id: 1, access_token: Date.now().toString(16) };
+
+        client.httpBackend.when('POST', '/login').respond(200, response);
+        client.httpBackend.flush('/login', 1, 100);
+        await client.client.login('m.login.any', { user: 'test', password: '12312za' });
+
+        expect(client.client.getAccessToken()).toBe(response.access_token);
+        expect(client.client.getUserId()).toBe(response.user_id);
+    });
+});
@@ -7,6 +7,7 @@ const utils = require("../test-utils");

 import expect from 'expect';
 import lolex from 'lolex';
+import logger from '../../src/logger';

 describe("MatrixClient", function() {
    const userId = "@alice:bar";
@@ -69,7 +70,7 @@ describe("MatrixClient", function() {
            "MatrixClient[UT] RECV " + method + " " + path + "  " +
            "EXPECT " + (next ? next.method : next) + " " + (next ? next.path : next)
        );
-        console.log(logLine);
+        logger.log(logLine);

        if (!next) { // no more things to return
            if (pendingLookup) {
@@ -91,7 +92,7 @@ describe("MatrixClient", function() {
            return pendingLookup.promise;
        }
        if (next.path === path && next.method === method) {
-            console.log(
+            logger.log(
                "MatrixClient[UT] Matched. Returning " +
                (next.error ? "BAD" : "GOOD") + " response",
            );
@@ -124,7 +125,7 @@ describe("MatrixClient", function() {
    }

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        clock = lolex.install();
        scheduler = [
            "getQueueForEvent", "queueEvent", "removeEventFromQueue",
@@ -153,12 +154,9 @@ describe("MatrixClient", function() {
        });
        // FIXME: We shouldn't be yanking _http like this.
        client._http = [
-            "authedRequest", "authedRequestWithPrefix", "getContentUri",
-            "request", "requestWithPrefix", "uploadContent",
+            "authedRequest", "getContentUri", "request", "uploadContent",
        ].reduce((r, k) => { r[k] = expect.createSpy(); return r; }, {});
        client._http.authedRequest.andCall(httpReq);
-        client._http.authedRequestWithPrefix.andCall(httpReq);
-        client._http.requestWithPrefix.andCall(httpReq);
        client._http.request.andCall(httpReq);

        // set reasonable working defaults
@@ -180,9 +178,6 @@ describe("MatrixClient", function() {
        client._http.authedRequest.andCall(function() {
            return Promise.defer().promise;
        });
-        client._http.authedRequestWithPrefix.andCall(function() {
-            return Promise.defer().promise;
-        });
    });

    it("should not POST /filter if a matching filter already exists", async function() {
@@ -353,7 +348,7 @@ describe("MatrixClient", function() {
        function syncChecker(expectedStates, done) {
            return function syncListener(state, old) {
                const expected = expectedStates.shift();
-                console.log(
+                logger.log(
                    "'sync' curr=%s old=%s EXPECT=%s", state, old, expected,
                );
                if (!expected) {
@@ -15,7 +15,7 @@ describe("realtime-callbacks", function() {
    }

    beforeEach(function() {
-        testUtils.beforeEach(this); // eslint-disable-line no-invalid-this
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        clock = lolex.install();
        const fakeDate = clock.Date;
        callbacks.setNow(fakeDate.now.bind(fakeDate));
@@ -56,8 +56,8 @@ describe("realtime-callbacks", function() {
        it("should set 'this' to the global object", function() {
            let passed = false;
            const callback = function() {
-                expect(this).toBe(global); // eslint-disable-line no-invalid-this
-                expect(this.console).toBeTruthy(); // eslint-disable-line no-invalid-this
+                expect(this).toBe(global); // eslint-disable-line babel/no-invalid-this
+                expect(this.console).toBeTruthy(); // eslint-disable-line babel/no-invalid-this
                passed = true;
            };
            callbacks.setTimeout(callback);
@@ -14,7 +14,7 @@ describe("RoomMember", function() {
    let member;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        member = new RoomMember(roomId, userA);
    });

@@ -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);
+        });
    });
 });
@@ -17,7 +17,7 @@ describe("RoomState", function() {
    let state;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        state = new RoomState(roomId);
        state.setStateEvents([
            utils.mkMembership({  // userA joined
@@ -19,7 +19,7 @@ describe("Room", function() {
    let room;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        room = new Room(roomId);
        // mock RoomStates
        room.oldState = room.getLiveTimeline()._startState =
@@ -104,7 +104,7 @@ describe("Room", function() {
                    user_ids: [userA],
                },
            });
-            room.addLiveEvents([typing]);
+            room.addEphemeralEvents([typing]);
            expect(room.currentState.setTypingEvent).toHaveBeenCalledWith(typing);
        });

@@ -1318,6 +1318,9 @@ describe("Room", function() {
                    // events should already be MatrixEvents
                    return function(event) {return event;};
                },
+                isCryptoEnabled() {
+                    return true;
+                },
                isRoomEncrypted: function() {
                    return false;
                },
@@ -26,7 +26,7 @@ describe("MatrixScheduler", function() {
    });

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        clock = lolex.install();
        scheduler = new MatrixScheduler(function(ev, attempts, err) {
            if (retryFn) {
@@ -48,7 +48,7 @@ describe("MatrixScheduler", function() {
        clock.uninstall();
    });

-    it("should process events in a queue in a FIFO manner", function(done) {
+    it("should process events in a queue in a FIFO manner", async function() {
        retryFn = function() {
            return 0;
        };
@@ -57,28 +57,30 @@ describe("MatrixScheduler", function() {
        };
        const deferA = Promise.defer();
        const deferB = Promise.defer();
-        let resolvedA = false;
+        let yieldedA = false;
        scheduler.setProcessFunction(function(event) {
-            if (resolvedA) {
+            if (yieldedA) {
                expect(event).toEqual(eventB);
                return deferB.promise;
            } else {
+                yieldedA = true;
                expect(event).toEqual(eventA);
                return deferA.promise;
            }
        });
-        scheduler.queueEvent(eventA);
-        scheduler.queueEvent(eventB).done(function() {
-            expect(resolvedA).toBe(true);
-            done();
-        });
-        deferA.resolve({});
-        resolvedA = true;
-        deferB.resolve({});
+        const abPromise = Promise.all([
+            scheduler.queueEvent(eventA),
+            scheduler.queueEvent(eventB),
+        ]);
+        deferB.resolve({b: true});
+        deferA.resolve({a: true});
+        const [a, b] = await abPromise;
+        expect(a.a).toEqual(true);
+        expect(b.b).toEqual(true);
    });

    it("should invoke the retryFn on failure and wait the amount of time specified",
-    function(done) {
+    async function() {
        const waitTimeMs = 1500;
        const retryDefer = Promise.defer();
        retryFn = function() {
@@ -97,24 +99,26 @@ describe("MatrixScheduler", function() {
                return defer.promise;
            } else if (procCount === 2) {
                // don't care about this defer
-                return Promise.defer().promise;
+                return new Promise();
            }
            expect(procCount).toBeLessThan(3);
        });

        scheduler.queueEvent(eventA);
+        // as queueing doesn't start processing synchronously anymore (see commit bbdb5ac)
+        // wait just long enough before it does
+        await Promise.resolve();
        expect(procCount).toEqual(1);
        defer.reject({});
-        retryDefer.promise.done(function() {
-            expect(procCount).toEqual(1);
-            clock.tick(waitTimeMs);
-            expect(procCount).toEqual(2);
-            done();
-        });
+        await retryDefer.promise;
+        expect(procCount).toEqual(1);
+        clock.tick(waitTimeMs);
+        await Promise.resolve();
+        expect(procCount).toEqual(2);
    });

    it("should give up if the retryFn on failure returns -1 and try the next event",
-    function(done) {
+    async function() {
        // Queue A & B.
        // Reject A and return -1 on retry.
        // Expect B to be tried next and the promise for A to be rejected.
@@ -122,8 +126,8 @@ describe("MatrixScheduler", function() {
            return -1;
        };
        queueFn = function() {
- return "yep";
-};
+            return "yep";
+        };

        const deferA = Promise.defer();
        const deferB = Promise.defer();
@@ -142,13 +146,17 @@ describe("MatrixScheduler", function() {

        const globalA = scheduler.queueEvent(eventA);
        scheduler.queueEvent(eventB);
-
+        // as queueing doesn't start processing synchronously anymore (see commit bbdb5ac)
+        // wait just long enough before it does
+        await Promise.resolve();
        expect(procCount).toEqual(1);
        deferA.reject({});
-        globalA.catch(function() {
+        try {
+            await globalA;
+        } catch(err) {
+            await Promise.resolve();
            expect(procCount).toEqual(2);
-            done();
-        });
+        }
    });

    it("should treat each queue separately", function(done) {
@@ -300,7 +308,11 @@ describe("MatrixScheduler", function() {
                expect(ev).toEqual(eventA);
                return defer.promise;
            });
-            expect(procCount).toEqual(1);
+            // as queueing doesn't start processing synchronously anymore (see commit bbdb5ac)
+            // wait just long enough before it does
+            Promise.resolve().then(() => {
+                expect(procCount).toEqual(1);
+            });
        });

        it("should not call the processFn if there are no queued events", function() {
@@ -26,7 +26,7 @@ describe("SyncAccumulator", function() {
    let sa;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        sa = new SyncAccumulator({
            maxTimelineEntries: 10,
        });
@@ -68,7 +68,7 @@ function createLinkedTimelines() {

 describe("TimelineIndex", function() {
    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
    });

    describe("minIndex", function() {
@@ -164,7 +164,7 @@ describe("TimelineWindow", function() {
    }

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
    });

    describe("load", function() {
@@ -11,7 +11,7 @@ describe("User", function() {
    let user;

    beforeEach(function() {
-        utils.beforeEach(this); // eslint-disable-line no-invalid-this
+        utils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
        user = new User(userId);
    });

@@ -7,7 +7,7 @@ import expect from 'expect';

 describe("utils", function() {
    beforeEach(function() {
-        testUtils.beforeEach(this); // eslint-disable-line no-invalid-this
+        testUtils.beforeEach(this); // eslint-disable-line babel/no-invalid-this
    });

    describe("encodeParams", function() {
@@ -34,12 +34,18 @@ export default class Reemitter {
    }

    reEmit(source, eventNames) {
+        // We include the source as the last argument for event handlers which may need it,
+        // such as read receipt listeners on the client class which won't have the context
+        // of the room.
+        const forSource = (handler, ...args) => {
+            handler(...args, source);
+        };
        for (const eventName of eventNames) {
            if (this.boundHandlers[eventName] === undefined) {
                this.boundHandlers[eventName] = this._handleEvent.bind(this, eventName);
            }
-            const boundHandler = this.boundHandlers[eventName];

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

        if (width) {
-            params.width = width;
+            params.width = Math.round(width);
        }
        if (height) {
-            params.height = height;
+            params.height = Math.round(height);
        }
        if (resizeMethod) {
            params.method = resizeMethod;
@@ -62,7 +62,7 @@ module.exports = {
        if (utils.keys(params).length > 0) {
            // these are thumbnailing params so they probably want the
            // thumbnailing API...
-            prefix = "/_matrix/media/v1/thumbnail/";
+            prefix = "/_matrix/media/r0/thumbnail/";
        }

        const fragmentOffset = serverAndMediaId.indexOf("#");
@@ -83,6 +83,7 @@ module.exports = {
     * @param {Number} width The desired width of the image in pixels. Default: 96.
     * @param {Number} height The desired height of the image in pixels. Default: 96.
     * @return {string} The complete URL to the identicon.
+     * @deprecated This is no longer in the specification.
     */
    getIdenticonUri: function(baseUrl, identiconString, width, height) {
        if (!identiconString) {
@@ -99,7 +100,7 @@ module.exports = {
            height: height,
        };

-        const path = utils.encodeUri("/_matrix/media/v1/identicon/$ident", {
+        const path = utils.encodeUri("/_matrix/media/unstable/identicon/$ident", {
            $ident: identiconString,
        });
        return baseUrl + path +
@@ -0,0 +1,487 @@
+/*
+Copyright 2019 New Vector Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * Cross signing methods
+ * @module crypto/CrossSigning
+ */
+
+import {pkSign, pkVerify} from './olmlib';
+import {EventEmitter} from 'events';
+import logger from '../logger';
+
+function publicKeyFromKeyInfo(keyInfo) {
+    return Object.entries(keyInfo.keys)[0];
+}
+
+export class CrossSigningInfo extends EventEmitter {
+    /**
+     * Information about a user's cross-signing keys
+     *
+     * @class
+     *
+     * @param {string} userId the user that the information is about
+     * @param {object} callbacks Callbacks used to interact with the app
+     *     Requires getCrossSigningKey and saveCrossSigningKeys
+     */
+    constructor(userId, callbacks) {
+        super();
+
+        // you can't change the userId
+        Object.defineProperty(this, 'userId', {
+            enumerable: true,
+            value: userId,
+        });
+        this._callbacks = callbacks || {};
+        this.keys = {};
+        this.firstUse = true;
+    }
+
+    /**
+     * Calls the app callback to ask for a private key
+     * @param {string} type The key type ("master", "self_signing", or "user_signing")
+     * @param {Uint8Array} expectedPubkey The matching public key or undefined to use
+     *     the stored public key for the given key type.
+     */
+    async getCrossSigningKey(type, expectedPubkey) {
+        if (!this._callbacks.getCrossSigningKey) {
+            throw new Error("No getCrossSigningKey callback supplied");
+        }
+
+        if (expectedPubkey === undefined) {
+            expectedPubkey = this.getId(type);
+        }
+
+        const privkey = await this._callbacks.getCrossSigningKey(type, expectedPubkey);
+        if (!privkey) {
+            throw new Error(
+                "getCrossSigningKey callback for  " + type + " returned falsey",
+            );
+        }
+        const signing = new global.Olm.PkSigning();
+        const gotPubkey = signing.init_with_seed(privkey);
+        if (gotPubkey !== expectedPubkey) {
+            signing.free();
+            throw new Error(
+                "Key type " + type + " from getCrossSigningKey callback did not match",
+            );
+        } else {
+            return [gotPubkey, signing];
+        }
+    }
+
+    static fromStorage(obj, userId) {
+        const res = new CrossSigningInfo(userId);
+        for (const prop in obj) {
+            if (obj.hasOwnProperty(prop)) {
+                res[prop] = obj[prop];
+            }
+        }
+        return res;
+    }
+
+    toStorage() {
+        return {
+            keys: this.keys,
+            firstUse: this.firstUse,
+        };
+    }
+
+    hasKeys() {
+        return Object.keys(this.keys).length > 0;
+    }
+
+    /**
+     * Get the ID used to identify the user
+     *
+     * @param {string} type The type of key to get the ID of.  One of "master",
+     * "self_signing", or "user_signing".  Defaults to "master".
+     *
+     * @return {string} the ID
+     */
+    getId(type) {
+        type = type || "master";
+        if (!this.keys[type]) return null;
+        const keyInfo = this.keys[type];
+        return publicKeyFromKeyInfo(keyInfo)[1];
+    }
+
+
+    async resetKeys(level) {
+        if (!this._callbacks.saveCrossSigningKeys) {
+            throw new Error("No saveCrossSigningKeys callback supplied");
+        }
+
+        // If we're resetting the master key, we reset all keys
+        if (
+            level === undefined ||
+            level & CrossSigningLevel.MASTER ||
+            !this.keys.master
+        ) {
+            level = (
+                CrossSigningLevel.MASTER |
+                CrossSigningLevel.USER_SIGNING |
+                CrossSigningLevel.SELF_SIGNING
+            );
+        } else if (level === 0) {
+            return;
+        }
+
+        const privateKeys = {};
+        const keys = {};
+        let masterSigning;
+        let masterPub;
+
+        try {
+            if (level & CrossSigningLevel.MASTER) {
+                masterSigning = new global.Olm.PkSigning();
+                privateKeys.master = masterSigning.generate_seed();
+                masterPub = masterSigning.init_with_seed(privateKeys.master);
+                keys.master = {
+                    user_id: this.userId,
+                    usage: ['master'],
+                    keys: {
+                        ['ed25519:' + masterPub]: masterPub,
+                    },
+                };
+            } else {
+                [masterPub, masterSigning] = await this.getCrossSigningyKey("master");
+            }
+
+            if (level & CrossSigningLevel.SELF_SIGNING) {
+                const sskSigning = new global.Olm.PkSigning();
+                try {
+                    privateKeys.self_signing = sskSigning.generate_seed();
+                    const sskPub = sskSigning.init_with_seed(privateKeys.self_signing);
+                    keys.self_signing = {
+                        user_id: this.userId,
+                        usage: ['self_signing'],
+                        keys: {
+                            ['ed25519:' + sskPub]: sskPub,
+                        },
+                    };
+                    pkSign(keys.self_signing, masterSigning, this.userId, masterPub);
+                } finally {
+                    sskSigning.free();
+                }
+            }
+
+            if (level & CrossSigningLevel.USER_SIGNING) {
+                const uskSigning = new global.Olm.PkSigning();
+                try {
+                    privateKeys.user_signing = uskSigning.generate_seed();
+                    const uskPub = uskSigning.init_with_seed(privateKeys.user_signing);
+                    keys.user_signing = {
+                        user_id: this.userId,
+                        usage: ['user_signing'],
+                        keys: {
+                            ['ed25519:' + uskPub]: uskPub,
+                        },
+                    };
+                    pkSign(keys.user_signing, masterSigning, this.userId, masterPub);
+                } finally {
+                    uskSigning.free();
+                }
+            }
+
+            Object.assign(this.keys, keys);
+            this._callbacks.saveCrossSigningKeys(privateKeys);
+        } finally {
+            if (masterSigning) {
+                masterSigning.free();
+            }
+        }
+    }
+
+    setKeys(keys) {
+        const signingKeys = {};
+        if (keys.master) {
+            if (keys.master.user_id !== this.userId) {
+                const error = "Mismatched user ID " + keys.master.user_id +
+                      " in master key from " + this.userId;
+                logger.error(error);
+                throw new Error(error);
+            }
+            if (!this.keys.master) {
+                // this is the first key we've seen, so first-use is true
+                this.firstUse = true;
+            } else if (publicKeyFromKeyInfo(keys.master)[1] !== this.getId()) {
+                // this is a different key, so first-use is false
+                this.firstUse = false;
+            } // otherwise, same key, so no change
+            signingKeys.master = keys.master;
+        } else if (this.keys.master) {
+            signingKeys.master = this.keys.master;
+        } else {
+            throw new Error("Tried to set cross-signing keys without a master key");
+        }
+        const masterKey = publicKeyFromKeyInfo(signingKeys.master)[1];
+
+        // verify signatures
+        if (keys.user_signing) {
+            if (keys.user_signing.user_id !== this.userId) {
+                const error = "Mismatched user ID " + keys.master.user_id +
+                      " in user_signing key from " + this.userId;
+                logger.error(error);
+                throw new Error(error);
+            }
+            try {
+                pkVerify(keys.user_signing, masterKey, this.userId);
+            } catch (e) {
+                logger.error("invalid signature on user-signing key");
+                // FIXME: what do we want to do here?
+                throw e;
+            }
+        }
+        if (keys.self_signing) {
+            if (keys.self_signing.user_id !== this.userId) {
+                const error = "Mismatched user ID " + keys.master.user_id +
+                      " in self_signing key from " + this.userId;
+                logger.error(error);
+                throw new Error(error);
+            }
+            try {
+                pkVerify(keys.self_signing, masterKey, this.userId);
+            } catch (e) {
+                logger.error("invalid signature on self-signing key");
+                // FIXME: what do we want to do here?
+                throw e;
+            }
+        }
+
+        // if everything checks out, then save the keys
+        if (keys.master) {
+            this.keys.master = keys.master;
+            // if the master key is set, then the old self-signing and
+            // user-signing keys are obsolete
+            delete this.keys.self_signing;
+            delete this.keys.user_signing;
+        }
+        if (keys.self_signing) {
+            this.keys.self_signing = keys.self_signing;
+        }
+        if (keys.user_signing) {
+            this.keys.user_signing = keys.user_signing;
+        }
+    }
+
+    async signObject(data, type) {
+        if (!this.keys[type]) {
+            throw new Error(
+                "Attempted to sign with " + type + " key but no such key present",
+            );
+        }
+        const [pubkey, signing] = await this.getCrossSigningKey(type);
+        try {
+            pkSign(data, signing, this.userId, pubkey);
+            return data;
+        } finally {
+            signing.free();
+        }
+    }
+
+    async signUser(key) {
+        if (!this.keys.user_signing) {
+            return;
+        }
+        return this.signObject(key.keys.master, "user_signing");
+    }
+
+    async signDevice(userId, device) {
+        if (userId !== this.userId) {
+            throw new Error(
+                `Trying to sign ${userId}'s device; can only sign our own device`,
+            );
+        }
+        if (!this.keys.self_signing) {
+            return;
+        }
+        return this.signObject(
+            {
+                algorithms: device.algorithms,
+                keys: device.keys,
+                device_id: device.deviceId,
+                user_id: userId,
+            }, "self_signing",
+        );
+    }
+
+    /**
+     * Check whether a given user is trusted.
+     *
+     * @param {CrossSigningInfo} userCrossSigning Cross signing info for user
+     *
+     * @returns {UserTrustLevel}
+     */
+    checkUserTrust(userCrossSigning) {
+        // if we're checking our own key, then it's trusted if the master key
+        // and self-signing key match
+        if (this.userId === userCrossSigning.userId
+            && this.getId() && this.getId() === userCrossSigning.getId()
+            && this.getId("self_signing")
+            && this.getId("self_signing") === userCrossSigning.getId("self_signing")
+        ) {
+            return new UserTrustLevel(true, this.firstUse);
+        }
+
+        if (!this.keys.user_signing) {
+            // If there's no user signing key, they can't possibly be verified.
+            // They may be TOFU trusted though.
+            return new UserTrustLevel(false, userCrossSigning.firstUse);
+        }
+
+        let userTrusted;
+        const userMaster = userCrossSigning.keys.master;
+        const uskId = this.getId('user_signing');
+        try {
+            pkVerify(userMaster, uskId, this.userId);
+            userTrusted = true;
+        } catch (e) {
+            userTrusted = false;
+        }
+        return new UserTrustLevel(userTrusted, userCrossSigning.firstUse);
+    }
+
+    /**
+     * Check whether a given device is trusted.
+     *
+     * @param {CrossSigningInfo} userCrossSigning Cross signing info for user
+     * @param {module:crypto/deviceinfo} device The device to check
+     * @param {bool} localTrust Whether the device is trusted locally
+     *
+     * @returns {DeviceTrustLevel}
+     */
+    checkDeviceTrust(userCrossSigning, device, localTrust) {
+        const userTrust = this.checkUserTrust(userCrossSigning);
+
+        const userSSK = userCrossSigning.keys.self_signing;
+        if (!userSSK) {
+            // if the user has no self-signing key then we cannot make any
+            // trust assertions about this device from cross-signing
+            return new DeviceTrustLevel(false, false, localTrust);
+        }
+
+        const deviceObj = deviceToObject(device, userCrossSigning.userId);
+        try {
+            // if we can verify the user's SSK from their master key...
+            pkVerify(userSSK, userCrossSigning.getId(), userCrossSigning.userId);
+            // ...and this device's key from their SSK...
+            pkVerify(
+                deviceObj, publicKeyFromKeyInfo(userSSK)[1], userCrossSigning.userId,
+            );
+            // ...then we trust this device as much as far as we trust the user
+            return DeviceTrustLevel.fromUserTrustLevel(userTrust, localTrust);
+        } catch (e) {
+            return new DeviceTrustLevel(false, false, localTrust);
+        }
+    }
+}
+
+function deviceToObject(device, userId) {
+    return {
+        algorithms: device.algorithms,
+        keys: device.keys,
+        device_id: device.deviceId,
+        user_id: userId,
+        signatures: device.signatures,
+    };
+}
+
+export const CrossSigningLevel = {
+    MASTER: 4,
+    USER_SIGNING: 2,
+    SELF_SIGNING: 1,
+};
+
+/**
+ * Represents the ways in which we trust a user
+ */
+export class UserTrustLevel {
+    constructor(crossSigningVerified, tofu) {
+        this._crossSigningVerified = crossSigningVerified;
+        this._tofu = tofu;
+    }
+
+    /**
+     * @returns {bool} true if this user is verified via any means
+     */
+    isVerified() {
+        return this.isCrossSigningVerified();
+    }
+
+    /**
+     * @returns {bool} true if this user is verified via cross signing
+     */
+    isCrossSigningVerified() {
+        return this._crossSigningVerified;
+    }
+
+    /**
+     * @returns {bool} true if this user's key is trusted on first use
+     */
+    isTofu() {
+        return this._tofu;
+    }
+}
+
+/**
+ * Represents the ways in which we trust a device
+ */
+export class DeviceTrustLevel {
+    constructor(crossSigningVerified, tofu, localVerified) {
+        this._crossSigningVerified = crossSigningVerified;
+        this._tofu = tofu;
+        this._localVerified = localVerified;
+    }
+
+    static fromUserTrustLevel(userTrustLevel, localVerified) {
+        return new DeviceTrustLevel(
+            userTrustLevel._crossSigningVerified,
+            userTrustLevel._tofu,
+            localVerified,
+        );
+    }
+
+    /**
+     * @returns {bool} true if this device is verified via any means
+     */
+    isVerified() {
+        return this.isCrossSigningVerified() || this.isLocallyVerified();
+    }
+
+    /**
+     * @returns {bool} true if this device is verified via cross signing
+     */
+    isCrossSigningVerified() {
+        return this._crossSigningVerified;
+    }
+
+    /**
+     * @returns {bool} true if this device is verified locally
+     */
+    isLocallyVerified() {
+        return this._localVerified;
+    }
+
+    /**
+     * @returns {bool} true if this device is trusted from a user's key
+     * that is trusted on first use
+     */
+    isTofu() {
+        return this._tofu;
+    }
+}
@@ -1,6 +1,7 @@
 /*
 Copyright 2017 Vector Creations Ltd
-Copyright 2018 New Vector Ltd
+Copyright 2018, 2019 New Vector Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -23,8 +24,11 @@ limitations under the License.
 */

 import Promise from 'bluebird';
+import {EventEmitter} from 'events';

+import logger from '../logger';
 import DeviceInfo from './deviceinfo';
+import {CrossSigningInfo} from './CrossSigning';
 import olmlib from './olmlib';
 import IndexedDBCryptoStore from './store/indexeddb-crypto-store';

@@ -59,10 +63,11 @@ const TRACKING_STATUS_UP_TO_DATE = 3;
 /**
 * @alias module:crypto/DeviceList
 */
-export default class DeviceList {
-    constructor(baseApis, cryptoStore, sessionStore, olmDevice) {
+export default class DeviceList extends EventEmitter {
+    constructor(baseApis, cryptoStore, olmDevice) {
+        super();
+
        this._cryptoStore = cryptoStore;
-        this._sessionStore = sessionStore;

        // userId -> {
        //     deviceId -> {
@@ -71,6 +76,14 @@ export default class DeviceList {
        // }
        this._devices = {};

+        // userId -> {
+        //     [key info]
+        // }
+        this._crossSigningInfo = {};
+
+        // 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()
@@ -104,39 +117,28 @@ export default class DeviceList {
     * Load the device tracking state from storage
     */
    async load() {
-        let shouldDeleteSessionStore = false;
        await this._cryptoStore.doTxn(
-            // migrate from session store if there's data there and not here
-            'readwrite', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
+            'readonly', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
                this._cryptoStore.getEndToEndDeviceData(txn, (deviceData) => {
-                    if (deviceData === null) {
-                        console.log("Migrating e2e device data...");
-                        this._devices = this._sessionStore.getAllEndToEndDevices() || {};
-                        this._deviceTrackingStatus = (
-                            this._sessionStore.getEndToEndDeviceTrackingStatus() || {}
-                        );
-                        this._syncToken = this._sessionStore.getEndToEndDeviceSyncToken();
-                        this._cryptoStore.storeEndToEndDeviceData({
-                            devices: this._devices,
-                            trackingStatus: this._deviceTrackingStatus,
-                            syncToken: this._syncToken,
-                        }, txn);
-                        shouldDeleteSessionStore = true;
-                    } else {
-                        this._devices = deviceData ? deviceData.devices : {},
-                        this._deviceTrackingStatus = deviceData ?
-                            deviceData.trackingStatus : {};
-                        this._syncToken = deviceData ? deviceData.syncToken : null;
+                    this._devices = deviceData ? deviceData.devices : {},
+                    this._ssks = deviceData ? deviceData.self_signing_keys || {} : {};
+                    this._deviceTrackingStatus = deviceData ?
+                        deviceData.trackingStatus : {};
+                    this._syncToken = deviceData ? deviceData.syncToken : null;
+                    this._userByIdentityKey = {};
+                    for (const user of Object.keys(this._devices)) {
+                        const userDevices = this._devices[user];
+                        for (const device of Object.keys(userDevices)) {
+                            const idKey = userDevices[device].keys['curve25519:'+device];
+                            if (idKey !== undefined) {
+                                this._userByIdentityKey[idKey] = user;
+                            }
+                        }
                    }
                });
            },
        );

-        if (shouldDeleteSessionStore) {
-            // migrated data is now safely persisted: remove from old store
-            this._sessionStore.removeEndToEndDeviceData();
-        }
-
        for (const u of Object.keys(this._deviceTrackingStatus)) {
            // if a download was in progress when we got shut down, it isn't any more.
            if (this._deviceTrackingStatus[u] == TRACKING_STATUS_DOWNLOAD_IN_PROGRESS) {
@@ -145,6 +147,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 +198,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.
@@ -204,6 +212,7 @@ export default class DeviceList {
                    'readwrite', [IndexedDBCryptoStore.STORE_DEVICE_DATA], (txn) => {
                        this._cryptoStore.storeEndToEndDeviceData({
                            devices: this._devices,
+                            self_signing_keys: this._ssks,
                            trackingStatus: this._deviceTrackingStatus,
                            syncToken: this._syncToken,
                        }, txn);
@@ -258,7 +267,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 +278,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(() => {
@@ -337,6 +346,17 @@ export default class DeviceList {
        return this._devices[userId];
    }

+    getStoredCrossSigningForUser(userId) {
+        if (!this._crossSigningInfo[userId]) return null;
+
+        return CrossSigningInfo.fromStorage(this._crossSigningInfo[userId], userId);
+    }
+
+    storeCrossSigningForUser(userId, info) {
+        this._crossSigningInfo[userId] = info;
+        this._dirty = true;
+    }
+
    /**
     * Get the stored keys for a single device
     *
@@ -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,27 @@ 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;
+        }
+    }
+
+    setRawStoredCrossSigningForUser(userId, info) {
+        this._crossSigningInfo[userId] = info;
    }

    /**
@@ -550,7 +610,7 @@ export default class DeviceList {
        ).then(() => {
            finished(true);
        }, (e) => {
-            console.error(
+            logger.error(
                'Error downloading keys for ' + users + ":", e,
            );
            finished(false);
@@ -573,7 +633,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,13 +644,14 @@ 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;
                    }
                }
            });
            this.saveIfDirty();
+            this.emit("crypto.devicesUpdated", users);
        };

        return prom;
@@ -659,7 +720,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 +740,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 = {};
@@ -691,6 +752,9 @@ class DeviceListUpdateSerialiser {
            downloadUsers, opts,
        ).then((res) => {
            const dk = res.device_keys || {};
+            const masterKeys = res.master_keys || {};
+            const ssks = res.self_signing_keys || {};
+            const usks = res.user_signing_keys || {};

            // do each user in a separate promise, to avoid wedging the CPU
            // (https://github.com/vector-im/riot-web/issues/3158)
@@ -700,13 +764,19 @@ class DeviceListUpdateSerialiser {
            let prom = Promise.resolve();
            for (const userId of downloadUsers) {
                prom = prom.delay(5).then(() => {
-                    return this._processQueryResponseForUser(userId, dk[userId]);
+                    return this._processQueryResponseForUser(
+                        userId, dk[userId], {
+                            master: masterKeys[userId],
+                            self_signing: ssks[userId],
+                            user_signing: usks[userId],
+                        },
+                    );
                });
            }

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

            this._downloadInProgress = false;
            deferred.resolve();
@@ -716,7 +786,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);
        });
@@ -724,30 +794,58 @@ class DeviceListUpdateSerialiser {
        return deferred.promise;
    }

-    async _processQueryResponseForUser(userId, response) {
-        console.log('got keys for ' + userId + ':', response);
+    async _processQueryResponseForUser(
+        userId, dkResponse, crossSigningResponse, sskResponse,
+    ) {
+        logger.log('got device keys for ' + userId + ':', dkResponse);
+        logger.log('got cross-signing keys for ' + userId + ':', crossSigningResponse);

-        // map from deviceid -> deviceinfo for this user
-        const userStore = {};
-        const devs = this._deviceList.getRawStoredDevicesForUser(userId);
-        if (devs) {
-            Object.keys(devs).forEach((deviceId) => {
-                const d = DeviceInfo.fromStorage(devs[deviceId], deviceId);
-                userStore[deviceId] = d;
+        {
+            // map from deviceid -> deviceinfo for this user
+            const userStore = {};
+            const devs = this._deviceList.getRawStoredDevicesForUser(userId);
+            if (devs) {
+                Object.keys(devs).forEach((deviceId) => {
+                    const d = DeviceInfo.fromStorage(devs[deviceId], deviceId);
+                    userStore[deviceId] = d;
+                });
+            }
+
+            await _updateStoredDeviceKeysForUser(
+                this._olmDevice, userId, userStore, dkResponse || {},
+            );
+
+            // put the updates into the object that will be returned as our results
+            const storage = {};
+            Object.keys(userStore).forEach((deviceId) => {
+                storage[deviceId] = userStore[deviceId].toStorage();
            });
+
+            this._deviceList._setRawStoredDevicesForUser(userId, storage);
        }

-        await _updateStoredDeviceKeysForUser(
-            this._olmDevice, userId, userStore, response || {},
-        );
+        // now do the same for the cross-signing keys
+        {
+            // FIXME: should we be ignoring empty cross-signing responses, or
+            // should we be dropping the keys?
+            if (crossSigningResponse
+                && (crossSigningResponse.master || crossSigningResponse.self_signing
+                    || crossSigningResponse.user_signing)) {
+                const crossSigning
+                      = this._deviceList.getStoredCrossSigningForUser(userId)
+                      || new CrossSigningInfo(userId);

-        // put the updates into thr object that will be returned as our results
-        const storage = {};
-        Object.keys(userStore).forEach((deviceId) => {
-            storage[deviceId] = userStore[deviceId].toStorage();
-        });
+                crossSigning.setKeys(crossSigningResponse);

-        this._deviceList._setRawStoredDevicesForUser(userId, storage);
+                this._deviceList.setRawStoredCrossSigningForUser(
+                    userId, crossSigning.toStorage(),
+                );
+
+                // NB. Unlike most events in the js-sdk, this one is internal to the
+                // js-sdk and is not re-emitted
+                this._deviceList.emit('userCrossSigningUpdated', userId);
+            }
+        }
    }
 }

@@ -763,7 +861,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 +878,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,17 +913,18 @@ 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;
    }

    const unsigned = deviceResult.unsigned || {};
+    const signatures = deviceResult.signatures || {};

    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 +941,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;
        }
@@ -853,5 +952,6 @@ async function _storeDeviceKeys(_olmDevice, userStore, deviceResult) {
    deviceStore.keys = deviceResult.keys || {};
    deviceStore.algorithms = deviceResult.algorithms || [];
    deviceStore.unsigned = unsigned;
+    deviceStore.signatures = signatures;
    return true;
 }
@@ -1,6 +1,6 @@
 /*
 Copyright 2016 OpenMarket Ltd
-Copyright 2017 New Vector Ltd
+Copyright 2017, 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.
@@ -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;
@@ -69,20 +59,17 @@ function checkPayloadLength(payloadString) {
 * Manages the olm cryptography functions. Each OlmDevice has a single
 * OlmAccount and a number of OlmSessions.
 *
- * Accounts and sessions are kept pickled in a sessionStore.
+ * Accounts and sessions are kept pickled in the cryptoStore.
 *
 * @constructor
 * @alias module:crypto/OlmDevice
 *
- * @param {Object} sessionStore A store to be used for data in end-to-end
- *    crypto. This is deprecated and being replaced by cryptoStore.
 * @param {Object} cryptoStore A store for crypto data
 *
 * @property {string} deviceCurve25519Key   Curve25519 key for the account
 * @property {string} deviceEd25519Key      Ed25519 key for the account
 */
-function OlmDevice(sessionStore, cryptoStore) {
-    this._sessionStore = sessionStore;
+function OlmDevice(cryptoStore) {
    this._cryptoStore = cryptoStore;
    this._pickleKey = "DEFAULT_KEY";

@@ -91,7 +78,7 @@ function OlmDevice(sessionStore, cryptoStore) {
    this.deviceEd25519Key = null;
    this._maxOneTimeKeys = null;

-    // we don't bother stashing outboundgroupsessions in the sessionstore -
+    // we don't bother stashing outboundgroupsessions in the cryptoStore -
    // instead we keep them here.
    this._outboundGroupSessionStore = {};

@@ -112,6 +99,10 @@ function OlmDevice(sessionStore, cryptoStore) {
    // Keys are strings of form "<senderKey>|<session_id>|<message_index>"
    // Values are objects of the form "{id: <event id>, timestamp: <ts>}"
    this._inboundGroupSessionMessageIndexes = {};
+
+    // Keep track of sessions that we're starting, so that we don't start
+    // multiple sessions for the same device at the same time.
+    this._sessionsInProgress = {};
 }

 /**
@@ -124,14 +115,10 @@ function OlmDevice(sessionStore, cryptoStore) {
 * Reads the device keys from the OlmAccount object.
 */
 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,
-        );
+        await _initialiseAccount(this._cryptoStore, this._pickleKey, account);
        e2eKeys = JSON.parse(account.identity_keys());

        this._maxOneTimeKeys = account.max_number_of_one_time_keys();
@@ -143,7 +130,7 @@ OlmDevice.prototype.init = async function() {
    this.deviceEd25519Key = e2eKeys.ed25519;
 };

-async function _initialiseAccount(sessionStore, cryptoStore, pickleKey, account) {
+async function _initialiseAccount(cryptoStore, pickleKey, account) {
    await cryptoStore.doTxn('readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
        cryptoStore.getAccount(txn, (pickledAccount) => {
            if (pickledAccount !== null) {
@@ -161,96 +148,7 @@ async function _initialiseAccount(sessionStore, cryptoStore, pickleKey, account)
 * @return {array} The version of Olm.
 */
 OlmDevice.getOlmVersion = function() {
-    return Olm.get_library_version();
-};
-
-OlmDevice.prototype._migrateFromSessionStore = async function() {
-    // account
-    await this._cryptoStore.doTxn(
-        'readwrite', [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
-            this._cryptoStore.getAccount(txn, (pickledAccount) => {
-                if (pickledAccount === null) {
-                    // Migrate from sessionStore
-                    pickledAccount = this._sessionStore.getEndToEndAccount();
-                    if (pickledAccount !== null) {
-                        console.log("Migrating account from session store");
-                        this._cryptoStore.storeAccount(txn, pickledAccount);
-                    }
-                }
-            });
-        },
-    );
-
-    // remove the old account now the transaction has completed. Either we've
-    // migrated it or decided not to, either way we want to blow away the old data.
-    this._sessionStore.removeEndToEndAccount();
-
-    // sessions
-    const sessions = this._sessionStore.getAllEndToEndSessions();
-    if (Object.keys(sessions).length > 0) {
-        await this._cryptoStore.doTxn(
-            'readwrite', [IndexedDBCryptoStore.STORE_SESSIONS], (txn) => {
-                // Don't migrate sessions from localstorage if we already have sessions
-                // in indexeddb, since this means we've already migrated and an old version
-                // 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");
-                        return;
-                    }
-                    let numSessions = 0;
-                    for (const deviceKey of Object.keys(sessions)) {
-                        for (const sessionId of Object.keys(sessions[deviceKey])) {
-                            numSessions++;
-                            this._cryptoStore.storeEndToEndSession(
-                                deviceKey, sessionId, sessions[deviceKey][sessionId], txn,
-                            );
-                        }
-                    }
-                    console.log(
-                        "Migrating " + numSessions + " sessions from session store",
-                    );
-                });
-            },
-        );
-
-        this._sessionStore.removeAllEndToEndSessions();
-    }
-
-    // inbound group sessions
-    const ibGroupSessions = this._sessionStore.getAllEndToEndInboundGroupSessionKeys();
-    if (Object.keys(ibGroupSessions).length > 0) {
-        let numIbSessions = 0;
-        await this._cryptoStore.doTxn(
-            'readwrite', [IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS], (txn) => {
-                // We always migrate inbound group sessions, even if we already have some
-                // in the new store. They should be be safe to migrate.
-                for (const s of ibGroupSessions) {
-                    try {
-                        this._cryptoStore.addEndToEndInboundGroupSession(
-                            s.senderKey, s.sessionId,
-                            JSON.parse(
-                                this._sessionStore.getEndToEndInboundGroupSession(
-                                    s.senderKey, s.sessionId,
-                                ),
-                            ), txn,
-                        );
-                    } catch (e) {
-                        console.warn(
-                            "Failed to migrate session " + s.senderKey + "/" +
-                            s.sessionId + ": " + e.stack || e,
-                        );
-                    }
-                    ++numIbSessions;
-                }
-                console.log(
-                    "Migrated " + numIbSessions +
-                    " inbound group sessions from session store",
-                );
-            },
-        );
-        this._sessionStore.removeAllEndToEndInboundGroupSessions();
-    }
+    return global.Olm.get_library_version();
 };

 /**
@@ -268,7 +166,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 +203,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 +214,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 +234,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 +257,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 +369,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 +420,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 +430,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,
@@ -545,6 +461,15 @@ OlmDevice.prototype.createInboundSession = async function(
 * @return {Promise<string[]>}  a list of known session ids for the device
 */
 OlmDevice.prototype.getSessionIdsForDevice = async function(theirDeviceIdentityKey) {
+    if (this._sessionsInProgress[theirDeviceIdentityKey]) {
+        logger.log("waiting for olm session to be created");
+        try {
+            await this._sessionsInProgress[theirDeviceIdentityKey];
+        } catch (e) {
+            // if the session failed to be created, just fall through and
+            // return an empty result
+        }
+    }
    let sessionIds;
    await this._cryptoStore.doTxn(
        'readonly', [IndexedDBCryptoStore.STORE_SESSIONS],
@@ -565,16 +490,41 @@ OlmDevice.prototype.getSessionIdsForDevice = async function(theirDeviceIdentityK
 *
 * @param {string} theirDeviceIdentityKey Curve25519 identity key for the
 *     remote device
+ * @param {boolean} nowait Don't wait for an in-progress session to complete.
+ *     This should only be set to true of the calling function is the function
+ *     that marked the session as being in-progress.
 * @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) {
+OlmDevice.prototype.getSessionIdForDevice = async function(
+    theirDeviceIdentityKey, nowait,
+) {
+    const sessionInfos = await this.getSessionInfoForDevice(
+        theirDeviceIdentityKey, nowait,
+    );
+
+    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;
 };

 /**
@@ -586,9 +536,21 @@ OlmDevice.prototype.getSessionIdForDevice = async function(theirDeviceIdentityKe
 * message and is therefore past the pre-key stage), and 'sessionId'.
 *
 * @param {string} deviceIdentityKey Curve25519 identity key for the device
+ * @param {boolean} nowait Don't wait for an in-progress session to complete.
+ *     This should only be set to true of the calling function is the function
+ *     that marked the session as being in-progress.
 * @return {Array.<{sessionId: string, hasReceivedMessage: Boolean}>}
 */
-OlmDevice.prototype.getSessionInfoForDevice = async function(deviceIdentityKey) {
+OlmDevice.prototype.getSessionInfoForDevice = async function(deviceIdentityKey, nowait) {
+    if (this._sessionsInProgress[deviceIdentityKey] && !nowait) {
+        logger.log("waiting for olm session to be created");
+        try {
+            await this._sessionsInProgress[deviceIdentityKey];
+        } catch (e) {
+            // if the session failed to be created, then just fall through and
+            // return an empty result
+        }
+    }
    const info = [];

    await this._cryptoStore.doTxn(
@@ -597,9 +559,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 +593,14 @@ 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) => {
+                const sessionDesc = sessionInfo.session.describe();
+                logger.log(
+                    "encryptMessage: Olm Session ID " + sessionId + " to " +
+                    theirDeviceIdentityKey + ": " + sessionDesc,
+                );
+                res = sessionInfo.session.encrypt(payloadString);
+                this._saveSession(theirDeviceIdentityKey, sessionInfo, txn);
            });
        },
    );
@@ -657,9 +625,15 @@ 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) => {
+                const sessionDesc = sessionInfo.session.describe();
+                logger.log(
+                    "decryptMessage: Olm Session ID " + sessionId + " from " +
+                    theirDeviceIdentityKey + ": " + sessionDesc,
+                );
+                payloadString = sessionInfo.session.decrypt(messageType, ciphertext);
+                sessionInfo.lastReceivedMessageTs = Date.now();
+                this._saveSession(theirDeviceIdentityKey, sessionInfo, txn);
            });
        },
    );
@@ -689,8 +663,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 +698,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 +718,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);
@@ -766,6 +740,8 @@ OlmDevice.prototype.createOutboundGroupSession = function() {
 OlmDevice.prototype.encryptGroupMessage = function(sessionId, payloadString) {
    const self = this;

+    logger.log(`encrypting msg with megolm session ${sessionId}`);
+
    checkPayloadLength(payloadString);

    return this._getOutboundGroupSession(sessionId, function(session) {
@@ -816,7 +792,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 +864,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 +879,22 @@ 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 megolm session ${sessionId}`,
+                                );
+                                return;
+                            }
+                        }
+
                        const sessionData = {
                            room_id: roomId,
                            session: session.pickle(this._pickleKey),
@@ -918,7 +902,7 @@ OlmDevice.prototype.addInboundGroupSession = async function(
                            forwardingCurve25519KeyChain: forwardingCurve25519KeyChain,
                        };

-                        this._cryptoStore.addEndToEndInboundGroupSession(
+                        this._cryptoStore.storeEndToEndInboundGroupSession(
                            senderKey, sessionId, sessionData, txn,
                        );
                    } finally {
@@ -1034,7 +1018,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 +1042,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 +1051,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 +1067,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 +1113,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)} ` +
@@ -1,5 +1,5 @@
 /*
-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.
@@ -26,40 +26,21 @@ import IndexedDBCryptoStore from './store/indexeddb-crypto-store';
 * @alias module:crypto/RoomList
 */
 export default class RoomList {
-    constructor(cryptoStore, sessionStore) {
+    constructor(cryptoStore) {
        this._cryptoStore = cryptoStore;
-        this._sessionStore = sessionStore;

        // Object of roomId -> room e2e info object (body of the m.room.encryption event)
        this._roomEncryption = {};
    }

    async init() {
-        let removeSessionStoreRooms = false;
        await this._cryptoStore.doTxn(
            'readwrite', [IndexedDBCryptoStore.STORE_ROOMS], (txn) => {
                this._cryptoStore.getEndToEndRooms(txn, (result) => {
-                    if (result === null || Object.keys(result).length === 0) {
-                        // migrate from session store, if there's data there
-                        const sessStoreRooms = this._sessionStore.getAllEndToEndRooms();
-                        if (sessStoreRooms !== null) {
-                            for (const roomId of Object.keys(sessStoreRooms)) {
-                                this._cryptoStore.storeEndToEndRoom(
-                                    roomId, sessStoreRooms[roomId], txn,
-                                );
-                            }
-                        }
-                        this._roomEncryption = sessStoreRooms;
-                        removeSessionStoreRooms = true;
-                    } else {
-                        this._roomEncryption = result;
-                    }
+                    this._roomEncryption = result;
                });
            },
        );
-        if (removeSessionStoreRooms) {
-            this._sessionStore.removeAllEndToEndRooms();
-        }
    }

    getRoomEncryption(roomId) {
@@ -0,0 +1,529 @@
+/*
+Copyright 2019 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import {EventEmitter} from 'events';
+import logger from '../logger';
+import olmlib from './olmlib';
+import { randomString } from '../randomstring';
+import { keyFromPassphrase } from './key_passphrase';
+import { encodeRecoveryKey } from './recoverykey';
+import { pkVerify } from './olmlib';
+
+export const SECRET_STORAGE_ALGORITHM_V1 = "m.secret_storage.v1.curve25519-aes-sha2";
+
+/**
+ * Implements Secure Secret Storage and Sharing (MSC1946)
+ * @module crypto/SecretStorage
+ */
+export default class SecretStorage extends EventEmitter {
+    constructor(baseApis, cryptoCallbacks, crossSigningInfo) {
+        super();
+        this._baseApis = baseApis;
+        this._cryptoCallbacks = cryptoCallbacks;
+        this._crossSigningInfo = crossSigningInfo;
+        this._requests = {};
+        this._incomingRequests = {};
+    }
+
+    getDefaultKeyId() {
+        const defaultKeyEvent = this._baseApis.getAccountData(
+            'm.secret_storage.default_key',
+        );
+        if (!defaultKeyEvent) return null;
+        return defaultKeyEvent.getContent().key;
+    }
+
+    setDefaultKeyId(keyId) {
+        return new Promise((resolve) => {
+            const listener = (ev) => {
+                if (
+                    ev.getType() === 'm.secret_storage.default_key' &&
+                    ev.getContent().key === keyId
+                ) {
+                    this._baseApis.removeListener('accountData', listener);
+                    resolve();
+                }
+            };
+            this._baseApis.on('accountData', listener);
+
+            this._baseApis.setAccountData(
+                'm.secret_storage.default_key',
+                { key: keyId },
+            );
+        });
+    }
+
+    /**
+     * Add a key for encrypting secrets.
+     *
+     * @param {string} algorithm the algorithm used by the key.
+     * @param {object} opts the options for the algorithm.  The properties used
+     *     depend on the algorithm given.  This object may be modified to pass
+     *     information back about the key.
+     * @param {string} [keyId] the ID of the key.  If not given, a random
+     *     ID will be generated.
+     *
+     * @return {string} the ID of the key
+     */
+    async addKey(algorithm, opts, keyId) {
+        const keyData = {algorithm};
+
+        if (!opts) opts = {};
+
+        if (opts.name) {
+            keyData.name = opts.name;
+        }
+
+        switch (algorithm) {
+        case SECRET_STORAGE_ALGORITHM_V1:
+        {
+            const decryption = new global.Olm.PkDecryption();
+            try {
+                if (opts.passphrase) {
+                    const key = await keyFromPassphrase(opts.passphrase);
+                    keyData.passphrase = {
+                        algorithm: "m.pbkdf2",
+                        iterations: key.iterations,
+                        salt: key.salt,
+                    };
+                    opts.encodedkey = encodeRecoveryKey(key.key);
+                    keyData.pubkey = decryption.init_with_private_key(key.key);
+                } else if (opts.privkey) {
+                    keyData.pubkey = decryption.init_with_private_key(opts.privkey);
+                    opts.encodedkey = encodeRecoveryKey(opts.privkey);
+                } else {
+                    keyData.pubkey = decryption.generate_key();
+                    opts.encodedkey = encodeRecoveryKey(decryption.get_private_key());
+                }
+            } finally {
+                decryption.free();
+            }
+            break;
+        }
+        default:
+            throw new Error(`Unknown key algorithm ${opts.algorithm}`);
+        }
+
+        if (!keyId) {
+            do {
+                keyId = randomString(32);
+            } while (this._baseApis.getAccountData(`m.secret_storage.key.${keyId}`));
+        }
+
+        await this._crossSigningInfo.signObject(keyData, 'master');
+
+        await this._baseApis.setAccountData(
+            `m.secret_storage.key.${keyId}`, keyData,
+        );
+
+        return keyId;
+    }
+
+    // TODO: need a function to get all the secret keys
+
+    /**
+     * Store an encrypted secret on the server
+     *
+     * @param {string} name The name of the secret
+     * @param {string} secret The secret contents.
+     * @param {Array} keys The IDs of the keys to use to encrypt the secret
+     *     or null/undefined to use the default key.
+     */
+    async store(name, secret, keys) {
+        const encrypted = {};
+
+        if (!keys) {
+            const defaultKeyId = this.getDefaultKeyId();
+            if (!defaultKeyId) {
+                throw new Error("No keys specified and no default key present");
+            }
+            keys = [defaultKeyId];
+        }
+
+        if (keys.length === 0) {
+            throw new Error("Zero keys given to encrypt with!");
+        }
+
+        for (const keyId of keys) {
+            // get key information from key storage
+            const keyInfo = this._baseApis.getAccountData(
+                "m.secret_storage.key." + keyId,
+            );
+            if (!keyInfo) {
+                throw new Error("Unknown key: " + keyId);
+            }
+            const keyInfoContent = keyInfo.getContent();
+
+            // check signature of key info
+            pkVerify(
+                keyInfoContent,
+                this._crossSigningInfo.getId('master'),
+                this._crossSigningInfo.userId,
+            );
+
+            // encrypt secret, based on the algorithm
+            switch (keyInfoContent.algorithm) {
+            case SECRET_STORAGE_ALGORITHM_V1:
+            {
+                const encryption = new global.Olm.PkEncryption();
+                try {
+                    encryption.set_recipient_key(keyInfoContent.pubkey);
+                    encrypted[keyId] = encryption.encrypt(secret);
+                } finally {
+                    encryption.free();
+                }
+                break;
+            }
+            default:
+                logger.warn("unknown algorithm for secret storage key " + keyId
+                            + ": " + keyInfoContent.algorithm);
+                // do nothing if we don't understand the encryption algorithm
+            }
+        }
+
+        // save encrypted secret
+        await this._baseApis.setAccountData(name, {encrypted});
+    }
+
+    /**
+     * Get a secret from storage.
+     *
+     * @param {string} name the name of the secret
+     *
+     * @return {string} the contents of the secret
+     */
+    async get(name) {
+        const secretInfo = this._baseApis.getAccountData(name);
+        if (!secretInfo) {
+            return;
+        }
+
+        const secretContent = secretInfo.getContent();
+
+        if (!secretContent.encrypted) {
+            throw new Error("Content is not encrypted!");
+        }
+
+        // get possible keys to decrypt
+        const keys = {};
+        for (const keyId of Object.keys(secretContent.encrypted)) {
+            // get key information from key storage
+            const keyInfo = this._baseApis.getAccountData(
+                "m.secret_storage.key." + keyId,
+            ).getContent();
+            const encInfo = secretContent.encrypted[keyId];
+            switch (keyInfo.algorithm) {
+            case SECRET_STORAGE_ALGORITHM_V1:
+                if (keyInfo.pubkey && encInfo.ciphertext && encInfo.mac
+                    && encInfo.ephemeral) {
+                    keys[keyId] = keyInfo;
+                }
+                break;
+            default:
+                // do nothing if we don't understand the encryption algorithm
+            }
+        }
+
+        let keyId;
+        let decryption;
+        try {
+            // fetch private key from app
+            [keyId, decryption] = await this._getSecretStorageKey(keys);
+
+            // decrypt secret
+            const encInfo = secretContent.encrypted[keyId];
+            switch (keys[keyId].algorithm) {
+            case SECRET_STORAGE_ALGORITHM_V1:
+                return decryption.decrypt(
+                    encInfo.ephemeral, encInfo.mac, encInfo.ciphertext,
+                );
+            }
+        } finally {
+            if (decryption) decryption.free();
+        }
+    }
+
+    /**
+     * Check if a secret is stored on the server.
+     *
+     * @param {string} name the name of the secret
+     * @param {boolean} checkKey check if the secret is encrypted by a trusted key
+     *
+     * @return {boolean} whether or not the secret is stored
+     */
+    isStored(name, checkKey) {
+        // check if secret exists
+        const secretInfo = this._baseApis.getAccountData(name);
+        if (!secretInfo) {
+            return false;
+        }
+
+        if (checkKey === undefined) checkKey = true;
+
+        const secretContent = secretInfo.getContent();
+
+        if (!secretContent.encrypted) {
+            return false;
+        }
+
+        // check if secret is encrypted by a known/trusted secret and
+        // encryption looks sane
+        for (const keyId of Object.keys(secretContent.encrypted)) {
+            // get key information from key storage
+            const keyInfo = this._baseApis.getAccountData(
+                "m.secret_storage.key." + keyId,
+            ).getContent();
+            const encInfo = secretContent.encrypted[keyId];
+            if (checkKey) {
+                pkVerify(
+                    keyInfo,
+                    this._crossSigningInfo.getId('master'),
+                    this._crossSigningInfo.userId,
+                );
+            }
+            switch (keyInfo.algorithm) {
+            case SECRET_STORAGE_ALGORITHM_V1:
+                if (keyInfo.pubkey && encInfo.ciphertext && encInfo.mac
+                    && encInfo.ephemeral) {
+                    return true;
+                }
+                break;
+            default:
+                // do nothing if we don't understand the encryption algorithm
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Request a secret from another device
+     *
+     * @param {string} name the name of the secret to request
+     * @param {string[]} devices the devices to request the secret from
+     *
+     * @return {string} the contents of the secret
+     */
+    request(name, devices) {
+        const requestId = this._baseApis.makeTxnId();
+
+        const requestControl = this._requests[requestId] = {
+            devices,
+        };
+        const promise = new Promise((resolve, reject) => {
+            requestControl.resolve = resolve;
+            requestControl.reject = reject;
+        });
+        const cancel = (reason) => {
+            // send cancellation event
+            const cancelData = {
+                action: "request_cancellation",
+                requesting_device_id: this._baseApis.deviceId,
+                request_id: requestId,
+            };
+            const toDevice = {};
+            for (const device of devices) {
+                toDevice[device] = cancelData;
+            }
+            this._baseApis.sendToDevice("m.secret.request", {
+                [this._baseApis.getUserId()]: toDevice,
+            });
+
+            // and reject the promise so that anyone waiting on it will be
+            // notified
+            requestControl.reject(new Error(reason || "Cancelled"));
+        };
+
+        // send request to devices
+        const requestData = {
+            name,
+            action: "request",
+            requesting_device_id: this._baseApis.deviceId,
+            request_id: requestId,
+        };
+        const toDevice = {};
+        for (const device of devices) {
+            toDevice[device] = requestData;
+        }
+        this._baseApis.sendToDevice("m.secret.request", {
+            [this._baseApis.getUserId()]: toDevice,
+        });
+
+        return {
+            request_id: requestId,
+            promise,
+            cancel,
+        };
+    }
+
+    async _onRequestReceived(event) {
+        const sender = event.getSender();
+        const content = event.getContent();
+        if (sender !== this._baseApis.getUserId()
+            || !(content.name && content.action
+                 && content.requesting_device_id && content.request_id)) {
+            // ignore requests from anyone else, for now
+            return;
+        }
+        const deviceId = content.requesting_device_id;
+        // check if it's a cancel
+        if (content.action === "request_cancellation") {
+            if (this._incomingRequests[deviceId]
+                && this._incomingRequests[deviceId][content.request_id]) {
+                logger.info("received request cancellation for secret (" + sender
+                            + ", " + deviceId + ", " + content.request_id + ")");
+                this.baseApis.emit("crypto.secrets.requestCancelled", {
+                    user_id: sender,
+                    device_id: deviceId,
+                    request_id: content.request_id,
+                });
+            }
+        } else if (content.action === "request") {
+            if (deviceId === this._baseApis.deviceId) {
+                // no point in trying to send ourself the secret
+                return;
+            }
+
+            // check if we have the secret
+            logger.info("received request for secret (" + sender
+                        + ", " + deviceId + ", " + content.request_id + ")");
+            if (!this._cryptoCallbacks.onSecretRequested) {
+                return;
+            }
+            const secret = await this._cryptoCallbacks.onSecretRequested({
+                user_id: sender,
+                device_id: deviceId,
+                request_id: content.request_id,
+                name: content.name,
+                device_trust: this._baseApis.checkDeviceTrust(sender, deviceId),
+            });
+            if (secret) {
+                const payload = {
+                    type: "m.secret.send",
+                    content: {
+                        request_id: content.request_id,
+                        secret: secret,
+                    },
+                };
+                const encryptedContent = {
+                    algorithm: olmlib.OLM_ALGORITHM,
+                    sender_key: this._baseApis._crypto._olmDevice.deviceCurve25519Key,
+                    ciphertext: {},
+                };
+                await olmlib.ensureOlmSessionsForDevices(
+                    this._baseApis._crypto._olmDevice,
+                    this._baseApis,
+                    {
+                        [sender]: [
+                            await this._baseApis.getStoredDevice(sender, deviceId),
+                        ],
+                    },
+                );
+                await olmlib.encryptMessageForDevice(
+                    encryptedContent.ciphertext,
+                    this._baseApis.getUserId(),
+                    this._baseApis.deviceId,
+                    this._baseApis._crypto._olmDevice,
+                    sender,
+                    this._baseApis._crypto.getStoredDevice(sender, deviceId),
+                    payload,
+                );
+                const contentMap = {
+                    [sender]: {
+                        [deviceId]: encryptedContent,
+                    },
+                };
+
+                this._baseApis.sendToDevice("m.room.encrypted", contentMap);
+            }
+        }
+    }
+
+    _onSecretReceived(event) {
+        if (event.getSender() !== this._baseApis.getUserId()) {
+            // we shouldn't be receiving secrets from anyone else, so ignore
+            // because someone could be trying to send us bogus data
+            return;
+        }
+        const content = event.getContent();
+        logger.log("got secret share for request ", content.request_id);
+        const requestControl = this._requests[content.request_id];
+        if (requestControl) {
+            // make sure that the device that sent it is one of the devices that
+            // we requested from
+            const deviceInfo = this._baseApis._crypto._deviceList.getDeviceByIdentityKey(
+                olmlib.OLM_ALGORITHM,
+                event.getSenderKey(),
+            );
+            if (!deviceInfo) {
+                logger.log(
+                    "secret share from unknown device with key", event.getSenderKey(),
+                );
+                return;
+            }
+            if (!requestControl.devices.includes(deviceInfo.deviceId)) {
+                logger.log("unsolicited secret share from device", deviceInfo.deviceId);
+                return;
+            }
+
+            requestControl.resolve(content.secret);
+        }
+    }
+
+    async _getSecretStorageKey(keys) {
+        if (!this._cryptoCallbacks.getSecretStorageKey) {
+            throw new Error("No getSecretStorageKey callback supplied");
+        }
+
+        const returned = await Promise.resolve(
+            this._cryptoCallbacks.getSecretStorageKey({keys}),
+        );
+
+        if (!returned) {
+            throw new Error("getSecretStorageKey callback returned falsey");
+        }
+        if (returned.length < 2) {
+            throw new Error("getSecretStorageKey callback returned invalid data");
+        }
+
+        const [keyId, privateKey] = returned;
+        if (!keys[keyId]) {
+            throw new Error("App returned unknown key from getSecretStorageKey!");
+        }
+
+        switch (keys[keyId].algorithm) {
+            case SECRET_STORAGE_ALGORITHM_V1:
+            {
+                const decryption = new global.Olm.PkDecryption();
+                let pubkey;
+                try {
+                    pubkey = decryption.init_with_private_key(privateKey);
+                } catch (e) {
+                    decryption.free();
+                    throw new Error("getSecretStorageKey callback returned invalid key");
+                }
+                if (pubkey !== keys[keyId].pubkey) {
+                    decryption.free();
+                    throw new Error(
+                        "getSecretStorageKey callback returned incorrect key",
+                    );
+                }
+                return [keyId, decryption];
+            }
+            default:
+                throw new Error("Unknown key type: " + keys[keyId].algorithm);
+        }
+    }
+}
@@ -23,6 +23,7 @@ limitations under the License.
 */

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

 const utils = require("../../utils");
 const olmlib = require("../olmlib");
@@ -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 megolm session because we shared with " + userId);
            return true;
        }

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

            if (!devicesInRoom[userId].hasOwnProperty(deviceId)) {
-                console.log(
-                    "Starting new session because we shared with " +
+                logger.log(
+                    "Starting new megolm session because we shared with " +
                        userId + ":" + deviceId,
                );
                return true;
@@ -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,11 @@ 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();
+            logger.log(`Started new megolm session ${session.sessionId} ` +
+                       `for room ${self._roomId}`);
+            self._outboundSessions[session.sessionId] = session;
        }

        // now check if we need to share with any devices
@@ -263,6 +272,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.
+            logger.log("Failed to back up megolm session", e);
+        });
+    }
+
    return new OutboundSessionInfo(sessionId);
 };

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

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

@@ -408,8 +429,97 @@ 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(`megolm session ${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(`megolm session ${sessionId} never shared with user ${userId}`);
+        return;
+    }
+    const sentChainIndex = obSessionInfo.sharedWithDevices[userId][device.deviceId];
+    if (sentChainIndex === undefined) {
+        logger.debug(
+            "megolm 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 inbound session key found for megolm ${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 megolm session ${sessionId} ` +
+                 `with ${userId}:${device.deviceId}`);
+};
+
+/**
 * @param {module:crypto/algorithms/megolm.OutboundSessionInfo} session
 *
 * @param {object<string, module:crypto/deviceinfo[]>} devicesByUser
@@ -441,10 +551,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} `
-                + `(slice ${i + 1}/${userDeviceMaps.length})`);
+            logger.log(`Completed megolm keyshare for ${session.sessionId} `
+                + `in ${this._roomId} (slice ${i + 1}/${userDeviceMaps.length})`);
        } catch (e) {
-            console.log(`megolm keyshare in ${this._roomId} `
+            logger.log(`megolm keyshare for ${session.sessionId} in ${this._roomId} `
                + `(slice ${i + 1}/${userDeviceMaps.length}) failed`);

            throw e;
@@ -463,7 +573,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 +759,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 +767,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 +816,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 +882,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 +904,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 +923,44 @@ MegolmDecryption.prototype.onRoomKeyEvent = function(event) {
        keysClaimed = event.getKeysClaimed();
    }

-    console.log(`Adding key for megolm session ${senderKey}|${sessionId}`);
-    this._olmDevice.addInboundGroupSession(
+    logger.log(`Received and 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.
+                logger.log("Failed to back up megolm session", e);
+            });
+        }
    }).catch((e) => {
-        console.error(`Error handling m.room_key_event: ${e}`);
+        logger.error(`Error handling m.room_key_event: ${e}`);
    });
 };

@@ -882,7 +1002,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 +1076,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.
+                logger.log("Failed to back up megolm session", e);
+            });
+        }
        // have another go at decrypting events sent with this session.
        this._retryDecryption(session.sender_key, session.session_id);
    });
@@ -967,19 +1103,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';

+import logger from '../../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,
    );
@@ -56,6 +56,7 @@ function DeviceInfo(deviceId) {
    this.verified = DeviceVerification.UNVERIFIED;
    this.known = false;
    this.unsigned = {};
+    this.signatures = {};
 }

 /**
@@ -88,6 +89,7 @@ DeviceInfo.prototype.toStorage = function() {
        verified: this.verified,
        known: this.known,
        unsigned: this.unsigned,
+        signatures: this.signatures,
    };
 };

@@ -0,0 +1,80 @@
+/*
+Copyright 2018 New Vector Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { randomString } from '../randomstring';
+
+const DEFAULT_ITERATIONS = 500000;
+
+export async function keyFromAuthData(authData, password) {
+    if (!global.Olm) {
+        throw new Error("Olm is not available");
+    }
+
+    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, authData.private_key_salt,
+        authData.private_key_iterations,
+    );
+}
+
+export async function keyFromPassphrase(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);
+}
@@ -1,5 +1,6 @@
 /*
 Copyright 2016 OpenMarket Ltd
+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.
@@ -23,6 +24,7 @@ limitations under the License.
 import Promise from 'bluebird';
 const anotherjson = require('another-json');

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

 /**
@@ -35,6 +37,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 +72,7 @@ module.exports.encryptMessageForDevice = async function(
        return;
    }

-    console.log(
+    logger.log(
        "Using sessionid " + sessionId + " for device " +
            recipientUserId + ":" + recipientDevice.deviceId,
    );
@@ -115,19 +122,23 @@ 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], ...
    ];
    const result = {};
+    const resolveSession = {};

    for (const userId in devicesByUser) {
        if (!devicesByUser.hasOwnProperty(userId)) {
@@ -139,8 +150,37 @@ module.exports.ensureOlmSessionsForDevices = async function(
            const deviceInfo = devices[j];
            const deviceId = deviceInfo.deviceId;
            const key = deviceInfo.getIdentityKey();
-            const sessionId = await olmDevice.getSessionIdForDevice(key);
-            if (sessionId === null) {
+            if (!olmDevice._sessionsInProgress[key]) {
+                // pre-emptively mark the session as in-progress to avoid race
+                // conditions.  If we find that we already have a session, then
+                // we'll resolve
+                olmDevice._sessionsInProgress[key] = new Promise(
+                    (resolve, reject) => {
+                        resolveSession[key] = {
+                            resolve: (...args) => {
+                                delete olmDevice._sessionsInProgress[key];
+                                resolve(...args);
+                            },
+                            reject: (...args) => {
+                                delete olmDevice._sessionsInProgress[key];
+                                reject(...args);
+                            },
+                        };
+                    },
+                );
+            }
+            const sessionId = await olmDevice.getSessionIdForDevice(
+                key, resolveSession[key],
+            );
+            if (sessionId !== null && resolveSession[key]) {
+                // we found a session, but we had marked the session as
+                // in-progress, so unmark it and unblock anything that was
+                // waiting
+                delete olmDevice._sessionsInProgress[key];
+                resolveSession[key].resolve();
+                delete resolveSession[key];
+            }
+            if (sessionId === null || force) {
                devicesWithoutSession.push([userId, deviceId]);
            }
            result[userId][deviceId] = {
@@ -154,16 +194,19 @@ module.exports.ensureOlmSessionsForDevices = async function(
        return result;
    }

-    // TODO: this has a race condition - if we try to send another message
-    // while we are claiming a key, we will end up claiming two and setting up
-    // two sessions.
-    //
-    // That should eventually resolve itself, but it's poor form.
-
    const oneTimeKeyAlgorithm = "signed_curve25519";
-    const res = await baseApis.claimOneTimeKeys(
-        devicesWithoutSession, oneTimeKeyAlgorithm,
-    );
+    let res;
+    try {
+        res = await baseApis.claimOneTimeKeys(
+            devicesWithoutSession, oneTimeKeyAlgorithm,
+        );
+    } catch (e) {
+        for (const resolver of Object.values(resolveSession)) {
+            resolver.resolve();
+        }
+        logger.log("failed to claim one-time keys", e, devicesWithoutSession);
+        throw e;
+    }

    const otk_res = res.one_time_keys || {};
    const promises = [];
@@ -176,7 +219,8 @@ 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) {
+            const key = deviceInfo.getIdentityKey();
+            if (result[userId][deviceId].sessionId && !force) {
                // we already have a result for this device
                continue;
            }
@@ -190,10 +234,12 @@ module.exports.ensureOlmSessionsForDevices = async function(
            }

            if (!oneTimeKey) {
-                console.warn(
-                    "No one-time keys (alg=" + oneTimeKeyAlgorithm +
-                        ") for device " + userId + ":" + deviceId,
-                );
+                const msg = "No one-time keys (alg=" + oneTimeKeyAlgorithm +
+                      ") for device " + userId + ":" + deviceId;
+                logger.warn(msg);
+                if (resolveSession[key]) {
+                    resolveSession[key].resolve();
+                }
                continue;
            }

@@ -201,7 +247,15 @@ module.exports.ensureOlmSessionsForDevices = async function(
                _verifyKeyAndStartSession(
                    olmDevice, oneTimeKey, userId, deviceInfo,
                ).then((sid) => {
+                    if (resolveSession[key]) {
+                        resolveSession[key].resolve(sid);
+                    }
                    result[userId][deviceId].sessionId = sid;
+                }, (e) => {
+                    if (resolveSession[key]) {
+                        resolveSession[key].resolve();
+                    }
+                    throw e;
                }),
            );
        }
@@ -219,7 +273,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 +287,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 olm session with device " +
                      userId + ":" + deviceId + ": " + e);
        return null;
    }

-    console.log("Started new sessionid " + sid +
+    logger.log("Started new olm sessionid " + sid +
                " for device " + userId + ":" + deviceId);
    return sid;
 }
@@ -274,11 +328,74 @@ const _verifySignature = module.exports.verifySignature = async function(

    // prepare the canonical json: remove unsigned and signatures, and stringify with
    // anotherjson
-    delete obj.unsigned;
-    delete obj.signatures;
-    const json = anotherjson.stringify(obj);
+    const mangledObj = Object.assign({}, obj);
+    delete mangledObj.unsigned;
+    delete mangledObj.signatures;
+    const json = anotherjson.stringify(mangledObj);

    olmDevice.verifySignature(
        signingKey, json, signature,
    );
 };
+
+/**
+ * Sign a JSON object using public key cryptography
+ * @param {Object} obj Object to sign.  The object will be modified to include
+ *     the new signature
+ * @param {Olm.PkSigning|Uint8Array} key the signing object or the private key
+ * seed
+ * @param {string} userId The user ID who owns the signing key
+ * @param {string} pubkey The public key (ignored if key is a seed)
+ * @returns {string} the signature for the object
+ */
+module.exports.pkSign = function(obj, key, userId, pubkey) {
+    let createdKey = false;
+    if (key instanceof Uint8Array) {
+        const keyObj = new global.Olm.PkSigning();
+        pubkey = keyObj.init_with_seed(key);
+        key = keyObj;
+        createdKey = true;
+    }
+    const sigs = obj.signatures || {};
+    delete obj.signatures;
+    const unsigned = obj.unsigned;
+    if (obj.unsigned) delete obj.unsigned;
+    try {
+        const mysigs = sigs[userId] || {};
+        sigs[userId] = mysigs;
+
+        return mysigs['ed25519:' + pubkey] = key.sign(anotherjson.stringify(obj));
+    } finally {
+        obj.signatures = sigs;
+        if (unsigned) obj.unsigned = unsigned;
+        if (createdKey) {
+            key.free();
+        }
+    }
+};
+
+/**
+ * Verify a signed JSON object
+ * @param {Object} obj Object to verify
+ * @param {string} pubkey The public key to use to verify
+ * @param {string} userId The user ID who signed the object
+ */
+module.exports.pkVerify = function(obj, pubkey, userId) {
+    const keyId = "ed25519:" + pubkey;
+    if (!(obj.signatures && obj.signatures[userId] && obj.signatures[userId][keyId])) {
+        throw new Error("No signature");
+    }
+    const signature = obj.signatures[userId][keyId];
+    const util = new global.Olm.Utility();
+    const sigs = obj.signatures;
+    delete obj.signatures;
+    const unsigned = obj.unsigned;
+    if (obj.unsigned) delete obj.unsigned;
+    try {
+        util.ed25519_verify(pubkey, anotherjson.stringify(obj), signature);
+    } finally {
+        obj.signatures = sigs;
+        if (unsigned) obj.unsigned = unsigned;
+        util.free();
+    }
+};
@@ -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 Buffer(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})`,
                );
@@ -294,6 +332,23 @@ export class Backend {
        objectStore.put(newData, "-");
    }

+    getCrossSigningKeys(txn, func) {
+        const objectStore = txn.objectStore("account");
+        const getReq = objectStore.get("crossSigningKeys");
+        getReq.onsuccess = function() {
+            try {
+                func(getReq.result || null);
+            } catch (e) {
+                abortWithException(txn, e);
+            }
+        };
+    }
+
+    storeCrossSigningKeys(txn, keys) {
+        const objectStore = txn.objectStore("account");
+        objectStore.put(keys, "crossSigningKeys");
+    }
+
    // Olm Sessions

    countEndToEndSessions(txn, func) {
@@ -312,7 +367,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 +388,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 +401,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 +484,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 +544,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 +634,7 @@ export class Backend {
 }

 export function upgradeDatabase(db, oldVersion) {
-    console.log(
+    logger.log(
        `Upgrading IndexedDBCryptoStore from version ${oldVersion}`
            + ` to ${VERSION}`,
    );
@@ -498,6 +661,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,12 +707,21 @@ function promiseifyTxn(txn) {
            }
            resolve();
        };
-        txn.onerror = () => {
+        txn.onerror = (event) => {
            if (txn._mx_abortexception !== undefined) {
                reject(txn._mx_abortexception);
+            } else {
+                logger.log("Error performing indexeddb txn", event);
+                reject(event.target.error);
+            }
+        };
+        txn.onabort = (event) => {
+            if (txn._mx_abortexception !== undefined) {
+                reject(txn._mx_abortexception);
+            } else {
+                logger.log("Error performing indexeddb txn", event);
+                reject(event.target.error);
            }
-            reject();
        };
-        txn.onabort = () => reject(txn._mx_abortexception);
    });
 }
@@ -17,9 +17,12 @@ 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';
+import * as IndexedDBHelpers from "../../indexeddb-helpers";

 /**
 * Internal module. indexeddb storage for e2e.
@@ -46,6 +49,10 @@ export default class IndexedDBCryptoStore {
        this._backendPromise = null;
    }

+    static exists(indexedDB, dbName) {
+        return IndexedDBHelpers.exists(indexedDB, dbName);
+    }
+
    /**
     * Ensure the database exists and is up-to-date, or fall back to
     * a local storage or in-memory store.
@@ -64,7 +71,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,19 +84,20 @@ export default class IndexedDBCryptoStore {
            };

            req.onblocked = () => {
-                console.log(
+                logger.log(
                    `can't yet open IndexedDBCryptoStore because it is open elsewhere`,
                );
            };

            req.onerror = (ev) => {
+                logger.log("Error connecting to indexeddb", ev);
                reject(ev.target.error);
            };

            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 +114,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,28 +150,29 @@ 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`,
                );
            };

            req.onerror = (ev) => {
+                logger.log("Error deleting data from indexeddb", ev);
                reject(ev.target.error);
            };

            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 +224,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
@@ -254,7 +290,7 @@ export default class IndexedDBCryptoStore {
        this._backendPromise.value().getAccount(txn, func);
    }

-    /*
+    /**
     * Write the account pickle to the store.
     * This requires an active transaction. See doTxn().
     *
@@ -265,6 +301,28 @@ export default class IndexedDBCryptoStore {
        this._backendPromise.value().storeAccount(txn, newData);
    }

+    /**
+     * Get the public part of the cross-signing keys (eg. self-signing key,
+     * user signing key).
+     *
+     * @param {*} txn An active transaction. See doTxn().
+     * @param {function(string)} func Called with the account keys object:
+     *        { key_type: base64 encoded seed } where key type = user_signing_key_seed or self_signing_key_seed
+     */
+    getCrossSigningKeys(txn, func) {
+        this._backendPromise.value().getCrossSigningKeys(txn, func);
+    }
+
+    /**
+     * Write the cross-signing keys back to the store
+     *
+     * @param {*} txn An active transaction. See doTxn().
+     * @param {string} keys keys object as getCrossSigningKeys()
+     */
+    storeCrossSigningKeys(txn, keys) {
+        this._backendPromise.value().storeCrossSigningKeys(txn, keys);
+    }
+
    // Olm sessions

    /**
@@ -283,7 +341,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,26 +356,40 @@ 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,
        );
    }

-    // Inbound group saessions
+    // Inbound group sessions

    /**
     * Retrieve the end-to-end inbound group session for a given
@@ -420,6 +495,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 +577,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,7 +15,9 @@ limitations under the License.
 */

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

 /**
 * Internal module. Partial localStorage backed storage for e2e.
@@ -29,9 +31,11 @@ import MemoryCryptoStore from './memory-crypto-store.js';

 const E2E_PREFIX = "crypto.";
 const KEY_END_TO_END_ACCOUNT = E2E_PREFIX + "account";
+const KEY_CROSS_SIGNING_KEYS = E2E_PREFIX + "cross_signing_keys";
 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;
@@ -54,6 +58,16 @@ export default class LocalStorageCryptoStore extends MemoryCryptoStore {
        this.store = webStore;
    }

+    static exists(webStore) {
+        const length = webStore.length;
+        for (let i = 0; i < length; i++) {
+            if (webStore.key(i).startsWith(E2E_PREFIX)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
    // Olm Sessions

    countEndToEndSessions(txn, func) {
@@ -65,7 +79,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 +105,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 +204,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.
     *
@@ -188,6 +285,17 @@ export default class LocalStorageCryptoStore extends MemoryCryptoStore {
        );
    }

+    getCrossSigningKeys(txn, func) {
+        const keys = getJsonItem(this.store, KEY_CROSS_SIGNING_KEYS);
+        func(keys);
+    }
+
+    storeCrossSigningKeys(txn, keys) {
+        setJsonItem(
+            this.store, KEY_CROSS_SIGNING_KEYS, keys,
+        );
+    }
+
    doTxn(mode, stores, func) {
        return Promise.resolve(func(null));
    }
@@ -199,8 +307,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';

 /**
@@ -32,6 +33,7 @@ export default class MemoryCryptoStore {
    constructor() {
        this._outgoingRoomKeyRequests = [];
        this._account = null;
+        this._crossSigningKeys = null;

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

    /**
@@ -71,7 +75,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 +85,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 +148,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 +180,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 +211,7 @@ export default class MemoryCryptoStore {
            }

            if (req.state != expectedState) {
-                console.warn(
+                logger.warn(
                    `Cannot delete room key request in state ${req.state} `
                    + `(expected ${expectedState})`,
                );
@@ -218,6 +235,14 @@ export default class MemoryCryptoStore {
        this._account = newData;
    }

+    getCrossSigningKeys(txn, func) {
+        func(this._crossSigningKeys);
+    }
+
+    storeCrossSigningKeys(txn, keys) {
+        this._crossSigningKeys = keys;
+    }
+
    // Olm Sessions

    countEndToEndSessions(txn, func) {
@@ -233,13 +258,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 +328,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,351 @@
+/*
+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';
+import logger from '../../logger';
+import DeviceInfo from '../deviceinfo';
+import {newTimeoutError} from "./Error";
+
+const timeoutException = new Error("Verification timed out");
+
+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 {string} [roomId] the room to use for verification
+     *
+     * @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
+     */
+    constructor(baseApis, userId, deviceId, transactionId, roomId, startEvent, request) {
+        super();
+        this._baseApis = baseApis;
+        this.userId = userId;
+        this.deviceId = deviceId;
+        this.transactionId = transactionId;
+        if (typeof(roomId) === "string" || roomId instanceof String) {
+            this.roomId = roomId;
+            this.startEvent = startEvent;
+            this.request = request;
+        } else {
+            // if room ID was omitted, but start event and request were not
+            this.startEvent= roomId;
+            this.request = startEvent;
+        }
+        this.cancelled = false;
+        this._done = false;
+        this._promise = null;
+        this._transactionTimeoutTimer = null;
+        this._eventsSubscription = null;
+
+        // At this point, the verification request was received so start the timeout timer.
+        this._resetTimer();
+
+        if (this.roomId) {
+            this._sendWithTxnId = this._sendMessage;
+        } else {
+            this._sendWithTxnId = this._sendToDevice;
+        }
+    }
+
+    _resetTimer() {
+        logger.info("Refreshing/starting the verification transaction timeout timer");
+        if (this._transactionTimeoutTimer !== null) {
+            clearTimeout(this._transactionTimeoutTimer);
+        }
+        this._transactionTimeoutTimer = setTimeout(() => {
+            if (!this._done && !this.cancelled) {
+                logger.info("Triggering verification timeout");
+                this.cancel(timeoutException);
+            }
+        }, 10 * 60 * 1000); // 10 minutes
+    }
+
+    _endTimer() {
+        if (this._transactionTimeoutTimer !== null) {
+            clearTimeout(this._transactionTimeoutTimer);
+            this._transactionTimeoutTimer = null;
+        }
+    }
+
+    _contentFromEventWithTxnId(event) {
+        if (this.roomId) {  // verification as timeline event
+            // ensure m.related_to is included in e2ee rooms
+            // as the field is excluded from encryption
+            const content = Object.assign({}, event.getContent());
+            content["m.relates_to"] = event.getRelation();
+            return content;
+        } else { // verification as to_device event
+            return event.getContent();
+        }
+    }
+
+    /* creates a content object with the transaction id added to it */
+    _contentWithTxnId(content) {
+        const copy = Object.assign({}, content);
+        if (this.roomId) { // verification as timeline event
+            copy["m.relates_to"] = {
+                rel_type: "m.reference",
+                event_id: this.transactionId,
+            };
+        } else { // verification as to_device event
+            copy.transaction_id = this.transactionId;
+        }
+        return copy;
+    }
+
+    _send(type, contentWithoutTxnId) {
+        const content = this._contentWithTxnId(contentWithoutTxnId);
+        return this._sendWithTxnId(type, content);
+    }
+
+    /* send a message to the other participant, using to-device messages
+     */
+    _sendToDevice(type, content) {
+        if (this._done) {
+            return Promise.reject(new Error("Verification is already done"));
+        }
+        return this._baseApis.sendToDevice(type, {
+            [this.userId]: { [this.deviceId]: content },
+        });
+    }
+
+    /* send a message to the other participant, using in-roomm messages
+     */
+    _sendMessage(type, content) {
+        if (this._done) {
+            return Promise.reject(new Error("Verification is already done"));
+        }
+        return this._baseApis.sendEvent(this.roomId, type, 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._resetTimer();
+            this._resolveEvent(e);
+        } else if (e.getType() === "m.key.verification.cancel") {
+            const reject = this._reject;
+            this._reject = undefined;
+            reject(new Error("Other side cancelled verification"));
+        } else {
+            const exception = new Error(
+                "Unexpected message: expecting " + this._expectedEvent
+                    + " but got " + e.getType(),
+            );
+            this._expectedEvent = undefined;
+            if (this._rejectEvent) {
+                const reject = this._rejectEvent;
+                this._rejectEvent = undefined;
+                reject(exception);
+            }
+            this.cancel(exception);
+        }
+    }
+
+    done() {
+        this._endTimer(); // always kill the activity timer
+        if (!this._done) {
+            if (this.roomId) {
+                // verification in DM requires a done message
+                this._send("m.key.verification.done", {});
+            }
+            this._resolve();
+        }
+    }
+
+    cancel(e) {
+        this._endTimer(); // always kill the activity timer
+        if (!this._done) {
+            this.cancelled = true;
+            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 === timeoutException) {
+                    const timeoutEvent = newTimeoutError();
+                    this._send(timeoutEvent.getType(), timeoutEvent.getContent());
+                } else 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._send("m.key.verification.cancel", content);
+                        } else {
+                            this._send("m.key.verification.cancel", {
+                                code: "m.unknown",
+                                reason: content.body || "Unknown reason",
+                                transaction_id: this.transactionId,
+                            });
+                        }
+                    }
+                } else {
+                    this._send("m.key.verification.cancel", {
+                        code: "m.unknown",
+                        reason: e.toString(),
+                        transaction_id: this.transactionId,
+                    });
+                }
+            }
+            if (this._promise !== null) {
+                // when we cancel without a promise, we end up with a promise
+                // but no reject function. If cancel is called again, we'd error.
+                if (this._reject) this._reject(e);
+            } else {
+                // unsubscribe from events, this happens in _reject usually but we don't have one here
+                if (this._eventsSubscription) {
+                    this._eventsSubscription = this._eventsSubscription();
+                }
+                // FIXME: this causes an "Uncaught promise" console message
+                // if nothing ends up chaining this promise.
+                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;
+                this._endTimer();
+                if (this.handler) {
+                    // these listeners are attached in Crypto.acceptVerificationDM
+                    if (this._eventsSubscription) {
+                        this._eventsSubscription = this._eventsSubscription();
+                    }
+                }
+                resolve(...args);
+            };
+            this._reject = (...args) => {
+                this._done = true;
+                this._endTimer();
+                if (this.handler) {
+                    // these listeners are attached in Crypto.acceptVerificationDM
+                    if (this._eventsSubscription) {
+                        this._eventsSubscription = this._eventsSubscription();
+                    }
+                }
+                reject(...args);
+            };
+        });
+        if (this._doVerification && !this._started) {
+            this._started = true;
+            this._resetTimer(); // restart the timeout
+            Promise.resolve(this._doVerification())
+                .then(this.done.bind(this), this.cancel.bind(this));
+        }
+        return this._promise;
+    }
+
+    async _verifyKeys(userId, keys, verifier) {
+        // we try to verify all the keys that we're told about, but we might
+        // not know about all of them, so keep track of the keys that we know
+        // about, and ignore the rest
+        const verifiedDevices = [];
+
+        for (const [keyId, keyInfo] of Object.entries(keys)) {
+            const deviceId = keyId.split(':', 2)[1];
+            const device = await this._baseApis.getStoredDevice(userId, deviceId);
+            if (device) {
+                await verifier(keyId, device, keyInfo);
+                verifiedDevices.push(deviceId);
+            } else {
+                const crossSigningInfo = this._baseApis._crypto._deviceList
+                      .getStoredCrossSigningForUser(userId);
+                if (crossSigningInfo && crossSigningInfo.getId() === deviceId) {
+                    await verifier(keyId, DeviceInfo.fromStorage({
+                        keys: {
+                            [keyId]: deviceId,
+                        },
+                    }, deviceId), keyInfo);
+                    verifiedDevices.push(deviceId);
+                } else {
+                    logger.warn(
+                        `verification: Could not find device ${deviceId} to verify`,
+                    );
+                }
+            }
+        }
+
+        // if none of the keys could be verified, then error because the app
+        // should be informed about that
+        if (!verifiedDevices.length) {
+            throw new Error("No devices could be verified");
+        }
+
+        for (const deviceId of verifiedDevices) {
+            await this._baseApis.setDeviceVerified(userId, deviceId);
+        }
+    }
+
+    setEventsSubscription(subscription) {
+        this._eventsSubscription = subscription;
+    }
+}
@@ -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,416 @@
+/*
+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]);
+}
+
+const sasGenerators = {
+    decimal: generateDecimalSas,
+    emoji: generateEmojiSas,
+};
+
+function generateSas(sasBytes, methods) {
+    const sas = {};
+    for (const method of methods) {
+        if (method in sasGenerators) {
+            sas[method] = sasGenerators[method](sasBytes);
+        }
+    }
+    return sas;
+}
+
+const macMethods = {
+    "hkdf-hmac-sha256": "calculate_mac",
+    "hmac-sha256": "calculate_mac_long_kdf",
+};
+
+/* lists of algorithms/methods that are supported.  The key agreement, hashes,
+ * and MAC lists should be sorted in order of preference (most preferred
+ * first).
+ */
+const KEY_AGREEMENT_LIST = ["curve25519"];
+const HASHES_LIST = ["sha256"];
+const MAC_LIST = ["hkdf-hmac-sha256", "hmac-sha256"];
+const SAS_LIST = Object.keys(sasGenerators);
+
+const KEY_AGREEMENT_SET = new Set(KEY_AGREEMENT_LIST);
+const HASHES_SET = new Set(HASHES_LIST);
+const MAC_SET = new Set(MAC_LIST);
+const SAS_SET = new Set(SAS_LIST);
+
+function intersection(anArray, aSet) {
+    return anArray instanceof Array ? anArray.filter(x => aSet.has(x)) : [];
+}
+
+/**
+ * @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 = this._contentWithTxnId({
+            method: SAS.NAME,
+            from_device: this._baseApis.deviceId,
+            key_agreement_protocols: KEY_AGREEMENT_LIST,
+            hashes: HASHES_LIST,
+            message_authentication_codes: MAC_LIST,
+            // FIXME: allow app to specify what SAS methods can be used
+            short_authentication_string: SAS_LIST,
+        });
+        // add the transaction id to the message beforehand because
+        // it needs to be included in the commitment hash later on
+        this._sendWithTxnId("m.key.verification.start", initialMessage);
+
+
+        let e = await this._waitForEvent("m.key.verification.accept");
+        let content = e.getContent();
+        const sasMethods
+              = intersection(content.short_authentication_string, SAS_SET);
+        if (!(KEY_AGREEMENT_SET.has(content.key_agreement_protocol)
+              && HASHES_SET.has(content.hash)
+              && MAC_SET.has(content.message_authentication_code)
+              && sasMethods.length)) {
+            throw newUnknownMethodError();
+        }
+        if (typeof content.commitment !== "string") {
+            throw newInvalidMessageError();
+        }
+        const macMethod = content.message_authentication_code;
+        const hashCommitment = content.commitment;
+        const olmSAS = new global.Olm.SAS();
+        try {
+            this._send("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);
+            // TODO: use selected hash function (when we support multiple)
+            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, macMethod);
+                        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, macMethod);
+        } finally {
+            olmSAS.free();
+        }
+    }
+
+    async _doRespondVerification() {
+        // as m.related_to is not included in the encrypted content in e2e rooms,
+        // we need to make sure it is added
+        let content = this._contentFromEventWithTxnId(this.startEvent);
+
+        // Note: we intersect using our pre-made lists, rather than the sets,
+        // so that the result will be in our order of preference.  Then
+        // fetching the first element from the array will give our preferred
+        // method out of the ones offered by the other party.
+        const keyAgreement
+              = intersection(
+                  KEY_AGREEMENT_LIST, new Set(content.key_agreement_protocols),
+              )[0];
+        const hashMethod
+              = intersection(HASHES_LIST, new Set(content.hashes))[0];
+        const macMethod
+              = intersection(MAC_LIST, new Set(content.message_authentication_codes))[0];
+        // FIXME: allow app to specify what SAS methods can be used
+        const sasMethods
+              = intersection(content.short_authentication_string, SAS_SET);
+        if (!(keyAgreement !== undefined
+              && hashMethod !== undefined
+              && macMethod !== undefined
+              && sasMethods.length)) {
+            throw newUnknownMethodError();
+        }
+
+        const olmSAS = new global.Olm.SAS();
+        try {
+            const commitmentStr = olmSAS.get_pubkey() + anotherjson.stringify(content);
+            this._send("m.key.verification.accept", {
+                key_agreement_protocol: keyAgreement,
+                hash: hashMethod,
+                message_authentication_code: macMethod,
+                short_authentication_string: sasMethods,
+                // TODO: use selected hash function (when we support multiple)
+                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._send("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, macMethod);
+                        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, macMethod);
+        } finally {
+            olmSAS.free();
+        }
+    }
+
+    _sendMAC(olmSAS, method) {
+        const mac = {};
+        const keyList = [];
+        const baseInfo = "MATRIX_KEY_VERIFICATION_MAC"
+              + this._baseApis.getUserId() + this._baseApis.deviceId
+              + this.userId + this.deviceId
+              + this.transactionId;
+
+        const deviceKeyId = `ed25519:${this._baseApis.deviceId}`;
+        mac[deviceKeyId] = olmSAS[macMethods[method]](
+            this._baseApis.getDeviceEd25519Key(),
+            baseInfo + deviceKeyId,
+        );
+        keyList.push(deviceKeyId);
+
+        const crossSigningId = this._baseApis.getCrossSigningId();
+        if (crossSigningId) {
+            const crossSigningKeyId = `ed25519:${crossSigningId}`;
+            mac[crossSigningKeyId] = olmSAS[macMethods[method]](
+                crossSigningId,
+                baseInfo + crossSigningKeyId,
+            );
+            keyList.push(crossSigningKeyId);
+        }
+
+        const keys = olmSAS[macMethods[method]](
+            keyList.sort().join(","),
+            baseInfo + "KEY_IDS",
+        );
+        this._send("m.key.verification.mac", { mac, keys });
+    }
+
+    async _checkMAC(olmSAS, content, method) {
+        const baseInfo = "MATRIX_KEY_VERIFICATION_MAC"
+              + this.userId + this.deviceId
+              + this._baseApis.getUserId() + this._baseApis.deviceId
+              + this.transactionId;
+
+        if (content.keys !== olmSAS[macMethods[method]](
+            Object.keys(content.mac).sort().join(","),
+            baseInfo + "KEY_IDS",
+        )) {
+            throw newKeyMismatchError();
+        }
+
+        await this._verifyKeys(this.userId, content.mac, (keyId, device, keyInfo) => {
+            if (keyInfo !== olmSAS[macMethods[method]](
+                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);
@@ -1,5 +1,6 @@
 /*
 Copyright 2015, 2016 OpenMarket Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -22,6 +23,7 @@ import Promise from 'bluebird';
 const parseContentType = require('content-type').parse;

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

 // we use our own implementation of setTimeout, so that if we get suspended in
 // the middle of a /sync, we cancel the sync as soon as we awake, rather than
@@ -45,10 +47,15 @@ module.exports.PREFIX_R0 = "/_matrix/client/r0";
 module.exports.PREFIX_UNSTABLE = "/_matrix/client/unstable";

 /**
- * URI path for the identity API
+ * URI path for v1 of the the identity API
 */
 module.exports.PREFIX_IDENTITY_V1 = "/_matrix/identity/api/v1";

+/**
+ * URI path for the v2 identity API
+ */
+module.exports.PREFIX_IDENTITY_V2 = "/_matrix/identity/v2";
+
 /**
 * URI path for the media repo API
 */
@@ -89,6 +96,13 @@ module.exports.MatrixHttpApi = function MatrixHttpApi(event_emitter, opts) {
 };

 module.exports.MatrixHttpApi.prototype = {
+    /**
+     * Sets the baase URL for the identity server
+     * @param {string} url The new base url
+     */
+    setIdBaseUrl: function(url) {
+        this.opts.idBaseUrl = url;
+    },

    /**
     * Get the content repository url with query parameters.
@@ -101,7 +115,7 @@ module.exports.MatrixHttpApi.prototype = {
        };
        return {
            base: this.opts.baseUrl,
-            path: "/_matrix/media/v1/upload",
+            path: "/_matrix/media/r0/upload",
            params: params,
        };
    },
@@ -164,9 +178,21 @@ module.exports.MatrixHttpApi.prototype = {
        const contentType = opts.type || file.type || 'application/octet-stream';
        const fileName = opts.name || file.name;

-        // we used to recommend setting file.stream to the thing to upload on
-        // nodejs.
-        const body = file.stream ? file.stream : file;
+        // We used to recommend setting file.stream to the thing to upload on
+        // Node.js. As of 2019-06-11, this is still in widespread use in various
+        // clients, so we should preserve this for simple objects used in
+        // Node.js. File API objects (via either the File or Blob interfaces) in
+        // the browser now define a `stream` method, which leads to trouble
+        // here, so we also check the type of `stream`.
+        let body = file;
+        if (body.stream && typeof body.stream !== "function") {
+            logger.warn(
+                "Using `file.stream` as the content to upload. Future " +
+                "versions of the js-sdk will change this to expect `file` to " +
+                "be the content directly.",
+            );
+            body = body.stream;
+        }

        // backwards-compatibility hacks where we used to do different things
        // between browser and node.
@@ -175,7 +201,7 @@ module.exports.MatrixHttpApi.prototype = {
            if (global.XMLHttpRequest) {
                rawResponse = false;
            } else {
-                console.warn(
+                logger.warn(
                    "Returning the raw JSON from uploadContent(). Future " +
                    "versions of the js-sdk will change this default, to " +
                    "return the parsed object. Set opts.rawResponse=false " +
@@ -188,7 +214,7 @@ module.exports.MatrixHttpApi.prototype = {
        let onlyContentUri = opts.onlyContentUri;
        if (!rawResponse && onlyContentUri === undefined) {
            if (global.XMLHttpRequest) {
-                console.warn(
+                logger.warn(
                    "Returning only the content-uri from uploadContent(). " +
                    "Future versions of the js-sdk will change this " +
                    "default, to return the whole response object. Set " +
@@ -278,7 +304,7 @@ module.exports.MatrixHttpApi.prototype = {
                    });
                }
            });
-            let url = this.opts.baseUrl + "/_matrix/media/v1/upload";
+            let url = this.opts.baseUrl + "/_matrix/media/r0/upload";

            const queryArgs = [];

@@ -314,7 +340,7 @@ module.exports.MatrixHttpApi.prototype = {

            promise = this.authedRequest(
                opts.callback, "POST", "/upload", queryParams, body, {
-                    prefix: "/_matrix/media/v1",
+                    prefix: "/_matrix/media/r0",
                    headers: {"Content-Type": contentType},
                    json: false,
                    bodyParser: bodyParser,
@@ -355,7 +381,18 @@ module.exports.MatrixHttpApi.prototype = {
        return this.uploads;
    },

-    idServerRequest: function(callback, method, path, params, prefix) {
+    idServerRequest: function(
+        callback,
+        method,
+        path,
+        params,
+        prefix,
+        accessToken,
+    ) {
+        if (!this.opts.idBaseUrl) {
+            throw new Error("No Identity Server base URL set");
+        }
+
        const fullUri = this.opts.idBaseUrl + prefix + path;

        if (callback !== undefined && !utils.isFunction(callback)) {
@@ -368,13 +405,17 @@ module.exports.MatrixHttpApi.prototype = {
            uri: fullUri,
            method: method,
            withCredentials: false,
-            json: false,
+            json: true, // we want a JSON response if we can
            _matrix_opts: this.opts,
+            headers: {},
        };
-        if (method == 'GET') {
+        if (method === 'GET') {
            opts.qs = params;
-        } else {
-            opts.form = params;
+        } else if (typeof params === "object") {
+            opts.json = params;
+        }
+        if (accessToken) {
+            opts.headers['Authorization'] = `Bearer ${accessToken}`;
        }

        const defer = Promise.defer();
@@ -382,12 +423,7 @@ module.exports.MatrixHttpApi.prototype = {
            opts,
            requestCallback(defer, callback, this.opts.onlyData),
        );
-        // ID server does not always take JSON, so we can't use requests' 'json'
-        // option as we do with the home server, but it does return JSON, so
-        // parse it manually
-        return defer.promise.then(function(response) {
-            return JSON.parse(response);
-        });
+        return defer.promise;
    },

    /**
@@ -457,7 +493,7 @@ module.exports.MatrixHttpApi.prototype = {
        const self = this;
        requestPromise.catch(function(err) {
            if (err.errcode == 'M_UNKNOWN_TOKEN') {
-                self.event_emitter.emit("Session.logged_out");
+                self.event_emitter.emit("Session.logged_out", err);
            } else if (err.errcode == 'M_CONSENT_NOT_GIVEN') {
                self.event_emitter.emit(
                    "no_consent",
@@ -512,76 +548,6 @@ module.exports.MatrixHttpApi.prototype = {
        );
    },

-    /**
-     * Perform an authorised request to the homeserver with a specific path
-     * prefix which overrides the default for this call only. Useful for hitting
-     * different Matrix Client-Server versions.
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @param {string} method The HTTP method e.g. "GET".
-     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
-     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
-     * @param {Object} data The HTTP JSON body.
-     * @param {string} prefix The full prefix to use e.g.
-     * "/_matrix/client/v2_alpha".
-     * @param {Number=} localTimeoutMs The maximum amount of time to wait before
-     * timing out the request. If not specified, there is no timeout.
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
-     * headers: {Object}, code: {Number}}</code>.
-     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
-     * object only.
-     * @return {module:http-api.MatrixError} Rejects with an error if a problem
-     * occurred. This includes network problems and Matrix-specific error JSON.
-     *
-     * @deprecated prefer authedRequest with opts.prefix
-     */
-    authedRequestWithPrefix: function(callback, method, path, queryParams, data,
-                                      prefix, localTimeoutMs) {
-        return this.authedRequest(
-            callback, method, path, queryParams, data, {
-                localTimeoutMs: localTimeoutMs,
-                prefix: prefix,
-            },
-        );
-    },
-
-    /**
-     * Perform a request to the homeserver without any credentials but with a
-     * specific path prefix which overrides the default for this call only.
-     * Useful for hitting different Matrix Client-Server versions.
-     * @param {Function} callback Optional. The callback to invoke on
-     * success/failure. See the promise return values for more information.
-     * @param {string} method The HTTP method e.g. "GET".
-     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
-     * "/createRoom".
-     * @param {Object} queryParams A dict of query params (these will NOT be
-     * urlencoded).
-     * @param {Object} data The HTTP JSON body.
-     * @param {string} prefix The full prefix to use e.g.
-     * "/_matrix/client/v2_alpha".
-     * @param {Number=} localTimeoutMs The maximum amount of time to wait before
-     * timing out the request. If not specified, there is no timeout.
-     * @return {module:client.Promise} Resolves to <code>{data: {Object},
-     * headers: {Object}, code: {Number}}</code>.
-     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
-     * object only.
-     * @return {module:http-api.MatrixError} Rejects with an error if a problem
-     * occurred. This includes network problems and Matrix-specific error JSON.
-     *
-     * @deprecated prefer request with opts.prefix
-     */
-    requestWithPrefix: function(callback, method, path, queryParams, data, prefix,
-                                localTimeoutMs) {
-        return this.request(
-            callback, method, path, queryParams, data, {
-                localTimeoutMs: localTimeoutMs,
-                prefix: prefix,
-            },
-        );
-    },
-
    /**
     * Perform a request to an arbitrary URL.
     * @param {Function} callback Optional. The callback to invoke on
@@ -752,6 +718,8 @@ module.exports.MatrixHttpApi.prototype = {
                    method: method,
                    withCredentials: false,
                    qs: queryParams,
+                    qsStringifyOptions: opts.qsStringifyOptions,
+                    useQuerystring: true,
                    body: data,
                    json: false,
                    timeout: localTimeoutMs,
@@ -868,7 +836,8 @@ function parseErrorResponse(response, body) {
    let err;
    if (contentType) {
        if (contentType.type === 'application/json') {
-            err = new module.exports.MatrixError(JSON.parse(body));
+            const jsonBody = typeof(body) === 'object' ? body : JSON.parse(body);
+            err = new module.exports.MatrixError(jsonBody);
        } else if (contentType.type === 'text/plain') {
            err = new Error(`Server returned ${httpStatus} error: ${body}`);
        }
@@ -0,0 +1,52 @@
+/*
+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 Promise from 'bluebird';
+
+/**
+ * Check if an IndexedDB database exists. The only way to do so is to try opening it, so
+ * we do that and then delete it did not exist before.
+ *
+ * @param {Object} indexedDB The `indexedDB` interface
+ * @param {string} dbName The database name to test for
+ * @returns {boolean} Whether the database exists
+ */
+export function exists(indexedDB, dbName) {
+    return new Promise((resolve, reject) => {
+        let exists = true;
+        const req = indexedDB.open(dbName);
+        req.onupgradeneeded = () => {
+            // Since we did not provide an explicit version when opening, this event
+            // should only fire if the DB did not exist before at any version.
+            exists = false;
+        };
+        req.onblocked = () => reject();
+        req.onsuccess = () => {
+            const db = req.result;
+            db.close();
+            if (!exists) {
+                // The DB did not exist before, but has been created as part of this
+                // existence check. Delete it now to restore previous state. Delete can
+                // actually take a while to complete in some browsers, so don't wait for
+                // it. This won't block future open calls that a store might issue next to
+                // properly set up the DB.
+                indexedDB.deleteDatabase(dbName);
+            }
+            resolve(exists);
+        };
+        req.onerror = ev => reject(ev.target.error);
+    });
+}
@@ -1,6 +1,7 @@
 /*
 Copyright 2016 OpenMarket Ltd
 Copyright 2017 Vector Creations Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -21,6 +22,7 @@ import Promise from 'bluebird';
 const url = require("url");

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

 const EMAIL_STAGE_TYPE = "m.login.email.identity";
 const MSISDN_STAGE_TYPE = "m.login.msisdn";
@@ -47,11 +49,18 @@ const MSISDN_STAGE_TYPE = "m.login.msisdn";
 * @param {object?} opts.authData error response from the last request. If
 *    null, a request will be made with no auth before starting.
 *
- * @param {function(object?, bool?): module:client.Promise} opts.doRequest
- *     called with the new auth dict to submit the request and a flag set
- *     to true if this request is a background request. Should return a
- *     promise which resolves to the successful response or rejects with a
- *     MatrixError.
+ * @param {function(object?): module:client.Promise} opts.doRequest
+ *     called with the new auth dict to submit the request. Also passes a
+ *     second deprecated arg which is a flag set to true if this request
+ *     is a background request. The busyChanged callback should be used
+ *     instead of the backfround flag. Should return a promise which resolves
+ *     to the successful response or rejects with a MatrixError.
+ *
+ * @param {function(bool): module:client.Promise} opts.busyChanged
+ *     called whenever the interactive auth logic becomes busy submitting
+ *     information provided by the user or finsihes. After this has been
+ *     called with true the UI should indicate that a request is in progress
+ *     until it is called again with false.
 *
 * @param {function(string, object?)} opts.stateUpdated
 *     called when the status of the UI auth changes, ie. when the state of
@@ -88,22 +97,37 @@ const MSISDN_STAGE_TYPE = "m.login.msisdn";
 * @param {string?} opts.emailSid If returning from having completed m.login.email.identity
 *     auth, the sid for the email verification session.
 *
+ * @param {function?} opts.requestEmailToken A function that takes the email address (string),
+ *     clientSecret (string), attempt number (int) and sessionId (string) and calls the
+ *     relevant requestToken function and returns the promise returned by that function.
+ *     If the resulting promise rejects, the rejection will propagate through to the
+ *     attemptAuth promise.
+ *
 */
 function InteractiveAuth(opts) {
    this._matrixClient = opts.matrixClient;
    this._data = opts.authData || {};
    this._requestCallback = opts.doRequest;
+    this._busyChangedCallback = opts.busyChanged;
    // startAuthStage included for backwards compat
    this._stateUpdatedCallback = opts.stateUpdated || opts.startAuthStage;
-    this._completionDeferred = null;
+    this._resolveFunc = null;
+    this._rejectFunc = null;
    this._inputs = opts.inputs || {};
+    this._requestEmailTokenCallback = opts.requestEmailToken;

    if (opts.sessionId) this._data.session = opts.sessionId;
    this._clientSecret = opts.clientSecret || this._matrixClient.generateClientSecret();
    this._emailSid = opts.emailSid;
    if (this._emailSid === undefined) this._emailSid = null;
+    this._requestingEmailToken = false;

+    this._chosenFlow = null;
    this._currentStage = null;
+
+    // if we are currently trying to submit an auth dict (which includes polling)
+    // the promise the will resolve/reject when it completes
+    this._submitPromise = null;
 }

 InteractiveAuth.prototype = {
@@ -115,19 +139,22 @@ InteractiveAuth.prototype = {
     *     no suitable authentication flow can be found
     */
    attemptAuth: function() {
-        this._completionDeferred = Promise.defer();
+        // This promise will be quite long-lived and will resolve when the
+        // request is authenticated and completes successfully.
+        return new Promise((resolve, reject) => {
+            this._resolveFunc = resolve;
+            this._rejectFunc = reject;

-        // wrap in a promise so that if _startNextAuthStage
-        // throws, it rejects the promise in a consistent way
-        return Promise.resolve().then(() => {
            // if we have no flows, try a request (we'll have
            // just a session ID in _data if resuming)
            if (!this._data.flows) {
-                this._doRequest(this._data);
+                if (this._busyChangedCallback) this._busyChangedCallback(true);
+                this._doRequest(this._data).finally(() => {
+                    if (this._busyChangedCallback) this._busyChangedCallback(false);
+                });
            } else {
                this._startNextAuthStage();
            }
-            return this._completionDeferred.promise;
        });
    },

@@ -136,24 +163,30 @@ InteractiveAuth.prototype = {
     * completed out-of-band. If so, the attemptAuth promise will
     * be resolved.
     */
-    poll: function() {
+    poll: async function() {
        if (!this._data.session) return;
+        // if we currently have a request in flight, there's no point making
+        // another just to check what the status is
+        if (this._submitPromise) return;

        let authDict = {};
        if (this._currentStage == EMAIL_STAGE_TYPE) {
            // The email can be validated out-of-band, but we need to provide the
            // creds so the HS can go & check it.
            if (this._emailSid) {
-                const idServerParsedUrl = url.parse(
-                    this._matrixClient.getIdentityServerUrl(),
-                );
+                const creds = {
+                    sid: this._emailSid,
+                    client_secret: this._clientSecret,
+                };
+                if (await this._matrixClient.doesServerRequireIdServerParam()) {
+                    const idServerParsedUrl = url.parse(
+                        this._matrixClient.getIdentityServerUrl(),
+                    );
+                    creds.id_server = idServerParsedUrl.host;
+                }
                authDict = {
                    type: EMAIL_STAGE_TYPE,
-                    threepid_creds: {
-                        sid: this._emailSid,
-                        client_secret: this._clientSecret,
-                        id_server: idServerParsedUrl.host,
-                    },
+                    threepid_creds: creds,
                };
            }
        }
@@ -194,6 +227,10 @@ InteractiveAuth.prototype = {
        return params[loginType];
    },

+    getChosenFlow() {
+        return this._chosenFlow;
+    },
+
    /**
     * submit a new auth dict and fire off the request. This will either
     * make attemptAuth resolve/reject, or cause the startAuthStage callback
@@ -206,18 +243,44 @@ InteractiveAuth.prototype = {
     *    in the attemptAuth promise being rejected. This can be set to true
     *    for requests that just poll to see if auth has been completed elsewhere.
     */
-    submitAuthDict: function(authData, background) {
-        if (!this._completionDeferred) {
+    submitAuthDict: async function(authData, background) {
+        if (!this._resolveFunc) {
            throw new Error("submitAuthDict() called before attemptAuth()");
        }

+        if (!background && this._busyChangedCallback) {
+            this._busyChangedCallback(true);
+        }
+
+        // if we're currently trying a request, wait for it to finish
+        // as otherwise we can get multiple 200 responses which can mean
+        // things like multiple logins for register requests.
+        // (but discard any expections as we only care when its done,
+        // not whether it worked or not)
+        while (this._submitPromise) {
+            try {
+                await this._submitPromise;
+            } catch (e) {
+            }
+        }
+
        // use the sessionid from the last request.
        const auth = {
            session: this._data.session,
        };
        utils.extend(auth, authData);

-        this._doRequest(auth, background);
+        try {
+            // NB. the 'background' flag is deprecated by the busyChanged
+            // callback and is here for backwards compat
+            this._submitPromise = this._doRequest(auth, background);
+            await this._submitPromise;
+        } finally {
+            this._submitPromise = null;
+            if (!background && this._busyChangedCallback) {
+                this._busyChangedCallback(false);
+            }
+        }
    },

    /**
@@ -253,58 +316,78 @@ InteractiveAuth.prototype = {
     *    This can be set to true for requests that just poll to see if auth has
     *    been completed elsewhere.
     */
-    _doRequest: function(auth, background) {
-        const self = this;
-
-        // hackery to make sure that synchronous exceptions end up in the catch
-        // handler (without the additional event loop entailed by q.fcall or an
-        // extra Promise.resolve().then)
-        let prom;
+    _doRequest: async function(auth, background) {
        try {
-            prom = this._requestCallback(auth, background);
-        } catch (e) {
-            prom = Promise.reject(e);
-        }
+            const result = await this._requestCallback(auth, background);
+            this._resolveFunc(result);
+        } catch (error) {
+            // sometimes UI auth errors don't come with flows
+            const errorFlows = error.data ? error.data.flows : null;
+            const haveFlows = Boolean(this._data.flows) || Boolean(errorFlows);
+            if (error.httpStatus !== 401 || !error.data || !haveFlows) {
+                // doesn't look like an interactive-auth failure.
+                if (!background) {
+                    this._rejectFunc(error);
+                } else {
+                    // We ignore all failures here (even non-UI auth related ones)
+                    // since we don't want to suddenly fail if the internet connection
+                    // had a blip whilst we were polling
+                    logger.log(
+                        "Background poll request failed doing UI auth: ignoring",
+                        error,
+                    );
+                }
+            }
+            // if the error didn't come with flows, completed flows or session ID,
+            // copy over the ones we have. Synapse sometimes sends responses without
+            // any UI auth data (eg. when polling for email validation, if the email
+            // has not yet been validated). This appears to be a Synapse bug, which
+            // we workaround here.
+            if (!error.data.flows && !error.data.completed && !error.data.session) {
+                error.data.flows = this._data.flows;
+                error.data.completed = this._data.completed;
+                error.data.session = this._data.session;
+            }
+            this._data = error.data;
+            this._startNextAuthStage();

-        prom = prom.then(
-            function(result) {
-                console.log("result from request: ", result);
-                self._completionDeferred.resolve(result);
-            }, function(error) {
-                // sometimes UI auth errors don't come with flows
-                const errorFlows = error.data ? error.data.flows : null;
-                const haveFlows = Boolean(self._data.flows) || Boolean(errorFlows);
-                if (error.httpStatus !== 401 || !error.data || !haveFlows) {
-                    // doesn't look like an interactive-auth failure. fail the whole lot.
-                    throw error;
+            if (
+                !this._emailSid &&
+                !this._requestingEmailToken &&
+                this._chosenFlow.stages.includes('m.login.email.identity')
+            ) {
+                // If we've picked a flow with email auth, we send the email
+                // now because we want the request to fail as soon as possible
+                // if the email address is not valid (ie. already taken or not
+                // registered, depending on what the operation is).
+                this._requestingEmailToken = true;
+                try {
+                    const requestTokenResult = await this._requestEmailTokenCallback(
+                        this._inputs.emailAddress,
+                        this._clientSecret,
+                        1, // TODO: Multiple send attempts?
+                        this._data.session,
+                    );
+                    this._emailSid = requestTokenResult.sid;
+                    // NB. promise is not resolved here - at some point, doRequest
+                    // will be called again and if the user has jumped through all
+                    // the hoops correctly, auth will be complete and the request
+                    // will succeed.
+                    // Also, we should expose the fact that this request has compledted
+                    // so clients can know that the email has actually been sent.
+                } catch (e) {
+                    // we failed to request an email token, so fail the request.
+                    // This could be due to the email already beeing registered
+                    // (or not being registered, depending on what we're trying
+                    // to do) or it could be a network failure. Either way, pass
+                    // the failure up as the user can't complete auth if we can't
+                    // send the email, foe whatever reason.
+                    this._rejectFunc(e);
+                } finally {
+                    this._requestingEmailToken = false;
                }
-                // if the error didn't come with flows, completed flows or session ID,
-                // copy over the ones we have. Synapse sometimes sends responses without
-                // any UI auth data (eg. when polling for email validation, if the email
-                // has not yet been validated). This appears to be a Synapse bug, which
-                // we workaround here.
-                if (!error.data.flows && !error.data.completed && !error.data.session) {
-                    error.data.flows = self._data.flows;
-                    error.data.completed = self._data.completed;
-                    error.data.session = self._data.session;
-                }
-                self._data = error.data;
-                self._startNextAuthStage();
-            },
-        );
-        if (!background) {
-            prom = prom.catch((e) => {
-                this._completionDeferred.reject(e);
-            });
-        } else {
-            // We ignore all failures here (even non-UI auth related ones)
-            // since we don't want to suddenly fail if the internet connection
-            // had a blip whilst we were polling
-            prom = prom.catch((error) => {
-                console.log("Ignoring error from UI auth: " + error);
-            });
+            }
        }
-        prom.done();
    },

    /**
@@ -320,7 +403,7 @@ InteractiveAuth.prototype = {
        }
        this._currentStage = nextStage;

-        if (nextStage == 'm.login.dummy') {
+        if (nextStage === 'm.login.dummy') {
            this.submitAuthDict({
                type: 'm.login.dummy',
            });
@@ -350,10 +433,12 @@ InteractiveAuth.prototype = {
     * @throws {NoAuthFlowFoundError} If no suitable authentication flow can be found
     */
    _chooseStage: function() {
-        const flow = this._chooseFlow();
-        console.log("Active flow => %s", JSON.stringify(flow));
-        const nextStage = this._firstUncompletedStage(flow);
-        console.log("Next stage: %s", nextStage);
+        if (this._chosenFlow === null) {
+            this._chosenFlow = this._chooseFlow();
+        }
+        logger.log("Active flow => %s", JSON.stringify(this._chosenFlow));
+        const nextStage = this._firstUncompletedStage(this._chosenFlow);
+        logger.log("Next stage: %s", nextStage);
        return nextStage;
    },

@@ -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;
@@ -1,6 +1,7 @@
 /*
 Copyright 2015, 2016 OpenMarket Ltd
 Copyright 2017 Vector Creations Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -22,8 +23,14 @@ module.exports.ContentHelpers = require("./content-helpers");
 module.exports.MatrixEvent = require("./models/event").MatrixEvent;
 /** The {@link module:models/event.EventStatus|EventStatus} enum. */
 module.exports.EventStatus = require("./models/event").EventStatus;
-/** The {@link module:store/memory.MatrixInMemoryStore|MatrixInMemoryStore} class. */
-module.exports.MatrixInMemoryStore = require("./store/memory").MatrixInMemoryStore;
+/** The {@link module:store/memory.MemoryStore|MemoryStore} class. */
+module.exports.MemoryStore = require("./store/memory").MemoryStore;
+/**
+ * The {@link module:store/memory.MemoryStore|MemoryStore} class was previously
+ * exported as `MatrixInMemoryStore`, so this is preserved for SDK consumers.
+ * @deprecated Prefer `MemoryStore` going forward.
+ */
+module.exports.MatrixInMemoryStore = module.exports.MemoryStore;
 /** The {@link module:store/indexeddb.IndexedDBStore|IndexedDBStore} class. */
 module.exports.IndexedDBStore = require("./store/indexeddb").IndexedDBStore;
 /** The {@link module:store/indexeddb.IndexedDBStoreBackend|IndexedDBStoreBackend} class. */
@@ -67,7 +74,10 @@ 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.SERVICE_TYPES = require('./service-types').SERVICE_TYPES;

 module.exports.MemoryCryptoStore =
    require("./crypto/store/memory-crypto-store").default;
@@ -86,21 +96,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
@@ -162,7 +172,7 @@ module.exports.setCryptoStoreFactory = function(fac) {
 * this is a string, it is assumed to be the base URL. These configuration
 * options will be passed directly to {@link module:client~MatrixClient}.
 * @param {Object} opts.store If not set, defaults to
- * {@link module:store/memory.MatrixInMemoryStore}.
+ * {@link module:store/memory.MemoryStore}.
 * @param {Object} opts.scheduler If not set, defaults to
 * {@link module:scheduler~MatrixScheduler}.
 * @param {requestFunction} opts.request If not set, defaults to the function
@@ -185,7 +195,7 @@ module.exports.createClient = function(opts) {
        };
    }
    opts.request = opts.request || request;
-    opts.store = opts.store || new module.exports.MatrixInMemoryStore({
+    opts.store = opts.store || new module.exports.MemoryStore({
      localStorage: global.localStorage,
    });
    opts.scheduler = opts.scheduler || new module.exports.MatrixScheduler();
@@ -20,6 +20,9 @@ limitations under the License.
 const EventEmitter = require("events").EventEmitter;
 const utils = require("../utils");
 const EventTimeline = require("./event-timeline");
+import {EventStatus} from "./event";
+import logger from '../logger';
+import Relations from './relations';

 // var DEBUG = false;
 const DEBUG = true;
@@ -27,7 +30,7 @@ const DEBUG = true;
 let debuglog;
 if (DEBUG) {
    // using bind means that we get to keep useful line numbers in the console
-    debuglog = console.log.bind(console);
+    debuglog = logger.log.bind(logger);
 } else {
    debuglog = function() {};
 }
@@ -54,25 +57,48 @@ if (DEBUG) {
 * map from event_id to timeline and index.
 *
 * @constructor
- * @param {?Room} room      the optional room for this timelineSet
- * @param {Object} opts     hash of options inherited from Room.
- *      opts.timelineSupport gives whether timeline support is enabled
- *      opts.filter is the filter object, if any, for this timelineSet.
+ * @param {?Room} room
+ * Room for this timelineSet. May be null for non-room cases, such as the
+ * notification timeline.
+ * @param {Object} opts Options inherited from Room.
+ *
+ * @param {boolean} [opts.timelineSupport = false]
+ * Set to true to enable improved timeline support.
+ * @param {Object} [opts.filter = null]
+ * The filter object, if any, for this timelineSet.
+ * @param {boolean} [opts.unstableClientRelationAggregation = false]
+ * Optional. Set to true to enable client-side aggregation of event relations
+ * via `getRelationsForEvent`.
+ * This feature is currently unstable and the API may change without notice.
 */
 function EventTimelineSet(room, opts) {
    this.room = room;

    this._timelineSupport = Boolean(opts.timelineSupport);
    this._liveTimeline = new EventTimeline(this);
+    this._unstableClientRelationAggregation = !!opts.unstableClientRelationAggregation;

    // just a list - *not* ordered.
    this._timelines = [this._liveTimeline];
    this._eventIdToTimeline = {};

    this._filter = opts.filter || null;
+
+    if (this._unstableClientRelationAggregation) {
+        // A tree of objects to access a set of relations for an event, as in:
+        // this._relations[relatesToEventId][relationType][relationEventType]
+        this._relations = {};
+    }
 }
 utils.inherits(EventTimelineSet, EventEmitter);

+/**
+ * Get all the timelines in this set
+ * @return {module:models/event-timeline~EventTimeline[]} the timelines in this set
+ */
+EventTimelineSet.prototype.getTimelines = function() {
+    return this._timelines;
+};
 /**
 * Get the filter object this timeline set is filtered on, if any
 * @return {?Filter} the optional filter for this timelineSet
@@ -405,11 +431,38 @@ EventTimelineSet.prototype.addEventsToTimeline = function(events, toStartOfTimel
        }

        // time to join the timelines.
-        console.info("Already have timeline for " + eventId +
+        logger.info("Already have timeline for " + eventId +
                     " - joining timeline " + timeline + " to " +
                     existingTimeline);
+
+        // Variables to keep the line length limited below.
+        const existingIsLive = existingTimeline === this._liveTimeline;
+        const timelineIsLive = timeline === this._liveTimeline;
+
+        const backwardsIsLive = direction === EventTimeline.BACKWARDS && existingIsLive;
+        const forwardsIsLive = direction === EventTimeline.FORWARDS && timelineIsLive;
+
+        if (backwardsIsLive || forwardsIsLive) {
+            // The live timeline should never be spliced into a non-live position.
+            // We use independent logging to better discover the problem at a glance.
+            if (backwardsIsLive) {
+                logger.warn(
+                    "Refusing to set a preceding existingTimeLine on our " +
+                    "timeline as the existingTimeLine is live (" + existingTimeline + ")",
+                );
+            }
+            if (forwardsIsLive) {
+                logger.warn(
+                    "Refusing to set our preceding timeline on a existingTimeLine " +
+                    "as our timeline is live (" + timeline + ")",
+                );
+            }
+            continue; // abort splicing - try next event
+        }
+
        timeline.setNeighbouringTimeline(existingTimeline, direction);
        existingTimeline.setNeighbouringTimeline(timeline, inverseDirection);
+
        timeline = existingTimeline;
        didUpdate = true;
    }
@@ -418,6 +471,14 @@ EventTimelineSet.prototype.addEventsToTimeline = function(events, toStartOfTimel
    // new information, we update the pagination token for whatever
    // timeline we ended up on.
    if (lastEventWasNew || !didUpdate) {
+        if (direction === EventTimeline.FORWARDS && timeline === this._liveTimeline) {
+            logger.warn({lastEventWasNew, didUpdate}); // for debugging
+            logger.warn(
+                `Refusing to set forwards pagination token of live timeline ` +
+                `${timeline} to ${paginationToken}`,
+            );
+            return;
+        }
        timeline.setPaginationToken(paginationToken, direction);
    }
 };
@@ -487,6 +548,9 @@ EventTimelineSet.prototype.addEventToTimeline = function(event, timeline,
    timeline.addEvent(event, toStartOfTimeline);
    this._eventIdToTimeline[eventId] = timeline;

+    this.setRelationsTarget(event);
+    this.aggregateRelations(event);
+
    const data = {
        timeline: timeline,
        liveEvent: !toStartOfTimeline && timeline == this._liveTimeline,
@@ -621,6 +685,136 @@ EventTimelineSet.prototype.compareEventOrdering = function(eventId1, eventId2) {
    return null;
 };

+/**
+ * Get a collection of relations to a given event in this timeline set.
+ *
+ * @param {String} eventId
+ * The ID of the event that you'd like to access relation events for.
+ * For example, with annotations, this would be the ID of the event being annotated.
+ * @param {String} relationType
+ * The type of relation involved, such as "m.annotation", "m.reference", "m.replace", etc.
+ * @param {String} eventType
+ * The relation event's type, such as "m.reaction", etc.
+ * @throws If <code>eventId</code>, <code>relationType</code> or <code>eventType</code>
+ * are not valid.
+ *
+ * @returns {?Relations}
+ * A container for relation events or undefined if there are no relation events for
+ * the relationType.
+ */
+EventTimelineSet.prototype.getRelationsForEvent = function(
+    eventId, relationType, eventType,
+) {
+    if (!this._unstableClientRelationAggregation) {
+        throw new Error("Client-side relation aggregation is disabled");
+    }
+
+    if (!eventId || !relationType || !eventType) {
+        throw new Error("Invalid arguments for `getRelationsForEvent`");
+    }
+
+    // debuglog("Getting relations for: ", eventId, relationType, eventType);
+
+    const relationsForEvent = this._relations[eventId] || {};
+    const relationsWithRelType = relationsForEvent[relationType] || {};
+    return relationsWithRelType[eventType];
+};
+
+/**
+ * Set an event as the target event if any Relations exist for it already
+ *
+ * @param {MatrixEvent} event
+ * The event to check as relation target.
+ */
+EventTimelineSet.prototype.setRelationsTarget = function(event) {
+    if (!this._unstableClientRelationAggregation) {
+        return;
+    }
+
+    const relationsForEvent = this._relations[event.getId()];
+    if (!relationsForEvent) {
+        return;
+    }
+    // don't need it for non m.replace relations for now
+    const relationsWithRelType = relationsForEvent["m.replace"];
+    if (!relationsWithRelType) {
+        return;
+    }
+    // only doing replacements for messages for now (e.g. edits)
+    const relationsWithEventType = relationsWithRelType["m.room.message"];
+
+    if (relationsWithEventType) {
+        relationsWithEventType.setTargetEvent(event);
+    }
+};
+
+/**
+ * Add relation events to the relevant relation collection.
+ *
+ * @param {MatrixEvent} event
+ * The new relation event to be aggregated.
+ */
+EventTimelineSet.prototype.aggregateRelations = function(event) {
+    if (!this._unstableClientRelationAggregation) {
+        return;
+    }
+
+    if (event.isRedacted() || event.status === EventStatus.CANCELLED) {
+        return;
+    }
+
+    // If the event is currently encrypted, wait until it has been decrypted.
+    if (event.isBeingDecrypted()) {
+        event.once("Event.decrypted", () => {
+            this.aggregateRelations(event);
+        });
+        return;
+    }
+
+    const relation = event.getRelation();
+    if (!relation) {
+        return;
+    }
+
+    const relatesToEventId = relation.event_id;
+    const relationType = relation.rel_type;
+    const eventType = event.getType();
+
+    // debuglog("Aggregating relation: ", event.getId(), eventType, relation);
+
+    let relationsForEvent = this._relations[relatesToEventId];
+    if (!relationsForEvent) {
+        relationsForEvent = this._relations[relatesToEventId] = {};
+    }
+    let relationsWithRelType = relationsForEvent[relationType];
+    if (!relationsWithRelType) {
+        relationsWithRelType = relationsForEvent[relationType] = {};
+    }
+    let relationsWithEventType = relationsWithRelType[eventType];
+
+    let isNewRelations = false;
+    let relatesToEvent;
+    if (!relationsWithEventType) {
+        relationsWithEventType = relationsWithRelType[eventType] = new Relations(
+            relationType,
+            eventType,
+            this.room,
+        );
+        isNewRelations = true;
+        relatesToEvent = this.findEventById(relatesToEventId);
+        if (relatesToEvent) {
+            relationsWithEventType.setTargetEvent(relatesToEvent);
+        }
+    }
+
+    relationsWithEventType.addEvent(event);
+
+    // only emit once event has been added to relations
+    if (isNewRelations && relatesToEvent) {
+        relatesToEvent.emit("Event.relationsCreated", relationType, eventType);
+    }
+};
+
 /**
 * The EventTimelineSet class.
 */
@@ -276,7 +276,7 @@ EventTimeline.prototype.getNeighbouringTimeline = function(direction) {
 EventTimeline.prototype.setNeighbouringTimeline = function(neighbour, direction) {
    if (this.getNeighbouringTimeline(direction)) {
        throw new Error("timeline already has a neighbouring timeline - " +
-                        "cannot reset neighbour");
+                        "cannot reset neighbour (direction: " + direction + ")");
    }

    if (direction == EventTimeline.BACKWARDS) {
@@ -24,13 +24,14 @@ limitations under the License.
 import Promise from 'bluebird';
 import {EventEmitter} from 'events';
 import utils from '../utils.js';
+import logger from '../logger';

 /**
 * Enum for event statuses.
 * @readonly
 * @enum {string}
 */
-module.exports.EventStatus = {
+const EventStatus = {
    /** The event was not sent and will no longer be retried. */
    NOT_SENT: "not_sent",

@@ -48,8 +49,15 @@ module.exports.EventStatus = {
    /** The event was cancelled before it was successfully sent. */
    CANCELLED: "cancelled",
 };
+module.exports.EventStatus = EventStatus;

 const interns = {};
+function intern(str) {
+    if (!interns[str]) {
+        interns[str] = str;
+    }
+    return interns[str];
+}

 /**
 * Construct a Matrix Event object
@@ -87,20 +95,25 @@ module.exports.MatrixEvent = function MatrixEvent(
        if (!event[prop]) {
            return;
        }
-        if (!interns[event[prop]]) {
-            interns[event[prop]] = event[prop];
-        }
-        event[prop] = interns[event[prop]];
+        event[prop] = intern(event[prop]);
    });

    ["membership", "avatar_url", "displayname"].forEach((prop) => {
        if (!event.content || !event.content[prop]) {
            return;
        }
-        if (!interns[event.content[prop]]) {
-            interns[event.content[prop]] = event.content[prop];
+        event.content[prop] = intern(event.content[prop]);
+    });
+
+    ["rel_type"].forEach((prop) => {
+        if (
+            !event.content ||
+            !event.content["m.relates_to"] ||
+            !event.content["m.relates_to"][prop]
+        ) {
+            return;
        }
-        event.content[prop] = interns[event.content[prop]];
+        event.content["m.relates_to"][prop] = intern(event.content["m.relates_to"][prop]);
    });

    this.event = event || {};
@@ -111,6 +124,9 @@ module.exports.MatrixEvent = function MatrixEvent(
    this.error = null;
    this.forwardLooking = true;
    this._pushActions = null;
+    this._replacingEvent = null;
+    this._localRedactionEvent = null;
+    this._isCancelled = false;

    this._clearEvent = {};

@@ -209,12 +225,33 @@ utils.extend(module.exports.MatrixEvent.prototype, {
    },

    /**
-     * Get the (decrypted, if necessary) event content JSON.
+     * Get the (decrypted, if necessary) event content JSON, even if the event
+     * was replaced by another event.
+     *
+     * @return {Object} The event content JSON, or an empty object.
+     */
+    getOriginalContent: function() {
+        if (this._localRedactionEvent) {
+            return {};
+        }
+        return this._clearEvent.content || this.event.content || {};
+    },
+
+    /**
+     * Get the (decrypted, if necessary) event content JSON,
+     * or the content from the replacing event, if any.
+     * See `makeReplaced`.
     *
     * @return {Object} The event content JSON, or an empty object.
     */
    getContent: function() {
-        return this._clearEvent.content || this.event.content || {};
+        if (this._localRedactionEvent) {
+            return {};
+        } else if (this._replacingEvent) {
+            return this._replacingEvent.getContent()["m.new_content"] || {};
+        } else {
+            return this.getOriginalContent();
+        }
    },

    /**
@@ -352,7 +389,7 @@ utils.extend(module.exports.MatrixEvent.prototype, {

        if (
            this._clearEvent && this._clearEvent.content &&
-                this._clearEvent.content.msgtype !== "m.bad.encrypted"
+            this._clearEvent.content.msgtype !== "m.bad.encrypted"
        ) {
            // we may want to just ignore this? let's start with rejecting it.
            throw new Error(
@@ -367,7 +404,7 @@ utils.extend(module.exports.MatrixEvent.prototype, {
        // new info.
        //
        if (this._decryptionPromise) {
-            console.log(
+            logger.log(
                `Event ${this.getId()} already being decrypted; queueing a retry`,
            );
            this._retryDecryption = true;
@@ -382,15 +419,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) {
@@ -415,7 +478,7 @@ utils.extend(module.exports.MatrixEvent.prototype, {
                if (e.name !== "DecryptionError") {
                    // not a decryption error: log the whole exception as an error
                    // (and don't bother with a retry)
-                    console.error(
+                    logger.error(
                        `Error decrypting event (id=${this.getId()}): ${e.stack || e}`,
                    );
                    this._decryptionPromise = null;
@@ -441,7 +504,7 @@ utils.extend(module.exports.MatrixEvent.prototype, {
                //
                if (this._retryDecryption) {
                    // decryption error, but we have a retry queued.
-                    console.log(
+                    logger.log(
                        `Got error decrypting event (id=${this.getId()}: ` +
                        `${e}), but retrying`,
                    );
@@ -450,7 +513,7 @@ utils.extend(module.exports.MatrixEvent.prototype, {

                // decryption error, no retries queued. Warn about the error and
                // set it to m.bad.encrypted.
-                console.warn(
+                logger.warn(
                    `Error decrypting event (id=${this.getId()}): ${e.detailedString}`,
                );

@@ -471,6 +534,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 +582,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.
@@ -592,6 +674,27 @@ utils.extend(module.exports.MatrixEvent.prototype, {
        return this.event.unsigned || {};
    },

+    unmarkLocallyRedacted: function() {
+        const value = this._localRedactionEvent;
+        this._localRedactionEvent = null;
+        if (this.event.unsigned) {
+            this.event.unsigned.redacted_because = null;
+        }
+        return !!value;
+    },
+
+    markLocallyRedacted: function(redactionEvent) {
+        if (this._localRedactionEvent) {
+            return;
+        }
+        this.emit("Event.beforeRedaction", this, redactionEvent);
+        this._localRedactionEvent = redactionEvent;
+        if (!this.event.unsigned) {
+            this.event.unsigned = {};
+        }
+        this.event.unsigned.redacted_because = redactionEvent.event;
+    },
+
    /**
     * Update the content of an event in the same way it would be by the server
     * if it were redacted before it was sent to us
@@ -605,6 +708,11 @@ utils.extend(module.exports.MatrixEvent.prototype, {
            throw new Error("invalid redaction_event in makeRedacted");
        }

+        this._localRedactionEvent = null;
+
+        this.emit("Event.beforeRedaction", this, redaction_event);
+
+        this._replacingEvent = null;
        // we attempt to replicate what we would see from the server if
        // the event had been redacted before we saw it.
        //
@@ -647,40 +755,305 @@ utils.extend(module.exports.MatrixEvent.prototype, {
        return Boolean(this.getUnsigned().redacted_because);
    },

+    /**
+     * Check if this event is a redaction of another event
+     *
+     * @return {boolean} True if this event is a redaction
+     */
+    isRedaction: function() {
+        return this.getType() === "m.room.redaction";
+    },
+
    /**
     * Get the push actions, if known, for this event
     *
     * @return {?Object} push actions
     */
-     getPushActions: function() {
+    getPushActions: function() {
        return this._pushActions;
-     },
+    },

    /**
     * Set the push actions for this event.
     *
     * @param {Object} pushActions push actions
     */
-     setPushActions: function(pushActions) {
+    setPushActions: function(pushActions) {
        this._pushActions = pushActions;
-     },
+    },

-     /**
-      * Replace the `event` property and recalculate any properties based on it.
-      * @param {Object} event the object to assign to the `event` property
-      */
-     handleRemoteEcho: function(event) {
+    /**
+     * Replace the `event` property and recalculate any properties based on it.
+     * @param {Object} event the object to assign to the `event` property
+     */
+    handleRemoteEcho: function(event) {
+        const oldUnsigned = this.getUnsigned();
+        const oldId = this.getId();
        this.event = event;
+        // if this event was redacted before it was sent, it's locally marked as redacted.
+        // At this point, we've received the remote echo for the event, but not yet for
+        // the redaction that we are sending ourselves. Preserve the locally redacted
+        // state by copying over redacted_because so we don't get a flash of
+        // redacted, not-redacted, redacted as remote echos come in
+        if (oldUnsigned.redacted_because) {
+            if (!this.event.unsigned) {
+                this.event.unsigned = {};
+            }
+            this.event.unsigned.redacted_because = oldUnsigned.redacted_because;
+        }
        // successfully sent.
-        this.status = null;
-     },
+        this.setStatus(null);
+        if (this.getId() !== oldId) {
+            // emit the event if it changed
+            this.emit("Event.localEventIdReplaced", this);
+        }
+    },
+
+    /**
+     * Whether the event is in any phase of sending, send failure, waiting for
+     * remote echo, etc.
+     *
+     * @return {boolean}
+     */
+    isSending() {
+        return !!this.status;
+    },
+
+    /**
+     * Update the event's sending status and emit an event as well.
+     *
+     * @param {String} status The new status
+     */
+    setStatus(status) {
+        this.status = status;
+        this.emit("Event.status", this, status);
+    },
+
+    replaceLocalEventId(eventId) {
+        this.event.event_id = eventId;
+        this.emit("Event.localEventIdReplaced", this);
+    },
+
+    /**
+     * Get whether the event is a relation event, and of a given type if
+     * `relType` is passed in.
+     *
+     * @param {string?} relType if given, checks that the relation is of the
+     * given type
+     * @return {boolean}
+     */
+    isRelation(relType = undefined) {
+        // Relation info is lifted out of the encrypted content when sent to
+        // encrypted rooms, so we have to check `getWireContent` for this.
+        const content = this.getWireContent();
+        const relation = content && content["m.relates_to"];
+        return relation && relation.rel_type && relation.event_id &&
+            ((relType && relation.rel_type === relType) || !relType);
+    },
+
+    /**
+     * Get relation info for the event, if any.
+     *
+     * @return {Object}
+     */
+    getRelation() {
+        if (!this.isRelation()) {
+            return null;
+        }
+        return this.getWireContent()["m.relates_to"];
+    },
+
+    /**
+     * Set an event that replaces the content of this event, through an m.replace relation.
+     *
+     * @param {MatrixEvent?} newEvent the event with the replacing content, if any.
+     */
+    makeReplaced(newEvent) {
+        // don't allow redacted events to be replaced.
+        // if newEvent is null we allow to go through though,
+        // as with local redaction, the replacing event might get
+        // cancelled, which should be reflected on the target event.
+        if (this.isRedacted() && newEvent) {
+            return;
+        }
+        if (this._replacingEvent !== newEvent) {
+            this._replacingEvent = newEvent;
+            this.emit("Event.replaced", this);
+        }
+    },
+
+    /**
+     * Returns the status of any associated edit or redaction
+     * (not for reactions/annotations as their local echo doesn't affect the orignal event),
+     * or else the status of the event.
+     *
+     * @return {EventStatus}
+     */
+    getAssociatedStatus() {
+        if (this._replacingEvent) {
+            return this._replacingEvent.status;
+        } else if (this._localRedactionEvent) {
+            return this._localRedactionEvent.status;
+        }
+        return this.status;
+    },
+
+    getServerAggregatedRelation(relType) {
+        const relations = this.getUnsigned()["m.relations"];
+        if (relations) {
+            return relations[relType];
+        }
+    },
+
+    /**
+     * Returns the event ID of the event replacing the content of this event, if any.
+     *
+     * @return {string?}
+     */
+    replacingEventId() {
+        const replaceRelation = this.getServerAggregatedRelation("m.replace");
+        if (replaceRelation) {
+            return replaceRelation.event_id;
+        } else if (this._replacingEvent) {
+            return this._replacingEvent.getId();
+        }
+    },
+
+    /**
+     * Returns the event replacing the content of this event, if any.
+     * Replacements are aggregated on the server, so this would only
+     * return an event in case it came down the sync, or for local echo of edits.
+     *
+     * @return {MatrixEvent?}
+     */
+    replacingEvent() {
+        return this._replacingEvent;
+    },
+
+    /**
+     * Returns the origin_server_ts of the event replacing the content of this event, if any.
+     *
+     * @return {Date?}
+     */
+    replacingEventDate() {
+        const replaceRelation = this.getServerAggregatedRelation("m.replace");
+        if (replaceRelation) {
+            const ts = replaceRelation.origin_server_ts;
+            if (Number.isFinite(ts)) {
+                return new Date(ts);
+            }
+        } else if (this._replacingEvent) {
+            return this._replacingEvent.getDate();
+        }
+    },
+
+    /**
+     * Returns the event that wants to redact this event, but hasn't been sent yet.
+     * @return {MatrixEvent} the event
+     */
+    localRedactionEvent() {
+        return this._localRedactionEvent;
+    },
+
+    /**
+     * For relations and redactions, returns the event_id this event is referring to.
+     *
+     * @return {string?}
+     */
+    getAssociatedId() {
+        const relation = this.getRelation();
+        if (relation) {
+            return relation.event_id;
+        } else if (this.isRedaction()) {
+            return this.event.redacts;
+        }
+    },
+
+    /**
+     * Checks if this event is associated with another event. See `getAssociatedId`.
+     *
+     * @return {bool}
+     */
+    hasAssocation() {
+        return !!this.getAssociatedId();
+    },
+
+    /**
+     * Update the related id with a new one.
+     *
+     * Used to replace a local id with remote one before sending
+     * an event with a related id.
+     *
+     * @param {string} eventId the new event id
+     */
+    updateAssociatedId(eventId) {
+        const relation = this.getRelation();
+        if (relation) {
+            relation.event_id = eventId;
+        } else if (this.isRedaction()) {
+            this.event.redacts = eventId;
+        }
+    },
+
+    /**
+     * Flags an event as cancelled due to future conditions. For example, a verification
+     * request event in the same sync transaction may be flagged as cancelled to warn
+     * listeners that a cancellation event is coming down the same pipe shortly.
+     * @param {boolean} cancelled Whether the event is to be cancelled or not.
+     */
+    flagCancelled(cancelled = true) {
+        this._isCancelled = cancelled;
+    },
+
+    /**
+     * Gets whether or not the event is flagged as cancelled. See flagCancelled() for
+     * more information.
+     * @returns {boolean} True if the event is cancelled, false otherwise.
+     */
+    isCancelled() {
+        return this._isCancelled;
+    },
+
+    /**
+     * Summarise the event as JSON for debugging. If encrypted, include both the
+     * decrypted and encrypted view of the event. This is named `toJSON` for use
+     * with `JSON.stringify` which checks objects for functions named `toJSON`
+     * and will call them to customise the output if they are defined.
+     *
+     * @return {Object}
+     */
+    toJSON() {
+        const event = {
+            type: this.getType(),
+            sender: this.getSender(),
+            content: this.getContent(),
+            event_id: this.getId(),
+            origin_server_ts: this.getTs(),
+            unsigned: this.getUnsigned(),
+            room_id: this.getRoomId(),
+        };
+
+        // if this is a redaction then attach the redacts key
+        if (this.isRedaction()) {
+            event.redacts = this.event.redacts;
+        }
+
+        if (!this.isEncrypted()) {
+            return event;
+        }
+
+        return {
+            decrypted: event,
+            encrypted: this.event,
+        };
+    },
 });


 /* _REDACT_KEEP_KEY_MAP gives the keys we keep when an event is redacted
 *
 * This is specified here:
- *  http://matrix.org/speculator/spec/HEAD/client_server/unstable.html#redactions
+ *  http://matrix.org/speculator/spec/HEAD/client_server/latest.html#redactions
 *
 * Also:
 *  - We keep 'unsigned' since that is created by the local server
@@ -0,0 +1,342 @@
+/*
+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 EventEmitter from 'events';
+import { EventStatus } from '../../lib/models/event';
+
+/**
+ * A container for relation events that supports easy access to common ways of
+ * aggregating such events. Each instance holds events that of a single relation
+ * type and event type. All of the events also relate to the same original event.
+ *
+ * The typical way to get one of these containers is via
+ * EventTimelineSet#getRelationsForEvent.
+ */
+export default class Relations extends EventEmitter {
+    /**
+     * @param {String} relationType
+     * The type of relation involved, such as "m.annotation", "m.reference",
+     * "m.replace", etc.
+     * @param {String} eventType
+     * The relation event's type, such as "m.reaction", etc.
+     * @param {?Room} room
+     * Room for this container. May be null for non-room cases, such as the
+     * notification timeline.
+     */
+    constructor(relationType, eventType, room) {
+        super();
+        this.relationType = relationType;
+        this.eventType = eventType;
+        this._relations = new Set();
+        this._annotationsByKey = {};
+        this._annotationsBySender = {};
+        this._sortedAnnotationsByKey = [];
+        this._targetEvent = null;
+    }
+
+    /**
+     * Add relation events to this collection.
+     *
+     * @param {MatrixEvent} event
+     * The new relation event to be added.
+     */
+    addEvent(event) {
+        if (this._relations.has(event)) {
+            return;
+        }
+
+        const relation = event.getRelation();
+        if (!relation) {
+            console.error("Event must have relation info");
+            return;
+        }
+
+        const relationType = relation.rel_type;
+        const eventType = event.getType();
+
+        if (this.relationType !== relationType || this.eventType !== eventType) {
+            console.error("Event relation info doesn't match this container");
+            return;
+        }
+
+        // If the event is in the process of being sent, listen for cancellation
+        // so we can remove the event from the collection.
+        if (event.isSending()) {
+            event.on("Event.status", this._onEventStatus);
+        }
+
+        this._relations.add(event);
+
+        if (this.relationType === "m.annotation") {
+            this._addAnnotationToAggregation(event);
+        } else if (this.relationType === "m.replace" && this._targetEvent) {
+            this._targetEvent.makeReplaced(this.getLastReplacement());
+        }
+
+        event.on("Event.beforeRedaction", this._onBeforeRedaction);
+
+        this.emit("Relations.add", event);
+    }
+
+    /**
+     * Remove relation event from this collection.
+     *
+     * @param {MatrixEvent} event
+     * The relation event to remove.
+     */
+    _removeEvent(event) {
+        if (!this._relations.has(event)) {
+            return;
+        }
+
+        const relation = event.getRelation();
+        if (!relation) {
+            console.error("Event must have relation info");
+            return;
+        }
+
+        const relationType = relation.rel_type;
+        const eventType = event.getType();
+
+        if (this.relationType !== relationType || this.eventType !== eventType) {
+            console.error("Event relation info doesn't match this container");
+            return;
+        }
+
+        this._relations.delete(event);
+
+        if (this.relationType === "m.annotation") {
+            this._removeAnnotationFromAggregation(event);
+        } else if (this.relationType === "m.replace" && this._targetEvent) {
+            this._targetEvent.makeReplaced(this.getLastReplacement());
+        }
+
+        this.emit("Relations.remove", event);
+    }
+
+    /**
+     * Listens for event status changes to remove cancelled events.
+     *
+     * @param {MatrixEvent} event The event whose status has changed
+     * @param {EventStatus} status The new status
+     */
+    _onEventStatus = (event, status) => {
+        if (!event.isSending()) {
+            // Sending is done, so we don't need to listen anymore
+            event.removeListener("Event.status", this._onEventStatus);
+            return;
+        }
+        if (status !== EventStatus.CANCELLED) {
+            return;
+        }
+        // Event was cancelled, remove from the collection
+        event.removeListener("Event.status", this._onEventStatus);
+        this._removeEvent(event);
+    }
+
+    /**
+     * Get all relation events in this collection.
+     *
+     * These are currently in the order of insertion to this collection, which
+     * won't match timeline order in the case of scrollback.
+     * TODO: Tweak `addEvent` to insert correctly for scrollback.
+     *
+     * @return {Array}
+     * Relation events in insertion order.
+     */
+    getRelations() {
+        return [...this._relations];
+    }
+
+    _addAnnotationToAggregation(event) {
+        const { key } = event.getRelation();
+        if (!key) {
+            return;
+        }
+
+        let eventsForKey = this._annotationsByKey[key];
+        if (!eventsForKey) {
+            eventsForKey = this._annotationsByKey[key] = new Set();
+            this._sortedAnnotationsByKey.push([key, eventsForKey]);
+        }
+        // Add the new event to the set for this key
+        eventsForKey.add(event);
+        // Re-sort the [key, events] pairs in descending order of event count
+        this._sortedAnnotationsByKey.sort((a, b) => {
+            const aEvents = a[1];
+            const bEvents = b[1];
+            return bEvents.size - aEvents.size;
+        });
+
+        const sender = event.getSender();
+        let eventsFromSender = this._annotationsBySender[sender];
+        if (!eventsFromSender) {
+            eventsFromSender = this._annotationsBySender[sender] = new Set();
+        }
+        // Add the new event to the set for this sender
+        eventsFromSender.add(event);
+    }
+
+    _removeAnnotationFromAggregation(event) {
+        const { key } = event.getRelation();
+        if (!key) {
+            return;
+        }
+
+        const eventsForKey = this._annotationsByKey[key];
+        if (eventsForKey) {
+            eventsForKey.delete(event);
+
+            // Re-sort the [key, events] pairs in descending order of event count
+            this._sortedAnnotationsByKey.sort((a, b) => {
+                const aEvents = a[1];
+                const bEvents = b[1];
+                return bEvents.size - aEvents.size;
+            });
+        }
+
+        const sender = event.getSender();
+        const eventsFromSender = this._annotationsBySender[sender];
+        if (eventsFromSender) {
+            eventsFromSender.delete(event);
+        }
+    }
+
+    /**
+     * For relations that have been redacted, we want to remove them from
+     * aggregation data sets and emit an update event.
+     *
+     * To do so, we listen for `Event.beforeRedaction`, which happens:
+     *   - after the server accepted the redaction and remote echoed back to us
+     *   - before the original event has been marked redacted in the client
+     *
+     * @param {MatrixEvent} redactedEvent
+     * The original relation event that is about to be redacted.
+     */
+    _onBeforeRedaction = (redactedEvent) => {
+        if (!this._relations.has(redactedEvent)) {
+            return;
+        }
+
+        this._relations.delete(redactedEvent);
+
+        if (this.relationType === "m.annotation") {
+            // Remove the redacted annotation from aggregation by key
+            this._removeAnnotationFromAggregation(redactedEvent);
+        } else if (this.relationType === "m.replace" && this._targetEvent) {
+            this._targetEvent.makeReplaced(this.getLastReplacement());
+        }
+
+        redactedEvent.removeListener("Event.beforeRedaction", this._onBeforeRedaction);
+
+        this.emit("Relations.redaction", redactedEvent);
+    }
+
+    /**
+     * Get all events in this collection grouped by key and sorted by descending
+     * event count in each group.
+     *
+     * This is currently only supported for the annotation relation type.
+     *
+     * @return {Array}
+     * An array of [key, events] pairs sorted by descending event count.
+     * The events are stored in a Set (which preserves insertion order).
+     */
+    getSortedAnnotationsByKey() {
+        if (this.relationType !== "m.annotation") {
+            // Other relation types are not grouped currently.
+            return null;
+        }
+
+        return this._sortedAnnotationsByKey;
+    }
+
+    /**
+     * Get all events in this collection grouped by sender.
+     *
+     * This is currently only supported for the annotation relation type.
+     *
+     * @return {Object}
+     * An object with each relation sender as a key and the matching Set of
+     * events for that sender as a value.
+     */
+    getAnnotationsBySender() {
+        if (this.relationType !== "m.annotation") {
+            // Other relation types are not grouped currently.
+            return null;
+        }
+
+        return this._annotationsBySender;
+    }
+
+    /**
+     * Returns the most recent (and allowed) m.replace relation, if any.
+     *
+     * This is currently only supported for the m.replace relation type,
+     * once the target event is known, see `addEvent`.
+     *
+     * @return {MatrixEvent?}
+     */
+    getLastReplacement() {
+        if (this.relationType !== "m.replace") {
+            // Aggregating on last only makes sense for this relation type
+            return null;
+        }
+        if (!this._targetEvent) {
+            // Don't know which replacements to accept yet.
+            // This method shouldn't be called before the original
+            // event is known anyway.
+            return null;
+        }
+
+        // the all-knowning server tells us that the event at some point had
+        // this timestamp for its replacement, so any following replacement should definitely not be less
+        const replaceRelation =
+            this._targetEvent.getServerAggregatedRelation("m.replace");
+        const minTs = replaceRelation && replaceRelation.origin_server_ts;
+
+        return this.getRelations().reduce((last, event) => {
+            if (event.getSender() !== this._targetEvent.getSender()) {
+                return last;
+            }
+            if (minTs && minTs > event.getTs()) {
+                return last;
+            }
+            if (last && last.getTs() > event.getTs()) {
+                return last;
+            }
+            return event;
+        }, null);
+    }
+
+    /*
+     * @param {MatrixEvent} targetEvent the event the relations are related to.
+     */
+    setTargetEvent(event) {
+        if (this._targetEvent) {
+            return;
+        }
+        this._targetEvent = event;
+        if (this.relationType === "m.replace") {
+            const replacement = this.getLastReplacement();
+            // this is the initial update, so only call it if we already have something
+            // to not emit Event.replaced needlessly
+            if (replacement) {
+                this._targetEvent.makeReplaced(replacement);
+            }
+        }
+    }
+}
@@ -249,7 +249,7 @@ RoomMember.prototype.getDMInviter = function() {
 * "crop" or "scale".
 * @param {Boolean} allowDefault (optional) Passing false causes this method to
 * return null if the user has no avatar image. Otherwise, a default image URL
- * will be returned. Default: true.
+ * will be returned. Default: true. (Deprecated)
 * @param {Boolean} allowDirectLinks (optional) If true, the avatar URL will be
 * returned even if it is a direct hyperlink rather than a matrix content URL.
 * If false, any non-matrix content URLs will be ignored. Setting this option to
@@ -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);
    }

@@ -21,6 +21,7 @@ const EventEmitter = require("events").EventEmitter;

 const utils = require("../utils");
 const RoomMember = require("./room-member");
+import logger from '../logger';

 // possible statuses for out-of-band member loading
 const OOB_STATUS_NOTSTARTED = 1;
@@ -75,6 +76,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 +157,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.
@@ -435,7 +448,7 @@ RoomState.prototype.clearOutOfBandMembers = function() {
            delete this.members[userId];
        }
    });
-    console.log(`LL: RoomState removed ${count} members...`);
+    logger.log(`LL: RoomState removed ${count} members...`);
    this._oobMemberFlags.status = OOB_STATUS_NOTSTARTED;
 };

@@ -444,11 +457,11 @@ RoomState.prototype.clearOutOfBandMembers = function() {
 * @param {MatrixEvent[]} stateEvents array of membership state events
 */
 RoomState.prototype.setOutOfBandMembers = function(stateEvents) {
-    console.log(`LL: RoomState about to set ${stateEvents.length} OOB members ...`);
+    logger.log(`LL: RoomState about to set ${stateEvents.length} OOB members ...`);
    if (this._oobMemberFlags.status !== OOB_STATUS_INPROGRESS) {
        return;
    }
-    console.log(`LL: RoomState put in OOB_STATUS_FINISHED state ...`);
+    logger.log(`LL: RoomState put in OOB_STATUS_FINISHED state ...`);
    this._oobMemberFlags.status = OOB_STATUS_FINISHED;
    stateEvents.forEach((e) => this._setOutOfBandMember(e));
 };
@@ -519,12 +532,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)] || [];
 };

 /**
@@ -1,6 +1,7 @@
 /*
 Copyright 2015, 2016 OpenMarket Ltd
-Copyright 2018 New Vector Ltd
+Copyright 2018, 2019 New Vector Ltd
+Copyright 2019 The Matrix.org Foundation C.I.C.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -29,9 +30,17 @@ const ContentRepo = require("../content-repo");
 const EventTimeline = require("./event-timeline");
 const EventTimelineSet = require("./event-timeline-set");

+import logger from '../logger';
 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 = '4';
+const SAFE_ROOM_VERSIONS = ['1', '2', '3', '4'];

 function synthesizeReceipt(userId, event, receiptType) {
    // console.log("synthesizing receipt for "+event.getId());
@@ -85,9 +94,12 @@ function synthesizeReceipt(userId, event, receiptType) {
 * "<b>detached</b>", pending messages will appear in a separate list,
 * accessbile via {@link module:models/room#getPendingEvents}. Default:
 * "chronological".
- *
 * @param {boolean} [opts.timelineSupport = false] Set to true to enable improved
 * timeline support.
+ * @param {boolean} [opts.unstableClientRelationAggregation = false]
+ * Optional. Set to true to enable client-side aggregation of event relations
+ * via `EventTimelineSet#getRelationsForEvent`.
+ * This feature is currently unstable and the API may change without notice.
 *
 * @prop {string} roomId The ID of this room.
 * @prop {string} name The human-readable display name for this room.
@@ -199,7 +211,7 @@ utils.inherits(Room, EventEmitter);
 Room.prototype.getVersion = function() {
    const createEvent = this.currentState.getStateEvents("m.room.create", "");
    if (!createEvent) {
-        console.warn("Room " + this.room_id + " does not have an m.room.create event");
+        logger.warn("Room " + this.room_id + " does not have an m.room.create event");
        return '1';
    }
    const ver = createEvent.getContent()['room_version'];
@@ -211,12 +223,108 @@ 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";
+        }
+    }
+
+    let result = this._checkVersionAgainstCapability(versionCap);
+    if (result.urgent && result.needsUpgrade) {
+        // Something doesn't feel right: we shouldn't need to update
+        // because the version we're on should be in the protocol's
+        // namespace. This usually means that the server was updated
+        // before the client was, making us think the newest possible
+        // room version is not stable. As a solution, we'll refresh
+        // the capability we're using to determine this.
+        logger.warn(
+            "Refreshing room version capability because the server looks " +
+            "to be supporting a newer room version we don't know about.",
+        );
+
+        const caps = await this._client.getCapabilities(true);
+        versionCap = caps["m.room_versions"];
+        if (!versionCap) {
+            logger.warn("No room version capability - assuming upgrade required.");
+            return result;
+        } else {
+            result = this._checkVersionAgainstCapability(versionCap);
+        }
+    }
+
+    return result;
+};
+
+Room.prototype._checkVersionAgainstCapability = function(versionCap) {
+    const currentVersion = this.getVersion();
+    logger.log(`[${this.roomId}] Current version: ${currentVersion}`);
+    logger.log(`[${this.roomId}] Version capability: `, versionCap);
+
+    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 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);
+        if (result.urgent) {
+            logger.warn(`URGENT upgrade required on ${this.roomId}`);
+        } else {
+            logger.warn(`Non-urgent upgrade required on ${this.roomId}`);
+        }
+        return result;
+    }
+
+    // The room is on a stable, but non-default, version by this point.
+    // No upgrade needed.
+    return result;
 };

 /**
@@ -239,13 +347,30 @@ Room.prototype.userMayUpgradeRoom = function(userId) {
 Room.prototype.getPendingEvents = function() {
    if (this._opts.pendingEventOrdering !== "detached") {
        throw new Error(
-            "Cannot call getPendingEventList with pendingEventOrdering == " +
+            "Cannot call getPendingEvents with pendingEventOrdering == " +
                this._opts.pendingEventOrdering);
    }

    return this._pendingEventList;
 };

+/**
+ * Check whether the pending event list contains a given event by ID.
+ *
+ * @param {string} eventId The event ID to check for.
+ * @return {boolean}
+ * @throws If <code>opts.pendingEventOrdering</code> was not 'detached'
+ */
+Room.prototype.hasPendingEvent = function(eventId) {
+    if (this._opts.pendingEventOrdering !== "detached") {
+        throw new Error(
+            "Cannot call hasPendingEvent with pendingEventOrdering == " +
+                this._opts.pendingEventOrdering);
+    }
+
+    return this._pendingEventList.some(event => event.getId() === eventId);
+};
+
 /**
 * Get the live unfiltered timeline for this room.
 *
@@ -255,6 +380,23 @@ Room.prototype.getLiveTimeline = function() {
    return this.getUnfilteredTimelineSet().getLiveTimeline();
 };

+
+/**
+ * Get the timestamp of the last message in the room
+ *
+ * @return {number} the timestamp of the last message in the room
+ */
+Room.prototype.getLastActiveTimestamp = function() {
+    const timeline = this.getLiveTimeline();
+    const events = timeline.getEvents();
+    if (events.length) {
+        const lastEvent = events[events.length - 1];
+        return lastEvent.getTs();
+    } else {
+        return Number.MIN_SAFE_INTEGER;
+    }
+};
+
 /**
 * @param {string} myUserId the user id for the logged in member
 * @return {string} the membership type (join | leave | invite) for the logged in user
@@ -392,7 +534,7 @@ Room.prototype._loadMembers = async function() {
    if (rawMembersEvents === null) {
        fromServer = true;
        rawMembersEvents = await this._loadMembersFromServer();
-        console.log(`LL: got ${rawMembersEvents.length} ` +
+        logger.log(`LL: got ${rawMembersEvents.length} ` +
            `members from server for room ${this.roomId}`);
    }
    const memberEvents = rawMembersEvents.map(this._client.getEventMapper());
@@ -420,7 +562,7 @@ Room.prototype.loadMembersIfNeeded = function() {
    const inMemoryUpdate = this._loadMembers().then((result) => {
        this.currentState.setOutOfBandMembers(result.memberEvents);
        // now the members are loaded, start to track the e2e devices if needed
-        if (this._client.isRoomEncrypted(this.roomId)) {
+        if (this._client.isCryptoEnabled() && this._client.isRoomEncrypted(this.roomId)) {
            this._client._crypto.trackRoomDevices(this.roomId);
        }
        return result.fromServer;
@@ -436,21 +578,21 @@ Room.prototype.loadMembersIfNeeded = function() {
            const oobMembers = this.currentState.getMembers()
                .filter((m) => m.isOutOfBand())
                .map((m) => m.events.member.event);
-            console.log(`LL: telling store to write ${oobMembers.length}`
+            logger.log(`LL: telling store to write ${oobMembers.length}`
                + ` members for room ${this.roomId}`);
            const store = this._client.store;
            return store.setOutOfBandMembers(this.roomId, oobMembers)
                // swallow any IDB error as we don't want to fail
                // because of this
                .catch((err) => {
-                    console.log("LL: storing OOB room members failed, oh well",
+                    logger.log("LL: storing OOB room members failed, oh well",
                        err);
                });
        }
    }).catch((err) => {
        // as this is not awaited anywhere,
        // at least show the error in the console
-        console.error(err);
+        logger.error(err);
    });

    this._membersPromise = inMemoryUpdate;
@@ -476,9 +618,9 @@ Room.prototype.clearLoadedMembersIfNeeded = async function() {
 */
 Room.prototype._cleanupAfterLeaving = function() {
    this.clearLoadedMembersIfNeeded().catch((err) => {
-        console.error(`error after clearing loaded members from ` +
+        logger.error(`error after clearing loaded members from ` +
            `room ${this.roomId} after leaving`);
-        console.dir(err);
+        logger.log(err);
    });
 };

@@ -520,6 +662,29 @@ Room.prototype._fixUpLegacyTimelineFields = function() {
                            .getState(EventTimeline.FORWARDS);
 };

+/**
+ * Returns whether there are any devices in the room that are unverified
+ *
+ * Note: Callers should first check if crypto is enabled on this device. If it is
+ * disabled, then we aren't tracking room devices at all, so we can't answer this, and an
+ * error will be thrown.
+ *
+ * @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
@@ -633,7 +798,7 @@ Room.prototype.getBlacklistUnverifiedDevices = function() {
 * @param {string} resizeMethod The thumbnail resize method to use, either
 * "crop" or "scale".
 * @param {boolean} allowDefault True to allow an identicon for this room if an
- * avatar URL wasn't explicitly set. Default: true.
+ * avatar URL wasn't explicitly set. Default: true. (Deprecated)
 * @return {?string} the avatar URL or null.
 */
 Room.prototype.getAvatarUrl = function(baseUrl, width, height, resizeMethod,
@@ -667,20 +832,20 @@ Room.prototype.getAvatarUrl = function(baseUrl, width, height, resizeMethod,
 * @return {array} The room's alias as an array of strings
 */
 Room.prototype.getAliases = function() {
-    const alias_strings = [];
+    const aliasStrings = [];

-    const alias_events = this.currentState.getStateEvents("m.room.aliases");
-    if (alias_events) {
-        for (let i = 0; i < alias_events.length; ++i) {
-            const alias_event = alias_events[i];
-            if (utils.isArray(alias_event.getContent().aliases)) {
+    const aliasEvents = this.currentState.getStateEvents("m.room.aliases");
+    if (aliasEvents) {
+        for (let i = 0; i < aliasEvents.length; ++i) {
+            const aliasEvent = aliasEvents[i];
+            if (utils.isArray(aliasEvent.getContent().aliases)) {
                Array.prototype.push.apply(
-                    alias_strings, alias_event.getContent().aliases,
+                    aliasStrings, aliasEvent.getContent().aliases,
                );
            }
        }
    }
-    return alias_strings;
+    return aliasStrings;
 };

 /**
@@ -902,14 +1067,25 @@ Room.prototype.removeFilteredTimelineSet = function(filter) {
 * @private
 */
 Room.prototype._addLiveEvent = function(event, duplicateStrategy) {
-    let i;
-    if (event.getType() === "m.room.redaction") {
+    if (event.isRedaction()) {
        const redactId = event.event.redacts;

        // if we know about this event, redact its contents now.
        const redactedEvent = this.getUnfilteredTimelineSet().findEventById(redactId);
        if (redactedEvent) {
            redactedEvent.makeRedacted(event);
+
+            // If this is in the current state, replace it with the redacted version
+            if (redactedEvent.getStateKey()) {
+                const currentStateEvent = this.currentState.getStateEvents(
+                    redactedEvent.getType(),
+                    redactedEvent.getStateKey(),
+                );
+                if (currentStateEvent.getId() === redactedEvent.getId()) {
+                    this.currentState.setStateEvents([redactedEvent]);
+                }
+            }
+
            this.emit("Room.redaction", event, this);

            // TODO: we stash user displaynames (among other things) in
@@ -936,7 +1112,7 @@ Room.prototype._addLiveEvent = function(event, duplicateStrategy) {
    }

    // add to our timeline sets
-    for (i = 0; i < this._timelineSets.length; i++) {
+    for (let i = 0; i < this._timelineSets.length; i++) {
        this._timelineSets[i].addLiveEvent(event, duplicateStrategy);
    }

@@ -999,12 +1175,36 @@ 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)) {
+            logger.warn("Setting event as NOT_SENT due to messages in the same state");
+            event.setStatus(EventStatus.NOT_SENT);
+        }
        this._pendingEventList.push(event);
+
+        if (event.isRelation()) {
+            // For pending events, add them to the relations collection immediately.
+            // (The alternate case below already covers this as part of adding to
+            // the timeline set.)
+            this._aggregateNonLiveRelation(event);
+        }
+
+        if (event.isRedaction()) {
+            const redactId = event.event.redacts;
+            let redactedEvent = this._pendingEventList &&
+                this._pendingEventList.find(e => e.getId() === redactId);
+            if (!redactedEvent) {
+                redactedEvent = this.getUnfilteredTimelineSet().findEventById(redactId);
+            }
+            if (redactedEvent) {
+                redactedEvent.markLocallyRedacted(event);
+                this.emit("Room.redaction", event, this);
+            }
+        }
    } else {
        for (let i = 0; i < this._timelineSets.length; i++) {
            const timelineSet = this._timelineSets[i];
            if (timelineSet.getFilter()) {
-                if (this._filter.filterRoomTimeline([event]).length) {
+                if (timelineSet.getFilter().filterRoomTimeline([event]).length) {
                    timelineSet.addEventToTimeline(event,
                        timelineSet.getLiveTimeline(), false);
                }
@@ -1017,6 +1217,30 @@ Room.prototype.addPendingEvent = function(event, txnId) {

    this.emit("Room.localEchoUpdated", event, this, null, null);
 };
+/**
+ * Used to aggregate the local echo for a relation, and also
+ * for re-applying a relation after it's redaction has been cancelled,
+ * as the local echo for the redaction of the relation would have
+ * un-aggregated the relation. Note that this is different from regular messages,
+ * which are just kept detached for their local echo.
+ *
+ * Also note that live events are aggregated in the live EventTimelineSet.
+ * @param {module:models/event.MatrixEvent} event the relation event that needs to be aggregated.
+ */
+Room.prototype._aggregateNonLiveRelation = function(event) {
+    // TODO: We should consider whether this means it would be a better
+    // design to lift the relations handling up to the room instead.
+    for (let i = 0; i < this._timelineSets.length; i++) {
+        const timelineSet = this._timelineSets[i];
+        if (timelineSet.getFilter()) {
+            if (timelineSet.getFilter().filterRoomTimeline([event]).length) {
+                timelineSet.aggregateRelations(event);
+            }
+        } else {
+            timelineSet.aggregateRelations(event);
+        }
+    }
+};

 /**
 * Deal with the echo of a message we sent.
@@ -1038,7 +1262,7 @@ Room.prototype._handleRemoteEcho = function(remoteEvent, localEvent) {
    const oldStatus = localEvent.status;

    // no longer pending
-    delete this._txnToEvent[remoteEvent.transaction_id];
+    delete this._txnToEvent[remoteEvent.getUnsigned().transaction_id];

    // if it's in the pending list, remove it
    if (this._pendingEventList) {
@@ -1106,7 +1330,7 @@ ALLOWED_TRANSITIONS[EventStatus.CANCELLED] =
 * @fires module:client~MatrixClient#event:"Room.localEchoUpdated"
 */
 Room.prototype.updatePendingEvent = function(event, newStatus, newEventId) {
-    console.log(`setting pendingEvent status to ${newStatus} in ${event.getRoomId()}`);
+    logger.log(`setting pendingEvent status to ${newStatus} in ${event.getRoomId()}`);

    // if the message was sent, we expect an event id
    if (newStatus == EventStatus.SENT && !newEventId) {
@@ -1138,11 +1362,11 @@ Room.prototype.updatePendingEvent = function(event, newStatus, newEventId) {
                        newStatus);
    }

-    event.status = newStatus;
+    event.setStatus(newStatus);

    if (newStatus == EventStatus.SENT) {
        // update the event id
-        event.event.event_id = newEventId;
+        event.replaceLocalEventId(newEventId);

        // if the event was already in the timeline (which will be the case if
        // opts.pendingEventOrdering==chronological), we need to update the
@@ -1153,19 +1377,37 @@ Room.prototype.updatePendingEvent = function(event, newStatus, newEventId) {
    } else if (newStatus == EventStatus.CANCELLED) {
        // remove it from the pending event list, or the timeline.
        if (this._pendingEventList) {
-            utils.removeElement(
-                this._pendingEventList,
-                function(ev) {
-                    return ev.getId() == oldEventId;
-                }, false,
-            );
+            const idx = this._pendingEventList.findIndex(ev => ev.getId() === oldEventId);
+            if (idx !== -1) {
+                const [removedEvent] = this._pendingEventList.splice(idx, 1);
+                if (removedEvent.isRedaction()) {
+                    this._revertRedactionLocalEcho(removedEvent);
+                }
+            }
        }
        this.removeEvent(oldEventId);
    }

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

+Room.prototype._revertRedactionLocalEcho = function(redactionEvent) {
+    const redactId = redactionEvent.event.redacts;
+    if (!redactId) {
+        return;
+    }
+    const redactedEvent = this.getUnfilteredTimelineSet()
+        .findEventById(redactId);
+    if (redactedEvent) {
+        redactedEvent.unmarkLocallyRedacted();
+        // re-render after undoing redaction
+        this.emit("Room.redactionCancelled", redactionEvent, this);
+        // reapply relation now redaction failed
+        if (redactedEvent.isRelation()) {
+            this._aggregateNonLiveRelation(redactedEvent);
+        }
+    }
+};

 /**
 * Add some events to this room. This can include state events, message
@@ -1207,28 +1449,33 @@ Room.prototype.addLiveEvents = function(events, duplicateStrategy) {
    }

    for (i = 0; i < events.length; i++) {
-        if (events[i].getType() === "m.typing") {
-            this.currentState.setTypingEvent(events[i]);
-        } else if (events[i].getType() === "m.receipt") {
-            this.addReceipt(events[i]);
-        }
-        // N.B. account_data is added directly by /sync to avoid
-        // having to maintain an event.isAccountData() here
-        else {
-            // TODO: We should have a filter to say "only add state event
-            // types X Y Z to the timeline".
-            this._addLiveEvent(events[i], duplicateStrategy);
-        }
+        // TODO: We should have a filter to say "only add state event
+        // types X Y Z to the timeline".
+        this._addLiveEvent(events[i], duplicateStrategy);
+    }
+};
+
+/**
+ * Adds/handles ephemeral events such as typing notifications and read receipts.
+ * @param {MatrixEvent[]} events A list of events to process
+ */
+Room.prototype.addEphemeralEvents = function(events) {
+    for (const event of events) {
+        if (event.getType() === 'm.typing') {
+            this.currentState.setTypingEvent(event);
+        } else if (event.getType() === 'm.receipt') {
+            this.addReceipt(event);
+        } // else ignore - life is too short for us to care about these events
    }
 };

 /**
 * Removes events from this room.
- * @param {String[]} event_ids A list of event_ids to remove.
+ * @param {String[]} eventIds A list of eventIds to remove.
 */
-Room.prototype.removeEvents = function(event_ids) {
-    for (let i = 0; i < event_ids.length; ++i) {
-        this.removeEvent(event_ids[i]);
+Room.prototype.removeEvents = function(eventIds) {
+    for (let i = 0; i < eventIds.length; ++i) {
+        this.removeEvent(eventIds[i]);
    }
 };

@@ -1244,6 +1491,9 @@ Room.prototype.removeEvent = function(eventId) {
    for (let i = 0; i < this._timelineSets.length; i++) {
        const removed = this._timelineSets[i].removeEvent(eventId);
        if (removed) {
+            if (removed.isRedaction()) {
+                this._revertRedactionLocalEcho(removed);
+            }
            removedAny = true;
        }
    }
@@ -1333,6 +1583,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 +1890,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) {
@@ -1633,10 +1917,21 @@ module.exports = Room;
 * event).
 *
 * @event module:client~MatrixClient#"Room.redaction"
- * @param {MatrixEvent} event The matrix event which was redacted
+ * @param {MatrixEvent} event The matrix redaction event
 * @param {Room} room The room containing the redacted event
 */

+/**
+ * Fires when an event that was previously redacted isn't anymore.
+ * This happens when the redaction couldn't be sent and
+ * was subsequently cancelled by the user. Redactions have a local echo
+ * which is undone in this scenario.
+ *
+ * @event module:client~MatrixClient#"Room.redactionCancelled"
+ * @param {MatrixEvent} event The matrix redaction event that was cancelled.
+ * @param {Room} room The room containing the unredacted event
+ */
+
 /**
 * Fires whenever the name of a room is updated.
 * @event module:client~MatrixClient#"Room.name"
@@ -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,22 +14,73 @@ 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
 */

 const RULEKINDS_IN_ORDER = ['override', 'content', 'room', 'sender', 'underride'];

+// The default override rules to apply when calculating actions for an event. These
+// defaults apply under no other circumstances to avoid confusing the client with server
+// state. We do this for two reasons:
+//   1. Synapse is unlikely to send us the push rule in an incremental sync - see
+//      https://github.com/matrix-org/synapse/pull/4867#issuecomment-481446072 for
+//      more details.
+//   2. We often want to start using push rules ahead of the server supporting them,
+//      and so we can put them here.
+const DEFAULT_OVERRIDE_RULES = [
+    {
+        // For homeservers which don't support MSC1930 yet
+        rule_id: ".m.rule.tombstone",
+        default: true,
+        enabled: true,
+        conditions: [
+            {
+                kind: "event_match",
+                key: "type",
+                pattern: "m.room.tombstone",
+            },
+            {
+                kind: "event_match",
+                key: "state_key",
+                pattern: "",
+            },
+        ],
+        actions: [
+            "notify",
+            {
+                set_tweak: "highlight",
+                value: true,
+            },
+        ],
+    },
+    {
+        // For homeservers which don't support MSC2153 yet
+        rule_id: ".m.rule.reaction",
+        default: true,
+        enabled: true,
+        conditions: [
+            {
+                kind: "event_match",
+                key: "type",
+                pattern: "m.reaction",
+            },
+        ],
+        actions: [
+            "dont_notify",
+        ],
+    },
+];
+
 /**
 * Construct a Push Processor.
 * @constructor
 * @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 +236,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 +298,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;
@@ -326,6 +364,33 @@ function PushProcessor(client) {
        return actionObj;
    };

+    const applyRuleDefaults = function(clientRuleset) {
+        // Deep clone the object before we mutate it
+        const ruleset = JSON.parse(JSON.stringify(clientRuleset));
+
+        if (!clientRuleset['global']) {
+            clientRuleset['global'] = {};
+        }
+        if (!clientRuleset['global']['override']) {
+            clientRuleset['global']['override'] = [];
+        }
+
+        // Apply default overrides
+        const globalOverrides = clientRuleset['global']['override'];
+        for (const override of DEFAULT_OVERRIDE_RULES) {
+            const existingRule = globalOverrides
+                .find((r) => r.rule_id === override.rule_id);
+
+            if (!existingRule) {
+                const ruleId = override.rule_id;
+                console.warn(`Adding default global override for ${ruleId}`);
+                globalOverrides.push(override);
+            }
+        }
+
+        return ruleset;
+    };
+
    this.ruleMatchesEvent = function(rule, ev) {
        let ret = true;
        for (let i = 0; i < rule.conditions.length; ++i) {
@@ -345,7 +410,8 @@ function PushProcessor(client) {
     * @return {PushAction}
     */
    this.actionsForEvent = function(ev) {
-        return pushActionsForEventAndRulesets(ev, client.pushRules);
+        const rules = applyRuleDefaults(client.pushRules);
+        return pushActionsForEventAndRulesets(ev, rules);
    };

    /**
@@ -394,6 +460,38 @@ PushProcessor.actionListToActionsObject = function(actionlist) {
    return actionobj;
 };

+/**
+ * Rewrites conditions on a client's push rules to match the defaults
+ * where applicable. Useful for upgrading push rules to more strict
+ * conditions when the server is falling behind on defaults.
+ * @param {object} incomingRules The client's existing push rules
+ * @returns {object} The rewritten rules
+ */
+PushProcessor.rewriteDefaultRules = function(incomingRules) {
+    let newRules = JSON.parse(JSON.stringify(incomingRules)); // deep clone
+
+    // These lines are mostly to make the tests happy. We shouldn't run into these
+    // properties missing in practice.
+    if (!newRules) newRules = {};
+    if (!newRules.global) newRules.global = {};
+    if (!newRules.global.override) newRules.global.override = [];
+
+    // Fix default override rules
+    newRules.global.override = newRules.global.override.map(r => {
+        const defaultRule = DEFAULT_OVERRIDE_RULES.find(d => d.rule_id === r.rule_id);
+        if (!defaultRule) return r;
+
+        // Copy over the actions, default, and conditions. Don't touch the user's
+        // preference.
+        r.default = defaultRule.default;
+        r.conditions = defaultRule.conditions;
+        r.actions = defaultRule.actions;
+        return r;
+    });
+
+    return newRules;
+};
+
 /**
 * @typedef {Object} PushAction
 * @type {Object}
@@ -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;
+}
@@ -24,6 +24,7 @@ limitations under the License.
 */

 "use strict";
+import logger from './logger';

 // we schedule a callback at least this often, to check if we've missed out on
 // some wall-clock time due to being suspended.
@@ -39,7 +40,7 @@ let _realCallbackKey;
 // each is an object with keys [runAt, func, params, key].
 const _callbackList = [];

-// var debuglog = console.log.bind(console);
+// var debuglog = logger.log.bind(logger);
 const debuglog = function() {};

 /**
@@ -170,7 +171,7 @@ function _runCallbacks() {
        try {
            cb.func.apply(global, cb.params);
        } catch (e) {
-            console.error("Uncaught exception in callback function",
+            logger.error("Uncaught exception in callback function",
                          e.stack || e);
        }
    }
@@ -21,6 +21,7 @@ limitations under the License.
 */
 const utils = require("./utils");
 import Promise from 'bluebird';
+import logger from './logger';

 const DEBUG = false;  // set true to enable console logging.

@@ -176,7 +177,8 @@ MatrixScheduler.RETRY_BACKOFF_RATELIMIT = function(event, attempts, err) {
 * @see module:scheduler~queueAlgorithm
 */
 MatrixScheduler.QUEUE_MESSAGES = function(event) {
-    if (event.getType() === "m.room.message") {
+    // enqueue messages or events that associate with another event (redactions and relations)
+    if (event.getType() === "m.room.message" || event.hasAssocation()) {
        // put these events in the 'message' queue.
        return "message";
    }
@@ -219,7 +221,14 @@ function _processQueue(scheduler, queueName) {
    );
    // fire the process function and if it resolves, resolve the deferred. Else
    // invoke the retry algorithm.
-    scheduler._procFn(obj.event).done(function(res) {
+
+    // First wait for a resolved promise, so the resolve handlers for
+    // the deferred of the previously sent event can run.
+    // This way enqueued relations/redactions to enqueued events can receive
+    // the remove id of their target before being sent.
+    Promise.resolve().then(() => {
+        return scheduler._procFn(obj.event);
+    }).then(function(res) {
        // remove this from the queue
        _removeNextEvent(scheduler, queueName);
        debuglog("Queue '%s' sent event %s", queueName, obj.event.getId());
@@ -269,7 +278,7 @@ function _removeNextEvent(scheduler, queueName) {

 function debuglog() {
    if (DEBUG) {
-        console.log(...arguments);
+        logger.log(...arguments);
    }
 }

--- a/Show More
+++ b/Show More