@gakr-gakr/matrix 0.1.0

package/src/matrix/monitor/route.ts

@@ -0,0 +1,179 @@
+import { resolveConfiguredAcpBindingRecord } from "autobot/plugin-sdk/acp-binding-resolve-runtime";
+import type { PluginRuntime } from "autobot/plugin-sdk/plugin-runtime";
+import {
+  buildAgentSessionKey,
+  deriveLastRoutePolicy,
+  resolveAgentIdFromSessionKey,
+} from "autobot/plugin-sdk/routing";
+import { getSessionBindingService } from "autobot/plugin-sdk/session-binding-runtime";
+import type { CoreConfig } from "../../types.js";
+import { resolveMatrixThreadSessionKeys } from "./threads.js";
+
+type MatrixResolvedRoute = ReturnType<PluginRuntime["channel"]["routing"]["resolveAgentRoute"]>;
+
+function resolveMatrixDmSessionKey(params: {
+  accountId: string;
+  agentId: string;
+  roomId: string;
+  dmSessionScope?: "per-user" | "per-room";
+  fallbackSessionKey: string;
+}): string {
+  if (params.dmSessionScope !== "per-room") {
+    return params.fallbackSessionKey;
+  }
+  return buildAgentSessionKey({
+    agentId: params.agentId,
+    channel: "matrix",
+    accountId: params.accountId,
+    peer: {
+      kind: "channel",
+      id: params.roomId,
+    },
+  });
+}
+
+function shouldApplyMatrixPerRoomDmSessionScope(params: {
+  isDirectMessage: boolean;
+  configuredSessionKey?: string;
+}): boolean {
+  return params.isDirectMessage && !params.configuredSessionKey;
+}
+
+export function resolveMatrixInboundRoute(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  roomId: string;
+  senderId: string;
+  isDirectMessage: boolean;
+  dmSessionScope?: "per-user" | "per-room";
+  threadId?: string;
+  eventTs?: number;
+  resolveAgentRoute: PluginRuntime["channel"]["routing"]["resolveAgentRoute"];
+}): {
+  route: MatrixResolvedRoute;
+  configuredBinding: ReturnType<typeof resolveConfiguredAcpBindingRecord>;
+  runtimeBindingId: string | null;
+} {
+  const baseRoute = params.resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "matrix",
+    accountId: params.accountId,
+    peer: {
+      kind: params.isDirectMessage ? "direct" : "channel",
+      id: params.isDirectMessage ? params.senderId : params.roomId,
+    },
+    // Matrix DMs are still sender-addressed first, but the room ID remains a
+    // useful fallback binding key for generic route matching.
+    parentPeer: params.isDirectMessage
+      ? {
+          kind: "channel",
+          id: params.roomId,
+        }
+      : undefined,
+  });
+  const bindingConversationId = params.threadId ?? params.roomId;
+  const bindingParentConversationId = params.threadId ? params.roomId : undefined;
+  const sessionBindingService = getSessionBindingService();
+  const runtimeBinding = sessionBindingService.resolveByConversation({
+    channel: "matrix",
+    accountId: params.accountId,
+    conversationId: bindingConversationId,
+    parentConversationId: bindingParentConversationId,
+  });
+  const boundSessionKey = runtimeBinding?.targetSessionKey?.trim();
+
+  if (runtimeBinding && boundSessionKey) {
+    return {
+      route: {
+        ...baseRoute,
+        sessionKey: boundSessionKey,
+        agentId: resolveAgentIdFromSessionKey(boundSessionKey) || baseRoute.agentId,
+        lastRoutePolicy: deriveLastRoutePolicy({
+          sessionKey: boundSessionKey,
+          mainSessionKey: baseRoute.mainSessionKey,
+        }),
+        matchedBy: "binding.channel",
+      },
+      configuredBinding: null,
+      runtimeBindingId: runtimeBinding.bindingId,
+    };
+  }
+
+  const configuredBinding =
+    runtimeBinding == null
+      ? resolveConfiguredAcpBindingRecord({
+          cfg: params.cfg,
+          channel: "matrix",
+          accountId: params.accountId,
+          conversationId: bindingConversationId,
+          parentConversationId: bindingParentConversationId,
+        })
+      : null;
+  const configuredSessionKey = configuredBinding?.record.targetSessionKey?.trim();
+
+  const effectiveRoute =
+    configuredBinding && configuredSessionKey
+      ? {
+          ...baseRoute,
+          sessionKey: configuredSessionKey,
+          agentId:
+            resolveAgentIdFromSessionKey(configuredSessionKey) ||
+            configuredBinding.spec.agentId ||
+            baseRoute.agentId,
+          lastRoutePolicy: deriveLastRoutePolicy({
+            sessionKey: configuredSessionKey,
+            mainSessionKey: baseRoute.mainSessionKey,
+          }),
+          matchedBy: "binding.channel" as const,
+        }
+      : baseRoute;
+
+  const dmSessionKey = shouldApplyMatrixPerRoomDmSessionScope({
+    isDirectMessage: params.isDirectMessage,
+    configuredSessionKey,
+  })
+    ? resolveMatrixDmSessionKey({
+        accountId: params.accountId,
+        agentId: effectiveRoute.agentId,
+        roomId: params.roomId,
+        dmSessionScope: params.dmSessionScope,
+        fallbackSessionKey: effectiveRoute.sessionKey,
+      })
+    : effectiveRoute.sessionKey;
+  const routeWithDmScope =
+    dmSessionKey === effectiveRoute.sessionKey
+      ? effectiveRoute
+      : {
+          ...effectiveRoute,
+          sessionKey: dmSessionKey,
+          lastRoutePolicy: "session" as const,
+        };
+
+  // When no binding overrides the session key, isolate threads into their own sessions.
+  if (!configuredBinding && !configuredSessionKey && params.threadId) {
+    const threadKeys = resolveMatrixThreadSessionKeys({
+      baseSessionKey: routeWithDmScope.sessionKey,
+      threadId: params.threadId,
+      parentSessionKey: routeWithDmScope.sessionKey,
+    });
+    return {
+      route: {
+        ...routeWithDmScope,
+        sessionKey: threadKeys.sessionKey,
+        mainSessionKey: threadKeys.parentSessionKey ?? routeWithDmScope.sessionKey,
+        lastRoutePolicy: deriveLastRoutePolicy({
+          sessionKey: threadKeys.sessionKey,
+          mainSessionKey: threadKeys.parentSessionKey ?? routeWithDmScope.sessionKey,
+        }),
+      },
+      configuredBinding,
+      runtimeBindingId: null,
+    };
+  }
+
+  return {
+    route: routeWithDmScope,
+    configuredBinding,
+    runtimeBindingId: null,
+  };
+}

