@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/startup.test.ts

@@ -0,0 +1,257 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CoreConfig } from "../../types.js";
+import type { MatrixAccountPatch } from "../config-update.js";
+import type { MatrixManagedDeviceInfo } from "../device-health.js";
+import type { MatrixProfileSyncResult } from "../profile.js";
+import type { MatrixOwnDeviceVerificationStatus } from "../sdk.js";
+import type { MatrixLegacyCryptoRestoreResult } from "./legacy-crypto-restore.js";
+import type { MatrixStartupVerificationOutcome } from "./startup-verification.js";
+import type { MatrixStartupMaintenanceDeps } from "./startup.js";
+import { runMatrixStartupMaintenance } from "./startup.js";
+
+function createVerificationStatus(
+  overrides: Partial<MatrixOwnDeviceVerificationStatus> = {},
+): MatrixOwnDeviceVerificationStatus {
+  return {
+    encryptionEnabled: true,
+    userId: "@bot:example.org",
+    deviceId: "DEVICE",
+    verified: false,
+    localVerified: false,
+    crossSigningVerified: false,
+    signedByOwner: false,
+    recoveryKeyStored: false,
+    recoveryKeyCreatedAt: null,
+    recoveryKeyId: null,
+    backupVersion: null,
+    backup: {
+      serverVersion: null,
+      activeVersion: null,
+      trusted: null,
+      matchesDecryptionKey: null,
+      decryptionKeyCached: null,
+      keyLoadAttempted: false,
+      keyLoadError: null,
+    },
+    ...overrides,
+  };
+}
+
+function createProfileSyncResult(
+  overrides: Partial<MatrixProfileSyncResult> = {},
+): MatrixProfileSyncResult {
+  return {
+    skipped: false,
+    displayNameUpdated: false,
+    avatarUpdated: false,
+    resolvedAvatarUrl: null,
+    uploadedAvatarSource: null,
+    convertedAvatarFromHttp: false,
+    ...overrides,
+  };
+}
+
+function createStartupVerificationOutcome(
+  kind: Exclude<MatrixStartupVerificationOutcome["kind"], "unsupported">,
+  overrides: Partial<Extract<MatrixStartupVerificationOutcome, { kind: typeof kind }>> = {},
+): MatrixStartupVerificationOutcome {
+  return {
+    kind,
+    verification: createVerificationStatus({ verified: kind === "verified" }),
+    ...overrides,
+  } as MatrixStartupVerificationOutcome;
+}
+
+function createLegacyCryptoRestoreResult(
+  overrides: Partial<MatrixLegacyCryptoRestoreResult> = {},
+): MatrixLegacyCryptoRestoreResult {
+  return {
+    kind: "skipped",
+    ...overrides,
+  } as MatrixLegacyCryptoRestoreResult;
+}
+
+function createDeps(
+  overrides: Partial<MatrixStartupMaintenanceDeps> = {},
+): MatrixStartupMaintenanceDeps {
+  return {
+    maybeRestoreLegacyMatrixBackup: vi.fn(async () => createLegacyCryptoRestoreResult()),
+    summarizeMatrixDeviceHealth: vi.fn(() => ({
+      currentDeviceId: null,
+      staleOpenClawDevices: [] as MatrixManagedDeviceInfo[],
+      currentOpenClawDevices: [] as MatrixManagedDeviceInfo[],
+    })),
+    syncMatrixOwnProfile: vi.fn(async () => createProfileSyncResult()),
+    ensureMatrixStartupVerification: vi.fn(async () =>
+      createStartupVerificationOutcome("verified"),
+    ),
+    updateMatrixAccountConfig: vi.fn(
+      (cfg: CoreConfig, _accountId: string, _patch: MatrixAccountPatch) => cfg,
+    ),
+    ...overrides,
+  };
+}
+
+describe("runMatrixStartupMaintenance", () => {
+  let deps: MatrixStartupMaintenanceDeps;
+
+  beforeEach(() => {
+    deps = createDeps();
+  });
+
+  function createParams(): Parameters<typeof runMatrixStartupMaintenance>[0] {
+    return {
+      client: {
+        crypto: {},
+        listOwnDevices: vi.fn(async () => []),
+        getOwnDeviceVerificationStatus: vi.fn(async () => createVerificationStatus()),
+      } as never,
+      auth: {
+        accountId: "ops",
+        homeserver: "https://matrix.example.org",
+        userId: "@bot:example.org",
+        accessToken: "token",
+        encryption: false,
+      },
+      accountId: "ops",
+      effectiveAccountId: "ops",
+      accountConfig: {
+        name: "Ops Bot",
+        avatarUrl: "https://example.org/avatar.png",
+      },
+      logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        debug: vi.fn(),
+        error: vi.fn(),
+      },
+      logVerboseMessage: vi.fn(),
+      loadConfig: vi.fn(() => ({ channels: { matrix: {} } })),
+      writeConfigFile: vi.fn(async () => {}),
+      loadWebMedia: vi.fn(async () => ({
+        buffer: Buffer.from("avatar"),
+        contentType: "image/png",
+        fileName: "avatar.png",
+      })),
+      abortSignal: undefined,
+      env: {},
+    };
+  }
+
+  it("persists converted avatar URLs after profile sync", async () => {
+    const params = createParams();
+    const updatedCfg = { channels: { matrix: { avatarUrl: "mxc://avatar" } } };
+    vi.mocked(deps.syncMatrixOwnProfile).mockResolvedValue(
+      createProfileSyncResult({
+        avatarUpdated: true,
+        resolvedAvatarUrl: "mxc://avatar",
+        uploadedAvatarSource: "http",
+        convertedAvatarFromHttp: true,
+      }),
+    );
+    vi.mocked(deps.updateMatrixAccountConfig).mockReturnValue(updatedCfg);
+
+    await runMatrixStartupMaintenance(params, deps);
+
+    expect(deps.syncMatrixOwnProfile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: "@bot:example.org",
+        displayName: "Ops Bot",
+        avatarUrl: "https://example.org/avatar.png",
+      }),
+    );
+    expect(deps.updateMatrixAccountConfig).toHaveBeenCalledWith(
+      { channels: { matrix: {} } },
+      "ops",
+      { avatarUrl: "mxc://avatar" },
+    );
+    expect(params.writeConfigFile).toHaveBeenCalledWith(updatedCfg as never);
+    expect(params.logVerboseMessage).toHaveBeenCalledWith(
+      "matrix: persisted converted avatar URL for account ops (mxc://avatar)",
+    );
+  });
+
+  it("reports stale devices, pending verification, and restored legacy backups", async () => {
+    const params = createParams();
+    params.auth.encryption = true;
+    vi.mocked(deps.summarizeMatrixDeviceHealth).mockReturnValue({
+      currentDeviceId: null,
+      staleOpenClawDevices: [
+        { deviceId: "DEV123", displayName: "OpenClaw Device", current: false },
+      ],
+      currentOpenClawDevices: [],
+    });
+    vi.mocked(deps.ensureMatrixStartupVerification).mockResolvedValue(
+      createStartupVerificationOutcome("pending"),
+    );
+    vi.mocked(deps.maybeRestoreLegacyMatrixBackup).mockResolvedValue(
+      createLegacyCryptoRestoreResult({
+        kind: "restored",
+        imported: 2,
+        total: 3,
+        localOnlyKeys: 1,
+      }),
+    );
+
+    await runMatrixStartupMaintenance(params, deps);
+
+    expect(params.logger.warn).toHaveBeenCalledWith(
+      "matrix: stale OpenClaw devices detected for @bot:example.org: DEV123. Run 'openclaw matrix devices prune-stale --account ops' to keep encrypted-room trust healthy.",
+    );
+    expect(params.logger.info).toHaveBeenCalledWith(
+      "matrix: device not verified — run 'openclaw matrix verify device <key>' to enable E2EE",
+    );
+    expect(params.logger.info).toHaveBeenCalledWith(
+      "matrix: startup verification request is already pending; finish it in another Matrix client",
+    );
+    expect(params.logger.info).toHaveBeenCalledWith(
+      "matrix: restored 2/3 room key(s) from legacy encrypted-state backup",
+    );
+    expect(params.logger.warn).toHaveBeenCalledWith(
+      "matrix: 1 legacy local-only room key(s) were never backed up and could not be restored automatically",
+    );
+  });
+
+  it("logs cooldown and request-failure verification outcomes without throwing", async () => {
+    const params = createParams();
+    params.auth.encryption = true;
+    vi.mocked(deps.ensureMatrixStartupVerification).mockResolvedValueOnce(
+      createStartupVerificationOutcome("cooldown", { retryAfterMs: 321 }),
+    );
+
+    await runMatrixStartupMaintenance(params, deps);
+
+    expect(params.logVerboseMessage).toHaveBeenCalledWith(
+      "matrix: skipped startup verification request due to cooldown (retryAfterMs=321)",
+    );
+
+    vi.mocked(deps.ensureMatrixStartupVerification).mockResolvedValueOnce(
+      createStartupVerificationOutcome("request-failed", { error: "boom" }),
+    );
+
+    await runMatrixStartupMaintenance(params, deps);
+
+    expect(params.logger.debug).toHaveBeenCalledWith(
+      "Matrix startup verification request failed (non-fatal)",
+      { error: "boom" },
+    );
+  });
+
+  it("aborts maintenance before later startup steps continue", async () => {
+    const params = createParams();
+    params.auth.encryption = true;
+    const abortController = new AbortController();
+    params.abortSignal = abortController.signal;
+    vi.mocked(deps.syncMatrixOwnProfile).mockImplementation(async () => {
+      abortController.abort();
+      return createProfileSyncResult();
+    });
+
+    await expect(runMatrixStartupMaintenance(params, deps)).rejects.toMatchObject({
+      message: "Matrix startup aborted",
+      name: "AbortError",
+    });
+    expect(deps.ensureMatrixStartupVerification).not.toHaveBeenCalled();
+    expect(deps.maybeRestoreLegacyMatrixBackup).not.toHaveBeenCalled();
+  });
+});

