@gakr-gakr/matrix 0.1.0

package/src/matrix/sdk/verification-manager.ts

@@ -0,0 +1,795 @@
+import {
+  VerificationPhase,
+  VerificationRequestEvent,
+  VerifierEvent,
+} from "matrix-js-sdk/lib/crypto-api/verification.js";
+import { VerificationMethod } from "matrix-js-sdk/lib/types.js";
+import { formatMatrixErrorMessage } from "../errors.js";
+
+export type MatrixVerificationMethod = "sas" | "show-qr" | "scan-qr";
+type MatrixVerificationPhase = VerificationPhase | -1;
+
+const MATRIX_VERIFICATION_PHASES = new Set<MatrixVerificationPhase>([
+  -1,
+  VerificationPhase.Unsent,
+  VerificationPhase.Requested,
+  VerificationPhase.Ready,
+  VerificationPhase.Started,
+  VerificationPhase.Cancelled,
+  VerificationPhase.Done,
+]);
+
+function isMatrixVerificationPhase(value: unknown): value is MatrixVerificationPhase {
+  return (
+    typeof value === "number" && MATRIX_VERIFICATION_PHASES.has(value as MatrixVerificationPhase)
+  );
+}
+
+export type MatrixVerificationSummary = {
+  id: string;
+  transactionId?: string;
+  roomId?: string;
+  otherUserId: string;
+  otherDeviceId?: string;
+  isSelfVerification: boolean;
+  initiatedByMe: boolean;
+  phase: number;
+  phaseName: string;
+  pending: boolean;
+  methods: string[];
+  chosenMethod?: string | null;
+  canAccept: boolean;
+  hasSas: boolean;
+  sas?: {
+    decimal?: [number, number, number];
+    emoji?: Array<[string, string]>;
+  };
+  hasReciprocateQr: boolean;
+  completed: boolean;
+  error?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type MatrixVerificationSummaryListener = (summary: MatrixVerificationSummary) => void;
+type MatrixVerificationOwnerTrustCallback = (deviceId: string) => Promise<void>;
+
+export type MatrixShowSasCallbacks = {
+  sas: {
+    decimal?: [number, number, number];
+    emoji?: Array<[string, string]>;
+  };
+  confirm: () => Promise<void>;
+  mismatch: () => void;
+  cancel: () => void;
+};
+
+export type MatrixShowQrCodeCallbacks = {
+  confirm: () => void;
+  cancel: () => void;
+};
+
+export type MatrixVerifierLike = {
+  verify: () => Promise<void>;
+  cancel: (e: Error) => void;
+  getShowSasCallbacks: () => MatrixShowSasCallbacks | null;
+  getReciprocateQrCodeCallbacks: () => MatrixShowQrCodeCallbacks | null;
+  on: (eventName: string, listener: (...args: unknown[]) => void) => void;
+};
+
+export type MatrixVerificationRequestLike = {
+  transactionId?: string;
+  roomId?: string;
+  initiatedByMe: boolean;
+  otherUserId: string;
+  otherDeviceId?: string;
+  isSelfVerification: boolean;
+  phase: number;
+  pending: boolean;
+  accepting: boolean;
+  declining: boolean;
+  methods: string[];
+  chosenMethod?: string | null;
+  cancellationCode?: string | null;
+  accept: () => Promise<void>;
+  cancel: (params?: { reason?: string; code?: string }) => Promise<void>;
+  startVerification: (method: string) => Promise<MatrixVerifierLike>;
+  scanQRCode: (qrCodeData: Uint8ClampedArray) => Promise<MatrixVerifierLike>;
+  generateQRCode: () => Promise<Uint8ClampedArray | undefined>;
+  verifier?: MatrixVerifierLike;
+  on: (eventName: string, listener: (...args: unknown[]) => void) => void;
+};
+
+export type MatrixVerificationCryptoApi = {
+  requestOwnUserVerification: () => Promise<MatrixVerificationRequestLike | null>;
+  getVerificationRequestsToDeviceInProgress?: (userId: string) => MatrixVerificationRequestLike[];
+  findVerificationRequestDMInProgress?: (
+    roomId: string,
+    userId: string,
+  ) => MatrixVerificationRequestLike | undefined;
+  requestDeviceVerification?: (
+    userId: string,
+    deviceId: string,
+  ) => Promise<MatrixVerificationRequestLike>;
+  requestVerificationDM?: (
+    userId: string,
+    roomId: string,
+  ) => Promise<MatrixVerificationRequestLike>;
+};
+
+type MatrixVerificationSession = {
+  id: string;
+  request: MatrixVerificationRequestLike;
+  createdAtMs: number;
+  updatedAtMs: number;
+  error?: string;
+  activeVerifier?: MatrixVerifierLike;
+  verifyPromise?: Promise<void>;
+  verifyStarted: boolean;
+  startRequested: boolean;
+  acceptRequested: boolean;
+  sasAutoConfirmStarted: boolean;
+  sasAutoConfirmTimer?: ReturnType<typeof setTimeout>;
+  sasCallbacks?: MatrixShowSasCallbacks;
+  reciprocateQrCallbacks?: MatrixShowQrCodeCallbacks;
+};
+
+type MatrixVerificationRequestIdentity = {
+  transactionId: string;
+  roomId: string;
+  otherUserId: string;
+  otherDeviceId: string;
+  isSelfVerification: boolean;
+  initiatedByMe: boolean;
+};
+
+const MAX_TRACKED_VERIFICATION_SESSIONS = 256;
+const TERMINAL_SESSION_RETENTION_MS = 24 * 60 * 60 * 1000;
+const SAS_AUTO_CONFIRM_DELAY_MS = 30_000;
+
+export class MatrixVerificationManager {
+  private readonly verificationSessions = new Map<string, MatrixVerificationSession>();
+  private verificationSessionCounter = 0;
+  private readonly trackedVerificationRequests = new WeakSet<object>();
+  private readonly trackedVerificationVerifiers = new WeakSet<object>();
+  private readonly summaryListeners = new Set<MatrixVerificationSummaryListener>();
+
+  constructor(
+    private readonly opts: {
+      trustOwnDeviceAfterSas?: MatrixVerificationOwnerTrustCallback;
+    } = {},
+  ) {}
+
+  private readRequestValue<T>(
+    _request: MatrixVerificationRequestLike,
+    reader: () => T,
+    fallback: T,
+  ): T {
+    try {
+      return reader();
+    } catch {
+      return fallback;
+    }
+  }
+
+  private readVerificationPhase(
+    request: MatrixVerificationRequestLike,
+    fallback: MatrixVerificationPhase,
+  ): MatrixVerificationPhase {
+    const phase = this.readRequestValue<unknown>(request, () => request.phase, fallback);
+    return isMatrixVerificationPhase(phase) ? phase : fallback;
+  }
+
+  private readVerificationRequestIdentity(
+    request: MatrixVerificationRequestLike,
+  ): MatrixVerificationRequestIdentity {
+    return {
+      transactionId: this.readRequestValue(request, () => request.transactionId?.trim() ?? "", ""),
+      roomId: this.readRequestValue(request, () => request.roomId ?? "", ""),
+      otherUserId: this.readRequestValue(request, () => request.otherUserId, ""),
+      otherDeviceId: this.readRequestValue(request, () => request.otherDeviceId ?? "", ""),
+      isSelfVerification: this.readRequestValue(request, () => request.isSelfVerification, false),
+      initiatedByMe: this.readRequestValue(request, () => request.initiatedByMe, false),
+    };
+  }
+
+  private isSameLogicalVerificationRequest(
+    left: MatrixVerificationRequestLike,
+    right: MatrixVerificationRequestLike,
+  ): boolean {
+    const leftIdentity = this.readVerificationRequestIdentity(left);
+    const rightIdentity = this.readVerificationRequestIdentity(right);
+    return (
+      leftIdentity.transactionId !== "" &&
+      leftIdentity.transactionId === rightIdentity.transactionId &&
+      leftIdentity.roomId === rightIdentity.roomId &&
+      leftIdentity.otherUserId === rightIdentity.otherUserId &&
+      this.isSameOptionalIdentityValue(leftIdentity.otherDeviceId, rightIdentity.otherDeviceId) &&
+      leftIdentity.isSelfVerification === rightIdentity.isSelfVerification &&
+      leftIdentity.initiatedByMe === rightIdentity.initiatedByMe
+    );
+  }
+
+  private isSameOptionalIdentityValue(left: string, right: string): boolean {
+    return left === "" || right === "" || left === right;
+  }
+
+  private pruneVerificationSessions(nowMs: number): void {
+    for (const [id, session] of this.verificationSessions) {
+      const phase = this.readVerificationPhase(session.request, -1);
+      const isTerminal = phase === VerificationPhase.Done || phase === VerificationPhase.Cancelled;
+      if (isTerminal && nowMs - session.updatedAtMs > TERMINAL_SESSION_RETENTION_MS) {
+        this.verificationSessions.delete(id);
+      }
+    }
+
+    if (this.verificationSessions.size <= MAX_TRACKED_VERIFICATION_SESSIONS) {
+      return;
+    }
+
+    const sortedByAge = Array.from(this.verificationSessions.entries()).toSorted(
+      (a, b) => a[1].updatedAtMs - b[1].updatedAtMs,
+    );
+    const overflow = this.verificationSessions.size - MAX_TRACKED_VERIFICATION_SESSIONS;
+    for (let i = 0; i < overflow; i += 1) {
+      const entry = sortedByAge[i];
+      if (entry) {
+        this.verificationSessions.delete(entry[0]);
+      }
+    }
+  }
+
+  private getVerificationPhaseName(phase: MatrixVerificationPhase): string {
+    switch (phase) {
+      case VerificationPhase.Unsent:
+        return "unsent";
+      case VerificationPhase.Requested:
+        return "requested";
+      case VerificationPhase.Ready:
+        return "ready";
+      case VerificationPhase.Started:
+        return "started";
+      case VerificationPhase.Cancelled:
+        return "cancelled";
+      case VerificationPhase.Done:
+        return "done";
+      default:
+        return `unknown(${phase})`;
+    }
+  }
+
+  private emitVerificationSummary(session: MatrixVerificationSession): void {
+    const summary = this.buildVerificationSummary(session);
+    for (const listener of this.summaryListeners) {
+      listener(summary);
+    }
+  }
+
+  private touchVerificationSession(session: MatrixVerificationSession): void {
+    session.updatedAtMs = Date.now();
+    this.emitVerificationSummary(session);
+  }
+
+  private clearSasAutoConfirmTimer(session: MatrixVerificationSession): void {
+    if (!session.sasAutoConfirmTimer) {
+      return;
+    }
+    clearTimeout(session.sasAutoConfirmTimer);
+    session.sasAutoConfirmTimer = undefined;
+  }
+
+  private buildVerificationSummary(session: MatrixVerificationSession): MatrixVerificationSummary {
+    const request = session.request;
+    const phase = this.readVerificationPhase(request, VerificationPhase.Requested);
+    const accepting = this.readRequestValue(request, () => request.accepting, false);
+    const declining = this.readRequestValue(request, () => request.declining, false);
+    const pending = this.readRequestValue(request, () => request.pending, false);
+    const methodsRaw = this.readRequestValue<unknown>(request, () => request.methods, []);
+    const methods = Array.isArray(methodsRaw)
+      ? methodsRaw.filter((entry): entry is string => typeof entry === "string")
+      : [];
+    const sasCallbacks = session.sasCallbacks ?? session.activeVerifier?.getShowSasCallbacks();
+    if (sasCallbacks) {
+      session.sasCallbacks = sasCallbacks;
+    }
+    const canAccept = phase < VerificationPhase.Ready && !accepting && !declining;
+    return {
+      id: session.id,
+      transactionId: this.readRequestValue(request, () => request.transactionId, undefined),
+      roomId: this.readRequestValue(request, () => request.roomId, undefined),
+      otherUserId: this.readRequestValue(request, () => request.otherUserId, "unknown"),
+      otherDeviceId: this.readRequestValue(request, () => request.otherDeviceId, undefined),
+      isSelfVerification: this.readRequestValue(request, () => request.isSelfVerification, false),
+      initiatedByMe: this.readRequestValue(request, () => request.initiatedByMe, false),
+      phase,
+      phaseName: this.getVerificationPhaseName(phase),
+      pending,
+      methods,
+      chosenMethod: this.readRequestValue(request, () => request.chosenMethod ?? null, null),
+      canAccept,
+      hasSas: Boolean(sasCallbacks),
+      sas: sasCallbacks
+        ? {
+            decimal: sasCallbacks.sas.decimal,
+            emoji: sasCallbacks.sas.emoji,
+          }
+        : undefined,
+      hasReciprocateQr: Boolean(session.reciprocateQrCallbacks),
+      completed: phase === VerificationPhase.Done,
+      error: session.error,
+      createdAt: new Date(session.createdAtMs).toISOString(),
+      updatedAt: new Date(session.updatedAtMs).toISOString(),
+    };
+  }
+
+  private findVerificationSession(id: string): MatrixVerificationSession {
+    const direct = this.verificationSessions.get(id);
+    if (direct) {
+      return direct;
+    }
+    const transactionMatches = Array.from(this.verificationSessions.values()).filter((session) => {
+      const txId = this.readRequestValue(
+        session.request,
+        () => session.request.transactionId?.trim(),
+        "",
+      );
+      return txId === id;
+    });
+    if (transactionMatches.length === 1) {
+      return transactionMatches[0];
+    }
+    if (transactionMatches.length > 1) {
+      throw new Error(
+        `Matrix verification request id is ambiguous for transaction ${id}; use the verification id instead`,
+      );
+    }
+    throw new Error(`Matrix verification request not found: ${id}`);
+  }
+
+  private ensureVerificationRequestTracked(session: MatrixVerificationSession): void {
+    const requestObj = session.request as unknown as object;
+    if (this.trackedVerificationRequests.has(requestObj)) {
+      return;
+    }
+    this.trackedVerificationRequests.add(requestObj);
+    session.request.on(VerificationRequestEvent.Change, () => {
+      this.touchVerificationSession(session);
+      this.maybeAutoAcceptInboundRequest(session);
+      const verifier = this.readRequestValue(session.request, () => session.request.verifier, null);
+      if (verifier) {
+        this.attachVerifierToVerificationSession(session, verifier);
+      }
+      this.maybeAutoStartInboundSas(session);
+    });
+  }
+
+  private maybeAutoAcceptInboundRequest(session: MatrixVerificationSession): void {
+    if (session.acceptRequested) {
+      return;
+    }
+    const request = session.request;
+    const isSelfVerification = this.readRequestValue(
+      request,
+      () => request.isSelfVerification,
+      false,
+    );
+    const initiatedByMe = this.readRequestValue(request, () => request.initiatedByMe, false);
+    const phase = this.readVerificationPhase(request, VerificationPhase.Requested);
+    const accepting = this.readRequestValue(request, () => request.accepting, false);
+    const declining = this.readRequestValue(request, () => request.declining, false);
+    if (isSelfVerification || initiatedByMe) {
+      return;
+    }
+    if (phase !== VerificationPhase.Requested || accepting || declining) {
+      return;
+    }
+
+    session.acceptRequested = true;
+    void request
+      .accept()
+      .then(() => {
+        this.touchVerificationSession(session);
+      })
+      .catch((err) => {
+        session.acceptRequested = false;
+        session.error = formatMatrixErrorMessage(err);
+        this.touchVerificationSession(session);
+      });
+  }
+
+  private maybeAutoStartInboundSas(session: MatrixVerificationSession): void {
+    if (session.activeVerifier || session.verifyStarted || session.startRequested) {
+      return;
+    }
+    if (this.readRequestValue(session.request, () => session.request.initiatedByMe, true)) {
+      return;
+    }
+    if (!this.readRequestValue(session.request, () => session.request.isSelfVerification, false)) {
+      return;
+    }
+    const phase = this.readVerificationPhase(session.request, VerificationPhase.Requested);
+    if (phase < VerificationPhase.Ready || phase >= VerificationPhase.Cancelled) {
+      return;
+    }
+    const methodsRaw = this.readRequestValue<unknown>(
+      session.request,
+      () => session.request.methods,
+      [],
+    );
+    const methods = Array.isArray(methodsRaw)
+      ? methodsRaw.filter((entry): entry is string => typeof entry === "string")
+      : [];
+    const chosenMethod = this.readRequestValue(
+      session.request,
+      () => session.request.chosenMethod,
+      null,
+    );
+    const supportsSas =
+      methods.includes(VerificationMethod.Sas) || chosenMethod === VerificationMethod.Sas;
+    if (!supportsSas) {
+      return;
+    }
+
+    session.startRequested = true;
+    void session.request
+      .startVerification(VerificationMethod.Sas)
+      .then((verifier) => {
+        this.attachVerifierToVerificationSession(session, verifier);
+        this.touchVerificationSession(session);
+      })
+      .catch(() => {
+        session.startRequested = false;
+      });
+  }
+
+  private attachVerifierToVerificationSession(
+    session: MatrixVerificationSession,
+    verifier: MatrixVerifierLike,
+  ): void {
+    session.activeVerifier = verifier;
+    this.touchVerificationSession(session);
+
+    const maybeSas = verifier.getShowSasCallbacks();
+    if (maybeSas) {
+      session.sasCallbacks = maybeSas;
+      this.maybeAutoConfirmSas(session);
+    }
+    const maybeReciprocateQr = verifier.getReciprocateQrCodeCallbacks();
+    if (maybeReciprocateQr) {
+      session.reciprocateQrCallbacks = maybeReciprocateQr;
+    }
+
+    const verifierObj = verifier as unknown as object;
+    if (this.trackedVerificationVerifiers.has(verifierObj)) {
+      this.ensureVerificationStarted(session);
+      return;
+    }
+    this.trackedVerificationVerifiers.add(verifierObj);
+
+    verifier.on(VerifierEvent.ShowSas, (sas) => {
+      session.sasCallbacks = sas as MatrixShowSasCallbacks;
+      this.touchVerificationSession(session);
+      this.maybeAutoConfirmSas(session);
+    });
+    verifier.on(VerifierEvent.ShowReciprocateQr, (qr) => {
+      session.reciprocateQrCallbacks = qr as MatrixShowQrCodeCallbacks;
+      this.touchVerificationSession(session);
+    });
+    verifier.on(VerifierEvent.Cancel, (err) => {
+      this.clearSasAutoConfirmTimer(session);
+      session.error = formatMatrixErrorMessage(err);
+      this.touchVerificationSession(session);
+    });
+    this.ensureVerificationStarted(session);
+  }
+
+  private maybeAutoConfirmSas(session: MatrixVerificationSession): void {
+    if (session.sasAutoConfirmStarted || session.sasAutoConfirmTimer) {
+      return;
+    }
+    if (this.readRequestValue(session.request, () => session.request.initiatedByMe, true)) {
+      return;
+    }
+    const callbacks = session.sasCallbacks ?? session.activeVerifier?.getShowSasCallbacks();
+    if (!callbacks) {
+      return;
+    }
+    session.sasCallbacks = callbacks;
+    // Give the remote client a moment to surface the compare-emoji UI before
+    // we send our MAC and finish our side of the SAS flow.
+    session.sasAutoConfirmTimer = setTimeout(() => {
+      session.sasAutoConfirmTimer = undefined;
+      const phase = this.readVerificationPhase(session.request, VerificationPhase.Requested);
+      if (phase >= VerificationPhase.Cancelled) {
+        return;
+      }
+      session.sasAutoConfirmStarted = true;
+      // For self-verifications, trustOwnDeviceAfterConfirmedSas is gated on
+      // isSelfVerification, so non-self requests remain unaffected. Without
+      // this, the bot's own device never gets cross-signed when SAS lands
+      // via the auto-confirm timer (initiated remotely).
+      void this.confirmSasForSession(session, callbacks, { trustOwnDevice: true })
+        .then(() => {
+          this.touchVerificationSession(session);
+        })
+        .catch((err) => {
+          session.error = formatMatrixErrorMessage(err);
+          this.touchVerificationSession(session);
+        });
+    }, SAS_AUTO_CONFIRM_DELAY_MS);
+  }
+
+  private async confirmSasForSession(
+    session: MatrixVerificationSession,
+    callbacks: MatrixShowSasCallbacks,
+    opts: { trustOwnDevice: boolean } = { trustOwnDevice: true },
+  ): Promise<void> {
+    await callbacks.confirm();
+    if (opts.trustOwnDevice) {
+      await this.trustOwnDeviceAfterConfirmedSas(session);
+    }
+  }
+
+  private ensureVerificationStarted(session: MatrixVerificationSession): void {
+    if (!session.activeVerifier || session.verifyStarted) {
+      return;
+    }
+    session.verifyStarted = true;
+    const verifier = session.activeVerifier;
+    session.verifyPromise = verifier
+      .verify()
+      .then(() => {
+        this.touchVerificationSession(session);
+      })
+      .catch((err) => {
+        session.error = formatMatrixErrorMessage(err);
+        this.touchVerificationSession(session);
+      });
+  }
+
+  private async trustOwnDeviceAfterConfirmedSas(session: MatrixVerificationSession): Promise<void> {
+    if (!this.readRequestValue(session.request, () => session.request.isSelfVerification, false)) {
+      return;
+    }
+    const deviceId = this.readRequestValue(
+      session.request,
+      () => session.request.otherDeviceId?.trim(),
+      "",
+    );
+    if (!deviceId || !this.opts.trustOwnDeviceAfterSas) {
+      return;
+    }
+    await this.opts.trustOwnDeviceAfterSas(deviceId);
+  }
+
+  onSummaryChanged(listener: MatrixVerificationSummaryListener): () => void {
+    this.summaryListeners.add(listener);
+    return () => {
+      this.summaryListeners.delete(listener);
+    };
+  }
+
+  trackVerificationRequest(request: MatrixVerificationRequestLike): MatrixVerificationSummary {
+    this.pruneVerificationSessions(Date.now());
+    const requestObj = request as unknown as object;
+    for (const existing of this.verificationSessions.values()) {
+      if ((existing.request as unknown as object) === requestObj) {
+        this.touchVerificationSession(existing);
+        return this.buildVerificationSummary(existing);
+      }
+    }
+    const txId = this.readVerificationRequestIdentity(request).transactionId;
+    if (txId) {
+      for (const existing of this.verificationSessions.values()) {
+        if (this.isSameLogicalVerificationRequest(existing.request, request)) {
+          existing.request = request;
+          this.ensureVerificationRequestTracked(existing);
+          const verifier = this.readRequestValue(request, () => request.verifier, null);
+          if (verifier) {
+            this.attachVerifierToVerificationSession(existing, verifier);
+          }
+          this.touchVerificationSession(existing);
+          return this.buildVerificationSummary(existing);
+        }
+      }
+    }
+
+    const now = Date.now();
+    const id = `verification-${++this.verificationSessionCounter}`;
+    const session: MatrixVerificationSession = {
+      id,
+      request,
+      createdAtMs: now,
+      updatedAtMs: now,
+      verifyStarted: false,
+      startRequested: false,
+      acceptRequested: false,
+      sasAutoConfirmStarted: false,
+    };
+    this.verificationSessions.set(session.id, session);
+    this.ensureVerificationRequestTracked(session);
+    this.maybeAutoAcceptInboundRequest(session);
+    const verifier = this.readRequestValue(request, () => request.verifier, null);
+    if (verifier) {
+      this.attachVerifierToVerificationSession(session, verifier);
+    }
+    this.maybeAutoStartInboundSas(session);
+    this.emitVerificationSummary(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  async requestOwnUserVerification(
+    crypto: MatrixVerificationCryptoApi | undefined,
+  ): Promise<MatrixVerificationSummary | null> {
+    if (!crypto) {
+      return null;
+    }
+    const request = await crypto.requestOwnUserVerification();
+    if (!request) {
+      return null;
+    }
+    return this.trackVerificationRequest(request);
+  }
+
+  listVerifications(): MatrixVerificationSummary[] {
+    this.pruneVerificationSessions(Date.now());
+    const summaries = Array.from(this.verificationSessions.values()).map((session) =>
+      this.buildVerificationSummary(session),
+    );
+    return summaries.toSorted((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  }
+
+  async requestVerification(
+    crypto: MatrixVerificationCryptoApi | undefined,
+    params: {
+      ownUser?: boolean;
+      userId?: string;
+      deviceId?: string;
+      roomId?: string;
+    },
+  ): Promise<MatrixVerificationSummary> {
+    if (!crypto) {
+      throw new Error("Matrix crypto is not available");
+    }
+    let request: MatrixVerificationRequestLike | null = null;
+    if (params.ownUser) {
+      request = await crypto.requestOwnUserVerification();
+    } else if (params.userId && params.deviceId && crypto.requestDeviceVerification) {
+      request = await crypto.requestDeviceVerification(params.userId, params.deviceId);
+    } else if (params.userId && params.roomId && crypto.requestVerificationDM) {
+      request = await crypto.requestVerificationDM(params.userId, params.roomId);
+    } else {
+      throw new Error(
+        "Matrix verification request requires one of: ownUser, userId+deviceId, or userId+roomId",
+      );
+    }
+
+    if (!request) {
+      throw new Error("Matrix verification request could not be created");
+    }
+    return this.trackVerificationRequest(request);
+  }
+
+  async acceptVerification(id: string): Promise<MatrixVerificationSummary> {
+    const session = this.findVerificationSession(id);
+    await session.request.accept();
+    this.touchVerificationSession(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  async cancelVerification(
+    id: string,
+    params?: { reason?: string; code?: string },
+  ): Promise<MatrixVerificationSummary> {
+    const session = this.findVerificationSession(id);
+    await session.request.cancel(params);
+    this.touchVerificationSession(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  async startVerification(
+    id: string,
+    method: MatrixVerificationMethod = "sas",
+  ): Promise<MatrixVerificationSummary> {
+    const session = this.findVerificationSession(id);
+    if (method !== "sas") {
+      throw new Error("Matrix startVerification currently supports only SAS directly");
+    }
+    const verifier = await session.request.startVerification(VerificationMethod.Sas);
+    this.attachVerifierToVerificationSession(session, verifier);
+    this.ensureVerificationStarted(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  async generateVerificationQr(id: string): Promise<{ qrDataBase64: string }> {
+    const session = this.findVerificationSession(id);
+    const qr = await session.request.generateQRCode();
+    if (!qr) {
+      throw new Error("Matrix verification QR data is not available yet");
+    }
+    return { qrDataBase64: Buffer.from(qr).toString("base64") };
+  }
+
+  async scanVerificationQr(id: string, qrDataBase64: string): Promise<MatrixVerificationSummary> {
+    const session = this.findVerificationSession(id);
+    const trimmed = qrDataBase64.trim();
+    if (!trimmed) {
+      throw new Error("Matrix verification QR payload is required");
+    }
+    const qrBytes = Buffer.from(trimmed, "base64");
+    if (qrBytes.length === 0) {
+      throw new Error("Matrix verification QR payload is invalid base64");
+    }
+    const verifier = await session.request.scanQRCode(new Uint8ClampedArray(qrBytes));
+    this.attachVerifierToVerificationSession(session, verifier);
+    this.ensureVerificationStarted(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  async confirmVerificationSas(id: string): Promise<MatrixVerificationSummary> {
+    const session = this.findVerificationSession(id);
+    const callbacks = session.sasCallbacks ?? session.activeVerifier?.getShowSasCallbacks();
+    if (!callbacks) {
+      throw new Error("Matrix SAS confirmation is not available for this verification request");
+    }
+    this.clearSasAutoConfirmTimer(session);
+    session.sasCallbacks = callbacks;
+    session.sasAutoConfirmStarted = true;
+    await this.confirmSasForSession(session, callbacks);
+    // Wait for the rust-crypto verifier to fully resolve (done-exchange + any
+    // pending cross-signing uploads triggered by trustOwnDeviceAfterSas) so
+    // the operator's client sees a settled state on the next /keys/query.
+    // verifyPromise is set inside ensureVerificationStarted and already
+    // funnels its own rejection into session.error, so awaiting it here
+    // cannot double-throw.
+    if (session.verifyPromise) {
+      await session.verifyPromise;
+    }
+    this.touchVerificationSession(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  mismatchVerificationSas(id: string): MatrixVerificationSummary {
+    const session = this.findVerificationSession(id);
+    const callbacks = session.sasCallbacks ?? session.activeVerifier?.getShowSasCallbacks();
+    if (!callbacks) {
+      throw new Error("Matrix SAS mismatch is not available for this verification request");
+    }
+    this.clearSasAutoConfirmTimer(session);
+    session.sasCallbacks = callbacks;
+    callbacks.mismatch();
+    this.touchVerificationSession(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  confirmVerificationReciprocateQr(id: string): MatrixVerificationSummary {
+    const session = this.findVerificationSession(id);
+    const callbacks =
+      session.reciprocateQrCallbacks ?? session.activeVerifier?.getReciprocateQrCodeCallbacks();
+    if (!callbacks) {
+      throw new Error(
+        "Matrix reciprocate-QR confirmation is not available for this verification request",
+      );
+    }
+    session.reciprocateQrCallbacks = callbacks;
+    callbacks.confirm();
+    this.touchVerificationSession(session);
+    return this.buildVerificationSummary(session);
+  }
+
+  getVerificationSas(id: string): {
+    decimal?: [number, number, number];
+    emoji?: Array<[string, string]>;
+  } {
+    const session = this.findVerificationSession(id);
+    const callbacks = session.sasCallbacks ?? session.activeVerifier?.getShowSasCallbacks();
+    if (!callbacks) {
+      throw new Error("Matrix SAS data is not available for this verification request");
+    }
+    session.sasCallbacks = callbacks;
+    return {
+      decimal: callbacks.sas.decimal,
+      emoji: callbacks.sas.emoji,
+    };
+  }
+}