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

package/lib/e2ee/RoomTracker.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoomTracker = void 0;
+// noinspection ES6RedundantAwait
+/**
+ * Tracks room encryption status for a MatrixClient.
+ * @category Encryption
+ */
+class RoomTracker {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Handles a room join
+     * @internal
+     * @param roomId The room ID.
+     */
+    async onRoomJoin(roomId) {
+        await this.queueRoomCheck(roomId);
+    }
+    /**
+     * Handles a room event.
+     * @internal
+     * @param roomId The room ID.
+     * @param event The event.
+     */
+    async onRoomEvent(roomId, event) {
+        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.
+     */
+    async prepare(roomIds) {
+        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.
+     */
+    async queueRoomCheck(roomId) {
+        const config = await this.client.cryptoStore.getRoom(roomId);
+        if (config) {
+            if (config.algorithm !== undefined) {
+                return; // assume no change to encryption config
+            }
+        }
+        let encEvent;
+        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;
+        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.
+     */
+    async getRoomCryptoConfig(roomId) {
+        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;
+    }
+}
+exports.RoomTracker = RoomTracker;
+//# sourceMappingURL=RoomTracker.js.map

package/lib/e2ee/RoomTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoomTracker.js","sourceRoot":"","sources":["../../src/e2ee/RoomTracker.ts"],"names":[],"mappings":";;;AAIA,iCAAiC;AACjC;;;GAGG;AACH,MAAa,WAAW;IACpB,YAA2B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAC/C,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,UAAU,CAAC,MAAc;QAClC,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,KAAU;QAC/C,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE;YAAE,OAAO,CAAC,oCAAoC;QAC3E,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,mBAAmB,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,2BAA2B,EAAE,CAAC;YACzF,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;IACL,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,OAAO,CAAC,OAAiB;QAClC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,cAAc,CAAC,MAAc;QACtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7D,IAAI,MAAM,EAAE,CAAC;YACT,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBACjC,OAAO,CAAC,wCAAwC;YACpD,CAAC;QACL,CAAC;QAED,IAAI,QAAyC,CAAC;QAC9C,IAAI,CAAC;YACD,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;YAChF,QAAQ,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,SAAS,CAAC;QACzD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,OAAO,CAAC,2BAA2B;QACvC,CAAC;QAED,8CAA8C;QAC9C,IAAI,iBAAyB,CAAC;QAC9B,IAAI,CAAC;YACD,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,2BAA2B,EAAE,EAAE,CAAC,CAAC;YACxF,iBAAiB,GAAG,EAAE,CAAC,kBAAkB,CAAC;QAC9C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,yDAAyD;QAC7D,CAAC;QAED,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE;YAC5C,GAAG,QAAQ;YACX,iBAAiB;SACpB,CAAC,CAAC;IACP,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,mBAAmB,CAAC,MAAc;QAC3C,IAAI,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAClC,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ;AAzFD,kCAyFC"}

package/lib/e2ee/RustEngine.d.ts

@@ -0,0 +1,149 @@
+import { OlmMachine } from "@matrix-org/matrix-sdk-crypto-nodejs";
+import * as AsyncLock from "async-lock";
+import { MatrixClient } from "../MatrixClient";
+import { ICryptoRoomInformation } from "./ICryptoRoomInformation";
+/**
+ * @internal
+ */
+export declare const SYNC_LOCK_NAME = "sync";
+/**
+ * Callback invoked to satisfy a User-Interactive Authentication (UIA) challenge
+ * when uploading cross-signing keys. Given the `flows`/`params`/`session` from a
+ * 401 response, it must return the `auth` dict to retry with (e.g. an
+ * `m.login.password` stage), or `null` to give up. May be called more than once
+ * if the server requires multiple stages.
+ *
+ * @category Encryption
+ */
+export type UIACallback = (uia: {
+    flows: {
+        stages: string[];
+    }[];
+    params?: Record<string, unknown>;
+    session?: string;
+}) => Promise<Record<string, unknown> | null>;
+/**
+ * @internal
+ */
+export declare class RustEngine {
+    readonly machine: OlmMachine;
+    private client;
+    readonly lock: AsyncLock;
+    constructor(machine: OlmMachine, client: MatrixClient);
+    run(): Promise<void>;
+    private runOnly;
+    addTrackedUsers(userIds: string[]): Promise<void>;
+    prepareEncrypt(roomId: string, roomInfo: ICryptoRoomInformation): Promise<void>;
+    private processKeysClaimRequest;
+    private processKeysUploadRequest;
+    private processKeysQueryRequest;
+    private processToDeviceRequest;
+    private actuallyProcessToDeviceRequest;
+    private processSignatureUploadRequest;
+    private processKeysBackupRequest;
+    /** The currently-active server-side key-backup version, or null if none. */
+    private activeKeyBackupVersion;
+    /**
+     * Publish a cross-signing identity for this account so the device becomes
+     * cross-signed (self-verified). This is the piece matrix-bot-sdk historically
+     * could not drive: `runOnly` threw on the request types it produces, and the
+     * cross-signing public-key upload is not an outgoing-queue request at all —
+     * it is returned by `OlmMachine.bootstrapCrossSigning()`.
+     *
+     * Flow:
+     *   1. `machine.bootstrapCrossSigning(reset)` creates the identity locally
+     *      and (on matrix-sdk-crypto-nodejs >= 0.5.0) returns the three upload
+     *      requests.
+     *   2. Upload device keys (`uploadKeysReq`) if present.
+     *   3. POST the cross-signing public keys to `/keys/device_signing/upload`,
+     *      completing the User-Interactive Auth challenge via `uiaCallback`.
+     *   4. POST the self-signature to `/keys/signatures/upload`.
+     *
+     * On bindings <= 0.4.0, `bootstrapCrossSigning` returns `void` and gives no
+     * way to retrieve the upload requests, so this method throws a clear,
+     * actionable error (callers are expected to treat that as non-fatal).
+     *
+     * @param uiaCallback Resolves the UIA challenge for the device-signing upload.
+     * @param reset Pass `false` (default) to reuse an existing local identity;
+     *              the same request can be re-sent across UIA stages. `true`
+     *              wipes any existing identity and resets device trust.
+     */
+    bootstrapCrossSigning(uiaCallback: UIACallback, reset?: boolean): Promise<void>;
+    /**
+     * POST the cross-signing public keys to `/keys/device_signing/upload`,
+     * driving the UIA challenge. The first attempt is sent without `auth`; the
+     * server replies 401 with the available flows, which `uiaCallback` resolves
+     * (typically an `m.login.password` stage). We then resubmit the SAME key
+     * body with the returned `auth` dict (including the `session` id).
+     */
+    private uploadDeviceSigningKeys;
+    /**
+     * Create + activate a server-side key-backup version derived from the given
+     * recovery/backup public key, and tell the OlmMachine to use it. After this,
+     * `KeysBackup` requests produced by `backupRoomKeys()` will have a version to
+     * write into (handled in `processKeysBackupRequest`).
+     *
+     * NOTE: key backup is secondary to cross-signing. This wires the version
+     * plumbing; the caller is responsible for generating the backup key and for
+     * calling `machine.enableBackupV1()` / `backupRoomKeys()`. It is intentionally
+     * conservative — see the adapter docs.
+     */
+    enableKeyBackup(authData: Record<string, unknown>, algorithm?: string): Promise<string>;
+    /**
+     * Restore cross-signing private keys (and optionally the megolm backup decryption
+     * key) from Secure Secret Storage (4S/SSSS) into the local crypto store.
+     *
+     * This is the recovery path when the local crypto store has been lost: the
+     * cross-signing keys were previously uploaded encrypted to account data by
+     * `bootstrapSecretStorage*`, and this method fetches and decrypts them using
+     * the same passphrase. After a successful restore:
+     *
+     * - The OlmMachine has the master / self-signing / user-signing private keys.
+     * - The device re-signs itself, so it continues to appear verified without
+     *   needing UIA or a fresh cross-signing bootstrap.
+     * - If the megolm backup decryption key is in account data, it is also
+     *   restored so room-key backup requests work with the existing backup version.
+     *
+     * Requires `@matrix-org/matrix-sdk-crypto-nodejs >= 0.6.0` (for
+     * `importSecretsFromSecretStorage`). Throws if the passphrase does not match
+     * the SSSS key on the server, or if account data is missing.
+     *
+     * @param passphrase The same passphrase that was used to bootstrap 4S.
+     */
+    restoreSecretsFromSecretStorage(passphrase: string): Promise<void>;
+    private bootstrapSecretStorage;
+    bootstrapSecretStorageFromPassphrase(passphrase: string, opts?: {
+        withKeyBackup?: boolean;
+        reset?: boolean;
+    }): Promise<void>;
+    bootstrapSecretStorageFromKey(ssssKey: import("@matrix-org/matrix-sdk-crypto-nodejs").SecretStorageKey, opts?: {
+        withKeyBackup?: boolean;
+        reset?: boolean;
+    }): Promise<void>;
+    private bootstrapKeyBackupIntoSecretStorage;
+    private putAccountData;
+}
+/**
+ * Extract a UIA challenge from a thrown matrix-bot-sdk request error. A 401 UIA
+ * body has `flows`/`session` and no `errcode`, so matrix-bot-sdk throws the raw
+ * response object (`throw response`) rather than a `MatrixError`. We also accept
+ * a `MatrixError`-like shape defensively. Returns null if it is not a UIA 401.
+ *
+ * @internal
+ */
+export declare function extractUIA(err: unknown): {
+    flows: {
+        stages: string[];
+    }[];
+    params?: Record<string, unknown>;
+    session?: string;
+} | null;
+/**
+ * A second 401 whose body reports `completed: []` (or an unchanged stage list)
+ * after we supplied credentials indicates the credentials were rejected, not a
+ * stacked second stage. We treat the presence of an `error`/`errcode` in the
+ * body as a hard rejection.
+ *
+ * @internal
+ */
+export declare function hasFailedUIA(err: unknown): boolean;