package/src/matrix/monitor/startup.ts

@@ -0,0 +1,218 @@
+import type { RuntimeLogger } from "../../runtime-api.js";
+import type { CoreConfig, MatrixConfig } from "../../types.js";
+import type { MatrixAuth } from "../client.js";
+import type { MatrixClient } from "../sdk.js";
+import { isMatrixStartupAbortError, throwIfMatrixStartupAborted } from "../startup-abort.js";
+
+type MatrixStartupClient = Pick<
+  MatrixClient,
+  | "crypto"
+  | "getOwnDeviceVerificationStatus"
+  | "getUserProfile"
+  | "listOwnDevices"
+  | "restoreRoomKeyBackup"
+  | "setAvatarUrl"
+  | "setDisplayName"
+  | "uploadContent"
+>;
+
+export type MatrixStartupMaintenanceDeps = {
+  updateMatrixAccountConfig: typeof import("../config-update.js").updateMatrixAccountConfig;
+  summarizeMatrixDeviceHealth: typeof import("../device-health.js").summarizeMatrixDeviceHealth;
+  syncMatrixOwnProfile: typeof import("../profile.js").syncMatrixOwnProfile;
+  maybeRestoreLegacyMatrixBackup: typeof import("./legacy-crypto-restore.js").maybeRestoreLegacyMatrixBackup;
+  ensureMatrixStartupVerification: typeof import("./startup-verification.js").ensureMatrixStartupVerification;
+};
+
+let matrixStartupMaintenanceDepsPromise: Promise<MatrixStartupMaintenanceDeps> | undefined;
+
+async function loadMatrixStartupMaintenanceDeps(): Promise<MatrixStartupMaintenanceDeps> {
+  matrixStartupMaintenanceDepsPromise ??= Promise.all([
+    import("../config-update.js"),
+    import("../device-health.js"),
+    import("../profile.js"),
+    import("./legacy-crypto-restore.js"),
+    import("./startup-verification.js"),
+  ]).then(
+    ([
+      configUpdateModule,
+      deviceHealthModule,
+      profileModule,
+      legacyCryptoRestoreModule,
+      startupVerificationModule,
+    ]) => ({
+      updateMatrixAccountConfig: configUpdateModule.updateMatrixAccountConfig,
+      summarizeMatrixDeviceHealth: deviceHealthModule.summarizeMatrixDeviceHealth,
+      syncMatrixOwnProfile: profileModule.syncMatrixOwnProfile,
+      maybeRestoreLegacyMatrixBackup: legacyCryptoRestoreModule.maybeRestoreLegacyMatrixBackup,
+      ensureMatrixStartupVerification: startupVerificationModule.ensureMatrixStartupVerification,
+    }),
+  );
+  return await matrixStartupMaintenanceDepsPromise;
+}
+
+export async function runMatrixStartupMaintenance(
+  params: {
+    client: MatrixStartupClient;
+    auth: MatrixAuth;
+    accountId: string;
+    effectiveAccountId: string;
+    accountConfig: MatrixConfig;
+    logger: RuntimeLogger;
+    logVerboseMessage: (message: string) => void;
+    loadConfig: () => CoreConfig;
+    writeConfigFile: (cfg: never) => Promise<void>;
+    loadWebMedia: (
+      url: string,
+      maxBytes: number,
+    ) => Promise<{ buffer: Buffer; contentType?: string; fileName?: string }>;
+    env?: NodeJS.ProcessEnv;
+    abortSignal?: AbortSignal;
+  },
+  deps?: MatrixStartupMaintenanceDeps,
+): Promise<void> {
+  const runtimeDeps = deps ?? (await loadMatrixStartupMaintenanceDeps());
+  throwIfMatrixStartupAborted(params.abortSignal);
+  try {
+    const profileSync = await runtimeDeps.syncMatrixOwnProfile({
+      client: params.client,
+      userId: params.auth.userId,
+      displayName: params.accountConfig.name,
+      avatarUrl: params.accountConfig.avatarUrl,
+      loadAvatarFromUrl: async (url, maxBytes) => await params.loadWebMedia(url, maxBytes),
+    });
+    throwIfMatrixStartupAborted(params.abortSignal);
+    if (profileSync.displayNameUpdated) {
+      params.logger.info(`matrix: profile display name updated for ${params.auth.userId}`);
+    }
+    if (profileSync.avatarUpdated) {
+      params.logger.info(`matrix: profile avatar updated for ${params.auth.userId}`);
+    }
+    if (
+      profileSync.convertedAvatarFromHttp &&
+      profileSync.resolvedAvatarUrl &&
+      params.accountConfig.avatarUrl !== profileSync.resolvedAvatarUrl
+    ) {
+      const latestCfg = params.loadConfig();
+      const updatedCfg = runtimeDeps.updateMatrixAccountConfig(latestCfg, params.accountId, {
+        avatarUrl: profileSync.resolvedAvatarUrl,
+      });
+      await params.writeConfigFile(updatedCfg as never);
+      throwIfMatrixStartupAborted(params.abortSignal);
+      params.logVerboseMessage(
+        `matrix: persisted converted avatar URL for account ${params.accountId} (${profileSync.resolvedAvatarUrl})`,
+      );
+    }
+  } catch (err) {
+    if (isMatrixStartupAbortError(err)) {
+      throw err;
+    }
+    params.logger.warn("matrix: failed to sync profile from config", { error: String(err) });
+  }
+
+  if (!(params.auth.encryption && params.client.crypto)) {
+    return;
+  }
+
+  try {
+    throwIfMatrixStartupAborted(params.abortSignal);
+    const deviceHealth = runtimeDeps.summarizeMatrixDeviceHealth(
+      await params.client.listOwnDevices(),
+    );
+    if (deviceHealth.staleOpenClawDevices.length > 0) {
+      params.logger.warn(
+        `matrix: stale OpenClaw devices detected for ${params.auth.userId}: ${deviceHealth.staleOpenClawDevices.map((device) => device.deviceId).join(", ")}. Run 'openclaw matrix devices prune-stale --account ${params.effectiveAccountId}' to keep encrypted-room trust healthy.`,
+      );
+    }
+  } catch (err) {
+    if (isMatrixStartupAbortError(err)) {
+      throw err;
+    }
+    params.logger.debug?.("Failed to inspect matrix device hygiene (non-fatal)", {
+      error: String(err),
+    });
+  }
+
+  try {
+    throwIfMatrixStartupAborted(params.abortSignal);
+    const startupVerification = await runtimeDeps.ensureMatrixStartupVerification({
+      client: params.client,
+      auth: params.auth,
+      accountConfig: params.accountConfig,
+      env: params.env,
+    });
+    throwIfMatrixStartupAborted(params.abortSignal);
+    if (startupVerification.kind === "verified") {
+      params.logger.info("matrix: device is verified by its owner and ready for encrypted rooms");
+    } else if (
+      startupVerification.kind === "disabled" ||
+      startupVerification.kind === "cooldown" ||
+      startupVerification.kind === "pending" ||
+      startupVerification.kind === "request-failed"
+    ) {
+      params.logger.info(
+        "matrix: device not verified — run 'openclaw matrix verify device <key>' to enable E2EE",
+      );
+      if (startupVerification.kind === "pending") {
+        params.logger.info(
+          "matrix: startup verification request is already pending; finish it in another Matrix client",
+        );
+      } else if (startupVerification.kind === "cooldown") {
+        params.logVerboseMessage(
+          `matrix: skipped startup verification request due to cooldown (retryAfterMs=${startupVerification.retryAfterMs ?? 0})`,
+        );
+      } else if (startupVerification.kind === "request-failed") {
+        params.logger.debug?.("Matrix startup verification request failed (non-fatal)", {
+          error: startupVerification.error ?? "unknown",
+        });
+      }
+    } else if (startupVerification.kind === "requested") {
+      params.logger.info(
+        "matrix: device not verified — requested verification in another Matrix client",
+      );
+    }
+  } catch (err) {
+    if (isMatrixStartupAbortError(err)) {
+      throw err;
+    }
+    params.logger.debug?.("Failed to resolve matrix verification status (non-fatal)", {
+      error: String(err),
+    });
+  }
+
+  try {
+    throwIfMatrixStartupAborted(params.abortSignal);
+    const legacyCryptoRestore = await runtimeDeps.maybeRestoreLegacyMatrixBackup({
+      client: params.client,
+      auth: params.auth,
+      env: params.env,
+    });
+    throwIfMatrixStartupAborted(params.abortSignal);
+    if (legacyCryptoRestore.kind === "restored") {
+      params.logger.info(
+        `matrix: restored ${legacyCryptoRestore.imported}/${legacyCryptoRestore.total} room key(s) from legacy encrypted-state backup`,
+      );
+      if (legacyCryptoRestore.localOnlyKeys > 0) {
+        params.logger.warn(
+          `matrix: ${legacyCryptoRestore.localOnlyKeys} legacy local-only room key(s) were never backed up and could not be restored automatically`,
+        );
+      }
+    } else if (legacyCryptoRestore.kind === "failed") {
+      params.logger.warn(
+        `matrix: failed restoring room keys from legacy encrypted-state backup: ${legacyCryptoRestore.error}`,
+      );
+      if (legacyCryptoRestore.localOnlyKeys > 0) {
+        params.logger.warn(
+          `matrix: ${legacyCryptoRestore.localOnlyKeys} legacy local-only room key(s) were never backed up and may remain unavailable until manually recovered`,
+        );
+      }
+    }
+  } catch (err) {
+    if (isMatrixStartupAbortError(err)) {
+      throw err;
+    }
+    params.logger.warn("matrix: failed restoring legacy encrypted-state backup", {
+      error: String(err),
+    });
+  }
+}

