import { DeviceId, OlmMachine, UserId, DeviceLists, RoomId, Attachment, EncryptedAttachment, SecretStorageKey, SecretStorageItems, } from "@matrix-org/matrix-sdk-crypto-nodejs"; import { MatrixClient } from "../MatrixClient"; import { LogService } from "../logging/LogService"; import { IMegolmEncrypted, IOlmEncrypted, IToDeviceMessage, OTKAlgorithm, OTKCounts, Signatures, } from "../models/Crypto"; import { requiresReady } from "./decorators"; import { RoomTracker } from "./RoomTracker"; import { EncryptedRoomEvent } from "../models/events/EncryptedRoomEvent"; import { RoomEvent } from "../models/events/RoomEvent"; import { EncryptedFile } from "../models/events/MessageEvent"; import { RustSdkCryptoStorageProvider } from "../storage/RustSdkCryptoStorageProvider"; import { RustEngine, SYNC_LOCK_NAME } from "./RustEngine"; import { MembershipEvent } from "../models/events/MembershipEvent"; import { IKeyBackupInfoRetrieved } from "../models/KeyBackup"; /** * Manages encryption for a MatrixClient. Get an instance from a MatrixClient directly * rather than creating one manually. * @category Encryption */ export class CryptoClient { private ready = false; private deviceId: string; private deviceEd25519: string; private deviceCurve25519: string; private roomTracker: RoomTracker; private engine: RustEngine; public constructor(private client: MatrixClient) { this.roomTracker = new RoomTracker(this.client); } private get storage(): RustSdkCryptoStorageProvider { return this.client.cryptoStore; } /** * The device ID for the MatrixClient. */ public get clientDeviceId(): string { return this.deviceId; } /** * The device's Ed25519 identity */ public get clientDeviceEd25519(): string { return this.deviceEd25519; } /** * Whether or not the crypto client is ready to be used. If not ready, prepare() should be called. * @see prepare */ public get isReady(): boolean { return this.ready; } /** * Prepares the crypto client for usage. * @param {string[]} roomIds The room IDs the MatrixClient is joined to. */ public async prepare() { if (this.ready) return; // stop re-preparing here const storedDeviceId = await this.client.cryptoStore.getDeviceId(); const { user_id: userId, device_id: deviceId } = (await this.client.getWhoAmI()); if (!deviceId) { throw new Error("Encryption not possible: server not revealing device ID"); } const storagePath = await this.storage.getMachineStoragePath(deviceId); if (storedDeviceId !== deviceId) { this.client.cryptoStore.setDeviceId(deviceId); } this.deviceId = deviceId; LogService.info("CryptoClient", `Starting ${userId} with device ID:`, this.deviceId); // info so all bots know for debugging const machine = await OlmMachine.initialize( new UserId(userId), new DeviceId(this.deviceId), storagePath, "", this.storage.storageType, ); this.engine = new RustEngine(machine, this.client); await this.engine.run(); const identity = this.engine.machine.identityKeys; this.deviceCurve25519 = identity.curve25519.toBase64(); this.deviceEd25519 = identity.ed25519.toBase64(); LogService.info("CryptoClient", `Running ${userId} with device Ed25519 identity:`, this.deviceEd25519); // info so all bots know for debugging this.ready = true; this.client.emit("crypto.ready"); } /** * Handles a room event. * @internal * @param roomId The room ID. * @param event The event. */ public async onRoomEvent(roomId: string, event: any): Promise { await this.roomTracker.onRoomEvent(roomId, event); if (typeof event['state_key'] !== 'string') return; if (event['type'] === 'm.room.member') { const membership = new MembershipEvent(event); if (membership.effectiveMembership !== 'join' && membership.effectiveMembership !== 'invite') return; await this.engine.addTrackedUsers([membership.membershipFor]); } else if (event['type'] === 'm.room.encryption') { return this.client.getRoomMembers(roomId, null, ['join', 'invite']).then( members => this.engine.addTrackedUsers(members.map(e => e.membershipFor)), e => void LogService.warn("CryptoClient", `Unable to get members of room ${roomId}`), ); } } /** * Handles a room join. * @internal * @param roomId The room ID. */ public async onRoomJoin(roomId: string) { await this.roomTracker.onRoomJoin(roomId); if (await this.isRoomEncrypted(roomId)) { const members = await this.client.getRoomMembers(roomId, null, ['join', 'invite']); await this.engine.addTrackedUsers(members.map(e => e.membershipFor)); } } /** * Exports a set of keys for a given session. * @param roomId The room ID for the session. * @param sessionId The session ID. * @returns An array of session keys. */ public async exportRoomKeysForSession(roomId: string, sessionId: string) { return this.engine.exportRoomKeysForSession(roomId, sessionId); } /** * Checks if a room is encrypted. * @param {string} roomId The room ID to check. * @returns {Promise} Resolves to true if encrypted, false otherwise. */ @requiresReady() public async isRoomEncrypted(roomId: string): Promise { const config = await this.roomTracker.getRoomCryptoConfig(roomId); return !!config?.algorithm; } /** * Updates the client's sync-related data. * @param {Array.>} toDeviceMessages The to-device messages received. * @param {OTKCounts} otkCounts The current OTK counts. * @param {OTKAlgorithm[]} unusedFallbackKeyAlgs The unused fallback key algorithms. * @param {string[]} changedDeviceLists The user IDs which had device list changes. * @param {string[]} leftDeviceLists The user IDs which the server believes we no longer need to track. * @returns {Promise} Resolves when complete. */ @requiresReady() public async updateSyncData( toDeviceMessages: IToDeviceMessage[], otkCounts: OTKCounts, unusedFallbackKeyAlgs: OTKAlgorithm[], changedDeviceLists: string[], leftDeviceLists: string[], ): Promise { const deviceMessages = JSON.stringify(toDeviceMessages); const deviceLists = new DeviceLists( changedDeviceLists.map(u => new UserId(u)), leftDeviceLists.map(u => new UserId(u))); await this.engine.lock.acquire(SYNC_LOCK_NAME, async () => { const syncResp = JSON.parse(await this.engine.machine.receiveSyncChanges(deviceMessages, deviceLists, otkCounts, unusedFallbackKeyAlgs)); if (Array.isArray(syncResp) && syncResp.length === 2 && Array.isArray(syncResp[0])) { for (const msg of syncResp[0] as IToDeviceMessage[]) { this.client.emit("to_device.decrypted", msg); } } else { LogService.error("CryptoClient", "OlmMachine.receiveSyncChanges did not return an expected value of [to-device events, room key changes]"); } await this.engine.run(); }); } /** * Signs an object using the device keys. * @param {object} obj The object to sign. * @returns {Promise} The signatures for the object. */ @requiresReady() public async sign(obj: object): Promise { obj = JSON.parse(JSON.stringify(obj)); const existingSignatures = obj['signatures'] || {}; delete obj['signatures']; delete obj['unsigned']; const container = await this.engine.machine.sign(JSON.stringify(obj)); const userSignature = container.get(new UserId(await this.client.getUserId())); const sig: Signatures = { [await this.client.getUserId()]: {}, }; for (const [key, maybeSignature] of Object.entries(userSignature)) { if (maybeSignature.isValid) { sig[await this.client.getUserId()][key] = maybeSignature.signature.toBase64(); } } return { ...sig, ...existingSignatures, }; } /** * Encrypts the details of a room event, returning an encrypted payload to be sent in an * `m.room.encrypted` event to the room. If needed, this function will send decryption keys * to the appropriate devices in the room (this happens when the Megolm session rotates or * gets created). * @param {string} roomId The room ID to encrypt within. If the room is not encrypted, an * error is thrown. * @param {string} eventType The event type being encrypted. * @param {any} content The event content being encrypted. * @returns {Promise} Resolves to the encrypted content for an `m.room.encrypted` event. */ @requiresReady() public async encryptRoomEvent(roomId: string, eventType: string, content: any): Promise { if (!(await this.isRoomEncrypted(roomId))) { throw new Error("Room is not encrypted"); } await this.engine.prepareEncrypt(roomId, await this.roomTracker.getRoomCryptoConfig(roomId)); const encrypted = JSON.parse(await this.engine.machine.encryptRoomEvent(new RoomId(roomId), eventType, JSON.stringify(content))); await this.engine.run(); return encrypted as IMegolmEncrypted; } /** * Decrypts a room event. Currently only supports Megolm-encrypted events (default for this SDK). * @param {EncryptedRoomEvent} event The encrypted event. * @param {string} roomId The room ID where the event was sent. * @returns {Promise>} Resolves to a decrypted room event, or rejects/throws with * an error if the event is undecryptable. */ @requiresReady() public async decryptRoomEvent(event: EncryptedRoomEvent, roomId: string): Promise> { const decrypted = await this.engine.machine.decryptRoomEvent(JSON.stringify(event.raw), new RoomId(roomId)); const clearEvent = JSON.parse(decrypted.event); return new RoomEvent({ ...event.raw, type: clearEvent.type || "io.t2bot.unknown", content: (typeof (clearEvent.content) === 'object') ? clearEvent.content : {}, }); } /** * Encrypts a file for uploading in a room, returning the encrypted data and information * to include in a message event (except media URL) for sending. * @param {Buffer} file The file to encrypt. * @returns {{buffer: Buffer, file: Omit}} Resolves to the encrypted * contents and file information. */ @requiresReady() public async encryptMedia(file: Buffer): Promise<{ buffer: Buffer, file: Omit }> { const encrypted = Attachment.encrypt(file); const info = JSON.parse(encrypted.mediaEncryptionInfo); return { buffer: Buffer.from(encrypted.encryptedData), file: info, }; } /** * Decrypts a previously-uploaded encrypted file, validating the fields along the way. * @param {EncryptedFile} file The file to decrypt. * @returns {Promise} Resolves to the decrypted file contents. */ @requiresReady() public async decryptMedia(file: EncryptedFile): Promise { const contents = this.client.contentScannerInstance ? await this.client.contentScannerInstance.downloadEncryptedContent(file) : (await this.client.downloadContent(file.url)).data; const encrypted = new EncryptedAttachment( contents, JSON.stringify(file), ); const decrypted = Attachment.decrypt(encrypted); return Buffer.from(decrypted); } /** * Confirm's the bot's identity by using a recovery key or passphrase. * * @param key The recovery key or passphrase. */ @requiresReady() public async confirmIdentityWithRecoveryKey(key: string): Promise { const machine = this.engine.machine; const ownDevice = await machine.getDevice(machine.userId, machine.deviceId); if (!ownDevice) { LogService.debug("CryptoClient", "Own device not set up yet"); throw new Error("Own device not set up yet"); } else if (ownDevice.isCrossSigningTrusted()) { LogService.debug("CryptoClient", "Cryptographic identity already confirmed"); return; } LogService.debug("CryptoClient", "Confirming cryptographic identity with recovery key"); const client = this.client; const secretStorageKey = await this.getDefaultSecretStorageKey(key); const masterKeyEvent = await client.getAccountData("m.cross_signing.master"); const userSigningKeyEvent = await client.getAccountData("m.cross_signing.user_signing"); const selfSigningKeyEvent = await client.getAccountData("m.cross_signing.self_signing"); const signatureUploadRequest = await machine.importSecretsFromSecretStorage( secretStorageKey, new SecretStorageItems({ masterKey: JSON.stringify(masterKeyEvent), userSigningKey: JSON.stringify(userSigningKeyEvent), selfSigningKey: JSON.stringify(selfSigningKeyEvent), }), ); LogService.debug("CryptoClient", "Secrets obtained"); await this.engine.processOutgoingRequests([signatureUploadRequest]); LogService.debug("CryptoClient", "Identity confirmed"); } /** * Has recovery been set up on this account. * * Checks whether the account has a default Secret Storage key set up, and * has the cross-signing keys stored in Secret Storage. It does not check * the validity of the stored keys. * * @returns Whether recovery has been set up on this account. */ public async isRecoveryAvailable(): Promise { try { const client = this.client; const defaultKeyData = await client.getAccountData<{key: string}>("m.secret_storage.default_key"); if (!defaultKeyData.key) { return false; } const keyId = defaultKeyData.key; const keyAccountDataName = "m.secret_storage.key." + keyId; const keyInfo = await client.getAccountData<{algorithm: string}>(keyAccountDataName); const masterKeyEvent = await client.getAccountData<{encrypted: Record}>("m.cross_signing.master"); const userSigningKeyEvent = await client.getAccountData<{encrypted: Record}>("m.cross_signing.user_signing"); const selfSigningKeyEvent = await client.getAccountData<{encrypted: Record}>("m.cross_signing.self_signing"); return Boolean(keyInfo.algorithm && masterKeyEvent?.encrypted?.[keyId] && userSigningKeyEvent?.encrypted?.[keyId] && selfSigningKeyEvent?.encrypted?.[keyId]); } catch { return false; } } /** * Creates the bot's cryptographic identity. * * Note: only works if the bot does not have an existing cryptographic * identity, since this doesn't yet perform user interactive auth. * * @param key The recovery key or passphrase. If omitted, a new recovery * key will be created and set as the default recovery key. * * @returns The recovery key. */ public async createIdentity(key?: string): Promise { const client = this.client; const secretStorageKey = key === undefined ? SecretStorageKey.createRandomKey() : await this.getDefaultSecretStorageKey(key); const machine = this.engine.machine; const bootstrapRequests = await machine.bootstrapCrossSigning(true); if (bootstrapRequests.uploadKeysReq) { await this.engine.processOutgoingRequests([bootstrapRequests.uploadKeysReq]); } await client.doRequest("POST", "/_matrix/client/v3/keys/device_signing/upload", null, JSON.parse(bootstrapRequests.uploadSigningKeysReq)); await this.engine.processOutgoingRequests([bootstrapRequests.uploadSignaturesReq]); if (key === undefined) { // If we created a new secret storage key (`key` was not given), // then we need to save the key info to account data, and set it as // the default key. await client.setAccountData("m.secret_storage.default_key", {key: secretStorageKey.keyId()}); await client.setAccountData(secretStorageKey.eventType(), JSON.parse(secretStorageKey.accountDataContent())); } const secretStorageItems = await machine.exportSecretsForSecretStorage(secretStorageKey); await client.setAccountData("m.cross_signing.master", JSON.parse(secretStorageItems.masterKey)); await client.setAccountData("m.cross_signing.user_signing", JSON.parse(secretStorageItems.userSigningKey)); await client.setAccountData("m.cross_signing.self_signing", JSON.parse(secretStorageItems.selfSigningKey)); return secretStorageKey.toBase58(); } /** * Create a `SecretStorageKey` from the given key, assuming it is the default * secret storage key. * * @param key The recovery key or passphrase. * * @returns The `SecretStorageKey`. */ private async getDefaultSecretStorageKey(key: string): Promise { const client = this.client; const defaultKeyData = await client.getAccountData<{key: string}>("m.secret_storage.default_key"); if (!defaultKeyData || !defaultKeyData.key) { throw new Error("No default recovery key available"); } const keyAccountDataName = "m.secret_storage.key." + defaultKeyData.key; const keyInfo = await client.getAccountData(keyAccountDataName); return SecretStorageKey.fromAccountData(key, keyAccountDataName, JSON.stringify(keyInfo)); } /** * Enable backing up of room keys. * @param {IKeyBackupInfoRetrieved} info The configuration for key backup behaviour, * as returned by {@link MatrixClient#getKeyBackupVersion}. * @returns {Promise} Resolves once backups have been enabled. */ @requiresReady() public async enableKeyBackup(info: IKeyBackupInfoRetrieved): Promise { if (!this.engine.isBackupEnabled()) { // Only add the listener if we didn't add it already this.client.on("to_device.decrypted", this.onToDeviceMessage); } await this.engine.enableKeyBackup(info); // Back up any pending keys now, but asynchronously void this.engine.backupRoomKeys(); } /** * Disable backing up of room keys. */ @requiresReady() public async disableKeyBackup(): Promise { await this.engine.disableKeyBackup(); this.client.removeListener("to_device.decrypted", this.onToDeviceMessage); } private readonly onToDeviceMessage = (msg: IToDeviceMessage): void => { if (msg.type === "m.room_key") { this.engine.backupRoomKeys(); } }; }