feat: End-to-End Encryption with historical key sharing

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
-playground/
+playground/.env
+playground/.state.json

index.mjs

@@ -5,7 +5,9 @@ import { CommandAPI } from './src/command-api.mjs'
 import { ProjectList } from './src/project-list.mjs'
 import { Project } from './src/project.mjs'
 import { discover, errors } from './src/discover-api.mjs'
+import { setLogger, LEVELS, consoleLogger, noopLogger } from './src/logger.mjs'
 import { chill } from './src/convenience.mjs'
+import { CryptoManager, VerificationMethod, VerificationRequestPhase } from './src/crypto.mjs'
 
 /*
   connect() resolves if the home_server can be connected. It does
@@ -36,45 +38,108 @@ const connect = (home_server_url) => async (controller) => {
  * @property {String} user_id
  * @property {String} password
  * @property {String} home_server_url
+ * @property {Object} [encryption] - Optional encryption configuration
+ * @property {boolean} [encryption.enabled=false] - Enable E2EE
+ * @property {string} [encryption.storeName] - IndexedDB store name for persistent crypto state (e.g. 'crypto-<projectUUID>')
+ * @property {string} [encryption.passphrase] - Passphrase to encrypt the IndexedDB store
  * 
  * @param {LoginData} loginData 
  * @returns {Object} matrixClient
  */
