@gakr-gakr/matrix 0.1.0

package/src/matrix/sdk/crypto-bootstrap.ts

@@ -0,0 +1,438 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { CryptoEvent } from "matrix-js-sdk/lib/crypto-api/CryptoEvent.js";
+import type { MatrixDecryptBridge } from "./decrypt-bridge.js";
+import { LogService } from "./logger.js";
+import type { MatrixRecoveryKeyStore } from "./recovery-key-store.js";
+import { isRepairableSecretStorageAccessError } from "./recovery-key-store.js";
+import type {
+  MatrixAuthDict,
+  MatrixCryptoBootstrapApi,
+  MatrixRawEvent,
+  MatrixUiAuthCallback,
+} from "./types.js";
+import type {
+  MatrixVerificationManager,
+  MatrixVerificationRequestLike,
+} from "./verification-manager.js";
+import { isMatrixDeviceOwnerVerified } from "./verification-status.js";
+
+export type MatrixCryptoBootstrapperDeps<TRawEvent extends MatrixRawEvent> = {
+  getUserId: () => Promise<string>;
+  getPassword?: () => string | undefined;
+  getDeviceId: () => string | null | undefined;
+  verificationManager: MatrixVerificationManager;
+  recoveryKeyStore: MatrixRecoveryKeyStore;
+  decryptBridge: Pick<MatrixDecryptBridge<TRawEvent>, "bindCryptoRetrySignals">;
+};
+
+export type MatrixCryptoBootstrapOptions = {
+  forceResetCrossSigning?: boolean;
+  allowAutomaticCrossSigningReset?: boolean;
+  allowSecretStorageRecreateWithoutRecoveryKey?: boolean;
+  strict?: boolean;
+};
+
+export type MatrixCryptoBootstrapResult = {
+  crossSigningReady: boolean;
+  crossSigningPublished: boolean;
+  ownDeviceVerified: boolean | null;
+};
+
+const CROSS_SIGNING_PUBLICATION_WAIT_MS = 5_000;
+
+export class MatrixCryptoBootstrapper<TRawEvent extends MatrixRawEvent> {
+  private verificationHandlerRegistered = false;
+
+  constructor(private readonly deps: MatrixCryptoBootstrapperDeps<TRawEvent>) {}
+
+  async bootstrap(
+    crypto: MatrixCryptoBootstrapApi,
+    options: MatrixCryptoBootstrapOptions = {},
+  ): Promise<MatrixCryptoBootstrapResult> {
+    const strict = options.strict === true;
+    const deferSecretStorageBootstrapUntilAfterCrossSigning =
+      options.forceResetCrossSigning === true;
+    // Register verification listeners before expensive bootstrap work so incoming requests
+    // are not missed during startup.
+    this.registerVerificationRequestHandler(crypto);
+    if (!deferSecretStorageBootstrapUntilAfterCrossSigning) {
+      await this.bootstrapSecretStorage(crypto, {
+        strict,
+        allowSecretStorageRecreateWithoutRecoveryKey:
+          options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+      });
+    }
+    let crossSigning = await this.bootstrapCrossSigning(crypto, {
+      forceResetCrossSigning: options.forceResetCrossSigning === true,
+      allowAutomaticCrossSigningReset: options.allowAutomaticCrossSigningReset !== false,
+      allowSecretStorageRecreateWithoutRecoveryKey:
+        options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+      strict,
+    });
+    // Forced repair may need password UIA to upload new cross-signing keys. Delay any
+    // secret-storage repair/recreation until after that step succeeds so passwordless bots do
+    // not partially mutate SSSS on homeservers that require password-based UIA.
+    await this.bootstrapSecretStorage(crypto, {
+      strict,
+      allowSecretStorageRecreateWithoutRecoveryKey:
+        options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+    });
+    if (deferSecretStorageBootstrapUntilAfterCrossSigning) {
+      crossSigning = await this.bootstrapCrossSigning(crypto, {
+        forceResetCrossSigning: false,
+        allowAutomaticCrossSigningReset: false,
+        allowSecretStorageRecreateWithoutRecoveryKey:
+          options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+        strict,
+      });
+    }
+    const ownDeviceVerified = await this.ensureOwnDeviceTrust(crypto, {
+      strict,
+    });
+    return {
+      crossSigningReady: crossSigning.ready,
+      crossSigningPublished: crossSigning.published,
+      ownDeviceVerified,
+    };
+  }
+
+  private createSigningKeysUiAuthCallback(params: {
+    userId: string;
+    password?: string;
+  }): MatrixUiAuthCallback {
+    return async <T>(makeRequest: (authData: MatrixAuthDict | null) => Promise<T>): Promise<T> => {
+      try {
+        return await makeRequest(null);
+      } catch {
+        // Some homeservers require an explicit dummy UIA stage even when no user interaction is needed.
+        try {
+          return await makeRequest({ type: "m.login.dummy" });
+        } catch {
+          if (!params.password?.trim()) {
+            throw new Error(
+              "Matrix cross-signing key upload requires UIA; provide matrix.password for m.login.password fallback",
+            );
+          }
+          return await makeRequest({
+            type: "m.login.password",
+            identifier: { type: "m.id.user", user: params.userId },
+            password: params.password,
+          });
+        }
+      }
+    };
+  }
+
+  private async bootstrapCrossSigning(
+    crypto: MatrixCryptoBootstrapApi,
+    options: {
+      forceResetCrossSigning: boolean;
+      allowAutomaticCrossSigningReset: boolean;
+      allowSecretStorageRecreateWithoutRecoveryKey: boolean;
+      strict: boolean;
+    },
+  ): Promise<{ ready: boolean; published: boolean }> {
+    const userId = await this.deps.getUserId();
+    const authUploadDeviceSigningKeys = this.createSigningKeysUiAuthCallback({
+      userId,
+      password: this.deps.getPassword?.(),
+    });
+    const hasPublishedCrossSigningKeys = async (): Promise<boolean> => {
+      if (typeof crypto.userHasCrossSigningKeys !== "function") {
+        return true;
+      }
+      try {
+        return await crypto.userHasCrossSigningKeys(userId, true);
+      } catch {
+        return false;
+      }
+    };
+    const refreshPublishedCrossSigningKeys = async (): Promise<void> => {
+      if (typeof crypto.userHasCrossSigningKeys !== "function") {
+        return;
+      }
+      try {
+        await crypto.userHasCrossSigningKeys(userId, true);
+      } catch {
+        // The normal bootstrap flow below handles missing or unavailable keys.
+      }
+    };
+    const isCrossSigningReady = async (): Promise<boolean> => {
+      if (typeof crypto.isCrossSigningReady !== "function") {
+        return true;
+      }
+      try {
+        return await crypto.isCrossSigningReady();
+      } catch {
+        return false;
+      }
+    };
+
+    const finalize = async (): Promise<{ ready: boolean; published: boolean }> => {
+      const ready = await isCrossSigningReady();
+      const published = ready
+        ? await waitForPublishedCrossSigningKeys()
+        : await hasPublishedCrossSigningKeys();
+      if (ready && published) {
+        LogService.info("MatrixClientLite", "Cross-signing bootstrap complete");
+        return { ready, published };
+      }
+      const message = "Cross-signing bootstrap finished but server keys are still not published";
+      LogService.warn("MatrixClientLite", message);
+      if (options.strict) {
+        throw new Error(message);
+      }
+      return { ready, published };
+    };
+
+    const waitForPublishedCrossSigningKeys = async (): Promise<boolean> => {
+      const startedAt = Date.now();
+      do {
+        if (await hasPublishedCrossSigningKeys()) {
+          return true;
+        }
+        await sleep(250);
+      } while (Date.now() - startedAt < CROSS_SIGNING_PUBLICATION_WAIT_MS);
+      return false;
+    };
+
+    if (options.forceResetCrossSigning) {
+      const resetCrossSigning = async (): Promise<void> => {
+        await crypto.bootstrapCrossSigning({
+          setupNewCrossSigning: true,
+          authUploadDeviceSigningKeys,
+        });
+      };
+      try {
+        await resetCrossSigning();
+        await this.trustFreshOwnIdentity(crypto);
+      } catch (err) {
+        const shouldRepairSecretStorage =
+          options.allowSecretStorageRecreateWithoutRecoveryKey &&
+          isRepairableSecretStorageAccessError(err);
+        if (shouldRepairSecretStorage) {
+          LogService.warn(
+            "MatrixClientLite",
+            "Forced cross-signing reset could not unlock secret storage; recreating secret storage and retrying.",
+          );
+          try {
+            await this.deps.recoveryKeyStore.bootstrapSecretStorageWithRecoveryKey(crypto, {
+              allowSecretStorageRecreateWithoutRecoveryKey: true,
+              forceNewSecretStorage: true,
+            });
+            await resetCrossSigning();
+            await this.trustFreshOwnIdentity(crypto);
+          } catch (repairErr) {
+            LogService.warn("MatrixClientLite", "Forced cross-signing reset failed:", repairErr);
+            if (options.strict) {
+              throw repairErr instanceof Error ? repairErr : new Error(String(repairErr));
+            }
+            return { ready: false, published: false };
+          }
+          return await finalize();
+        }
+        LogService.warn("MatrixClientLite", "Forced cross-signing reset failed:", err);
+        if (options.strict) {
+          throw err instanceof Error ? err : new Error(String(err));
+        }
+        return { ready: false, published: false };
+      }
+      return await finalize();
+    }
+
+    // First pass: preserve existing cross-signing identity and ensure public keys are uploaded.
+    try {
+      await refreshPublishedCrossSigningKeys();
+      await crypto.bootstrapCrossSigning({
+        authUploadDeviceSigningKeys,
+      });
+    } catch (err) {
+      const shouldRepairSecretStorage =
+        options.allowSecretStorageRecreateWithoutRecoveryKey &&
+        isRepairableSecretStorageAccessError(err);
+      if (shouldRepairSecretStorage) {
+        LogService.warn(
+          "MatrixClientLite",
+          "Cross-signing bootstrap could not unlock secret storage; recreating secret storage during explicit bootstrap and retrying.",
+        );
+        await this.deps.recoveryKeyStore.bootstrapSecretStorageWithRecoveryKey(crypto, {
+          allowSecretStorageRecreateWithoutRecoveryKey: true,
+          forceNewSecretStorage: true,
+        });
+        await crypto.bootstrapCrossSigning({
+          authUploadDeviceSigningKeys,
+        });
+      } else if (!options.allowAutomaticCrossSigningReset) {
+        LogService.warn(
+          "MatrixClientLite",
+          "Initial cross-signing bootstrap failed and automatic reset is disabled:",
+          err,
+        );
+        return { ready: false, published: false };
+      } else {
+        LogService.warn(
+          "MatrixClientLite",
+          "Initial cross-signing bootstrap failed, trying reset:",
+          err,
+        );
+        try {
+          await crypto.bootstrapCrossSigning({
+            setupNewCrossSigning: true,
+            authUploadDeviceSigningKeys,
+          });
+        } catch (resetErr) {
+          LogService.warn("MatrixClientLite", "Failed to bootstrap cross-signing:", resetErr);
+          if (options.strict) {
+            throw resetErr instanceof Error ? resetErr : new Error(String(resetErr));
+          }
+          return { ready: false, published: false };
+        }
+      }
+    }
+
+    const firstPassReady = await isCrossSigningReady();
+    const firstPassPublished = await hasPublishedCrossSigningKeys();
+    if (firstPassReady && firstPassPublished) {
+      LogService.info("MatrixClientLite", "Cross-signing bootstrap complete");
+      return { ready: true, published: true };
+    }
+
+    if (!options.allowAutomaticCrossSigningReset) {
+      return { ready: firstPassReady, published: firstPassPublished };
+    }
+
+    // Fallback: recover from broken local/server state by creating a fresh identity.
+    try {
+      await crypto.bootstrapCrossSigning({
+        setupNewCrossSigning: true,
+        authUploadDeviceSigningKeys,
+      });
+      await this.trustFreshOwnIdentity(crypto);
+    } catch (err) {
+      LogService.warn("MatrixClientLite", "Fallback cross-signing bootstrap failed:", err);
+      if (options.strict) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+      return { ready: false, published: false };
+    }
+
+    return await finalize();
+  }
+
+  private async trustFreshOwnIdentity(crypto: MatrixCryptoBootstrapApi): Promise<void> {
+    const ownIdentity =
+      typeof crypto.getOwnIdentity === "function"
+        ? await crypto.getOwnIdentity().catch(() => undefined)
+        : undefined;
+    if (!ownIdentity) {
+      return;
+    }
+
+    try {
+      if (typeof ownIdentity.isVerified === "function" && ownIdentity.isVerified()) {
+        return;
+      }
+      await ownIdentity.verify?.();
+    } finally {
+      ownIdentity.free?.();
+    }
+  }
+
+  private async bootstrapSecretStorage(
+    crypto: MatrixCryptoBootstrapApi,
+    options: {
+      strict: boolean;
+      allowSecretStorageRecreateWithoutRecoveryKey: boolean;
+    },
+  ): Promise<void> {
+    try {
+      await this.deps.recoveryKeyStore.bootstrapSecretStorageWithRecoveryKey(crypto, {
+        allowSecretStorageRecreateWithoutRecoveryKey:
+          options.allowSecretStorageRecreateWithoutRecoveryKey,
+      });
+      LogService.info("MatrixClientLite", "Secret storage bootstrap complete");
+    } catch (err) {
+      LogService.warn("MatrixClientLite", "Failed to bootstrap secret storage:", err);
+      if (options.strict) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+    }
+  }
+
+  private registerVerificationRequestHandler(crypto: MatrixCryptoBootstrapApi): void {
+    if (this.verificationHandlerRegistered) {
+      return;
+    }
+    this.verificationHandlerRegistered = true;
+
+    // Track incoming requests; verification lifecycle decisions live in the
+    // verification manager so acceptance/start/dedupe share one code path.
+    // Remote-user verifications are only auto-accepted. The human-operated
+    // client must explicitly choose "Verify by emoji" so we do not race a
+    // second SAS start from the bot side and end up with mismatched keys.
+    crypto.on(CryptoEvent.VerificationRequestReceived, async (request) => {
+      const verificationRequest = request as MatrixVerificationRequestLike;
+      try {
+        this.deps.verificationManager.trackVerificationRequest(verificationRequest);
+      } catch (err) {
+        LogService.warn(
+          "MatrixClientLite",
+          `Failed to track verification request from ${verificationRequest.otherUserId}:`,
+          err,
+        );
+      }
+    });
+
+    this.deps.decryptBridge.bindCryptoRetrySignals(crypto);
+    LogService.info("MatrixClientLite", "Verification request handler registered");
+  }
+
+  private async ensureOwnDeviceTrust(
+    crypto: MatrixCryptoBootstrapApi,
+    options: {
+      strict: boolean;
+    },
+  ): Promise<boolean | null> {
+    const deviceId = this.deps.getDeviceId()?.trim();
+    if (!deviceId) {
+      return null;
+    }
+    const userId = await this.deps.getUserId();
+
+    const deviceStatus =
+      typeof crypto.getDeviceVerificationStatus === "function"
+        ? await crypto.getDeviceVerificationStatus(userId, deviceId).catch(() => null)
+        : null;
+    const alreadyVerified = isMatrixDeviceOwnerVerified(deviceStatus);
+
+    if (alreadyVerified) {
+      return true;
+    }
+
+    if (typeof crypto.setDeviceVerified === "function") {
+      await crypto.setDeviceVerified(userId, deviceId, true);
+    }
+
+    if (typeof crypto.crossSignDevice === "function") {
+      const crossSigningReady =
+        typeof crypto.isCrossSigningReady === "function"
+          ? await crypto.isCrossSigningReady()
+          : true;
+      if (crossSigningReady) {
+        await crypto.crossSignDevice(deviceId);
+      }
+    }
+
+    const refreshedStatus =
+      typeof crypto.getDeviceVerificationStatus === "function"
+        ? await crypto.getDeviceVerificationStatus(userId, deviceId).catch(() => null)
+        : null;
+    const verified = isMatrixDeviceOwnerVerified(refreshedStatus);
+    if (!verified && options.strict) {
+      throw new Error(
+        `Matrix own device ${deviceId} does not have full Matrix identity trust after bootstrap`,
+      );
+    }
+    return verified;
+  }
+}

