@archipelagolab/lobi 1.0.0

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

@@ -0,0 +1,341 @@
+import { CryptoEvent } from "@archipelagolab/lobi-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;
+};
+
+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;
+    // Register verification listeners before expensive bootstrap work so incoming requests
+    // are not missed during startup.
+    this.registerVerificationRequestHandler(crypto);
+    await this.bootstrapSecretStorage(crypto, {
+      strict,
+      allowSecretStorageRecreateWithoutRecoveryKey:
+        options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+    });
+    const crossSigning = await this.bootstrapCrossSigning(crypto, {
+      forceResetCrossSigning: options.forceResetCrossSigning === true,
+      allowAutomaticCrossSigningReset: options.allowAutomaticCrossSigningReset !== false,
+      allowSecretStorageRecreateWithoutRecoveryKey:
+        options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+      strict,
+    });
+    await this.bootstrapSecretStorage(crypto, {
+      strict,
+      allowSecretStorageRecreateWithoutRecoveryKey:
+        options.allowSecretStorageRecreateWithoutRecoveryKey === true,
+    });
+    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 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 = 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 };
+    };
+
+    if (options.forceResetCrossSigning) {
+      try {
+        await crypto.bootstrapCrossSigning({
+          setupNewCrossSigning: true,
+          authUploadDeviceSigningKeys,
+        });
+      } catch (err) {
+        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 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,
+      });
+    } 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 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,
+    strict = false,
+  ): 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 && strict) {
+      throw new Error(`Matrix own device ${deviceId} is not verified by its owner after bootstrap`);
+    }
+    return verified;
+  }
+}

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