-const MatrixClient = (loginData) => ({
+const MatrixClient = (loginData) => {
 
-  connect: connect(loginData.home_server_url),
-
-  projectList: async mostRecentCredentials => {
-
-    const credentials = mostRecentCredentials ? mostRecentCredentials : (await HttpAPI.loginWithPassword(loginData))
-    const httpAPI = new HttpAPI(credentials)
-    const projectListParames = {
-      structureAPI: new StructureAPI(httpAPI),
-      timelineAPI: new TimelineAPI(httpAPI)
+  const encryption = loginData.encryption || null
+
+  // Shared CryptoManager instance – initialized once, reused across projectList/project calls
+  let sharedCryptoManager = null
+  let cryptoInitialized = false
+
+  /**
+   * Get or create the shared CryptoManager.
+   * If encryption.storeName is provided, uses IndexedDB-backed persistent store.
+   * Otherwise, uses in-memory store (keys lost on restart).
+   * @param {HttpAPI} httpAPI
+   * @returns {Promise<{cryptoManager: CryptoManager, httpAPI: HttpAPI} | null>}
+   */
+  const getCrypto = async (httpAPI) => {
+    if (!encryption?.enabled) return null
+    if (sharedCryptoManager) {
+      // Reuse existing CryptoManager, just process any pending outgoing requests
+      if (!cryptoInitialized) {
+        await httpAPI.processOutgoingCryptoRequests(sharedCryptoManager)
+        cryptoInitialized = true
+      }
+      return { cryptoManager: sharedCryptoManager, httpAPI }
     }
-    const projectList = new ProjectList(projectListParames)
-    projectList.tokenRefreshed = handler => httpAPI.tokenRefreshed(handler)
-    projectList.credentials = () => (httpAPI.credentials)
-    return projectList
-  },
+    const credentials = httpAPI.credentials
+    if (!credentials.device_id) {
+      throw new Error('E2EE requires a device_id in credentials. Ensure a fresh login (delete .state.json if reusing saved credentials).')
+    }
+    sharedCryptoManager = new CryptoManager()
 
-  project: async mostRecentCredentials => {
-    const credentials = mostRecentCredentials ? mostRecentCredentials : (await HttpAPI.loginWithPassword(loginData))
-    const httpAPI = new HttpAPI(credentials)
-    const projectParams = {
-      structureAPI: new StructureAPI(httpAPI),
-      timelineAPI: new TimelineAPI(httpAPI),
-      commandAPI: new CommandAPI(httpAPI)
+    if (encryption.storeName) {
+      // Persistent store: crypto state survives restarts (requires IndexedDB, i.e. Electron/browser)
+      await sharedCryptoManager.initializeWithStore(
+        credentials.user_id,
+        credentials.device_id,
+        encryption.storeName,
+        encryption.passphrase
+      )
+    } else {
+      // In-memory: keys are lost on restart (for testing or non-browser environments)
+      await sharedCryptoManager.initialize(credentials.user_id, credentials.device_id)
     }
-    const project = new Project(projectParams)
-    project.tokenRefreshed = handler => httpAPI.tokenRefreshed(handler)
-    project.credentials = () => (httpAPI.credentials)
-    return project
+
+    await httpAPI.processOutgoingCryptoRequests(sharedCryptoManager)
+    cryptoInitialized = true
+    return { cryptoManager: sharedCryptoManager, httpAPI }
   }
-})
+
+  return {
+    connect: connect(loginData.home_server_url),
+
+    projectList: async mostRecentCredentials => {
+      const credentials = mostRecentCredentials ? mostRecentCredentials : (await HttpAPI.loginWithPassword(loginData))
+      const httpAPI = new HttpAPI(credentials)
+      const crypto = await getCrypto(httpAPI)
+      const projectListParames = {
+        structureAPI: new StructureAPI(httpAPI),
+        timelineAPI: new TimelineAPI(httpAPI, crypto)
+      }
+      const projectList = new ProjectList(projectListParames)
+      projectList.tokenRefreshed = handler => httpAPI.tokenRefreshed(handler)
+      projectList.credentials = () => (httpAPI.credentials)
+      if (crypto) projectList.cryptoManager = crypto.cryptoManager
+      return projectList
+    },
+
+    project: async mostRecentCredentials => {
+      const credentials = mostRecentCredentials ? mostRecentCredentials : (await HttpAPI.loginWithPassword(loginData))
+      const httpAPI = new HttpAPI(credentials)
+      const crypto = await getCrypto(httpAPI)
+      const projectParams = {
+        structureAPI: new StructureAPI(httpAPI),
+        timelineAPI: new TimelineAPI(httpAPI, crypto),
+        commandAPI: new CommandAPI(httpAPI, crypto?.cryptoManager || null),
+        cryptoManager: crypto?.cryptoManager || null
+      }
+      const project = new Project(projectParams)
+      project.tokenRefreshed = handler => httpAPI.tokenRefreshed(handler)
+      project.credentials = () => (httpAPI.credentials)
+      return project
+    }
+  }
+}
 
 export {
   MatrixClient,
+  CryptoManager,
+  VerificationMethod,
+  VerificationRequestPhase,
   connect,
-  discover
-}
+  discover,
+  setLogger,
+  LEVELS,
+  consoleLogger,
+  noopLogger
+}

package.json

@@ -4,7 +4,8 @@
   "description": "A minimal client API for [matrix]",
   "main": "index.mjs",
   "scripts": {
-    "test": "mocha ./test/*"
+    "test": "mocha ./test/*",
+    "test:e2e": "mocha --timeout 30000 ./test-e2e/*.test.mjs"
   },
   "keywords": [
     "Matrix",
@@ -14,6 +15,7 @@
   "author": "thomas.halwax@syncpoint.io",
   "license": "MIT",
   "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-wasm": "^17.1.0",
     "js-base64": "^3.7.7",
     "ky": "^1.7.2"
   },

playground/.env.example

@@ -0,0 +1,6 @@
+# Copy to .env and fill in your values
+MATRIX_HOMESERVER=https://matrix.example.com
+MATRIX_USER=@user:example.com
+MATRIX_PASSWORD=your-password
+# Set to "true" to enable E2EE (requires @matrix-org/matrix-sdk-crypto-wasm)
+MATRIX_ENCRYPTION=false

playground/README.md

@@ -0,0 +1,47 @@
+# Playground
+
+Interactive CLI to test the `matrix-client-api`.
+
+## Setup
+
+```bash
+cd playground
+cp .env.example .env
+# Edit .env with your Matrix credentials
+```
+
+## Run
+
+```bash
+node cli.mjs
+```
+
+## Commands
+
+Type `help` in the CLI for a full command list. Quick start:
+
+```
+login                        # Connect and authenticate
+projects                     # List your projects
+open <odin-id>               # Open a specific project
+layers                       # See layers in the project
+layer-content <layer-id>     # Fetch layer operations
+listen                       # Stream live changes
+stop                         # Stop streaming
+loglevel 3                   # Enable DEBUG logging
+```
+
+## E2EE
+
+Set `MATRIX_ENCRYPTION=true` in `.env` to enable End-to-End Encryption.
+Use `crypto-status` to check the OlmMachine state after login.
+
+## Session Persistence
+
+After login, credentials are saved to `.state.json` so you don't need to re-authenticate every time. Delete this file to force a fresh login.
+
+## Notes
+
+- This playground uses the library directly via relative import (`../index.mjs`)
+- No `npm install` needed in the playground dir (dependencies come from the parent)
+- The `.env` and `.state.json` files are gitignored