@archipelagolab/lobi 1.0.6 → 1.0.7

package/src/matrix/sdk.ts

@@ -0,0 +1,1789 @@
+import { EventEmitter } from "node:events";
+import {
+  ClientEvent,
+  MatrixEventEvent,
+  Preset,
+  createClient as createMatrixJsClient,
+  type MatrixClient as MatrixJsClient,
+  type MatrixEvent,
+} from "matrix-js-sdk/lib/matrix.js";
+import { VerificationMethod } from "matrix-js-sdk/lib/types.js";
+import type { PinnedDispatcherPolicy } from "openclaw/plugin-sdk/infra-runtime";
+import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
+import { normalizeNullableString } from "openclaw/plugin-sdk/text-runtime";
+import type { SsrFPolicy } from "../runtime-api.js";
+import { resolveMatrixRoomKeyBackupReadinessError } from "./backup-health.js";
+import { FileBackedMatrixSyncStore } from "./client/file-sync-store.js";
+import { createMatrixJsSdkClientLogger } from "./client/logging.js";
+import {
+  formatMatrixErrorMessage,
+  formatMatrixErrorReason,
+  isMatrixNotFoundError,
+} from "./errors.js";
+import type {
+  MatrixCryptoBootstrapOptions,
+  MatrixCryptoBootstrapResult,
+} from "./sdk/crypto-bootstrap.js";
+import type { MatrixCryptoFacade } from "./sdk/crypto-facade.js";
+import type { MatrixDecryptBridge } from "./sdk/decrypt-bridge.js";
+import { matrixEventToRaw, parseMxc } from "./sdk/event-helpers.js";
+import { MatrixAuthedHttpClient } from "./sdk/http-client.js";
+import { MATRIX_IDB_PERSIST_INTERVAL_MS } from "./sdk/idb-persistence-lock.js";
+import { ConsoleLogger, LogService, noop } from "./sdk/logger.js";
+import {
+  MatrixRecoveryKeyStore,
+  isRepairableSecretStorageAccessError,
+} from "./sdk/recovery-key-store.js";
+import { createMatrixGuardedFetch, type HttpMethod, type QueryParams } from "./sdk/transport.js";
+import type {
+  MatrixClientEventMap,
+  MatrixCryptoBootstrapApi,
+  MatrixDeviceVerificationStatusLike,
+  MatrixRelationsPage,
+  MatrixRawEvent,
+  MessageEventContent,
+} from "./sdk/types.js";
+import type { MatrixVerificationSummary } from "./sdk/verification-manager.js";
+import { createMatrixStartupAbortError, throwIfMatrixStartupAborted } from "./startup-abort.js";
+import {
+  isMatrixReadySyncState,
+  isMatrixTerminalSyncState,
+  type MatrixSyncState,
+} from "./sync-state.js";
+
+export { ConsoleLogger, LogService };
+export type {
+  DimensionalFileInfo,
+  FileWithThumbnailInfo,
+  TimedFileInfo,
+  VideoFileInfo,
+} from "./sdk/types.js";
+export type {
+  EncryptedFile,
+  LocationMessageEventContent,
+  MatrixRawEvent,
+  MessageEventContent,
+  TextualMessageEventContent,
+} from "./sdk/types.js";
+
+export type MatrixOwnDeviceVerificationStatus = {
+  encryptionEnabled: boolean;
+  userId: string | null;
+  deviceId: string | null;
+  // "verified" is intentionally strict: other Matrix clients should trust messages
+  // from this device without showing "not verified by its owner" warnings.
+  verified: boolean;
+  localVerified: boolean;
+  crossSigningVerified: boolean;
+  signedByOwner: boolean;
+  recoveryKeyStored: boolean;
+  recoveryKeyCreatedAt: string | null;
+  recoveryKeyId: string | null;
+  backupVersion: string | null;
+  backup: MatrixRoomKeyBackupStatus;
+};
+
+export type MatrixRoomKeyBackupStatus = {
+  serverVersion: string | null;
+  activeVersion: string | null;
+  trusted: boolean | null;
+  matchesDecryptionKey: boolean | null;
+  decryptionKeyCached: boolean | null;
+  keyLoadAttempted: boolean;
+  keyLoadError: string | null;
+};
+
+export type MatrixRoomKeyBackupRestoreResult = {
+  success: boolean;
+  error?: string;
+  backupVersion: string | null;
+  imported: number;
+  total: number;
+  loadedFromSecretStorage: boolean;
+  restoredAt?: string;
+  backup: MatrixRoomKeyBackupStatus;
+};
+
+export type MatrixRoomKeyBackupResetResult = {
+  success: boolean;
+  error?: string;
+  previousVersion: string | null;
+  deletedVersion: string | null;
+  createdVersion: string | null;
+  resetAt?: string;
+  backup: MatrixRoomKeyBackupStatus;
+};
+
+export type MatrixRecoveryKeyVerificationResult = MatrixOwnDeviceVerificationStatus & {
+  success: boolean;
+  verifiedAt?: string;
+  error?: string;
+};
+
+export type MatrixOwnCrossSigningPublicationStatus = {
+  userId: string | null;
+  masterKeyPublished: boolean;
+  selfSigningKeyPublished: boolean;
+  userSigningKeyPublished: boolean;
+  published: boolean;
+};
+
+export type MatrixVerificationBootstrapResult = {
+  success: boolean;
+  error?: string;
+  verification: MatrixOwnDeviceVerificationStatus;
+  crossSigning: MatrixOwnCrossSigningPublicationStatus;
+  pendingVerifications: number;
+  cryptoBootstrap: MatrixCryptoBootstrapResult | null;
+};
+
+const MATRIX_INITIAL_CRYPTO_BOOTSTRAP_OPTIONS = {
+  allowAutomaticCrossSigningReset: false,
+} satisfies MatrixCryptoBootstrapOptions;
+
+const MATRIX_AUTOMATIC_REPAIR_BOOTSTRAP_OPTIONS = {
+  forceResetCrossSigning: true,
+  allowSecretStorageRecreateWithoutRecoveryKey: true,
+  strict: true,
+} satisfies MatrixCryptoBootstrapOptions;
+
+function createMatrixExplicitBootstrapOptions(params?: {
+  forceResetCrossSigning?: boolean;
+}): MatrixCryptoBootstrapOptions {
+  return {
+    forceResetCrossSigning: params?.forceResetCrossSigning === true,
+    allowSecretStorageRecreateWithoutRecoveryKey: true,
+    strict: true,
+  };
+}
+
+export type MatrixOwnDeviceInfo = {
+  deviceId: string;
+  displayName: string | null;
+  lastSeenIp: string | null;
+  lastSeenTs: number | null;
+  current: boolean;
+};
+
+export type MatrixOwnDeviceDeleteResult = {
+  currentDeviceId: string | null;
+  deletedDeviceIds: string[];
+  remainingDevices: MatrixOwnDeviceInfo[];
+};
+
+type MatrixCryptoRuntime = typeof import("./sdk/crypto-runtime.js");
+
+let loadedMatrixCryptoRuntime: MatrixCryptoRuntime | null = null;
+let matrixCryptoRuntimePromise: Promise<MatrixCryptoRuntime> | null = null;
+
+async function loadMatrixCryptoRuntime(): Promise<MatrixCryptoRuntime> {
+  matrixCryptoRuntimePromise ??= import("./sdk/crypto-runtime.js").then((runtime) => {
+    loadedMatrixCryptoRuntime = runtime;
+    return runtime;
+  });
+  return await matrixCryptoRuntimePromise;
+}
+
+const normalizeOptionalString = normalizeNullableString;
+
+function isUnsupportedAuthenticatedMediaEndpointError(err: unknown): boolean {
+  const statusCode = (err as { statusCode?: number })?.statusCode;
+  if (statusCode === 404 || statusCode === 405 || statusCode === 501) {
+    return true;
+  }
+  const message = formatMatrixErrorReason(err);
+  return (
+    message.includes("m_unrecognized") ||
+    message.includes("unrecognized request") ||
+    message.includes("method not allowed") ||
+    message.includes("not implemented")
+  );
+}
+
+export class MatrixClient {
+  private readonly client: MatrixJsClient;
+  private readonly emitter = new EventEmitter();
+  private readonly httpClient: MatrixAuthedHttpClient;
+  private readonly localTimeoutMs: number;
+  private readonly initialSyncLimit?: number;
+  private readonly encryptionEnabled: boolean;
+  private readonly password?: string;
+  private readonly syncStore?: FileBackedMatrixSyncStore;
+  private readonly idbSnapshotPath?: string;
+  private readonly cryptoDatabasePrefix?: string;
+  private bridgeRegistered = false;
+  private started = false;
+  private cryptoBootstrapped = false;
+  private selfUserId: string | null;
+  private readonly dmRoomIds = new Set<string>();
+  private cryptoInitialized = false;
+  private decryptBridge?: MatrixDecryptBridge<MatrixRawEvent>;
+  private verificationManager?: import("./sdk/verification-manager.js").MatrixVerificationManager;
+  private readonly sendQueue = new KeyedAsyncQueue();
+  private readonly recoveryKeyStore: MatrixRecoveryKeyStore;
+  private cryptoBootstrapper?:
+    | import("./sdk/crypto-bootstrap.js").MatrixCryptoBootstrapper<MatrixRawEvent>
+    | undefined;
+  private readonly autoBootstrapCrypto: boolean;
+  private stopPersistPromise: Promise<void> | null = null;
+  private verificationSummaryListenerBound = false;
+  private currentSyncState: MatrixSyncState | null = null;
+
+  readonly dms = {
+    update: async (): Promise<boolean> => {
+      return await this.refreshDmCache();
+    },
+    isDm: (roomId: string): boolean => this.dmRoomIds.has(roomId),
+  };
+
+  crypto?: MatrixCryptoFacade;
+
+  constructor(
+    homeserver: string,
+    accessToken: string,
+    opts: {
+      userId?: string;
+      password?: string;
+      deviceId?: string;
+      localTimeoutMs?: number;
+      encryption?: boolean;
+      initialSyncLimit?: number;
+      storagePath?: string;
+      recoveryKeyPath?: string;
+      idbSnapshotPath?: string;
+      cryptoDatabasePrefix?: string;
+      autoBootstrapCrypto?: boolean;
+      ssrfPolicy?: SsrFPolicy;
+      dispatcherPolicy?: PinnedDispatcherPolicy;
+    } = {},
+  ) {
+    this.httpClient = new MatrixAuthedHttpClient({
+      homeserver,
+      accessToken,
+      ssrfPolicy: opts.ssrfPolicy,
+      dispatcherPolicy: opts.dispatcherPolicy,
+    });
+    this.localTimeoutMs = Math.max(1, opts.localTimeoutMs ?? 60_000);
+    this.initialSyncLimit = opts.initialSyncLimit;
+    this.encryptionEnabled = opts.encryption === true;
+    this.password = opts.password;
+    this.syncStore = opts.storagePath ? new FileBackedMatrixSyncStore(opts.storagePath) : undefined;
+    this.idbSnapshotPath = opts.idbSnapshotPath;
+    this.cryptoDatabasePrefix = opts.cryptoDatabasePrefix;
+    this.selfUserId = opts.userId?.trim() || null;
+    this.autoBootstrapCrypto = opts.autoBootstrapCrypto !== false;
+    this.recoveryKeyStore = new MatrixRecoveryKeyStore(opts.recoveryKeyPath);
+    const cryptoCallbacks = this.encryptionEnabled
+      ? this.recoveryKeyStore.buildCryptoCallbacks()
+      : undefined;
+    this.client = createMatrixJsClient({
+      baseUrl: homeserver,
+      accessToken,
+      userId: opts.userId,
+      deviceId: opts.deviceId,
+      logger: createMatrixJsSdkClientLogger("MatrixClient"),
+      localTimeoutMs: this.localTimeoutMs,
+      fetchFn: createMatrixGuardedFetch({
+        ssrfPolicy: opts.ssrfPolicy,
+        dispatcherPolicy: opts.dispatcherPolicy,
+      }),
+      store: this.syncStore,
+      cryptoCallbacks: cryptoCallbacks as never,
+      verificationMethods: [
+        VerificationMethod.Sas,
+        VerificationMethod.ShowQrCode,
+        VerificationMethod.ScanQrCode,
+        VerificationMethod.Reciprocate,
+      ],
+    });
+  }
+
+  on<TEvent extends keyof MatrixClientEventMap>(
+    eventName: TEvent,
+    listener: (...args: MatrixClientEventMap[TEvent]) => void,
+  ): this;
+  on(eventName: string, listener: (...args: unknown[]) => void): this;
+  on(eventName: string, listener: (...args: unknown[]) => void): this {
+    this.emitter.on(eventName, listener as (...args: unknown[]) => void);
+    return this;
+  }
+
+  off<TEvent extends keyof MatrixClientEventMap>(
+    eventName: TEvent,
+    listener: (...args: MatrixClientEventMap[TEvent]) => void,
+  ): this;
+  off(eventName: string, listener: (...args: unknown[]) => void): this;
+  off(eventName: string, listener: (...args: unknown[]) => void): this {
+    this.emitter.off(eventName, listener as (...args: unknown[]) => void);
+    return this;
+  }
+
+  private idbPersistTimer: ReturnType<typeof setInterval> | null = null;
+
+  private async ensureCryptoSupportInitialized(): Promise<void> {
+    if (
+      this.decryptBridge &&
+      (!this.encryptionEnabled ||
+        (this.verificationManager && this.cryptoBootstrapper && this.crypto))
+    ) {
+      return;
+    }
+
+    const runtime = await loadMatrixCryptoRuntime();
+    this.decryptBridge ??= new runtime.MatrixDecryptBridge<MatrixRawEvent>({
+      client: this.client,
+      toRaw: (event) => matrixEventToRaw(event),
+      emitDecryptedEvent: (roomId, event) => {
+        this.emitter.emit("room.decrypted_event", roomId, event);
+      },
+      emitMessage: (roomId, event) => {
+        this.emitter.emit("room.message", roomId, event);
+      },
+      emitFailedDecryption: (roomId, event, error) => {
+        this.emitter.emit("room.failed_decryption", roomId, event, error);
+      },
+    });
+    if (!this.encryptionEnabled) {
+      return;
+    }
+
+    this.verificationManager ??= new runtime.MatrixVerificationManager();
+    this.cryptoBootstrapper ??= new runtime.MatrixCryptoBootstrapper<MatrixRawEvent>({
+      getUserId: () => this.getUserId(),
+      getPassword: () => this.password,
+      getDeviceId: () => this.client.getDeviceId(),
+      verificationManager: this.verificationManager,
+      recoveryKeyStore: this.recoveryKeyStore,
+      decryptBridge: this.decryptBridge,
+    });
+    if (!this.crypto) {
+      this.crypto = runtime.createMatrixCryptoFacade({
+        client: this.client,
+        verificationManager: this.verificationManager,
+        recoveryKeyStore: this.recoveryKeyStore,
+        getRoomStateEvent: (roomId, eventType, stateKey = "") =>
+          this.getRoomStateEvent(roomId, eventType, stateKey),
+        downloadContent: (mxcUrl) => this.downloadContent(mxcUrl),
+      });
+    }
+    if (!this.verificationSummaryListenerBound) {
+      this.verificationSummaryListenerBound = true;
+      this.verificationManager.onSummaryChanged((summary: MatrixVerificationSummary) => {
+        this.emitter.emit("verification.summary", summary);
+      });
+    }
+  }
+
+  async start(opts: { abortSignal?: AbortSignal; readyTimeoutMs?: number } = {}): Promise<void> {
+    await this.startSyncSession({
+      bootstrapCrypto: true,
+      abortSignal: opts.abortSignal,
+      readyTimeoutMs: opts.readyTimeoutMs,
+    });
+  }
+
+  private async waitForInitialSyncReady(
+    params: {
+      timeoutMs?: number;
+      abortSignal?: AbortSignal;
+    } = {},
+  ): Promise<void> {
+    const timeoutMs = params.timeoutMs ?? 30_000;
+    if (isMatrixReadySyncState(this.currentSyncState)) {
+      return;
+    }
+    if (isMatrixTerminalSyncState(this.currentSyncState)) {
+      throw new Error(`Matrix sync entered ${this.currentSyncState} during startup`);
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const abortSignal = params.abortSignal;
+
+      const cleanup = () => {
+        this.off("sync.state", onSyncState);
+        this.off("sync.unexpected_error", onUnexpectedError);
+        abortSignal?.removeEventListener("abort", onAbort);
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = undefined;
+        }
+      };
+
+      const settleResolve = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve();
+      };
+
+      const settleReject = (error: Error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+
+      const onSyncState = (state: MatrixSyncState, _prevState: string | null, error?: unknown) => {
+        if (isMatrixReadySyncState(state)) {
+          settleResolve();
+          return;
+        }
+        if (isMatrixTerminalSyncState(state)) {
+          settleReject(
+            new Error(
+              error instanceof Error && error.message
+                ? error.message
+                : `Matrix sync entered ${state} during startup`,
+            ),
+          );
+        }
+      };
+
+      const onUnexpectedError = (error: Error) => {
+        settleReject(error);
+      };
+
+      const onAbort = () => {
+        settleReject(createMatrixStartupAbortError());
+      };
+
+      this.on("sync.state", onSyncState);
+      this.on("sync.unexpected_error", onUnexpectedError);
+      if (abortSignal?.aborted) {
+        onAbort();
+        return;
+      }
+      abortSignal?.addEventListener("abort", onAbort, { once: true });
+      timeoutId = setTimeout(() => {
+        settleReject(
+          new Error(`Matrix client did not reach a ready sync state within ${timeoutMs}ms`),
+        );
+      }, timeoutMs);
+      timeoutId.unref?.();
+    });
+  }
+
+  private async startSyncSession(opts: {
+    bootstrapCrypto: boolean;
+    abortSignal?: AbortSignal;
+    readyTimeoutMs?: number;
+  }): Promise<void> {
+    if (this.started) {
+      return;
+    }
+
+    throwIfMatrixStartupAborted(opts.abortSignal);
+    await this.ensureCryptoSupportInitialized();
+    throwIfMatrixStartupAborted(opts.abortSignal);
+    this.registerBridge();
+    await this.initializeCryptoIfNeeded(opts.abortSignal);
+
+    await this.client.startClient({
+      initialSyncLimit: this.initialSyncLimit,
+    });
+    await this.waitForInitialSyncReady({
+      abortSignal: opts.abortSignal,
+      timeoutMs: opts.readyTimeoutMs,
+    });
+    throwIfMatrixStartupAborted(opts.abortSignal);
+    if (opts.bootstrapCrypto && this.autoBootstrapCrypto) {
+      await this.bootstrapCryptoIfNeeded(opts.abortSignal);
+    }
+    throwIfMatrixStartupAborted(opts.abortSignal);
+    this.started = true;
+    this.emitOutstandingInviteEvents();
+    await this.refreshDmCache().catch(noop);
+  }
+
+  async prepareForOneOff(): Promise<void> {
+    if (!this.encryptionEnabled) {
+      return;
+    }
+    await this.ensureCryptoSupportInitialized();
+    await this.initializeCryptoIfNeeded();
+    if (!this.crypto) {
+      return;
+    }
+    try {
+      const joinedRooms = await this.getJoinedRooms();
+      await this.crypto.prepare(joinedRooms);
+    } catch {
+      // One-off commands should continue even if crypto room prep is incomplete.
+    }
+  }
+
+  hasPersistedSyncState(): boolean {
+    // Only trust restart replay when the previous process completed a final
+    // sync-store persist. A stale cursor can make Matrix re-surface old events.
+    return this.syncStore?.hasSavedSyncFromCleanShutdown() === true;
+  }
+
+  private async ensureStartedForCryptoControlPlane(): Promise<void> {
+    if (this.started) {
+      return;
+    }
+    await this.startSyncSession({ bootstrapCrypto: false });
+  }
+
+  stopSyncWithoutPersist(): void {
+    if (this.idbPersistTimer) {
+      clearInterval(this.idbPersistTimer);
+      this.idbPersistTimer = null;
+    }
+    this.currentSyncState = null;
+    this.client.stopClient();
+    this.started = false;
+  }
+
+  async drainPendingDecryptions(reason = "matrix client shutdown"): Promise<void> {
+    await this.decryptBridge?.drainPendingDecryptions(reason);
+  }
+
+  stop(): void {
+    this.stopSyncWithoutPersist();
+    this.decryptBridge?.stop();
+    // Final persist on shutdown
+    this.syncStore?.markCleanShutdown();
+    if (loadedMatrixCryptoRuntime) {
+      const { persistIdbToDisk } = loadedMatrixCryptoRuntime;
+      this.stopPersistPromise = Promise.all([
+        persistIdbToDisk({
+          snapshotPath: this.idbSnapshotPath,
+          databasePrefix: this.cryptoDatabasePrefix,
+        }).catch(noop),
+        this.syncStore?.flush().catch(noop),
+      ]).then(() => undefined);
+      return;
+    }
+    this.stopPersistPromise = loadMatrixCryptoRuntime()
+      .then(async ({ persistIdbToDisk }) => {
+        await Promise.all([
+          persistIdbToDisk({
+            snapshotPath: this.idbSnapshotPath,
+            databasePrefix: this.cryptoDatabasePrefix,
+          }).catch(noop),
+          this.syncStore?.flush().catch(noop),
+        ]);
+      })
+      .catch(noop)
+      .then(() => undefined);
+  }
+
+  async stopAndPersist(): Promise<void> {
+    this.stop();
+    await this.stopPersistPromise;
+  }
+
+  private async bootstrapCryptoIfNeeded(abortSignal?: AbortSignal): Promise<void> {
+    if (!this.encryptionEnabled || !this.cryptoInitialized || this.cryptoBootstrapped) {
+      return;
+    }
+    throwIfMatrixStartupAborted(abortSignal);
+    await this.ensureCryptoSupportInitialized();
+    const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+    if (!crypto) {
+      return;
+    }
+    const cryptoBootstrapper = this.cryptoBootstrapper;
+    if (!cryptoBootstrapper) {
+      return;
+    }
+    const initial = await cryptoBootstrapper.bootstrap(
+      crypto,
+      MATRIX_INITIAL_CRYPTO_BOOTSTRAP_OPTIONS,
+    );
+    throwIfMatrixStartupAborted(abortSignal);
+    if (!initial.crossSigningPublished || initial.ownDeviceVerified === false) {
+      const status = await this.getOwnDeviceVerificationStatus();
+      if (status.signedByOwner) {
+        LogService.warn(
+          "MatrixClientLite",
+          "Cross-signing/bootstrap is incomplete for an already owner-signed device; skipping automatic reset and preserving the current identity. Restore the recovery key or run an explicit verification bootstrap if repair is needed.",
+        );
+      } else if (this.password?.trim()) {
+        try {
+          // The repair path already force-resets cross-signing; allow secret storage
+          // recreation so the new keys can be persisted. Without this, a device that
+          // lost its recovery key enters a permanent failure loop because the new
+          // cross-signing keys have nowhere to be stored.
+          const repaired = await cryptoBootstrapper.bootstrap(
+            crypto,
+            MATRIX_AUTOMATIC_REPAIR_BOOTSTRAP_OPTIONS,
+          );
+          throwIfMatrixStartupAborted(abortSignal);
+          if (repaired.crossSigningPublished && repaired.ownDeviceVerified !== false) {
+            LogService.info(
+              "MatrixClientLite",
+              "Cross-signing/bootstrap recovered after forced reset",
+            );
+          }
+        } catch (err) {
+          LogService.warn(
+            "MatrixClientLite",
+            "Failed to recover cross-signing/bootstrap with forced reset:",
+            err,
+          );
+        }
+      } else {
+        LogService.warn(
+          "MatrixClientLite",
+          "Cross-signing/bootstrap incomplete and no password is configured for UIA fallback",
+        );
+      }
+    }
+    this.cryptoBootstrapped = true;
+  }
+
+  private async initializeCryptoIfNeeded(abortSignal?: AbortSignal): Promise<void> {
+    if (!this.encryptionEnabled || this.cryptoInitialized) {
+      return;
+    }
+    throwIfMatrixStartupAborted(abortSignal);
+    const { persistIdbToDisk, restoreIdbFromDisk } = await loadMatrixCryptoRuntime();
+
+    // Restore persisted IndexedDB crypto store before initializing WASM crypto.
+    await restoreIdbFromDisk(this.idbSnapshotPath);
+    throwIfMatrixStartupAborted(abortSignal);
+
+    try {
+      await this.client.initRustCrypto({
+        cryptoDatabasePrefix: this.cryptoDatabasePrefix,
+      });
+      this.cryptoInitialized = true;
+      throwIfMatrixStartupAborted(abortSignal);
+
+      // Persist the crypto store after successful init (captures fresh keys on first run).
+      await persistIdbToDisk({
+        snapshotPath: this.idbSnapshotPath,
+        databasePrefix: this.cryptoDatabasePrefix,
+      });
+      throwIfMatrixStartupAborted(abortSignal);
+
+      // Periodically persist to capture new Olm sessions and room keys.
+      this.idbPersistTimer = setInterval(() => {
+        persistIdbToDisk({
+          snapshotPath: this.idbSnapshotPath,
+          databasePrefix: this.cryptoDatabasePrefix,
+        }).catch(noop);
+      }, MATRIX_IDB_PERSIST_INTERVAL_MS);
+    } catch (err) {
+      LogService.warn("MatrixClientLite", "Failed to initialize rust crypto:", err);
+    }
+  }
+
+  async getUserId(): Promise<string> {
+    const fromClient = this.client.getUserId();
+    if (fromClient) {
+      this.selfUserId = fromClient;
+      return fromClient;
+    }
+    if (this.selfUserId) {
+      return this.selfUserId;
+    }
+    const whoami = (await this.doRequest("GET", "/_matrix/client/v3/account/whoami")) as {
+      user_id?: string;
+    };
+    const resolved = whoami.user_id?.trim();
+    if (!resolved) {
+      throw new Error("Matrix whoami did not return user_id");
+    }
+    this.selfUserId = resolved;
+    return resolved;
+  }
+
+  async getJoinedRooms(): Promise<string[]> {
+    const joined = await this.client.getJoinedRooms();
+    return Array.isArray(joined.joined_rooms) ? joined.joined_rooms : [];
+  }
+
+  async getJoinedRoomMembers(roomId: string): Promise<string[]> {
+    const members = await this.client.getJoinedRoomMembers(roomId);
+    const joined = members?.joined;
+    if (!joined || typeof joined !== "object") {
+      return [];
+    }
+    return Object.keys(joined);
+  }
+
+  async getRoomStateEvent(
+    roomId: string,
+    eventType: string,
+    stateKey = "",
+  ): Promise<Record<string, unknown>> {
+    const state = await this.client.getStateEvent(roomId, eventType, stateKey);
+    return (state ?? {}) as Record<string, unknown>;
+  }
+
+  async getAccountData(eventType: string): Promise<Record<string, unknown> | undefined> {
+    const event = this.client.getAccountData(eventType as never);
+    return (event?.getContent() as Record<string, unknown> | undefined) ?? undefined;
+  }
+
+  async setAccountData(eventType: string, content: Record<string, unknown>): Promise<void> {
+    await this.client.setAccountData(eventType as never, content as never);
+    await this.refreshDmCache().catch(noop);
+  }
+
+  async resolveRoom(aliasOrRoomId: string): Promise<string | null> {
+    if (aliasOrRoomId.startsWith("!")) {
+      return aliasOrRoomId;
+    }
+    if (!aliasOrRoomId.startsWith("#")) {
+      return aliasOrRoomId;
+    }
+    try {
+      const resolved = await this.client.getRoomIdForAlias(aliasOrRoomId);
+      return resolved.room_id ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async createDirectRoom(
+    remoteUserId: string,
+    opts: { encrypted?: boolean } = {},
+  ): Promise<string> {
+    const initialState = opts.encrypted
+      ? [
+          {
+            type: "m.room.encryption",
+            state_key: "",
+            content: {
+              algorithm: "m.megolm.v1.aes-sha2",
+            },
+          },
+        ]
+      : undefined;
+    const result = await this.client.createRoom({
+      invite: [remoteUserId],
+      is_direct: true,
+      preset: Preset.TrustedPrivateChat,
+      initial_state: initialState,
+    });
+    return result.room_id;
+  }
+
+  async sendMessage(roomId: string, content: MessageEventContent): Promise<string> {
+    return await this.runSerializedRoomSend(roomId, async () => {
+      const sent = await this.client.sendMessage(roomId, content as never);
+      return sent.event_id;
+    });
+  }
+
+  async sendEvent(
+    roomId: string,
+    eventType: string,
+    content: Record<string, unknown>,
+  ): Promise<string> {
+    return await this.runSerializedRoomSend(roomId, async () => {
+      const sent = await this.client.sendEvent(roomId, eventType as never, content as never);
+      return sent.event_id;
+    });
+  }
+
+  // Keep outbound room events ordered when multiple plugin paths emit
+  // messages/reactions/polls into the same Matrix room concurrently.
+  private async runSerializedRoomSend<T>(roomId: string, task: () => Promise<T>): Promise<T> {
+    return await this.sendQueue.enqueue(roomId, task);
+  }
+
+  async sendStateEvent(
+    roomId: string,
+    eventType: string,
+    stateKey: string,
+    content: Record<string, unknown>,
+  ): Promise<string> {
+    const sent = await this.client.sendStateEvent(
+      roomId,
+      eventType as never,
+      content as never,
+      stateKey,
+    );
+    return sent.event_id;
+  }
+
+  async redactEvent(roomId: string, eventId: string, reason?: string): Promise<string> {
+    const sent = await this.client.redactEvent(
+      roomId,
+      eventId,
+      undefined,
+      reason?.trim() ? { reason } : undefined,
+    );
+    return sent.event_id;
+  }
+
+  async doRequest(
+    method: HttpMethod,
+    endpoint: string,
+    qs?: QueryParams,
+    body?: unknown,
+    opts?: { allowAbsoluteEndpoint?: boolean },
+  ): Promise<unknown> {
+    return await this.httpClient.requestJson({
+      method,
+      endpoint,
+      qs,
+      body,
+      timeoutMs: this.localTimeoutMs,
+      allowAbsoluteEndpoint: opts?.allowAbsoluteEndpoint,
+    });
+  }
+
+  async getUserProfile(userId: string): Promise<{ displayname?: string; avatar_url?: string }> {
+    return await this.client.getProfileInfo(userId);
+  }
+
+  async setDisplayName(displayName: string): Promise<void> {
+    await this.client.setDisplayName(displayName);
+  }
+
+  async setAvatarUrl(avatarUrl: string): Promise<void> {
+    await this.client.setAvatarUrl(avatarUrl);
+  }
+
+  async joinRoom(roomId: string): Promise<void> {
+    await this.client.joinRoom(roomId);
+  }
+
+  mxcToHttp(mxcUrl: string): string | null {
+    return this.client.mxcUrlToHttp(mxcUrl, undefined, undefined, undefined, true, false, true);
+  }
+
+  async downloadContent(
+    mxcUrl: string,
+    opts: {
+      allowRemote?: boolean;
+      maxBytes?: number;
+      readIdleTimeoutMs?: number;
+    } = {},
+  ): Promise<Buffer> {
+    const parsed = parseMxc(mxcUrl);
+    if (!parsed) {
+      throw new Error(`Invalid Matrix content URI: ${mxcUrl}`);
+    }
+    const encodedServer = encodeURIComponent(parsed.server);
+    const encodedMediaId = encodeURIComponent(parsed.mediaId);
+    const request = async (endpoint: string): Promise<Buffer> =>
+      await this.httpClient.requestRaw({
+        method: "GET",
+        endpoint,
+        qs: { allow_remote: opts.allowRemote ?? true },
+        timeoutMs: this.localTimeoutMs,
+        maxBytes: opts.maxBytes,
+        readIdleTimeoutMs: opts.readIdleTimeoutMs,
+      });
+
+    const authenticatedEndpoint = `/_matrix/client/v1/media/download/${encodedServer}/${encodedMediaId}`;
+    try {
+      return await request(authenticatedEndpoint);
+    } catch (err) {
+      if (!isUnsupportedAuthenticatedMediaEndpointError(err)) {
+        throw err;
+      }
+    }
+
+    const legacyEndpoint = `/_matrix/media/v3/download/${encodedServer}/${encodedMediaId}`;
+    return await request(legacyEndpoint);
+  }
+
+  async uploadContent(file: Buffer, contentType?: string, filename?: string): Promise<string> {
+    const uploaded = await this.client.uploadContent(new Uint8Array(file), {
+      type: contentType || "application/octet-stream",
+      name: filename,
+      includeFilename: Boolean(filename),
+    });
+    return uploaded.content_uri;
+  }
+
+  async getEvent(roomId: string, eventId: string): Promise<Record<string, unknown>> {
+    const rawEvent = (await this.client.fetchRoomEvent(roomId, eventId)) as Record<string, unknown>;
+    if (rawEvent.type !== "m.room.encrypted") {
+      return rawEvent;
+    }
+
+    const mapper = this.client.getEventMapper();
+    const event = mapper(rawEvent);
+    let decryptedEvent: MatrixEvent | undefined;
+    const onDecrypted = (candidate: MatrixEvent) => {
+      decryptedEvent = candidate;
+    };
+    event.once(MatrixEventEvent.Decrypted, onDecrypted);
+    try {
+      await this.client.decryptEventIfNeeded(event);
+    } finally {
+      event.off(MatrixEventEvent.Decrypted, onDecrypted);
+    }
+    return matrixEventToRaw(decryptedEvent ?? event);
+  }
+
+  async getRelations(
+    roomId: string,
+    eventId: string,
+    relationType: string | null,
+    eventType?: string | null,
+    opts: {
+      from?: string;
+    } = {},
+  ): Promise<MatrixRelationsPage> {
+    const result = await this.client.relations(roomId, eventId, relationType, eventType, opts);
+    return {
+      originalEvent: result.originalEvent ? matrixEventToRaw(result.originalEvent) : null,
+      events: result.events.map((event) => matrixEventToRaw(event)),
+      nextBatch: result.nextBatch ?? null,
+      prevBatch: result.prevBatch ?? null,
+    };
+  }
+
+  async hydrateEvents(
+    roomId: string,
+    events: Array<Record<string, unknown>>,
+  ): Promise<MatrixRawEvent[]> {
+    if (events.length === 0) {
+      return [];
+    }
+
+    const mapper = this.client.getEventMapper();
+    const mappedEvents = events.map((event) =>
+      mapper({
+        room_id: roomId,
+        ...event,
+      }),
+    );
+    await Promise.all(mappedEvents.map((event) => this.client.decryptEventIfNeeded(event)));
+    return mappedEvents.map((event) => matrixEventToRaw(event));
+  }
+
+  async setTyping(roomId: string, typing: boolean, timeoutMs: number): Promise<void> {
+    await this.client.sendTyping(roomId, typing, timeoutMs);
+  }
+
+  async sendReadReceipt(roomId: string, eventId: string): Promise<void> {
+    await this.httpClient.requestJson({
+      method: "POST",
+      endpoint: `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/receipt/m.read/${encodeURIComponent(
+        eventId,
+      )}`,
+      body: {},
+      timeoutMs: this.localTimeoutMs,
+    });
+  }
+
+  async getRoomKeyBackupStatus(): Promise<MatrixRoomKeyBackupStatus> {
+    if (!this.encryptionEnabled) {
+      return {
+        serverVersion: null,
+        activeVersion: null,
+        trusted: null,
+        matchesDecryptionKey: null,
+        decryptionKeyCached: null,
+        keyLoadAttempted: false,
+        keyLoadError: null,
+      };
+    }
+
+    const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+    const serverVersionFallback = await this.resolveRoomKeyBackupVersion();
+    if (!crypto) {
+      return {
+        serverVersion: serverVersionFallback,
+        activeVersion: null,
+        trusted: null,
+        matchesDecryptionKey: null,
+        decryptionKeyCached: null,
+        keyLoadAttempted: false,
+        keyLoadError: null,
+      };
+    }
+
+    let { activeVersion, decryptionKeyCached } = await this.resolveRoomKeyBackupLocalState(crypto);
+    let { serverVersion, trusted, matchesDecryptionKey } =
+      await this.resolveRoomKeyBackupTrustState(crypto, serverVersionFallback);
+    const shouldLoadBackupKey =
+      Boolean(serverVersion) && (decryptionKeyCached === false || matchesDecryptionKey === false);
+    const shouldActivateBackup = Boolean(serverVersion) && !activeVersion;
+    let keyLoadAttempted = false;
+    let keyLoadError: string | null = null;
+    if (serverVersion && (shouldLoadBackupKey || shouldActivateBackup)) {
+      if (shouldLoadBackupKey) {
+        if (
+          typeof crypto.loadSessionBackupPrivateKeyFromSecretStorage ===
+          "function" /* pragma: allowlist secret */
+        ) {
+          keyLoadAttempted = true;
+          try {
+            await crypto.loadSessionBackupPrivateKeyFromSecretStorage(); // pragma: allowlist secret
+          } catch (err) {
+            keyLoadError = formatMatrixErrorMessage(err);
+          }
+        } else {
+          keyLoadError =
+            "Matrix crypto backend does not support loading backup keys from secret storage";
+        }
+      }
+      if (!keyLoadError) {
+        await this.enableTrustedRoomKeyBackupIfPossible(crypto);
+      }
+      ({ activeVersion, decryptionKeyCached } = await this.resolveRoomKeyBackupLocalState(crypto));
+      ({ serverVersion, trusted, matchesDecryptionKey } = await this.resolveRoomKeyBackupTrustState(
+        crypto,
+        serverVersion,
+      ));
+    }
+
+    return {
+      serverVersion,
+      activeVersion,
+      trusted,
+      matchesDecryptionKey,
+      decryptionKeyCached,
+      keyLoadAttempted,
+      keyLoadError,
+    };
+  }
+
+  async getOwnDeviceVerificationStatus(): Promise<MatrixOwnDeviceVerificationStatus> {
+    const recoveryKey = this.recoveryKeyStore.getRecoveryKeySummary();
+    const userId = this.client.getUserId() ?? this.selfUserId ?? null;
+    const deviceId = this.client.getDeviceId()?.trim() || null;
+    const backup = await this.getRoomKeyBackupStatus();
+
+    if (!this.encryptionEnabled) {
+      return {
+        encryptionEnabled: false,
+        userId,
+        deviceId,
+        verified: false,
+        localVerified: false,
+        crossSigningVerified: false,
+        signedByOwner: false,
+        recoveryKeyStored: Boolean(recoveryKey),
+        recoveryKeyCreatedAt: recoveryKey?.createdAt ?? null,
+        recoveryKeyId: recoveryKey?.keyId ?? null,
+        backupVersion: backup.serverVersion,
+        backup,
+      };
+    }
+
+    const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+    let deviceStatus: MatrixDeviceVerificationStatusLike | null = null;
+    if (crypto && userId && deviceId && typeof crypto.getDeviceVerificationStatus === "function") {
+      deviceStatus = await crypto.getDeviceVerificationStatus(userId, deviceId).catch(() => null);
+    }
+    const { isMatrixDeviceOwnerVerified } = await loadMatrixCryptoRuntime();
+
+    return {
+      encryptionEnabled: true,
+      userId,
+      deviceId,
+      verified: isMatrixDeviceOwnerVerified(deviceStatus),
+      localVerified: deviceStatus?.localVerified === true,
+      crossSigningVerified: deviceStatus?.crossSigningVerified === true,
+      signedByOwner: deviceStatus?.signedByOwner === true,
+      recoveryKeyStored: Boolean(recoveryKey),
+      recoveryKeyCreatedAt: recoveryKey?.createdAt ?? null,
+      recoveryKeyId: recoveryKey?.keyId ?? null,
+      backupVersion: backup.serverVersion,
+      backup,
+    };
+  }
+
+  async verifyWithRecoveryKey(
+    rawRecoveryKey: string,
+  ): Promise<MatrixRecoveryKeyVerificationResult> {
+    const fail = async (error: string): Promise<MatrixRecoveryKeyVerificationResult> => ({
+      success: false,
+      error,
+      ...(await this.getOwnDeviceVerificationStatus()),
+    });
+
+    if (!this.encryptionEnabled) {
+      return await fail("Matrix encryption is disabled for this client");
+    }
+
+    await this.ensureStartedForCryptoControlPlane();
+    await this.ensureCryptoSupportInitialized();
+    const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+    if (!crypto) {
+      return await fail("Matrix crypto is not available (start client with encryption enabled)");
+    }
+
+    const trimmedRecoveryKey = rawRecoveryKey.trim();
+    if (!trimmedRecoveryKey) {
+      return await fail("Matrix recovery key is required");
+    }
+
+    try {
+      this.recoveryKeyStore.stageEncodedRecoveryKey({
+        encodedPrivateKey: trimmedRecoveryKey,
+        keyId: await this.resolveDefaultSecretStorageKeyId(crypto),
+      });
+    } catch (err) {
+      return await fail(formatMatrixErrorMessage(err));
+    }
+
+    try {
+      const cryptoBootstrapper = this.cryptoBootstrapper;
+      if (!cryptoBootstrapper) {
+        return await fail("Matrix crypto bootstrapper is not available");
+      }
+      await cryptoBootstrapper.bootstrap(crypto, {
+        allowAutomaticCrossSigningReset: false,
+      });
+      await this.enableTrustedRoomKeyBackupIfPossible(crypto);
+      const status = await this.getOwnDeviceVerificationStatus();
+      if (!status.verified) {
+        this.recoveryKeyStore.discardStagedRecoveryKey();
+        return {
+          success: false,
+          error:
+            "Matrix device is still not verified by its owner after applying the recovery key. Ensure cross-signing is available and the device is signed.",
+          ...status,
+        };
+      }
+      const backupError = resolveMatrixRoomKeyBackupReadinessError(status.backup, {
+        requireServerBackup: false,
+      });
+      if (backupError) {
+        this.recoveryKeyStore.discardStagedRecoveryKey();
+        return {
+          success: false,
+          error: backupError,
+          ...status,
+        };
+      }
+
+      this.recoveryKeyStore.commitStagedRecoveryKey({
+        keyId: await this.resolveDefaultSecretStorageKeyId(crypto),
+      });
+      const committedStatus = await this.getOwnDeviceVerificationStatus();
+      return {
+        success: true,
+        verifiedAt: new Date().toISOString(),
+        ...committedStatus,
+      };
+    } catch (err) {
+      this.recoveryKeyStore.discardStagedRecoveryKey();
+      return await fail(formatMatrixErrorMessage(err));
+    }
+  }
+
+  async restoreRoomKeyBackup(
+    params: {
+      recoveryKey?: string;
+    } = {},
+  ): Promise<MatrixRoomKeyBackupRestoreResult> {
+    let loadedFromSecretStorage = false;
+    const fail = async (error: string): Promise<MatrixRoomKeyBackupRestoreResult> => {
+      const backup = await this.getRoomKeyBackupStatus();
+      return {
+        success: false,
+        error,
+        backupVersion: backup.serverVersion,
+        imported: 0,
+        total: 0,
+        loadedFromSecretStorage,
+        backup,
+      };
+    };
+
+    if (!this.encryptionEnabled) {
+      return await fail("Matrix encryption is disabled for this client");
+    }
+
+    await this.ensureStartedForCryptoControlPlane();
+    const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+    if (!crypto) {
+      return await fail("Matrix crypto is not available (start client with encryption enabled)");
+    }
+
+    try {
+      const rawRecoveryKey = params.recoveryKey?.trim();
+      if (rawRecoveryKey) {
+        this.recoveryKeyStore.stageEncodedRecoveryKey({
+          encodedPrivateKey: rawRecoveryKey,
+          keyId: await this.resolveDefaultSecretStorageKeyId(crypto),
+        });
+      }
+
+      const backup = await this.getRoomKeyBackupStatus();
+      loadedFromSecretStorage = backup.keyLoadAttempted && !backup.keyLoadError;
+      const backupError = resolveMatrixRoomKeyBackupReadinessError(backup, {
+        requireServerBackup: true,
+      });
+      if (backupError) {
+        this.recoveryKeyStore.discardStagedRecoveryKey();
+        return await fail(backupError);
+      }
+      if (typeof crypto.restoreKeyBackup !== "function") {
+        this.recoveryKeyStore.discardStagedRecoveryKey();
+        return await fail("Matrix crypto backend does not support full key backup restore");
+      }
+
+      const restore = await crypto.restoreKeyBackup();
+      if (rawRecoveryKey) {
+        this.recoveryKeyStore.commitStagedRecoveryKey({
+          keyId: await this.resolveDefaultSecretStorageKeyId(crypto),
+        });
+      }
+      const finalBackup = await this.getRoomKeyBackupStatus();
+      return {
+        success: true,
+        backupVersion: backup.serverVersion,
+        imported: typeof restore.imported === "number" ? restore.imported : 0,
+        total: typeof restore.total === "number" ? restore.total : 0,
+        loadedFromSecretStorage,
+        restoredAt: new Date().toISOString(),
+        backup: finalBackup,
+      };
+    } catch (err) {
+      this.recoveryKeyStore.discardStagedRecoveryKey();
+      return await fail(formatMatrixErrorMessage(err));
+    }
+  }
+
+  async resetRoomKeyBackup(): Promise<MatrixRoomKeyBackupResetResult> {
+    let previousVersion: string | null = null;
+    let deletedVersion: string | null = null;
+    const fail = async (error: string): Promise<MatrixRoomKeyBackupResetResult> => {
+      const backup = await this.getRoomKeyBackupStatus();
+      return {
+        success: false,
+        error,
+        previousVersion,
+        deletedVersion,
+        createdVersion: backup.serverVersion,
+        backup,
+      };
+    };
+
+    if (!this.encryptionEnabled) {
+      return await fail("Matrix encryption is disabled for this client");
+    }
+
+    await this.ensureStartedForCryptoControlPlane();
+    const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+    if (!crypto) {
+      return await fail("Matrix crypto is not available (start client with encryption enabled)");
+    }
+
+    previousVersion = await this.resolveRoomKeyBackupVersion();
+
+    // Probe backup-secret access directly before reset. This keeps the reset preflight
+    // focused on durable secret-storage health instead of the broader backup status flow,
+    // and still catches stale SSSS/recovery-key state even when the server backup is gone.
+    const forceNewSecretStorage =
+      await this.shouldForceSecretStorageRecreationForBackupReset(crypto);
+
+    try {
+      if (previousVersion) {
+        try {
+          await this.doRequest(
+            "DELETE",
+            `/_matrix/client/v3/room_keys/version/${encodeURIComponent(previousVersion)}`,
+          );
+        } catch (err) {
+          if (!isMatrixNotFoundError(err)) {
+            throw err;
+          }
+        }
+        deletedVersion = previousVersion;
+      }
+
+      await this.recoveryKeyStore.bootstrapSecretStorageWithRecoveryKey(crypto, {
+        setupNewKeyBackup: true,
+        // Force SSSS recreation when the existing SSSS key is broken (bad MAC), so
+        // the new backup key is written into a fresh SSSS consistent with recovery_key.json.
+        forceNewSecretStorage,
+        // Also allow recreation if bootstrapSecretStorage itself surfaces a repairable
+        // error (e.g. bad MAC from a different SSSS entry).
+        allowSecretStorageRecreateWithoutRecoveryKey: true,
+      });
+      await this.enableTrustedRoomKeyBackupIfPossible(crypto);
+
+      const backup = await this.getRoomKeyBackupStatus();
+      const createdVersion = backup.serverVersion;
+      if (!createdVersion) {
+        return await fail("Matrix room key backup is still missing after reset.");
+      }
+      if (backup.activeVersion !== createdVersion) {
+        return await fail(
+          "Matrix room key backup was recreated on the server but is not active on this device.",
+        );
+      }
+      if (backup.decryptionKeyCached === false) {
+        return await fail(
+          "Matrix room key backup was recreated but its decryption key is not cached on this device.",
+        );
+      }
+      if (backup.matchesDecryptionKey === false) {
+        return await fail(
+          "Matrix room key backup was recreated but this device does not have the matching backup decryption key.",
+        );
+      }
+      if (backup.trusted === false) {
+        return await fail(
+          "Matrix room key backup was recreated but is not trusted on this device.",
+        );
+      }
+
+      return {
+        success: true,
+        previousVersion,
+        deletedVersion,
+        createdVersion,
+        resetAt: new Date().toISOString(),
+        backup,
+      };
+    } catch (err) {
+      return await fail(formatMatrixErrorMessage(err));
+    }
+  }
+
+  async getOwnCrossSigningPublicationStatus(): Promise<MatrixOwnCrossSigningPublicationStatus> {
+    const userId = this.client.getUserId() ?? this.selfUserId ?? null;
+    if (!userId) {
+      return {
+        userId: null,
+        masterKeyPublished: false,
+        selfSigningKeyPublished: false,
+        userSigningKeyPublished: false,
+        published: false,
+      };
+    }
+
+    try {
+      const response = (await this.doRequest("POST", "/_matrix/client/v3/keys/query", undefined, {
+        device_keys: { [userId]: [] as string[] },
+      })) as {
+        master_keys?: Record<string, unknown>;
+        self_signing_keys?: Record<string, unknown>;
+        user_signing_keys?: Record<string, unknown>;
+      };
+      const masterKeyPublished = Boolean(response.master_keys?.[userId]);
+      const selfSigningKeyPublished = Boolean(response.self_signing_keys?.[userId]);
+      const userSigningKeyPublished = Boolean(response.user_signing_keys?.[userId]);
+      return {
+        userId,
+        masterKeyPublished,
+        selfSigningKeyPublished,
+        userSigningKeyPublished,
+        published: masterKeyPublished && selfSigningKeyPublished && userSigningKeyPublished,
+      };
+    } catch {
+      return {
+        userId,
+        masterKeyPublished: false,
+        selfSigningKeyPublished: false,
+        userSigningKeyPublished: false,
+        published: false,
+      };
+    }
+  }
+
+  async bootstrapOwnDeviceVerification(params?: {
+    recoveryKey?: string;
+    forceResetCrossSigning?: boolean;
+  }): Promise<MatrixVerificationBootstrapResult> {
+    const pendingVerifications = async (): Promise<number> =>
+      this.crypto ? (await this.crypto.listVerifications()).length : 0;
+    if (!this.encryptionEnabled) {
+      return {
+        success: false,
+        error: "Matrix encryption is disabled for this client",
+        verification: await this.getOwnDeviceVerificationStatus(),
+        crossSigning: await this.getOwnCrossSigningPublicationStatus(),
+        pendingVerifications: await pendingVerifications(),
+        cryptoBootstrap: null,
+      };
+    }
+
+    let bootstrapError: string | undefined;
+    let bootstrapSummary: MatrixCryptoBootstrapResult | null = null;
+    try {
+      await this.ensureStartedForCryptoControlPlane();
+      await this.ensureCryptoSupportInitialized();
+      const crypto = this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined;
+      if (!crypto) {
+        throw new Error("Matrix crypto is not available (start client with encryption enabled)");
+      }
+
+      const rawRecoveryKey = params?.recoveryKey?.trim();
+      if (rawRecoveryKey) {
+        this.recoveryKeyStore.stageEncodedRecoveryKey({
+          encodedPrivateKey: rawRecoveryKey,
+          keyId: await this.resolveDefaultSecretStorageKeyId(crypto),
+        });
+      }
+
+      const cryptoBootstrapper = this.cryptoBootstrapper;
+      if (!cryptoBootstrapper) {
+        throw new Error("Matrix crypto bootstrapper is not available");
+      }
+      bootstrapSummary = await cryptoBootstrapper.bootstrap(
+        crypto,
+        createMatrixExplicitBootstrapOptions(params),
+      );
+      await this.ensureRoomKeyBackupEnabled(crypto);
+    } catch (err) {
+      this.recoveryKeyStore.discardStagedRecoveryKey();
+      bootstrapError = formatMatrixErrorMessage(err);
+    }
+
+    const verification = await this.getOwnDeviceVerificationStatus();
+    const crossSigning = await this.getOwnCrossSigningPublicationStatus();
+    const verificationError =
+      verification.verified && crossSigning.published
+        ? null
+        : (bootstrapError ??
+          "Matrix verification bootstrap did not produce a device verified by its owner with published cross-signing keys");
+    const backupError =
+      verificationError === null
+        ? resolveMatrixRoomKeyBackupReadinessError(verification.backup, {
+            requireServerBackup: true,
+          })
+        : null;
+    const success = verificationError === null && backupError === null;
+    if (success) {
+      this.recoveryKeyStore.commitStagedRecoveryKey({
+        keyId: await this.resolveDefaultSecretStorageKeyId(
+          this.client.getCrypto() as MatrixCryptoBootstrapApi | undefined,
+        ),
+      });
+    } else {
+      this.recoveryKeyStore.discardStagedRecoveryKey();
+    }
+    const error = success ? undefined : (backupError ?? verificationError ?? undefined);
+    return {
+      success,
+      error,
+      verification: success ? await this.getOwnDeviceVerificationStatus() : verification,
+      crossSigning,
+      pendingVerifications: await pendingVerifications(),
+      cryptoBootstrap: bootstrapSummary,
+    };
+  }
+
+  async listOwnDevices(): Promise<MatrixOwnDeviceInfo[]> {
+    const currentDeviceId = this.client.getDeviceId()?.trim() || null;
+    const devices = await this.client.getDevices();
+    const entries = Array.isArray(devices?.devices) ? devices.devices : [];
+    return entries.map((device) => ({
+      deviceId: device.device_id,
+      displayName: device.display_name?.trim() || null,
+      lastSeenIp: device.last_seen_ip?.trim() || null,
+      lastSeenTs:
+        typeof device.last_seen_ts === "number" && Number.isFinite(device.last_seen_ts)
+          ? device.last_seen_ts
+          : null,
+      current: currentDeviceId !== null && device.device_id === currentDeviceId,
+    }));
+  }
+
+  async deleteOwnDevices(deviceIds: string[]): Promise<MatrixOwnDeviceDeleteResult> {
+    const uniqueDeviceIds = [...new Set(deviceIds.map((value) => value.trim()).filter(Boolean))];
+    const currentDeviceId = this.client.getDeviceId()?.trim() || null;
+    const protectedDeviceIds = uniqueDeviceIds.filter((deviceId) => deviceId === currentDeviceId);
+    if (protectedDeviceIds.length > 0) {
+      throw new Error(`Refusing to delete the current Matrix device: ${protectedDeviceIds[0]}`);
+    }
+
+    const deleteWithAuth = async (authData?: Record<string, unknown>): Promise<void> => {
+      await this.client.deleteMultipleDevices(uniqueDeviceIds, authData as never);
+    };
+
+    if (uniqueDeviceIds.length > 0) {
+      try {
+        await deleteWithAuth();
+      } catch (err) {
+        const session =
+          err &&
+          typeof err === "object" &&
+          "data" in err &&
+          err.data &&
+          typeof err.data === "object" &&
+          "session" in err.data &&
+          typeof err.data.session === "string"
+            ? err.data.session
+            : null;
+        const userId = await this.getUserId().catch(() => this.selfUserId);
+        if (!session || !userId || !this.password?.trim()) {
+          throw err;
+        }
+        await deleteWithAuth({
+          type: "m.login.password",
+          session,
+          identifier: { type: "m.id.user", user: userId },
+          password: this.password,
+        });
+      }
+    }
+
+    return {
+      currentDeviceId,
+      deletedDeviceIds: uniqueDeviceIds,
+      remainingDevices: await this.listOwnDevices(),
+    };
+  }
+
+  private async resolveActiveRoomKeyBackupVersion(
+    crypto: MatrixCryptoBootstrapApi,
+  ): Promise<string | null> {
+    if (typeof crypto.getActiveSessionBackupVersion !== "function") {
+      return null;
+    }
+    const version = await crypto.getActiveSessionBackupVersion().catch(() => null);
+    return normalizeOptionalString(version);
+  }
+
+  private async resolveCachedRoomKeyBackupDecryptionKey(
+    crypto: MatrixCryptoBootstrapApi,
+  ): Promise<boolean | null> {
+    const getSessionBackupPrivateKey = crypto.getSessionBackupPrivateKey; // pragma: allowlist secret
+    if (typeof getSessionBackupPrivateKey !== "function") {
+      return null;
+    }
+    const key = await getSessionBackupPrivateKey.call(crypto).catch(() => null); // pragma: allowlist secret
+    return key ? key.length > 0 : false;
+  }
+
+  private async resolveRoomKeyBackupLocalState(
+    crypto: MatrixCryptoBootstrapApi,
+  ): Promise<{ activeVersion: string | null; decryptionKeyCached: boolean | null }> {
+    const [activeVersion, decryptionKeyCached] = await Promise.all([
+      this.resolveActiveRoomKeyBackupVersion(crypto),
+      this.resolveCachedRoomKeyBackupDecryptionKey(crypto),
+    ]);
+    return { activeVersion, decryptionKeyCached };
+  }
+
+  private async shouldForceSecretStorageRecreationForBackupReset(
+    crypto: MatrixCryptoBootstrapApi,
+  ): Promise<boolean> {
+    const decryptionKeyCached = await this.resolveCachedRoomKeyBackupDecryptionKey(crypto);
+    if (decryptionKeyCached !== false) {
+      return false;
+    }
+    const loadSessionBackupPrivateKeyFromSecretStorage =
+      crypto.loadSessionBackupPrivateKeyFromSecretStorage; // pragma: allowlist secret
+    if (typeof loadSessionBackupPrivateKeyFromSecretStorage !== "function") {
+      return false;
+    }
+    try {
+      await loadSessionBackupPrivateKeyFromSecretStorage.call(crypto); // pragma: allowlist secret
+      return false;
+    } catch (err) {
+      return isRepairableSecretStorageAccessError(err);
+    }
+  }
+
+  private async resolveRoomKeyBackupTrustState(
+    crypto: MatrixCryptoBootstrapApi,
+    fallbackVersion: string | null,
+  ): Promise<{
+    serverVersion: string | null;
+    trusted: boolean | null;
+    matchesDecryptionKey: boolean | null;
+  }> {
+    let serverVersion = fallbackVersion;
+    let trusted: boolean | null = null;
+    let matchesDecryptionKey: boolean | null = null;
+    if (typeof crypto.getKeyBackupInfo === "function") {
+      const info = await crypto.getKeyBackupInfo().catch(() => null);
+      serverVersion = normalizeOptionalString(info?.version) ?? serverVersion;
+      if (info && typeof crypto.isKeyBackupTrusted === "function") {
+        const trustInfo = await crypto.isKeyBackupTrusted(info).catch(() => null);
+        trusted = typeof trustInfo?.trusted === "boolean" ? trustInfo.trusted : null;
+        matchesDecryptionKey =
+          typeof trustInfo?.matchesDecryptionKey === "boolean"
+            ? trustInfo.matchesDecryptionKey
+            : null;
+      }
+    }
+    return { serverVersion, trusted, matchesDecryptionKey };
+  }
+
+  private async resolveDefaultSecretStorageKeyId(
+    crypto: MatrixCryptoBootstrapApi | undefined,
+  ): Promise<string | null | undefined> {
+    const getSecretStorageStatus = crypto?.getSecretStorageStatus; // pragma: allowlist secret
+    if (typeof getSecretStorageStatus !== "function") {
+      return undefined;
+    }
+    const status = await getSecretStorageStatus.call(crypto).catch(() => null); // pragma: allowlist secret
+    return status?.defaultKeyId;
+  }
+
+  private async resolveRoomKeyBackupVersion(): Promise<string | null> {
+    try {
+      const response = (await this.doRequest("GET", "/_matrix/client/v3/room_keys/version")) as {
+        version?: string;
+      };
+      return normalizeOptionalString(response.version);
+    } catch {
+      return null;
+    }
+  }
+
+  private async enableTrustedRoomKeyBackupIfPossible(
+    crypto: MatrixCryptoBootstrapApi,
+  ): Promise<void> {
+    if (typeof crypto.checkKeyBackupAndEnable !== "function") {
+      return;
+    }
+    await crypto.checkKeyBackupAndEnable();
+  }
+
+  private async ensureRoomKeyBackupEnabled(crypto: MatrixCryptoBootstrapApi): Promise<void> {
+    const existingVersion = await this.resolveRoomKeyBackupVersion();
+    if (existingVersion) {
+      return;
+    }
+    LogService.info(
+      "MatrixClientLite",
+      "No room key backup version found on server, creating one via secret storage bootstrap",
+    );
+    await this.recoveryKeyStore.bootstrapSecretStorageWithRecoveryKey(crypto, {
+      setupNewKeyBackup: true,
+    });
+    const createdVersion = await this.resolveRoomKeyBackupVersion();
+    if (!createdVersion) {
+      throw new Error("Matrix room key backup is still missing after bootstrap");
+    }
+    LogService.info("MatrixClientLite", `Room key backup enabled (version ${createdVersion})`);
+  }
+
+  private registerBridge(): void {
+    if (this.bridgeRegistered || !this.decryptBridge) {
+      return;
+    }
+    this.bridgeRegistered = true;
+    const decryptBridge = this.decryptBridge;
+
+    this.client.on(ClientEvent.Event, (event: MatrixEvent) => {
+      const roomId = event.getRoomId();
+      if (!roomId) {
+        return;
+      }
+
+      const raw = matrixEventToRaw(event);
+      const isEncryptedEvent = raw.type === "m.room.encrypted";
+      this.emitter.emit("room.event", roomId, raw);
+      if (isEncryptedEvent) {
+        this.emitter.emit("room.encrypted_event", roomId, raw);
+      } else {
+        if (decryptBridge.shouldEmitUnencryptedMessage(roomId, raw.event_id)) {
+          this.emitter.emit("room.message", roomId, raw);
+        }
+      }
+
+      const stateKey = raw.state_key ?? "";
+      const selfUserId = this.client.getUserId() ?? this.selfUserId ?? "";
+      const membership =
+        raw.type === "m.room.member"
+          ? (raw.content as { membership?: string }).membership
+          : undefined;
+      if (stateKey && selfUserId && stateKey === selfUserId) {
+        if (membership === "invite") {
+          this.emitter.emit("room.invite", roomId, raw);
+        } else if (membership === "join") {
+          this.emitter.emit("room.join", roomId, raw);
+        }
+      }
+
+      if (isEncryptedEvent) {
+        decryptBridge.attachEncryptedEvent(event, roomId);
+      }
+    });
+
+    // Some SDK invite transitions are surfaced as room lifecycle events instead of raw timeline events.
+    this.client.on(ClientEvent.Room, (room) => {
+      this.emitMembershipForRoom(room);
+    });
+    this.client.on(
+      ClientEvent.Sync,
+      (state: MatrixSyncState, prevState: string | null, data?: unknown) => {
+        this.currentSyncState = state;
+        const error =
+          data && typeof data === "object" && "error" in data
+            ? (data as { error?: unknown }).error
+            : undefined;
+        this.emitter.emit("sync.state", state, prevState, error);
+      },
+    );
+    this.client.on(ClientEvent.SyncUnexpectedError, (error: Error) => {
+      this.emitter.emit("sync.unexpected_error", error);
+    });
+  }
+
+  private emitMembershipForRoom(room: unknown): void {
+    const roomObj = room as {
+      roomId?: string;
+      getMyMembership?: () => string | null | undefined;
+      selfMembership?: string | null | undefined;
+    };
+    const roomId = roomObj.roomId?.trim();
+    if (!roomId) {
+      return;
+    }
+    const membership = roomObj.getMyMembership?.() ?? roomObj.selfMembership ?? undefined;
+    const selfUserId = this.client.getUserId() ?? this.selfUserId ?? "";
+    if (!selfUserId) {
+      return;
+    }
+    const raw: MatrixRawEvent = {
+      event_id: `$membership-${roomId}-${Date.now()}`,
+      type: "m.room.member",
+      sender: selfUserId,
+      state_key: selfUserId,
+      content: { membership },
+      origin_server_ts: Date.now(),
+      unsigned: { age: 0 },
+    };
+    if (membership === "invite") {
+      this.emitter.emit("room.invite", roomId, raw);
+      return;
+    }
+    if (membership === "join") {
+      this.emitter.emit("room.join", roomId, raw);
+    }
+  }
+
+  private emitOutstandingInviteEvents(): void {
+    const listRooms = (this.client as { getRooms?: () => unknown[] }).getRooms;
+    if (typeof listRooms !== "function") {
+      return;
+    }
+    const rooms = listRooms.call(this.client);
+    if (!Array.isArray(rooms)) {
+      return;
+    }
+    for (const room of rooms) {
+      this.emitMembershipForRoom(room);
+    }
+  }
+
+  private async refreshDmCache(): Promise<boolean> {
+    const direct = await this.getAccountData("m.direct");
+    this.dmRoomIds.clear();
+    if (!direct || typeof direct !== "object") {
+      return false;
+    }
+    for (const value of Object.values(direct)) {
+      if (!Array.isArray(value)) {
+        continue;
+      }
+      for (const roomId of value) {
+        if (typeof roomId === "string" && roomId.trim()) {
+          this.dmRoomIds.add(roomId);
+        }
+      }
+    }
+    return true;
+  }
+}