@@ -0,0 +1,197 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMatrixCryptoFacade } from "./crypto-facade.js";
+import type { MatrixRecoveryKeyStore } from "./recovery-key-store.js";
+import type { MatrixVerificationManager } from "./verification-manager.js";
+
+type MatrixCryptoFacadeDeps = Parameters<typeof createMatrixCryptoFacade>[0];
+
+function createVerificationManagerMock(
+  overrides: Partial<MatrixVerificationManager> = {},
+): MatrixVerificationManager {
+  return {
+    requestOwnUserVerification: vi.fn(async () => null),
+    listVerifications: vi.fn(async () => []),
+    ensureVerificationDmTracked: vi.fn(async () => null),
+    requestVerification: vi.fn(),
+    acceptVerification: vi.fn(),
+    cancelVerification: vi.fn(),
+    startVerification: vi.fn(),
+    generateVerificationQr: vi.fn(),
+    scanVerificationQr: vi.fn(),
+    confirmVerificationSas: vi.fn(),
+    mismatchVerificationSas: vi.fn(),
+    confirmVerificationReciprocateQr: vi.fn(),
+    getVerificationSas: vi.fn(),
+    ...overrides,
+  } as unknown as MatrixVerificationManager;
+}
+
+function createRecoveryKeyStoreMock(
+  summary: ReturnType<MatrixRecoveryKeyStore["getRecoveryKeySummary"]> = null,
+): MatrixRecoveryKeyStore {
+  return {
+    getRecoveryKeySummary: vi.fn(() => summary),
+  } as unknown as MatrixRecoveryKeyStore;
+}
+
+function createFacadeHarness(params?: {
+  client?: Partial<MatrixCryptoFacadeDeps["client"]>;
+  verificationManager?: Partial<MatrixVerificationManager>;
+  recoveryKeySummary?: ReturnType<MatrixRecoveryKeyStore["getRecoveryKeySummary"]>;
+  getRoomStateEvent?: MatrixCryptoFacadeDeps["getRoomStateEvent"];
+  downloadContent?: MatrixCryptoFacadeDeps["downloadContent"];
+}) {
+  const getRoomStateEvent: MatrixCryptoFacadeDeps["getRoomStateEvent"] =
+    params?.getRoomStateEvent ?? (async () => ({}));
+  const downloadContent: MatrixCryptoFacadeDeps["downloadContent"] =
+    params?.downloadContent ?? (async () => Buffer.alloc(0));
+  const facade = createMatrixCryptoFacade({
+    client: {
+      getRoom: params?.client?.getRoom ?? (() => null),
+      getCrypto: params?.client?.getCrypto ?? (() => undefined),
+    },
+    verificationManager: createVerificationManagerMock(params?.verificationManager),
+    recoveryKeyStore: createRecoveryKeyStoreMock(params?.recoveryKeySummary ?? null),
+    getRoomStateEvent,
+    downloadContent,
+  });
+  return { facade, getRoomStateEvent, downloadContent };
+}
+
+describe("createMatrixCryptoFacade", () => {
+  it("detects encrypted rooms from cached room state", async () => {
+    const { facade } = createFacadeHarness({
+      client: {
+        getRoom: () => ({
+          hasEncryptionStateEvent: () => true,
+        }),
+      },
+    });
+
+    await expect(facade.isRoomEncrypted("!room:example.org")).resolves.toBe(true);
+  });
+
+  it("falls back to server room state when room cache has no encryption event", async () => {
+    const getRoomStateEvent = vi.fn(async () => ({
+      algorithm: "m.megolm.v1.aes-sha2",
+    }));
+    const { facade } = createFacadeHarness({
+      client: {
+        getRoom: () => ({
+          hasEncryptionStateEvent: () => false,
+        }),
+      },
+      getRoomStateEvent,
+    });
+
+    await expect(facade.isRoomEncrypted("!room:example.org")).resolves.toBe(true);
+    expect(getRoomStateEvent).toHaveBeenCalledWith("!room:example.org", "m.room.encryption", "");
+  });
+
+  it("forwards verification requests and uses client crypto API", async () => {
+    const crypto = { requestOwnUserVerification: vi.fn(async () => null) };
+    const requestVerification = vi.fn(async () => ({
+      id: "verification-1",
+      otherUserId: "@alice:example.org",
+      isSelfVerification: false,
+      initiatedByMe: true,
+      phase: 2,
+      phaseName: "ready",
+      pending: true,
+      methods: ["m.sas.v1"],
+      canAccept: false,
+      hasSas: false,
+      hasReciprocateQr: false,
+      completed: false,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }));
+    const { facade } = createFacadeHarness({
+      client: {
+        getRoom: () => null,
+        getCrypto: () => crypto,
+      },
+      verificationManager: {
+        requestVerification,
+      },
+      recoveryKeySummary: { keyId: "KEY" },
+    });
+
+    const result = await facade.requestVerification({
+      userId: "@alice:example.org",
+      deviceId: "DEVICE",
+    });
+
+    expect(requestVerification).toHaveBeenCalledWith(crypto, {
+      userId: "@alice:example.org",
+      deviceId: "DEVICE",
+    });
+    expect(result.id).toBe("verification-1");
+    await expect(facade.getRecoveryKey()).resolves.toMatchObject({ keyId: "KEY" });
+  });
+
+  it("rehydrates in-progress DM verification requests from the raw crypto layer", async () => {
+    const request = {
+      transactionId: "txn-dm-in-progress",
+      roomId: "!dm:example.org",
+      otherUserId: "@alice:example.org",
+      initiatedByMe: false,
+      isSelfVerification: false,
+      phase: 3,
+      pending: true,
+      accepting: false,
+      declining: false,
+      methods: ["m.sas.v1"],
+      accept: vi.fn(async () => {}),
+      cancel: vi.fn(async () => {}),
+      startVerification: vi.fn(),
+      scanQRCode: vi.fn(),
+      generateQRCode: vi.fn(),
+      on: vi.fn(),
+      verifier: undefined,
+    };
+    const trackVerificationRequest = vi.fn(() => ({
+      id: "verification-1",
+      transactionId: "txn-dm-in-progress",
+      roomId: "!dm:example.org",
+      otherUserId: "@alice:example.org",
+      isSelfVerification: false,
+      initiatedByMe: false,
+      phase: 3,
+      phaseName: "started",
+      pending: true,
+      methods: ["m.sas.v1"],
+      canAccept: false,
+      hasSas: false,
+      hasReciprocateQr: false,
+      completed: false,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }));
+    const crypto = {
+      requestOwnUserVerification: vi.fn(async () => null),
+      findVerificationRequestDMInProgress: vi.fn(() => request),
+    };
+    const { facade } = createFacadeHarness({
+      client: {
+        getRoom: () => null,
+        getCrypto: () => crypto,
+      },
+      verificationManager: {
+        trackVerificationRequest,
+      },
+    });
+
+    const summary = await facade.ensureVerificationDmTracked({
+      roomId: "!dm:example.org",
+      userId: "@alice:example.org",
+    });
+
+    expect(crypto.findVerificationRequestDMInProgress).toHaveBeenCalledWith(
+      "!dm:example.org",
+      "@alice:example.org",
+    );
+    expect(trackVerificationRequest).toHaveBeenCalledWith(request);
+    expect(summary?.transactionId).toBe("txn-dm-in-progress");
+  });
+});