@unwanted/matrix-sdk-mini 34.12.0-1

package/src/crypto/OlmDevice.ts

@@ -0,0 +1,1500 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { Account, InboundGroupSession, OutboundGroupSession, Session, Utility } from "@matrix-org/olm";
+
+import { logger, Logger } from "../logger.ts";
+import { IndexedDBCryptoStore } from "./store/indexeddb-crypto-store.ts";
+import { CryptoStore, IProblem, ISessionInfo, IWithheld } from "./store/base.ts";
+import { IOlmDevice, IOutboundGroupSessionKey } from "./algorithms/megolm.ts";
+import { IMegolmSessionData, OlmGroupSessionExtraData } from "../@types/crypto.ts";
+import { IMessage } from "./algorithms/olm.ts";
+import { DecryptionFailureCode } from "../crypto-api/index.ts";
+import { DecryptionError } from "../common-crypto/CryptoBackend.ts";
+
+// 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;
+
+export class PayloadTooLargeError extends Error {
+    public readonly data = {
+        errcode: "M_TOO_LARGE",
+        error: "Payload too large for encrypted message",
+    };
+}
+
+function checkPayloadLength(payloadString: string): void {
+    if (payloadString === undefined) {
+        throw new Error("payloadString undefined");
+    }
+
+    if (payloadString.length > MAX_PLAINTEXT_LENGTH) {
+        // might as well fail early here rather than letting the olm library throw
+        // a cryptic memory allocation error.
+        //
+        // Note that even if we manage to do the encryption, the message send may fail,
+        // because by the time we've wrapped the ciphertext in the event object, it may
+        // exceed 65K. But at least we won't just fail with "abort()" in that case.
+        throw new PayloadTooLargeError(
+            `Message too long (${payloadString.length} bytes). ` +
+                `The maximum for an encrypted message is ${MAX_PLAINTEXT_LENGTH} bytes.`,
+        );
+    }
+}
+
+interface IInitOpts {
+    /**
+     * (Optional) data from exported device that must be re-created.
+     * If present, opts.pickleKey is ignored (exported data already provides a pickle key)
+     */
+    fromExportedDevice?: IExportedDevice;
+    /**
+     * (Optional) pickle key to set instead of default one
+     */
+    pickleKey?: string;
+}
+
+/** data stored in the session store about an inbound group session */
+export interface InboundGroupSessionData {
+    room_id: string; // eslint-disable-line camelcase
+    /** pickled Olm.InboundGroupSession */
+    session: string;
+    keysClaimed?: Record<string, string>;
+    /** Devices involved in forwarding this session to us (normally empty). */
+    forwardingCurve25519KeyChain: string[];
+    /** whether this session is untrusted. */
+    untrusted?: boolean;
+    /** whether this session exists during the room being set to shared history. */
+    sharedHistory?: boolean;
+}
+
+export interface IDecryptedGroupMessage {
+    result: string;
+    keysClaimed: Record<string, string>;
+    senderKey: string;
+    forwardingCurve25519KeyChain: string[];
+    untrusted: boolean;
+}
+
+export interface IInboundSession {
+    payload: string;
+    session_id: string;
+}
+
+export interface IExportedDevice {
+    pickleKey: string;
+    pickledAccount: string;
+    sessions: ISessionInfo[];
+}
+
+interface IUnpickledSessionInfo extends Omit<ISessionInfo, "session"> {
+    session: Session;
+}
+
+/* eslint-disable camelcase */
+interface IInboundGroupSessionKey {
+    chain_index: number;
+    key: string;
+    forwarding_curve25519_key_chain: string[];
+    sender_claimed_ed25519_key: string | null;
+    shared_history: boolean;
+    untrusted?: boolean;
+}
+/* eslint-enable camelcase */
+
+type OneTimeKeys = { curve25519: { [keyId: string]: string } };
+
+/**
+ * Manages the olm cryptography functions. Each OlmDevice has a single
+ * OlmAccount and a number of OlmSessions.
+ *
+ * Accounts and sessions are kept pickled in the cryptoStore.
+ */
+export class OlmDevice {
+    public pickleKey = "DEFAULT_KEY"; // set by consumers
+
+    /** Curve25519 key for the account, unknown until we load the account from storage in init() */
+    public deviceCurve25519Key: string | null = null;
+    /** Ed25519 key for the account, unknown until we load the account from storage in init() */
+    public deviceEd25519Key: string | null = null;
+    private maxOneTimeKeys: number | null = null;
+
+    // we don't bother stashing outboundgroupsessions in the cryptoStore -
+    // instead we keep them here.
+    private outboundGroupSessionStore: Record<string, string> = {};
+
+    // Store a set of decrypted message indexes for each group session.
+    // This partially mitigates a replay attack where a MITM resends a group
+    // message into the room.
+    //
+    // When we decrypt a message and the message index matches a previously
+    // decrypted message, one possible cause of that is that we are decrypting
+    // the same event, and may not indicate an actual replay attack.  For
+    // example, this could happen if we receive events, forget about them, and
+    // then re-fetch them when we backfill.  So we store the event ID and
+    // timestamp corresponding to each message index when we first decrypt it,
+    // and compare these against the event ID and timestamp every time we use
+    // that same index.  If they match, then we're probably decrypting the same
+    // event and we don't consider it a replay attack.
+    //
+    // Keys are strings of form "<senderKey>|<session_id>|<message_index>"
+    // Values are objects of the form "{id: <event id>, timestamp: <ts>}"
+    private inboundGroupSessionMessageIndexes: Record<string, { id: string; timestamp: number }> = {};
+
+    // Keep track of sessions that we're starting, so that we don't start
+    // multiple sessions for the same device at the same time.
+    public sessionsInProgress: Record<string, Promise<void>> = {}; // set by consumers
+
+    // Used by olm to serialise prekey message decryptions
+    public olmPrekeyPromise: Promise<any> = Promise.resolve(); // set by consumers
+
+    public constructor(private readonly cryptoStore: CryptoStore) {}
+
+    /**
+     * @returns The version of Olm.
+     */
+    public static getOlmVersion(): [number, number, number] {
+        return globalThis.Olm.get_library_version();
+    }
+
+    /**
+     * Initialise the OlmAccount. This must be called before any other operations
+     * on the OlmDevice.
+     *
+     * Data from an exported Olm device can be provided
+     * in order to re-create this device.
+     *
+     * Attempts to load the OlmAccount from the crypto store, or creates one if none is
+     * found.
+     *
+     * Reads the device keys from the OlmAccount object.
+     *
+     * @param IInitOpts - opts to initialise the OlmAccount with
+     */
+    public async init({ pickleKey, fromExportedDevice }: IInitOpts = {}): Promise<void> {
+        let e2eKeys;
+        const account = new globalThis.Olm.Account();
+
+        try {
+            if (fromExportedDevice) {
+                if (pickleKey) {
+                    logger.warn("ignoring opts.pickleKey" + " because opts.fromExportedDevice is present.");
+                }
+                this.pickleKey = fromExportedDevice.pickleKey;
+                await this.initialiseFromExportedDevice(fromExportedDevice, account);
+            } else {
+                if (pickleKey) {
+                    this.pickleKey = pickleKey;
+                }
+                await this.initialiseAccount(account);
+            }
+            e2eKeys = JSON.parse(account.identity_keys());
+
+            this.maxOneTimeKeys = account.max_number_of_one_time_keys();
+        } finally {
+            account.free();
+        }
+
+        this.deviceCurve25519Key = e2eKeys.curve25519;
+        this.deviceEd25519Key = e2eKeys.ed25519;
+    }
+
+    /**
+     * Populates the crypto store using data that was exported from an existing device.
+     * Note that for now only the “account” and “sessions” stores are populated;
+     * Other stores will be as with a new device.
+     *
+     * @param exportedData - Data exported from another device
+     *     through the “export” method.
+     * @param account - an olm account to initialize
+     */
+    private async initialiseFromExportedDevice(exportedData: IExportedDevice, account: Account): Promise<void> {
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [IndexedDBCryptoStore.STORE_ACCOUNT, IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.cryptoStore.storeAccount(txn, exportedData.pickledAccount);
+                exportedData.sessions.forEach((session) => {
+                    const { deviceKey, sessionId } = session;
+                    const sessionInfo = {
+                        session: session.session,
+                        lastReceivedMessageTs: session.lastReceivedMessageTs,
+                    };
+                    this.cryptoStore.storeEndToEndSession(deviceKey!, sessionId!, sessionInfo, txn);
+                });
+            },
+        );
+        account.unpickle(this.pickleKey, exportedData.pickledAccount);
+    }
+
+    private async initialiseAccount(account: Account): Promise<void> {
+        await this.cryptoStore.doTxn("readwrite", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.cryptoStore.getAccount(txn, (pickledAccount) => {
+                if (pickledAccount !== null) {
+                    account.unpickle(this.pickleKey, pickledAccount);
+                } else {
+                    account.create();
+                    pickledAccount = account.pickle(this.pickleKey);
+                    this.cryptoStore.storeAccount(txn, pickledAccount);
+                }
+            });
+        });
+    }
+
+    /**
+     * extract our OlmAccount from the crypto store and call the given function
+     * with the account object
+     * The `account` object is usable only within the callback passed to this
+     * function and will be freed as soon the callback returns. It is *not*
+     * usable for the rest of the lifetime of the transaction.
+     * This function requires a live transaction object from cryptoStore.doTxn()
+     * and therefore may only be called in a doTxn() callback.
+     *
+     * @param txn - Opaque transaction object from cryptoStore.doTxn()
+     * @internal
+     */
+    private getAccount(txn: unknown, func: (account: Account) => void): void {
+        this.cryptoStore.getAccount(txn, (pickledAccount: string | null) => {
+            const account = new globalThis.Olm.Account();
+            try {
+                account.unpickle(this.pickleKey, pickledAccount!);
+                func(account);
+            } finally {
+                account.free();
+            }
+        });
+    }
+
+    /*
+     * Saves an account to the crypto store.
+     * This function requires a live transaction object from cryptoStore.doTxn()
+     * and therefore may only be called in a doTxn() callback.
+     *
+     * @param txn - Opaque transaction object from cryptoStore.doTxn()
+     * @param Olm.Account object
+     * @internal
+     */
+    private storeAccount(txn: unknown, account: Account): void {
+        this.cryptoStore.storeAccount(txn, account.pickle(this.pickleKey));
+    }
+
+    /**
+     * Export data for re-creating the Olm device later.
+     * TODO export data other than just account and (P2P) sessions.
+     *
+     * @returns The exported data
+     */
+    public async export(): Promise<IExportedDevice> {
+        const result: Partial<IExportedDevice> = {
+            pickleKey: this.pickleKey,
+        };
+
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [IndexedDBCryptoStore.STORE_ACCOUNT, IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.cryptoStore.getAccount(txn, (pickledAccount: string | null) => {
+                    result.pickledAccount = pickledAccount!;
+                });
+                result.sessions = [];
+                // Note that the pickledSession object we get in the callback
+                // is not exactly the same thing you get in method _getSession
+                // see documentation of IndexedDBCryptoStore.getAllEndToEndSessions
+                this.cryptoStore.getAllEndToEndSessions(txn, (pickledSession) => {
+                    result.sessions!.push(pickledSession!);
+                });
+            },
+        );
+        return result as IExportedDevice;
+    }
+
+    /**
+     * extract an OlmSession from the session store and call the given function
+     * The session is usable only within the callback passed to this
+     * function and will be freed as soon the callback returns. It is *not*
+     * usable for the rest of the lifetime of the transaction.
+     *
+     * @param txn - Opaque transaction object from cryptoStore.doTxn()
+     * @internal
+     */
+    private getSession(
+        deviceKey: string,
+        sessionId: string,
+        txn: unknown,
+        func: (unpickledSessionInfo: IUnpickledSessionInfo) => void,
+    ): void {
+        this.cryptoStore.getEndToEndSession(deviceKey, sessionId, txn, (sessionInfo: ISessionInfo | null) => {
+            this.unpickleSession(sessionInfo!, func);
+        });
+    }
+
+    /**
+     * Creates a session object from a session pickle and executes the given
+     * function with it. The session object is destroyed once the function
+     * returns.
+     *
+     * @internal
+     */
+    private unpickleSession(
+        sessionInfo: ISessionInfo,
+        func: (unpickledSessionInfo: IUnpickledSessionInfo) => void,
+    ): void {
+        const session = new globalThis.Olm.Session();
+        try {
+            session.unpickle(this.pickleKey, sessionInfo.session!);
+            const unpickledSessInfo: IUnpickledSessionInfo = Object.assign({}, sessionInfo, { session });
+
+            func(unpickledSessInfo);
+        } finally {
+            session.free();
+        }
+    }
+
+    /**
+     * store our OlmSession in the session store
+     *
+     * @param sessionInfo - `{session: OlmSession, lastReceivedMessageTs: int}`
+     * @param txn - Opaque transaction object from cryptoStore.doTxn()
+     * @internal
+     */
+    private saveSession(deviceKey: string, sessionInfo: IUnpickledSessionInfo, txn: unknown): void {
+        const sessionId = sessionInfo.session.session_id();
+        logger.debug(`Saving Olm session ${sessionId} with device ${deviceKey}: ${sessionInfo.session.describe()}`);
+
+        // Why do we re-use the input object for this, overwriting the same key with a different
+        // type? Is it because we want to erase the unpickled session to enforce that it's no longer
+        // used? A comment would be great.
+        const pickledSessionInfo = Object.assign(sessionInfo, {
+            session: sessionInfo.session.pickle(this.pickleKey),
+        });
+        this.cryptoStore.storeEndToEndSession(deviceKey, sessionId, pickledSessionInfo, txn);
+    }
+
+    /**
+     * get an OlmUtility and call the given function
+     *
+     * @returns result of func
+     * @internal
+     */
+    private getUtility<T>(func: (utility: Utility) => T): T {
+        const utility = new globalThis.Olm.Utility();
+        try {
+            return func(utility);
+        } finally {
+            utility.free();
+        }
+    }
+
+    /**
+     * Signs a message with the ed25519 key for this account.
+     *
+     * @param message -  message to be signed
+     * @returns base64-encoded signature
+     */
+    public async sign(message: string): Promise<string> {
+        let result: string;
+        await this.cryptoStore.doTxn("readonly", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account: Account) => {
+                result = account.sign(message);
+            });
+        });
+        return result!;
+    }
+
+    /**
+     * Get the current (unused, unpublished) one-time keys for this account.
+     *
+     * @returns one time keys; an object with the single property
+     * <tt>curve25519</tt>, which is itself an object mapping key id to Curve25519
+     * key.
+     */
+    public async getOneTimeKeys(): Promise<OneTimeKeys> {
+        let result: OneTimeKeys;
+        await this.cryptoStore.doTxn("readonly", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account) => {
+                result = JSON.parse(account.one_time_keys());
+            });
+        });
+
+        return result!;
+    }
+
+    /**
+     * Get the maximum number of one-time keys we can store.
+     *
+     * @returns number of keys
+     */
+    public maxNumberOfOneTimeKeys(): number {
+        return this.maxOneTimeKeys ?? -1;
+    }
+
+    /**
+     * Marks all of the one-time keys as published.
+     */
+    public async markKeysAsPublished(): Promise<void> {
+        await this.cryptoStore.doTxn("readwrite", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account: Account) => {
+                account.mark_keys_as_published();
+                this.storeAccount(txn, account);
+            });
+        });
+    }
+
+    /**
+     * Generate some new one-time keys
+     *
+     * @param numKeys - number of keys to generate
+     * @returns Resolved once the account is saved back having generated the keys
+     */
+    public generateOneTimeKeys(numKeys: number): Promise<void> {
+        return this.cryptoStore.doTxn("readwrite", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account) => {
+                account.generate_one_time_keys(numKeys);
+                this.storeAccount(txn, account);
+            });
+        });
+    }
+
+    /**
+     * Generate a new fallback keys
+     *
+     * @returns Resolved once the account is saved back having generated the key
+     */
+    public async generateFallbackKey(): Promise<void> {
+        await this.cryptoStore.doTxn("readwrite", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account) => {
+                account.generate_fallback_key();
+                this.storeAccount(txn, account);
+            });
+        });
+    }
+
+    public async getFallbackKey(): Promise<Record<string, Record<string, string>>> {
+        let result: Record<string, Record<string, string>>;
+        await this.cryptoStore.doTxn("readonly", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account: Account) => {
+                result = JSON.parse(account.unpublished_fallback_key());
+            });
+        });
+        return result!;
+    }
+
+    public async forgetOldFallbackKey(): Promise<void> {
+        await this.cryptoStore.doTxn("readwrite", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
+            this.getAccount(txn, (account: Account) => {
+                account.forget_old_fallback_key();
+                this.storeAccount(txn, account);
+            });
+        });
+    }
+
+    /**
+     * Generate a new outbound session
+     *
+     * The new session will be stored in the cryptoStore.
+     *
+     * @param theirIdentityKey - remote user's Curve25519 identity key
+     * @param theirOneTimeKey -  remote user's one-time Curve25519 key
+     * @returns sessionId for the outbound session.
+     */
+    public async createOutboundSession(theirIdentityKey: string, theirOneTimeKey: string): Promise<string> {
+        let newSessionId: string;
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [IndexedDBCryptoStore.STORE_ACCOUNT, IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.getAccount(txn, (account: Account) => {
+                    const session = new globalThis.Olm.Session();
+                    try {
+                        session.create_outbound(account, theirIdentityKey, theirOneTimeKey);
+                        newSessionId = session.session_id();
+                        this.storeAccount(txn, account);
+                        const sessionInfo: IUnpickledSessionInfo = {
+                            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();
+                    }
+                });
+            },
+            logger.getChild("[createOutboundSession]"),
+        );
+        return newSessionId!;
+    }
+
+    /**
+     * Generate a new inbound session, given an incoming message
+     *
+     * @param theirDeviceIdentityKey - remote user's Curve25519 identity key
+     * @param messageType -  messageType field from the received message (must be 0)
+     * @param ciphertext - base64-encoded body from the received message
+     *
+     * @returns decrypted payload, and
+     *     session id of new session
+     *
+     * @throws Error if the received message was not valid (for instance, it didn't use a valid one-time key).
+     */
+    public async createInboundSession(
+        theirDeviceIdentityKey: string,
+        messageType: number,
+        ciphertext: string,
+    ): Promise<IInboundSession> {
+        if (messageType !== 0) {
+            throw new Error("Need messageType == 0 to create inbound session");
+        }
+
+        let result: { payload: string; session_id: string }; // eslint-disable-line camelcase
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [IndexedDBCryptoStore.STORE_ACCOUNT, IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.getAccount(txn, (account: Account) => {
+                    const session = new globalThis.Olm.Session();
+                    try {
+                        session.create_inbound_from(account, theirDeviceIdentityKey, ciphertext);
+                        account.remove_one_time_keys(session);
+                        this.storeAccount(txn, account);
+
+                        const payloadString = session.decrypt(messageType, ciphertext);
+
+                        const sessionInfo: IUnpickledSessionInfo = {
+                            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,
+                            session_id: session.session_id(),
+                        };
+                    } finally {
+                        session.free();
+                    }
+                });
+            },
+            logger.getChild("[createInboundSession]"),
+        );
+
+        return result!;
+    }
+
+    /**
+     * Get a list of known session IDs for the given device
+     *
+     * @param theirDeviceIdentityKey - Curve25519 identity key for the
+     *     remote device
+     * @returns  a list of known session ids for the device
+     */
+    public async getSessionIdsForDevice(theirDeviceIdentityKey: string): Promise<string[]> {
+        const log = logger.getChild("[getSessionIdsForDevice]");
+
+        if (theirDeviceIdentityKey in this.sessionsInProgress) {
+            log.debug(`Waiting for Olm session for ${theirDeviceIdentityKey} to be created`);
+            try {
+                await this.sessionsInProgress[theirDeviceIdentityKey];
+            } catch {
+                // if the session failed to be created, just fall through and
+                // return an empty result
+            }
+        }
+        let sessionIds: string[];
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.cryptoStore.getEndToEndSessions(theirDeviceIdentityKey, txn, (sessions) => {
+                    sessionIds = Object.keys(sessions);
+                });
+            },
+            log,
+        );
+
+        return sessionIds!;
+    }
+
+    /**
+     * Get the right olm session id for encrypting messages to the given identity key
+     *
+     * @param theirDeviceIdentityKey - Curve25519 identity key for the
+     *     remote device
+     * @param 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.
+     * @param log - A possibly customised log
+     * @returns  session id, or null if no established session
+     */
+    public async getSessionIdForDevice(
+        theirDeviceIdentityKey: string,
+        nowait = false,
+        log?: Logger,
+    ): Promise<string | null> {
+        const sessionInfos = await this.getSessionInfoForDevice(theirDeviceIdentityKey, nowait, log);
+
+        if (sessionInfos.length === 0) {
+            return null;
+        }
+        // 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;
+    }
+
+    /**
+     * Get information on the active Olm sessions for a device.
+     * <p>
+     * Returns an array, with an entry for each active session. The first entry in
+     * the result will be the one used for outgoing messages. Each entry contains
+     * the keys 'hasReceivedMessage' (true if the session has received an incoming
+     * message and is therefore past the pre-key stage), and 'sessionId'.
+     *
+     * @param deviceIdentityKey - Curve25519 identity key for the device
+     * @param 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.
+     * @param log - A possibly customised log
+     */
+    public async getSessionInfoForDevice(
+        deviceIdentityKey: string,
+        nowait = false,
+        log: Logger = logger,
+    ): Promise<{ sessionId: string; lastReceivedMessageTs: number; hasReceivedMessage: boolean }[]> {
+        log = log.getChild("[getSessionInfoForDevice]");
+
+        if (deviceIdentityKey in this.sessionsInProgress && !nowait) {
+            log.debug(`Waiting for Olm session for ${deviceIdentityKey} to be created`);
+            try {
+                await this.sessionsInProgress[deviceIdentityKey];
+            } catch {
+                // if the session failed to be created, then just fall through and
+                // return an empty result
+            }
+        }
+        const info: {
+            lastReceivedMessageTs: number;
+            hasReceivedMessage: boolean;
+            sessionId: string;
+        }[] = [];
+
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.cryptoStore.getEndToEndSessions(deviceIdentityKey, txn, (sessions) => {
+                    const sessionIds = Object.keys(sessions).sort();
+                    for (const sessionId of sessionIds) {
+                        this.unpickleSession(sessions[sessionId], (sessInfo: IUnpickledSessionInfo) => {
+                            info.push({
+                                lastReceivedMessageTs: sessInfo.lastReceivedMessageTs!,
+                                hasReceivedMessage: sessInfo.session.has_received_message(),
+                                sessionId,
+                            });
+                        });
+                    }
+                });
+            },
+            log,
+        );
+
+        return info;
+    }
+
+    /**
+     * Encrypt an outgoing message using an existing session
+     *
+     * @param theirDeviceIdentityKey - Curve25519 identity key for the
+     *     remote device
+     * @param sessionId -  the id of the active session
+     * @param payloadString -  payload to be encrypted and sent
+     *
+     * @returns ciphertext
+     */
+    public async encryptMessage(
+        theirDeviceIdentityKey: string,
+        sessionId: string,
+        payloadString: string,
+    ): Promise<IMessage> {
+        checkPayloadLength(payloadString);
+
+        let res: IMessage;
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [IndexedDBCryptoStore.STORE_SESSIONS],
+            (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);
+                });
+            },
+            logger.getChild("[encryptMessage]"),
+        );
+        return res!;
+    }
+
+    /**
+     * Decrypt an incoming message using an existing session
+     *
+     * @param theirDeviceIdentityKey - Curve25519 identity key for the
+     *     remote device
+     * @param sessionId -  the id of the active session
+     * @param messageType -  messageType field from the received message
+     * @param ciphertext - base64-encoded body from the received message
+     *
+     * @returns decrypted payload.
+     */
+    public async decryptMessage(
+        theirDeviceIdentityKey: string,
+        sessionId: string,
+        messageType: number,
+        ciphertext: string,
+    ): Promise<string> {
+        let payloadString: string;
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.getSession(theirDeviceIdentityKey, sessionId, txn, (sessionInfo: IUnpickledSessionInfo) => {
+                    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);
+                });
+            },
+            logger.getChild("[decryptMessage]"),
+        );
+        return payloadString!;
+    }
+
+    /**
+     * Determine if an incoming messages is a prekey message matching an existing session
+     *
+     * @param theirDeviceIdentityKey - Curve25519 identity key for the
+     *     remote device
+     * @param sessionId -  the id of the active session
+     * @param messageType -  messageType field from the received message
+     * @param ciphertext - base64-encoded body from the received message
+     *
+     * @returns true if the received message is a prekey message which matches
+     *    the given session.
+     */
+    public async matchesSession(
+        theirDeviceIdentityKey: string,
+        sessionId: string,
+        messageType: number,
+        ciphertext: string,
+    ): Promise<boolean> {
+        if (messageType !== 0) {
+            return false;
+        }
+
+        let matches: boolean;
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [IndexedDBCryptoStore.STORE_SESSIONS],
+            (txn) => {
+                this.getSession(theirDeviceIdentityKey, sessionId, txn, (sessionInfo) => {
+                    matches = sessionInfo.session.matches_inbound(ciphertext);
+                });
+            },
+            logger.getChild("[matchesSession]"),
+        );
+        return matches!;
+    }
+
+    public async recordSessionProblem(deviceKey: string, type: string, fixed: boolean): Promise<void> {
+        logger.info(`Recording problem on olm session with ${deviceKey} of type ${type}. Recreating: ${fixed}`);
+        await this.cryptoStore.storeEndToEndSessionProblem(deviceKey, type, fixed);
+    }
+
+    public sessionMayHaveProblems(deviceKey: string, timestamp: number): Promise<IProblem | null> {
+        return this.cryptoStore.getEndToEndSessionProblem(deviceKey, timestamp);
+    }
+
+    public filterOutNotifiedErrorDevices(devices: IOlmDevice[]): Promise<IOlmDevice[]> {
+        return this.cryptoStore.filterOutNotifiedErrorDevices(devices);
+    }
+
+    // Outbound group session
+    // ======================
+
+    /**
+     * store an OutboundGroupSession in outboundGroupSessionStore
+     *
+     * @internal
+     */
+    private saveOutboundGroupSession(session: OutboundGroupSession): void {
+        this.outboundGroupSessionStore[session.session_id()] = session.pickle(this.pickleKey);
+    }
+
+    /**
+     * extract an OutboundGroupSession from outboundGroupSessionStore and call the
+     * given function
+     *
+     * @returns result of func
+     * @internal
+     */
+    private getOutboundGroupSession<T>(sessionId: string, func: (session: OutboundGroupSession) => T): T {
+        const pickled = this.outboundGroupSessionStore[sessionId];
+        if (pickled === undefined) {
+            throw new Error("Unknown outbound group session " + sessionId);
+        }
+
+        const session = new globalThis.Olm.OutboundGroupSession();
+        try {
+            session.unpickle(this.pickleKey, pickled);
+            return func(session);
+        } finally {
+            session.free();
+        }
+    }
+
+    /**
+     * Generate a new outbound group session
+     *
+     * @returns sessionId for the outbound session.
+     */
+    public createOutboundGroupSession(): string {
+        const session = new globalThis.Olm.OutboundGroupSession();
+        try {
+            session.create();
+            this.saveOutboundGroupSession(session);
+            return session.session_id();
+        } finally {
+            session.free();
+        }
+    }
+
+    /**
+     * Encrypt an outgoing message with an outbound group session
+     *
+     * @param sessionId -  the id of the outboundgroupsession
+     * @param payloadString -  payload to be encrypted and sent
+     *
+     * @returns ciphertext
+     */
+    public encryptGroupMessage(sessionId: string, payloadString: string): string {
+        logger.log(`encrypting msg with megolm session ${sessionId}`);
+
+        checkPayloadLength(payloadString);
+
+        return this.getOutboundGroupSession(sessionId, (session: OutboundGroupSession) => {
+            const res = session.encrypt(payloadString);
+            this.saveOutboundGroupSession(session);
+            return res;
+        });
+    }
+
+    /**
+     * Get the session keys for an outbound group session
+     *
+     * @param sessionId -  the id of the outbound group session
+     *
+     * @returns current chain index, and
+     *     base64-encoded secret key.
+     */
+    public getOutboundGroupSessionKey(sessionId: string): IOutboundGroupSessionKey {
+        return this.getOutboundGroupSession(sessionId, function (session: OutboundGroupSession) {
+            return {
+                chain_index: session.message_index(),
+                key: session.session_key(),
+            };
+        });
+    }
+
+    // Inbound group session
+    // =====================
+
+    /**
+     * Unpickle a session from a sessionData object and invoke the given function.
+     * The session is valid only until func returns.
+     *
+     * @param sessionData - Object describing the session.
+     * @param func - Invoked with the unpickled session
+     * @returns result of func
+     */
+    private unpickleInboundGroupSession<T>(
+        sessionData: InboundGroupSessionData,
+        func: (session: InboundGroupSession) => T,
+    ): T {
+        const session = new globalThis.Olm.InboundGroupSession();
+        try {
+            session.unpickle(this.pickleKey, sessionData.session);
+            return func(session);
+        } finally {
+            session.free();
+        }
+    }
+
+    /**
+     * extract an InboundGroupSession from the crypto store and call the given function
+     *
+     * @param roomId - The room ID to extract the session for, or null to fetch
+     *     sessions for any room.
+     * @param txn - Opaque transaction object from cryptoStore.doTxn()
+     * @param func - function to call.
+     *
+     * @internal
+     */
+    private getInboundGroupSession(
+        roomId: string,
+        senderKey: string,
+        sessionId: string,
+        txn: unknown,
+        func: (
+            session: InboundGroupSession | null,
+            data: InboundGroupSessionData | null,
+            withheld: IWithheld | null,
+        ) => void,
+    ): void {
+        this.cryptoStore.getEndToEndInboundGroupSession(
+            senderKey,
+            sessionId,
+            txn,
+            (sessionData: InboundGroupSessionData | null, withheld: IWithheld | null) => {
+                if (sessionData === null) {
+                    func(null, null, withheld);
+                    return;
+                }
+
+                // if we were given a room ID, check that the it matches the original one for the session. This stops
+                // the HS pretending a message was targeting a different room.
+                if (roomId !== null && roomId !== sessionData.room_id) {
+                    throw new Error(
+                        "Mismatched room_id for inbound group session (expected " +
+                            sessionData.room_id +
+                            ", was " +
+                            roomId +
+                            ")",
+                    );
+                }
+
+                this.unpickleInboundGroupSession(sessionData, (session: InboundGroupSession) => {
+                    func(session, sessionData, withheld);
+                });
+            },
+        );
+    }
+
+    /**
+     * Add an inbound group session to the session store
+     *
+     * @param roomId -     room in which this session will be used
+     * @param senderKey -  base64-encoded curve25519 key of the sender
+     * @param forwardingCurve25519KeyChain -  Devices involved in forwarding
+     *     this session to us.
+     * @param sessionId -  session identifier
+     * @param sessionKey - base64-encoded secret key
+     * @param keysClaimed - Other keys the sender claims.
+     * @param exportFormat - true if the megolm keys are in export format
+     *    (ie, they lack an ed25519 signature)
+     * @param extraSessionData - any other data to be include with the session
+     */
+    public async addInboundGroupSession(
+        roomId: string,
+        senderKey: string,
+        forwardingCurve25519KeyChain: string[],
+        sessionId: string,
+        sessionKey: string,
+        keysClaimed: Record<string, string>,
+        exportFormat: boolean,
+        extraSessionData: OlmGroupSessionExtraData = {},
+    ): Promise<void> {
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS,
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS_WITHHELD,
+                IndexedDBCryptoStore.STORE_SHARED_HISTORY_INBOUND_GROUP_SESSIONS,
+            ],
+            (txn) => {
+                /* if we already have this session, consider updating it */
+                this.getInboundGroupSession(
+                    roomId,
+                    senderKey,
+                    sessionId,
+                    txn,
+                    (
+                        existingSession: InboundGroupSession | null,
+                        existingSessionData: InboundGroupSessionData | null,
+                    ) => {
+                        // new session.
+                        const session = new globalThis.Olm.InboundGroupSession();
+                        try {
+                            if (exportFormat) {
+                                session.import_session(sessionKey);
+                            } else {
+                                session.create(sessionKey);
+                            }
+                            if (sessionId != session.session_id()) {
+                                throw new Error("Mismatched group session ID from senderKey: " + senderKey);
+                            }
+
+                            if (existingSession) {
+                                logger.log(`Update for megolm session ${senderKey}|${sessionId}`);
+                                if (existingSession.first_known_index() <= session.first_known_index()) {
+                                    if (!existingSessionData!.untrusted || extraSessionData.untrusted) {
+                                        // existing session has less-than-or-equal index
+                                        // (i.e. can decrypt at least as much), and the
+                                        // new session's trust does not win over the old
+                                        // session's trust, so keep it
+                                        logger.log(`Keeping existing megolm session ${senderKey}|${sessionId}`);
+                                        return;
+                                    }
+                                    if (existingSession.first_known_index() < session.first_known_index()) {
+                                        // We want to upgrade the existing session's trust,
+                                        // but we can't just use the new session because we'll
+                                        // lose the lower index. Check that the sessions connect
+                                        // properly, and then manually set the existing session
+                                        // as trusted.
+                                        if (
+                                            existingSession.export_session(session.first_known_index()) ===
+                                            session.export_session(session.first_known_index())
+                                        ) {
+                                            logger.info(
+                                                "Upgrading trust of existing megolm session " +
+                                                    `${senderKey}|${sessionId} based on newly-received trusted session`,
+                                            );
+                                            existingSessionData!.untrusted = false;
+                                            this.cryptoStore.storeEndToEndInboundGroupSession(
+                                                senderKey,
+                                                sessionId,
+                                                existingSessionData!,
+                                                txn,
+                                            );
+                                        } else {
+                                            logger.warn(
+                                                `Newly-received megolm session ${senderKey}|$sessionId}` +
+                                                    " does not match existing session! Keeping existing session",
+                                            );
+                                        }
+                                        return;
+                                    }
+                                    // If the sessions have the same index, go ahead and store the new trusted one.
+                                }
+                            }
+
+                            logger.debug(
+                                `Storing megolm session ${senderKey}|${sessionId} with first index ` +
+                                    session.first_known_index(),
+                            );
+
+                            const sessionData = Object.assign({}, extraSessionData, {
+                                room_id: roomId,
+                                session: session.pickle(this.pickleKey),
+                                keysClaimed: keysClaimed,
+                                forwardingCurve25519KeyChain: forwardingCurve25519KeyChain,
+                            });
+
+                            this.cryptoStore.storeEndToEndInboundGroupSession(senderKey, sessionId, sessionData, txn);
+
+                            if (!existingSession && extraSessionData.sharedHistory) {
+                                this.cryptoStore.addSharedHistoryInboundGroupSession(roomId, senderKey, sessionId, txn);
+                            }
+                        } finally {
+                            session.free();
+                        }
+                    },
+                );
+            },
+            logger.getChild("[addInboundGroupSession]"),
+        );
+    }
+
+    /**
+     * Record in the data store why an inbound group session was withheld.
+     *
+     * @param roomId -     room that the session belongs to
+     * @param senderKey -  base64-encoded curve25519 key of the sender
+     * @param sessionId -  session identifier
+     * @param code -       reason code
+     * @param reason -     human-readable version of `code`
+     */
+    public async addInboundGroupSessionWithheld(
+        roomId: string,
+        senderKey: string,
+        sessionId: string,
+        code: string,
+        reason: string,
+    ): Promise<void> {
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS_WITHHELD],
+            (txn) => {
+                this.cryptoStore.storeEndToEndInboundGroupSessionWithheld(
+                    senderKey,
+                    sessionId,
+                    {
+                        room_id: roomId,
+                        code: code,
+                        reason: reason,
+                    },
+                    txn,
+                );
+            },
+        );
+    }
+
+    /**
+     * Decrypt a received message with an inbound group session
+     *
+     * @param roomId -    room in which the message was received
+     * @param senderKey - base64-encoded curve25519 key of the sender
+     * @param sessionId - session identifier
+     * @param body -      base64-encoded body of the encrypted message
+     * @param eventId -   ID of the event being decrypted
+     * @param timestamp - timestamp of the event being decrypted
+     *
+     * @returns null if the sessionId is unknown
+     */
+    public async decryptGroupMessage(
+        roomId: string,
+        senderKey: string,
+        sessionId: string,
+        body: string,
+        eventId: string,
+        timestamp: number,
+    ): Promise<IDecryptedGroupMessage | null> {
+        let result: IDecryptedGroupMessage | null = null;
+        // when the localstorage crypto store is used as an indexeddb backend,
+        // exceptions thrown from within the inner function are not passed through
+        // to the top level, so we store exceptions in a variable and raise them at
+        // the end
+        let error: Error;
+
+        await this.cryptoStore.doTxn(
+            "readwrite",
+            [
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS,
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS_WITHHELD,
+            ],
+            (txn) => {
+                this.getInboundGroupSession(roomId, senderKey, sessionId, txn, (session, sessionData, withheld) => {
+                    if (session === null || sessionData === null) {
+                        if (withheld) {
+                            const failureCode =
+                                withheld.code === "m.unverified"
+                                    ? DecryptionFailureCode.MEGOLM_KEY_WITHHELD_FOR_UNVERIFIED_DEVICE
+                                    : DecryptionFailureCode.MEGOLM_KEY_WITHHELD;
+                            error = new DecryptionError(failureCode, calculateWithheldMessage(withheld), {
+                                session: senderKey + "|" + sessionId,
+                            });
+                        }
+                        result = null;
+                        return;
+                    }
+                    let res: ReturnType<InboundGroupSession["decrypt"]>;
+                    try {
+                        res = session.decrypt(body);
+                    } catch (e) {
+                        if ((<Error>e)?.message === "OLM.UNKNOWN_MESSAGE_INDEX" && withheld) {
+                            const failureCode =
+                                withheld.code === "m.unverified"
+                                    ? DecryptionFailureCode.MEGOLM_KEY_WITHHELD_FOR_UNVERIFIED_DEVICE
+                                    : DecryptionFailureCode.MEGOLM_KEY_WITHHELD;
+                            error = new DecryptionError(failureCode, calculateWithheldMessage(withheld), {
+                                session: senderKey + "|" + sessionId,
+                            });
+                        } else {
+                            error = <Error>e;
+                        }
+                        return;
+                    }
+
+                    let plaintext: string = res.plaintext;
+                    if (plaintext === undefined) {
+                        // @ts-ignore - Compatibility for older olm versions.
+                        plaintext = res as string;
+                    } else {
+                        // Check if we have seen this message index before to detect replay attacks.
+                        // If the event ID and timestamp are specified, and the match the event ID
+                        // and timestamp from the last time we used this message index, then we
+                        // don't consider it a replay attack.
+                        const messageIndexKey = senderKey + "|" + sessionId + "|" + res.message_index;
+                        if (messageIndexKey in this.inboundGroupSessionMessageIndexes) {
+                            const msgInfo = this.inboundGroupSessionMessageIndexes[messageIndexKey];
+                            if (msgInfo.id !== eventId || msgInfo.timestamp !== timestamp) {
+                                error = new Error(
+                                    "Duplicate message index, possible replay attack: " + messageIndexKey,
+                                );
+                                return;
+                            }
+                        }
+                        this.inboundGroupSessionMessageIndexes[messageIndexKey] = {
+                            id: eventId,
+                            timestamp: timestamp,
+                        };
+                    }
+
+                    sessionData.session = session.pickle(this.pickleKey);
+                    this.cryptoStore.storeEndToEndInboundGroupSession(senderKey, sessionId, sessionData, txn);
+                    result = {
+                        result: plaintext,
+                        keysClaimed: sessionData.keysClaimed || {},
+                        senderKey: senderKey,
+                        forwardingCurve25519KeyChain: sessionData.forwardingCurve25519KeyChain || [],
+                        untrusted: !!sessionData.untrusted,
+                    };
+                });
+            },
+            logger.getChild("[decryptGroupMessage]"),
+        );
+
+        if (error!) {
+            throw error;
+        }
+        return result!;
+    }
+
+    /**
+     * Determine if we have the keys for a given megolm session
+     *
+     * @param roomId -    room in which the message was received
+     * @param senderKey - base64-encoded curve25519 key of the sender
+     * @param sessionId - session identifier
+     *
+     * @returns true if we have the keys to this session
+     */
+    public async hasInboundSessionKeys(roomId: string, senderKey: string, sessionId: string): Promise<boolean> {
+        let result: boolean;
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS,
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS_WITHHELD,
+            ],
+            (txn) => {
+                this.cryptoStore.getEndToEndInboundGroupSession(senderKey, sessionId, txn, (sessionData) => {
+                    if (sessionData === null) {
+                        result = false;
+                        return;
+                    }
+
+                    if (roomId !== sessionData.room_id) {
+                        logger.warn(
+                            `requested keys for inbound group session ${senderKey}|` +
+                                `${sessionId}, with incorrect room_id ` +
+                                `(expected ${sessionData.room_id}, ` +
+                                `was ${roomId})`,
+                        );
+                        result = false;
+                    } else {
+                        result = true;
+                    }
+                });
+            },
+            logger.getChild("[hasInboundSessionKeys]"),
+        );
+
+        return result!;
+    }
+
+    /**
+     * Extract the keys to a given megolm session, for sharing
+     *
+     * @param roomId -    room in which the message was received
+     * @param senderKey - base64-encoded curve25519 key of the sender
+     * @param sessionId - session identifier
+     * @param chainIndex - The chain index at which to export the session.
+     *     If omitted, export at the first index we know about.
+     *
+     * @returns
+     *    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).
+     */
+    public async getInboundGroupSessionKey(
+        roomId: string,
+        senderKey: string,
+        sessionId: string,
+        chainIndex?: number,
+    ): Promise<IInboundGroupSessionKey | null> {
+        let result: IInboundGroupSessionKey | null = null;
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS,
+                IndexedDBCryptoStore.STORE_INBOUND_GROUP_SESSIONS_WITHHELD,
+            ],
+            (txn) => {
+                this.getInboundGroupSession(roomId, senderKey, sessionId, txn, (session, sessionData) => {
+                    if (session === null || sessionData === null) {
+                        result = null;
+                        return;
+                    }
+
+                    if (chainIndex === undefined) {
+                        chainIndex = session.first_known_index();
+                    }
+
+                    const exportedSession = session.export_session(chainIndex);
+
+                    const claimedKeys = sessionData.keysClaimed || {};
+                    const senderEd25519Key = claimedKeys.ed25519 || null;
+
+                    const forwardingKeyChain = sessionData.forwardingCurve25519KeyChain || [];
+                    // older forwarded keys didn't set the "untrusted"
+                    // property, but can be identified by having a
+                    // non-empty forwarding key chain.  These keys should
+                    // be marked as untrusted since we don't know that they
+                    // can be trusted
+                    const untrusted =
+                        "untrusted" in sessionData ? sessionData.untrusted : forwardingKeyChain.length > 0;
+
+                    result = {
+                        chain_index: chainIndex,
+                        key: exportedSession,
+                        forwarding_curve25519_key_chain: forwardingKeyChain,
+                        sender_claimed_ed25519_key: senderEd25519Key,
+                        shared_history: sessionData.sharedHistory || false,
+                        untrusted: untrusted,
+                    };
+                });
+            },
+            logger.getChild("[getInboundGroupSessionKey]"),
+        );
+
+        return result;
+    }
+
+    /**
+     * Export an inbound group session
+     *
+     * @param senderKey - base64-encoded curve25519 key of the sender
+     * @param sessionId - session identifier
+     * @param sessionData - The session object from the store
+     * @returns exported session data
+     */
+    public exportInboundGroupSession(
+        senderKey: string,
+        sessionId: string,
+        sessionData: InboundGroupSessionData,
+    ): IMegolmSessionData {
+        return this.unpickleInboundGroupSession(sessionData, (session) => {
+            const messageIndex = session.first_known_index();
+
+            return {
+                "sender_key": senderKey,
+                "sender_claimed_keys": sessionData.keysClaimed,
+                "room_id": sessionData.room_id,
+                "session_id": sessionId,
+                "session_key": session.export_session(messageIndex),
+                "forwarding_curve25519_key_chain": sessionData.forwardingCurve25519KeyChain || [],
+                "first_known_index": session.first_known_index(),
+                "org.matrix.msc3061.shared_history": sessionData.sharedHistory || false,
+            } as IMegolmSessionData;
+        });
+    }
+
+    public async getSharedHistoryInboundGroupSessions(
+        roomId: string,
+    ): Promise<[senderKey: string, sessionId: string][]> {
+        let result: Promise<[senderKey: string, sessionId: string][]>;
+        await this.cryptoStore.doTxn(
+            "readonly",
+            [IndexedDBCryptoStore.STORE_SHARED_HISTORY_INBOUND_GROUP_SESSIONS],
+            (txn) => {
+                result = this.cryptoStore.getSharedHistoryInboundGroupSessions(roomId, txn);
+            },
+            logger.getChild("[getSharedHistoryInboundGroupSessionsForRoom]"),
+        );
+        return result!;
+    }
+
+    // Utilities
+    // =========
+
+    /**
+     * Verify an ed25519 signature.
+     *
+     * @param key - ed25519 key
+     * @param message - message which was signed
+     * @param signature - base64-encoded signature to be checked
+     *
+     * @throws Error if there is a problem with the verification. If the key was
+     * too small then the message will be "OLM.INVALID_BASE64". If the signature
+     * was invalid then the message will be "OLM.BAD_MESSAGE_MAC".
+     */
+    public verifySignature(key: string, message: string, signature: string): void {
+        this.getUtility(function (util: Utility) {
+            util.ed25519_verify(key, message, signature);
+        });
+    }
+}
+
+export const WITHHELD_MESSAGES: Record<string, string> = {
+    "m.unverified": "The sender has disabled encrypting to unverified devices.",
+    "m.blacklisted": "The sender has blocked you.",
+    "m.unauthorised": "You are not authorised to read the message.",
+    "m.no_olm": "Unable to establish a secure channel.",
+};
+
+/**
+ * Calculate the message to use for the exception when a session key is withheld.
+ *
+ * @param withheld -  An object that describes why the key was withheld.
+ *
+ * @returns the message
+ *
+ * @internal
+ */
+function calculateWithheldMessage(withheld: IWithheld): string {
+    if (withheld.code && withheld.code in WITHHELD_MESSAGES) {
+        return WITHHELD_MESSAGES[withheld.code];
+    } else if (withheld.reason) {
+        return withheld.reason;
+    } else {
+        return "decryption key withheld";
+    }
+}