package/src/matrix/monitor/status.ts

@@ -0,0 +1,111 @@
+import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
+import { createConnectedChannelStatusPatch } from "openclaw/plugin-sdk/gateway-runtime";
+import { formatMatrixErrorMessage } from "../errors.js";
+import {
+  isMatrixDisconnectedSyncState,
+  isMatrixReadySyncState,
+  type MatrixSyncState,
+} from "../sync-state.js";
+
+type MatrixMonitorStatusSink = (patch: ChannelAccountSnapshot) => void;
+
+function cloneLastDisconnect(
+  value: ChannelAccountSnapshot["lastDisconnect"],
+): ChannelAccountSnapshot["lastDisconnect"] {
+  if (!value || typeof value === "string") {
+    return value ?? null;
+  }
+  return { ...value };
+}
+
+function formatSyncError(error: unknown): string | null {
+  if (!error) {
+    return null;
+  }
+  if (error instanceof Error) {
+    return error.message || error.name || "unknown";
+  }
+  return formatMatrixErrorMessage(error);
+}
+
+export type MatrixMonitorStatusController = ReturnType<typeof createMatrixMonitorStatusController>;
+
+export function createMatrixMonitorStatusController(params: {
+  accountId: string;
+  baseUrl?: string;
+  statusSink?: MatrixMonitorStatusSink;
+}) {
+  const status: ChannelAccountSnapshot = {
+    accountId: params.accountId,
+    ...(params.baseUrl ? { baseUrl: params.baseUrl } : {}),
+    connected: false,
+    lastConnectedAt: null,
+    lastDisconnect: null,
+    lastError: null,
+    healthState: "starting",
+  };
+
+  const emit = () => {
+    params.statusSink?.({
+      ...status,
+      lastDisconnect: cloneLastDisconnect(status.lastDisconnect),
+    });
+  };
+
+  const noteConnected = (at = Date.now()) => {
+    if (status.connected === true) {
+      status.lastEventAt = at;
+    } else {
+      Object.assign(status, createConnectedChannelStatusPatch(at));
+    }
+    status.lastError = null;
+    status.lastDisconnect = null;
+    status.healthState = "healthy";
+    emit();
+  };
+
+  const noteDisconnected = (params: { state: MatrixSyncState; at?: number; error?: unknown }) => {
+    const at = params.at ?? Date.now();
+    const error = formatSyncError(params.error);
+    status.connected = false;
+    status.lastEventAt = at;
+    status.lastDisconnect = {
+      at,
+      ...(error ? { error } : {}),
+    };
+    status.lastError = error;
+    status.healthState = params.state.toLowerCase();
+    emit();
+  };
+
+  emit();
+
+  return {
+    noteSyncState(state: MatrixSyncState, error?: unknown, at = Date.now()) {
+      if (isMatrixReadySyncState(state)) {
+        noteConnected(at);
+        return;
+      }
+      if (isMatrixDisconnectedSyncState(state)) {
+        noteDisconnected({ state, at, error });
+        return;
+      }
+      // Unknown future SDK states inherit the current connectivity bit until the
+      // SDK classifies them as ready or disconnected. Avoid guessing here.
+      status.lastEventAt = at;
+      status.healthState = state.toLowerCase();
+      emit();
+    },
+    noteUnexpectedError(error: unknown, at = Date.now()) {
+      noteDisconnected({ state: "ERROR", at, error });
+    },
+    markStopped(at = Date.now()) {
+      status.connected = false;
+      status.lastEventAt = at;
+      if (status.healthState !== "error") {
+        status.healthState = "stopped";
+      }
+      emit();
+    },
+  };
+}