@jeongsu816/matrix-bot-sdk 0.0.0-stage → 0.8.1

package/src/e2ee/CrossSigningBootstrap.ts

@@ -0,0 +1,141 @@
+import { MatrixClient } from "../MatrixClient";
+import { LogService } from "../logging/LogService";
+import { UIACallback } from "./RustEngine";
+
+export type { UIACallback };
+
+/**
+ * The subset of RustEngine used by the cross-signing helpers below.
+ * @internal
+ */
+export interface CrossSigningEngine {
+    bootstrapCrossSigning(uiaCallback: UIACallback, reset?: boolean): Promise<void>;
+    bootstrapSecretStorageFromPassphrase(passphrase: string, opts?: { withKeyBackup?: boolean, reset?: boolean }): Promise<void>;
+    restoreSecretsFromSecretStorage(passphrase: string): Promise<void>;
+}
+
+/**
+ * Result of {@link CryptoClient.ensureCrossSigning}.
+ * - `already-signed`: our device was already signed by the account's self-signing key.
+ * - `restored`: the cross-signing keys were restored from secret storage (no reset).
+ * - `bootstrapped`: a new cross-signing identity was created and uploaded (reset).
+ * - `skipped-no-auth`: bootstrapping was needed, but no UIA callback was given.
+ * @category Encryption
+ */
+export type EnsureCrossSigningResult = "already-signed" | "restored" | "bootstrapped" | "skipped-no-auth";
+
+/**
+ * Result of {@link CryptoClient.ensureSecretStorage}.
+ * @category Encryption
+ */
+export type EnsureSecretStorageResult = "already-configured" | "bootstrapped";
+
+/**
+ * Options for {@link CryptoClient.ensureCrossSigning}.
+ * @category Encryption
+ */
+export interface EnsureCrossSigningOptions {
+    /**
+     * Answers the UIA challenge when uploading new cross-signing keys. Without it,
+     * bootstrapping is skipped. See {@link passwordUiaCallback}.
+     */
+    uiaCallback?: UIACallback;
+    /**
+     * Secret storage passphrase. When set and the account has secret storage, the
+     * existing cross-signing keys are restored from it before falling back to a reset.
+     */
+    recoveryPassphrase?: string;
+}
+
+/**
+ * Builds a UIA callback that answers with an `m.login.password` stage.
+ * @category Encryption
+ */
+export function passwordUiaCallback(userId: string, password: string): UIACallback {
+    return async (uia) => ({
+        type: "m.login.password",
+        identifier: { type: "m.id.user", user: userId },
+        password,
+        session: uia.session,
+    });
+}
+
+/**
+ * Checks whether the given device is signed by the account's self-signing key.
+ *
+ * This deliberately checks our device, not just whether the account has a master
+ * key: another client may have set up cross-signing without ever signing us.
+ * @internal
+ */
+export async function isOwnDeviceCrossSigned(client: MatrixClient, deviceId: string): Promise<boolean> {
+    const userId = await client.getUserId();
+    const resp = await client.doRequest("POST", "/_matrix/client/v3/keys/query", null, {
+        device_keys: { [userId]: [] },
+    });
+    const selfSigningKeyIds = Object.keys(resp?.["self_signing_keys"]?.[userId]?.["keys"] ?? {});
+    const deviceSignatures = resp?.["device_keys"]?.[userId]?.[deviceId]?.["signatures"]?.[userId] ?? {};
+    return selfSigningKeyIds.some((keyId) => keyId in deviceSignatures);
+}
+
+/**
+ * Checks whether the account has a default secret storage key configured.
+ * @internal
+ */
+export async function hasSecretStorage(client: MatrixClient): Promise<boolean> {
+    try {
+        const data = await client.getAccountData<{ key?: string }>("m.secret_storage.default_key");
+        return Boolean(data?.key);
+    } catch {
+        // getAccountData throws (404) when the event doesn't exist.
+        return false;
+    }
+}
+
+/**
+ * @internal
+ */
+export async function ensureCrossSigning(
+    client: MatrixClient,
+    engine: CrossSigningEngine,
+    deviceId: string,
+    opts: EnsureCrossSigningOptions,
+): Promise<EnsureCrossSigningResult> {
+    if (await isOwnDeviceCrossSigned(client, deviceId)) {
+        return "already-signed";
+    }
+
+    if (opts.recoveryPassphrase && await hasSecretStorage(client)) {
+        try {
+            await engine.restoreSecretsFromSecretStorage(opts.recoveryPassphrase);
+            return "restored";
+        } catch (e) {
+            LogService.warn("CryptoClient", "Restoring cross-signing keys from secret storage failed, falling back to a reset:", e);
+        }
+    }
+
+    if (!opts.uiaCallback) {
+        return "skipped-no-auth";
+    }
+
+    // Neither signed nor restorable: create a fresh identity. This replaces any
+    // existing cross-signing keys on the account, so other devices' trust in the
+    // old identity is lost.
+    await engine.bootstrapCrossSigning(opts.uiaCallback, true);
+    return "bootstrapped";
+}
+
+/**
+ * @internal
+ */
+export async function ensureSecretStorage(
+    client: MatrixClient,
+    engine: CrossSigningEngine,
+    passphrase: string,
+    opts: { withKeyBackup?: boolean },
+): Promise<EnsureSecretStorageResult> {
+    if (await hasSecretStorage(client)) {
+        return "already-configured";
+    }
+    await engine.bootstrapSecretStorageFromPassphrase(passphrase, { withKeyBackup: opts.withKeyBackup ?? true });
+    return "bootstrapped";
+}