package/src/matrix/monitor/runtime-api.ts

@@ -0,0 +1,28 @@
+// Narrow Matrix monitor helper seam.
+// Keep monitor internals off the broad package runtime-api barrel so monitor
+// tests and shared workers do not pull unrelated Matrix helper surfaces.
+
+export type { NormalizedLocation } from "autobot/plugin-sdk/channel-location";
+export type { PluginRuntime, RuntimeLogger } from "autobot/plugin-sdk/plugin-runtime";
+export type { BlockReplyContext, ReplyPayload } from "autobot/plugin-sdk/reply-runtime";
+export type { MarkdownTableMode, AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+export {
+  addAllowlistUserEntriesFromConfigEntry,
+  buildAllowlistResolutionSummary,
+  canonicalizeAllowlistWithResolvedIds,
+  formatAllowlistMatchMeta,
+  patchAllowlistUsersInConfigEntries,
+  summarizeMapping,
+} from "autobot/plugin-sdk/allow-from";
+export {
+  createReplyPrefixOptions,
+  createTypingCallbacks,
+} from "autobot/plugin-sdk/channel-reply-options-runtime";
+export { formatLocationText, toLocationContext } from "autobot/plugin-sdk/channel-location";
+export { getAgentScopedMediaLocalRoots } from "autobot/plugin-sdk/agent-media-payload";
+export { logInboundDrop, logTypingFailure } from "autobot/plugin-sdk/channel-logging";
+export {
+  buildChannelKeyCandidates,
+  resolveChannelEntryMatch,
+} from "autobot/plugin-sdk/channel-targets";

package/src/matrix/monitor/startup-verification.ts

@@ -0,0 +1,237 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "autobot/plugin-sdk/json-store";
+import type { MatrixConfig } from "../../types.js";
+import { resolveMatrixStoragePaths } from "../client/storage.js";
+import type { MatrixAuth } from "../client/types.js";
+import { formatMatrixErrorMessage } from "../errors.js";
+import type { MatrixClient, MatrixOwnDeviceVerificationStatus } from "../sdk.js";
+
+const STARTUP_VERIFICATION_STATE_FILENAME = "startup-verification.json";
+const DEFAULT_STARTUP_VERIFICATION_MODE = "if-unverified" as const;
+const DEFAULT_STARTUP_VERIFICATION_COOLDOWN_HOURS = 24;
+const DEFAULT_STARTUP_VERIFICATION_FAILURE_COOLDOWN_MS = 60 * 60 * 1000;
+
+type MatrixStartupVerificationState = {
+  userId?: string | null;
+  deviceId?: string | null;
+  attemptedAt?: string;
+  outcome?: "requested" | "failed";
+  requestId?: string;
+  transactionId?: string;
+  error?: string;
+};
+
+export type MatrixStartupVerificationOutcome =
+  | {
+      kind: "disabled" | "verified" | "cooldown" | "pending" | "requested" | "request-failed";
+      verification: MatrixOwnDeviceVerificationStatus;
+      requestId?: string;
+      transactionId?: string;
+      error?: string;
+      retryAfterMs?: number;
+    }
+  | {
+      kind: "unsupported";
+      verification?: undefined;
+    };
+
+function normalizeCooldownHours(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_STARTUP_VERIFICATION_COOLDOWN_HOURS;
+  }
+  return Math.max(0, value);
+}
+
+function resolveStartupVerificationStatePath(params: {
+  auth: MatrixAuth;
+  env?: NodeJS.ProcessEnv;
+}): string {
+  const storagePaths = resolveMatrixStoragePaths({
+    homeserver: params.auth.homeserver,
+    userId: params.auth.userId,
+    accessToken: params.auth.accessToken,
+    accountId: params.auth.accountId,
+    deviceId: params.auth.deviceId,
+    env: params.env,
+  });
+  return path.join(storagePaths.rootDir, STARTUP_VERIFICATION_STATE_FILENAME);
+}
+
+async function readStartupVerificationState(
+  filePath: string,
+): Promise<MatrixStartupVerificationState | null> {
+  const { value } = await readJsonFileWithFallback<MatrixStartupVerificationState | null>(
+    filePath,
+    null,
+  );
+  return value && typeof value === "object" ? value : null;
+}
+
+async function clearStartupVerificationState(filePath: string): Promise<void> {
+  await fs.rm(filePath, { force: true }).catch(() => {});
+}
+
+function resolveStateCooldownMs(
+  state: MatrixStartupVerificationState | null,
+  cooldownMs: number,
+): number {
+  if (state?.outcome === "failed") {
+    return Math.min(cooldownMs, DEFAULT_STARTUP_VERIFICATION_FAILURE_COOLDOWN_MS);
+  }
+  return cooldownMs;
+}
+
+function resolveRetryAfterMs(params: {
+  attemptedAt?: string;
+  cooldownMs: number;
+  nowMs: number;
+}): number | undefined {
+  const attemptedAtMs = Date.parse(params.attemptedAt ?? "");
+  if (!Number.isFinite(attemptedAtMs)) {
+    return undefined;
+  }
+  const remaining = attemptedAtMs + params.cooldownMs - params.nowMs;
+  return remaining > 0 ? remaining : undefined;
+}
+
+function shouldHonorCooldown(params: {
+  state: MatrixStartupVerificationState | null;
+  verification: MatrixOwnDeviceVerificationStatus;
+  stateCooldownMs: number;
+  nowMs: number;
+}): boolean {
+  if (!params.state || params.stateCooldownMs <= 0) {
+    return false;
+  }
+  if (
+    params.state.userId &&
+    params.verification.userId &&
+    params.state.userId !== params.verification.userId
+  ) {
+    return false;
+  }
+  if (
+    params.state.deviceId &&
+    params.verification.deviceId &&
+    params.state.deviceId !== params.verification.deviceId
+  ) {
+    return false;
+  }
+  return (
+    resolveRetryAfterMs({
+      attemptedAt: params.state.attemptedAt,
+      cooldownMs: params.stateCooldownMs,
+      nowMs: params.nowMs,
+    }) !== undefined
+  );
+}
+
+function hasPendingSelfVerification(
+  verifications: Array<{
+    isSelfVerification: boolean;
+    completed: boolean;
+    pending: boolean;
+  }>,
+): boolean {
+  return verifications.some(
+    (entry) => entry.isSelfVerification && !entry.completed && entry.pending,
+  );
+}
+
+export async function ensureMatrixStartupVerification(params: {
+  client: Pick<MatrixClient, "crypto" | "getOwnDeviceVerificationStatus">;
+  auth: MatrixAuth;
+  accountConfig: Pick<MatrixConfig, "startupVerification" | "startupVerificationCooldownHours">;
+  env?: NodeJS.ProcessEnv;
+  nowMs?: number;
+  stateFilePath?: string;
+}): Promise<MatrixStartupVerificationOutcome> {
+  if (params.auth.encryption !== true || !params.client.crypto) {
+    return { kind: "unsupported" };
+  }
+
+  const verification = await params.client.getOwnDeviceVerificationStatus();
+  const statePath =
+    params.stateFilePath ??
+    resolveStartupVerificationStatePath({
+      auth: params.auth,
+      env: params.env,
+    });
+
+  if (verification.verified) {
+    await clearStartupVerificationState(statePath);
+    return {
+      kind: "verified",
+      verification,
+    };
+  }
+
+  const mode = params.accountConfig.startupVerification ?? DEFAULT_STARTUP_VERIFICATION_MODE;
+  if (mode === "off") {
+    await clearStartupVerificationState(statePath);
+    return {
+      kind: "disabled",
+      verification,
+    };
+  }
+
+  const verifications = await params.client.crypto.listVerifications().catch(() => []);
+  if (hasPendingSelfVerification(verifications)) {
+    return {
+      kind: "pending",
+      verification,
+    };
+  }
+
+  const cooldownHours = normalizeCooldownHours(
+    params.accountConfig.startupVerificationCooldownHours,
+  );
+  const cooldownMs = cooldownHours * 60 * 60 * 1000;
+  const nowMs = params.nowMs ?? Date.now();
+  const state = await readStartupVerificationState(statePath);
+  const stateCooldownMs = resolveStateCooldownMs(state, cooldownMs);
+  if (shouldHonorCooldown({ state, verification, stateCooldownMs, nowMs })) {
+    return {
+      kind: "cooldown",
+      verification,
+      retryAfterMs: resolveRetryAfterMs({
+        attemptedAt: state?.attemptedAt,
+        cooldownMs: stateCooldownMs,
+        nowMs,
+      }),
+    };
+  }
+
+  try {
+    const request = await params.client.crypto.requestVerification({ ownUser: true });
+    await writeJsonFileAtomically(statePath, {
+      userId: verification.userId,
+      deviceId: verification.deviceId,
+      attemptedAt: new Date(nowMs).toISOString(),
+      outcome: "requested",
+      requestId: request.id,
+      transactionId: request.transactionId,
+    } satisfies MatrixStartupVerificationState);
+    return {
+      kind: "requested",
+      verification,
+      requestId: request.id,
+      transactionId: request.transactionId ?? undefined,
+    };
+  } catch (err) {
+    const error = formatMatrixErrorMessage(err);
+    await writeJsonFileAtomically(statePath, {
+      userId: verification.userId,
+      deviceId: verification.deviceId,
+      attemptedAt: new Date(nowMs).toISOString(),
+      outcome: "failed",
+      error,
+    } satisfies MatrixStartupVerificationState).catch(() => {});
+    return {
+      kind: "request-failed",
+      verification,
+      error,
+    };
+  }
+}

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;
+    getRuntimeConfig: () => CoreConfig;
+    replaceConfigFile: (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.getRuntimeConfig();
+      const updatedCfg = runtimeDeps.updateMatrixAccountConfig(latestCfg, params.accountId, {
+        avatarUrl: profileSync.resolvedAvatarUrl,
+      });
+      await params.replaceConfigFile(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.staleAutoBotDevices.length > 0) {
+      params.logger.warn(
+        `matrix: stale AutoBot devices detected for ${params.auth.userId}: ${deviceHealth.staleAutoBotDevices.map((device) => device.deviceId).join(", ")}. Run 'autobot 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 'autobot 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),
+    });
+  }
+}