package/src/matrix/sdk/crypto-facade.ts

@@ -0,0 +1,242 @@
+import { ensureMatrixCryptoRuntime } from "../deps.js";
+import type { MatrixRecoveryKeyStore } from "./recovery-key-store.js";
+import type { EncryptedFile } from "./types.js";
+import type {
+  MatrixVerificationCryptoApi,
+  MatrixVerificationManager,
+  MatrixVerificationMethod,
+  MatrixVerificationSummary,
+} from "./verification-manager.js";
+
+type MatrixCryptoFacadeClient = {
+  getRoom: (roomId: string) => { hasEncryptionStateEvent: () => boolean } | null;
+  getCrypto: () => unknown;
+  getUserId: () => string | null;
+};
+
+export type MatrixCryptoFacade = {
+  prepare: (joinedRooms: string[]) => Promise<void>;
+  updateSyncData: (
+    toDeviceMessages: unknown,
+    otkCounts: unknown,
+    unusedFallbackKeyAlgs: unknown,
+    changedDeviceLists: unknown,
+    leftDeviceLists: unknown,
+  ) => Promise<void>;
+  isRoomEncrypted: (roomId: string) => Promise<boolean>;
+  requestOwnUserVerification: () => Promise<MatrixVerificationSummary | null>;
+  encryptMedia: (buffer: Buffer) => Promise<{ buffer: Buffer; file: Omit<EncryptedFile, "url"> }>;
+  decryptMedia: (
+    file: EncryptedFile,
+    opts?: { maxBytes?: number; readIdleTimeoutMs?: number },
+  ) => Promise<Buffer>;
+  getRecoveryKey: () => Promise<{
+    encodedPrivateKey?: string;
+    keyId?: string | null;
+    createdAt?: string;
+  } | null>;
+  listVerifications: () => Promise<MatrixVerificationSummary[]>;
+  ensureVerificationDmTracked: (params: {
+    roomId: string;
+    userId: string;
+  }) => Promise<MatrixVerificationSummary | null>;
+  requestVerification: (params: {
+    ownUser?: boolean;
+    userId?: string;
+    deviceId?: string;
+    roomId?: string;
+  }) => Promise<MatrixVerificationSummary>;
+  acceptVerification: (id: string) => Promise<MatrixVerificationSummary>;
+  cancelVerification: (
+    id: string,
+    params?: { reason?: string; code?: string },
+  ) => Promise<MatrixVerificationSummary>;
+  startVerification: (
+    id: string,
+    method?: MatrixVerificationMethod,
+  ) => Promise<MatrixVerificationSummary>;
+  generateVerificationQr: (id: string) => Promise<{ qrDataBase64: string }>;
+  scanVerificationQr: (id: string, qrDataBase64: string) => Promise<MatrixVerificationSummary>;
+  confirmVerificationSas: (id: string) => Promise<MatrixVerificationSummary>;
+  mismatchVerificationSas: (id: string) => Promise<MatrixVerificationSummary>;
+  confirmVerificationReciprocateQr: (id: string) => Promise<MatrixVerificationSummary>;
+  getVerificationSas: (
+    id: string,
+  ) => Promise<{ decimal?: [number, number, number]; emoji?: Array<[string, string]> }>;
+};
+
+type MatrixCryptoNodeRuntime = typeof import("./crypto-node.runtime.js");
+let matrixCryptoNodeRuntimePromise: Promise<MatrixCryptoNodeRuntime> | null = null;
+
+async function loadMatrixCryptoNodeRuntime(): Promise<MatrixCryptoNodeRuntime> {
+  // Keep the native crypto package out of the main CLI startup graph.
+  matrixCryptoNodeRuntimePromise ??= import("./crypto-node.runtime.js").catch((error: unknown) => {
+    matrixCryptoNodeRuntimePromise = null;
+    throw error;
+  });
+  return await matrixCryptoNodeRuntimePromise;
+}
+
+async function loadMatrixCryptoNodeBindings() {
+  await ensureMatrixCryptoRuntime();
+  const runtime = await loadMatrixCryptoNodeRuntime();
+  return runtime.loadMatrixCryptoNodeBindings();
+}
+
+function trackInProgressToDeviceVerifications(deps: {
+  client: MatrixCryptoFacadeClient;
+  verificationManager: MatrixVerificationManager;
+}) {
+  const crypto = deps.client.getCrypto() as MatrixVerificationCryptoApi | undefined;
+  const userId = deps.client.getUserId();
+  if (!userId || typeof crypto?.getVerificationRequestsToDeviceInProgress !== "function") {
+    return;
+  }
+  for (const request of crypto.getVerificationRequestsToDeviceInProgress(userId)) {
+    deps.verificationManager.trackVerificationRequest(request);
+  }
+}
+
+export function createMatrixCryptoFacade(deps: {
+  client: MatrixCryptoFacadeClient;
+  verificationManager: MatrixVerificationManager;
+  recoveryKeyStore: MatrixRecoveryKeyStore;
+  getRoomStateEvent: (
+    roomId: string,
+    eventType: string,
+    stateKey?: string,
+  ) => Promise<Record<string, unknown>>;
+  downloadContent: (
+    mxcUrl: string,
+    opts?: { maxBytes?: number; readIdleTimeoutMs?: number },
+  ) => Promise<Buffer>;
+}): MatrixCryptoFacade {
+  return {
+    prepare: async (_joinedRooms: string[]) => {
+      // matrix-js-sdk performs crypto prep during startup; no extra work required here.
+    },
+    updateSyncData: async (
+      _toDeviceMessages: unknown,
+      _otkCounts: unknown,
+      _unusedFallbackKeyAlgs: unknown,
+      _changedDeviceLists: unknown,
+      _leftDeviceLists: unknown,
+    ) => {
+      // compatibility no-op
+    },
+    isRoomEncrypted: async (roomId: string): Promise<boolean> => {
+      const room = deps.client.getRoom(roomId);
+      if (room?.hasEncryptionStateEvent()) {
+        return true;
+      }
+      try {
+        const event = await deps.getRoomStateEvent(roomId, "m.room.encryption", "");
+        return typeof event.algorithm === "string" && event.algorithm.length > 0;
+      } catch {
+        return false;
+      }
+    },
+    requestOwnUserVerification: async () => {
+      const crypto = deps.client.getCrypto() as MatrixVerificationCryptoApi | undefined;
+      return await deps.verificationManager.requestOwnUserVerification(crypto);
+    },
+    encryptMedia: async (
+      buffer: Buffer,
+    ): Promise<{ buffer: Buffer; file: Omit<EncryptedFile, "url"> }> => {
+      const { Attachment } = await loadMatrixCryptoNodeBindings();
+      const encrypted = Attachment.encrypt(new Uint8Array(buffer));
+      const mediaInfoJson = encrypted.mediaEncryptionInfo;
+      if (!mediaInfoJson) {
+        throw new Error("Matrix media encryption failed: missing media encryption info");
+      }
+      const parsed = JSON.parse(mediaInfoJson) as EncryptedFile;
+      return {
+        buffer: Buffer.from(encrypted.encryptedData),
+        file: {
+          key: parsed.key,
+          iv: parsed.iv,
+          hashes: parsed.hashes,
+          v: parsed.v,
+        },
+      };
+    },
+    decryptMedia: async (
+      file: EncryptedFile,
+      opts?: { maxBytes?: number; readIdleTimeoutMs?: number },
+    ): Promise<Buffer> => {
+      const { Attachment, EncryptedAttachment } = await loadMatrixCryptoNodeBindings();
+      const encrypted = await deps.downloadContent(file.url, opts);
+      const metadata: EncryptedFile = {
+        url: file.url,
+        key: file.key,
+        iv: file.iv,
+        hashes: file.hashes,
+        v: file.v,
+      };
+      const attachment = new EncryptedAttachment(
+        new Uint8Array(encrypted),
+        JSON.stringify(metadata),
+      );
+      const decrypted = Attachment.decrypt(attachment);
+      return Buffer.from(decrypted);
+    },
+    getRecoveryKey: async () => {
+      return deps.recoveryKeyStore.getRecoveryKeySummary();
+    },
+    listVerifications: async () => {
+      trackInProgressToDeviceVerifications(deps);
+      return deps.verificationManager.listVerifications();
+    },
+    ensureVerificationDmTracked: async ({ roomId, userId }) => {
+      const crypto = deps.client.getCrypto() as MatrixVerificationCryptoApi | undefined;
+      const request =
+        typeof crypto?.findVerificationRequestDMInProgress === "function"
+          ? crypto.findVerificationRequestDMInProgress(roomId, userId)
+          : undefined;
+      if (!request) {
+        return null;
+      }
+      return deps.verificationManager.trackVerificationRequest(request);
+    },
+    requestVerification: async (params) => {
+      const crypto = deps.client.getCrypto() as MatrixVerificationCryptoApi | undefined;
+      return await deps.verificationManager.requestVerification(crypto, params);
+    },
+    acceptVerification: async (id) => {
+      trackInProgressToDeviceVerifications(deps);
+      return await deps.verificationManager.acceptVerification(id);
+    },
+    cancelVerification: async (id, params) => {
+      trackInProgressToDeviceVerifications(deps);
+      return await deps.verificationManager.cancelVerification(id, params);
+    },
+    startVerification: async (id, method = "sas") => {
+      trackInProgressToDeviceVerifications(deps);
+      return await deps.verificationManager.startVerification(id, method);
+    },
+    generateVerificationQr: async (id) => {
+      trackInProgressToDeviceVerifications(deps);
+      return await deps.verificationManager.generateVerificationQr(id);
+    },
+    scanVerificationQr: async (id, qrDataBase64) => {
+      trackInProgressToDeviceVerifications(deps);
+      return await deps.verificationManager.scanVerificationQr(id, qrDataBase64);
+    },
+    confirmVerificationSas: async (id) => {
+      trackInProgressToDeviceVerifications(deps);
+      return await deps.verificationManager.confirmVerificationSas(id);
+    },
+    mismatchVerificationSas: async (id) => {
+      trackInProgressToDeviceVerifications(deps);
+      return deps.verificationManager.mismatchVerificationSas(id);
+    },
+    confirmVerificationReciprocateQr: async (id) => {
+      trackInProgressToDeviceVerifications(deps);
+      return deps.verificationManager.confirmVerificationReciprocateQr(id);
+    },
+    getVerificationSas: async (id) => {
+      trackInProgressToDeviceVerifications(deps);
+      return deps.verificationManager.getVerificationSas(id);
+    },
+  };
+}

package/src/matrix/sdk/crypto-node.runtime.ts

@@ -0,0 +1,17 @@
+import { createRequire } from "node:module";
+
+// Load via createRequire so the CJS package gets __dirname (its index.js
+// uses __dirname to locate platform-specific native .node bindings).
+const require = createRequire(import.meta.url);
+type MatrixCryptoNodePackage = typeof import("@matrix-org/matrix-sdk-crypto-nodejs");
+
+export type MatrixCryptoNodeBindings = Pick<
+  MatrixCryptoNodePackage,
+  "Attachment" | "EncryptedAttachment"
+>;
+
+export function loadMatrixCryptoNodeBindings(): MatrixCryptoNodeBindings {
+  const { Attachment, EncryptedAttachment } =
+    require("@matrix-org/matrix-sdk-crypto-nodejs") as MatrixCryptoNodePackage;
+  return { Attachment, EncryptedAttachment };
+}