package/src/e2ee/CryptoClient.ts

@@ -0,0 +1,378 @@
+import {
+    DeviceId,
+    OlmMachine,
+    UserId,
+    DeviceLists,
+    RoomId,
+    Attachment,
+    EncryptedAttachment,
+} 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, UIACallback } from "./RustEngine";
+import {
+    ensureCrossSigning,
+    EnsureCrossSigningOptions,
+    EnsureCrossSigningResult,
+    ensureSecretStorage,
+    EnsureSecretStorageResult,
+    hasSecretStorage,
+    isOwnDeviceCrossSigned,
+} from "./CrossSigningBootstrap";
+import { MembershipEvent } from "../models/events/MembershipEvent";
+
+/**
+ * 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 <RustSdkCryptoStorageProvider> 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(roomIds: string[]) {
+        await this.roomTracker.prepare(roomIds);
+
+        if (this.ready) return; // stop re-preparing here
+
+        const storedDeviceId = await this.client.cryptoStore.getDeviceId();
+        if (storedDeviceId) {
+            this.deviceId = storedDeviceId;
+        } else {
+            const deviceId = (await this.client.getWhoAmI())['device_id'];
+            if (!deviceId) {
+                throw new Error("Encryption not possible: server not revealing device ID");
+            }
+            this.deviceId = deviceId;
+            await this.client.cryptoStore.setDeviceId(this.deviceId);
+        }
+
+        LogService.info("CryptoClient", "Starting with device ID:", this.deviceId); // info so all bots know for debugging
+
+        const machine = await OlmMachine.initialize(
+            new UserId(await this.client.getUserId()),
+            new DeviceId(this.deviceId),
+            this.storage.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.debug("CryptoClient", "Running with device Ed25519 identity:", this.deviceEd25519); // info so all bots know for debugging
+
+        this.ready = true;
+    }
+
+    /**
+     * Handles a room event.
+     * @internal
+     * @param roomId The room ID.
+     * @param event The event.
+     */
+    public async onRoomEvent(roomId: string, event: any) {
+        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') {
+            const members = await this.client.getRoomMembers(roomId, null, ['join', 'invite']);
+            await this.engine.addTrackedUsers(members.map(e => e.membershipFor));
+        }
+    }
+
+    /**
+     * 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));
+        }
+    }
+
+    /**
+     * Checks if a room is encrypted.
+     * @param {string} roomId The room ID to check.
+     * @returns {Promise<boolean>} Resolves to true if encrypted, false otherwise.
+     */
+    @requiresReady()
+    public async isRoomEncrypted(roomId: string): Promise<boolean> {
+        const config = await this.roomTracker.getRoomCryptoConfig(roomId);
+        return !!config?.algorithm;
+    }
+
+    /**
+     * Updates the client's sync-related data.
+     * @param {Array.<IToDeviceMessage<IOlmEncrypted>>} 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<void>} Resolves when complete.
+     */
+    @requiresReady()
+    public async updateSyncData(
+        toDeviceMessages: IToDeviceMessage<IOlmEncrypted>[],
+        otkCounts: OTKCounts,
+        unusedFallbackKeyAlgs: OTKAlgorithm[],
+        changedDeviceLists: string[],
+        leftDeviceLists: string[],
+    ): Promise<void> {
+        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 = await this.engine.machine.receiveSyncChanges(deviceMessages, deviceLists, otkCounts, unusedFallbackKeyAlgs);
+            const decryptedToDeviceMessages = JSON.parse(syncResp);
+            if (Array.isArray(decryptedToDeviceMessages)) {
+                for (const msg of decryptedToDeviceMessages) {
+                    this.client.emit("to_device.decrypted", msg);
+                }
+            }
+
+            await this.engine.run();
+        });
+    }
+
+    /**
+     * Signs an object using the device keys.
+     * @param {object} obj The object to sign.
+     * @returns {Promise<Signatures>} The signatures for the object.
+     */
+    @requiresReady()
+    public async sign(obj: object): Promise<Signatures> {
+        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<IMegolmEncrypted>} Resolves to the encrypted content for an `m.room.encrypted` event.
+     */
+    @requiresReady()
+    public async encryptRoomEvent(roomId: string, eventType: string, content: any): Promise<IMegolmEncrypted> {
+        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<RoomEvent<unknown>>} 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<RoomEvent<unknown>> {
+        const decrypted = await this.engine.machine.decryptRoomEvent(JSON.stringify(event.raw), new RoomId(roomId));
+        const clearEvent = JSON.parse(decrypted.event);
+
+        return new RoomEvent<unknown>({
+            ...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<EncryptedFile, "url">}} Resolves to the encrypted
+     * contents and file information.
+     */
+    @requiresReady()
+    public async encryptMedia(file: Buffer): Promise<{ buffer: Buffer, file: Omit<EncryptedFile, "url"> }> {
+        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<Buffer>} Resolves to the decrypted file contents.
+     */
+    @requiresReady()
+    public async decryptMedia(file: EncryptedFile): Promise<Buffer> {
+        const contents = (await this.client.downloadContent(file.url)).data;
+        const encrypted = new EncryptedAttachment(
+            contents,
+            JSON.stringify(file),
+        );
+        const decrypted = Attachment.decrypt(encrypted);
+        return Buffer.from(decrypted);
+    }
+
+    /**
+     * Creates and uploads a cross-signing identity, then signs this device with it.
+     * @param {UIACallback} uiaCallback Answers the UIA challenge for the key upload.
+     * @param {boolean} reset Whether to replace an existing local identity.
+     */
+    @requiresReady()
+    public async bootstrapCrossSigning(uiaCallback: UIACallback, reset = false): Promise<void> {
+        return this.engine.bootstrapCrossSigning(uiaCallback, reset);
+    }
+
+    /**
+     * Sets up secret storage (4S) from a passphrase and stores the cross-signing
+     * keys in it. Requires the cross-signing private keys to be available locally.
+     * @param {string} passphrase The secret storage passphrase.
+     * @param opts Whether to also set up server-side key backup, and whether to reset.
+     */
+    @requiresReady()
+    public async bootstrapSecretStorageFromPassphrase(passphrase: string, opts: { withKeyBackup?: boolean, reset?: boolean } = {}): Promise<void> {
+        return this.engine.bootstrapSecretStorageFromPassphrase(passphrase, opts);
+    }
+
+    /**
+     * Restores the cross-signing keys from secret storage, e.g. after losing the
+     * crypto store, without invalidating other devices' trust.
+     * @param {string} passphrase The secret storage passphrase.
+     */
+    @requiresReady()
+    public async restoreSecretsFromSecretStorage(passphrase: string): Promise<void> {
+        return this.engine.restoreSecretsFromSecretStorage(passphrase);
+    }
+
+    /**
+     * Whether this device is signed by the account's self-signing key.
+     */
+    @requiresReady()
+    public async isOwnDeviceCrossSigned(): Promise<boolean> {
+        return isOwnDeviceCrossSigned(this.client, this.deviceId);
+    }
+
+    /**
+     * Whether the account has a default secret storage key.
+     */
+    @requiresReady()
+    public async hasSecretStorage(): Promise<boolean> {
+        return hasSecretStorage(this.client);
+    }
+
+    /**
+     * Makes sure this device is cross-signed. In order: does nothing if it already
+     * is; restores the keys from secret storage if a passphrase is given and the
+     * account has secret storage; otherwise creates a new identity (replacing the
+     * account's existing one) if a UIA callback is given. Errors are thrown.
+     * @param {EnsureCrossSigningOptions} opts Credentials for restoring or bootstrapping.
+     * @returns {Promise<EnsureCrossSigningResult>} What was done.
+     */
+    @requiresReady()
+    public async ensureCrossSigning(opts: EnsureCrossSigningOptions = {}): Promise<EnsureCrossSigningResult> {
+        return ensureCrossSigning(this.client, this.engine, this.deviceId, opts);
+    }
+
+    /**
+     * Sets up secret storage from a passphrase unless the account already has it.
+     * Call after {@link ensureCrossSigning}, since the cross-signing private keys
+     * must be available locally to be stored.
+     * @param {string} passphrase The secret storage passphrase.
+     * @param opts Whether to also set up server-side key backup (default true).
+     * @returns {Promise<EnsureSecretStorageResult>} What was done.
+     */
+    @requiresReady()
+    public async ensureSecretStorage(passphrase: string, opts: { withKeyBackup?: boolean } = {}): Promise<EnsureSecretStorageResult> {
+        return ensureSecretStorage(this.client, this.engine, passphrase, opts);
+    }
+}

package/src/e2ee/ICryptoRoomInformation.ts

@@ -0,0 +1,9 @@
+import { EncryptionEventContent } from "../models/events/EncryptionEvent";
+
+/**
+ * Information about a room for the purposes of crypto.
+ * @category Encryption
+ */
+export interface ICryptoRoomInformation extends Partial<EncryptionEventContent> {
+    historyVisibility?: string;
+}

package/src/e2ee/RoomTracker.ts

@@ -0,0 +1,99 @@
+import { MatrixClient } from "../MatrixClient";
+import { EncryptionEventContent } from "../models/events/EncryptionEvent";
+import { ICryptoRoomInformation } from "./ICryptoRoomInformation";
+
+// noinspection ES6RedundantAwait
+/**
+ * Tracks room encryption status for a MatrixClient.
+ * @category Encryption
+ */
+export class RoomTracker {
+    public constructor(private client: MatrixClient) {
+    }
+
+    /**
+     * Handles a room join
+     * @internal
+     * @param roomId The room ID.
+     */
+    public async onRoomJoin(roomId: string) {
+        await this.queueRoomCheck(roomId);
+    }
+
+    /**
+     * Handles a room event.
+     * @internal
+     * @param roomId The room ID.
+     * @param event The event.
+     */
+    public async onRoomEvent(roomId: string, event: any) {
+        if (event['state_key'] !== '') return; // we don't care about anything else
+        if (event['type'] === 'm.room.encryption' || event['type'] === 'm.room.history_visibility') {
+            await this.queueRoomCheck(roomId);
+        }
+    }
+
+    /**
+     * Prepares the room tracker to track the given rooms.
+     * @param {string[]} roomIds The room IDs to track. This should be the joined rooms set.
+     */
+    public async prepare(roomIds: string[]) {
+        for (const roomId of roomIds) {
+            await this.queueRoomCheck(roomId);
+        }
+    }
+
+    /**
+     * Queues a room check for the tracker. If the room needs an update to the store, an
+     * update will be made.
+     * @param {string} roomId The room ID to check.
+     */
+    public async queueRoomCheck(roomId: string) {
+        const config = await this.client.cryptoStore.getRoom(roomId);
+        if (config) {
+            if (config.algorithm !== undefined) {
+                return; // assume no change to encryption config
+            }
+        }
+
+        let encEvent: Partial<EncryptionEventContent>;
+        try {
+            encEvent = await this.client.getRoomStateEvent(roomId, "m.room.encryption", "");
+            encEvent.algorithm = encEvent.algorithm ?? 'UNKNOWN';
+        } catch (e) {
+            return; // failure == no encryption
+        }
+
+        // Pick out the history visibility setting too
+        let historyVisibility: string;
+        try {
+            const ev = await this.client.getRoomStateEvent(roomId, "m.room.history_visibility", "");
+            historyVisibility = ev.history_visibility;
+        } catch (e) {
+            // ignore - we'll just treat history visibility as normal
+        }
+
+        await this.client.cryptoStore.storeRoom(roomId, {
+            ...encEvent,
+            historyVisibility,
+        });
+    }
+
+    /**
+     * Gets the room's crypto configuration, as known by the underlying store. If the room is
+     * not encrypted then this will return an empty object.
+     * @param {string} roomId The room ID to get the config for.
+     * @returns {Promise<ICryptoRoomInformation>} Resolves to the encryption config.
+     */
+    public async getRoomCryptoConfig(roomId: string): Promise<ICryptoRoomInformation> {
+        let config = await this.client.cryptoStore.getRoom(roomId);
+        if (!config) {
+            await this.queueRoomCheck(roomId);
+            config = await this.client.cryptoStore.getRoom(roomId);
+        }
+        if (!config) {
+            return {};
+        }
+        return config;
+    }
+}