@kodelyth/matrix 2026.5.42 → 2026.6.1

package/src/matrix/monitor/index.ts

@@ -1,540 +0,0 @@
-import { format } from "node:util";
-import { CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY } from "klaw/plugin-sdk/approval-handler-adapter-runtime";
-import type { ChannelRuntimeSurface } from "klaw/plugin-sdk/channel-contract";
-import { waitUntilAbort } from "klaw/plugin-sdk/channel-lifecycle";
-import { registerChannelRuntimeContext } from "klaw/plugin-sdk/channel-runtime-context";
-import {
-  GROUP_POLICY_BLOCKED_LABEL,
-  resolveThreadBindingIdleTimeoutMsForChannel,
-  resolveThreadBindingMaxAgeMsForChannel,
-  resolveAllowlistProviderRuntimeGroupPolicy,
-  resolveDefaultGroupPolicy,
-  warnMissingProviderGroupPolicyFallbackOnce,
-  type RuntimeEnv,
-} from "../../runtime-api.js";
-import { getMatrixRuntime } from "../../runtime.js";
-import type {
-  CoreConfig,
-  MatrixConfig,
-  MatrixStreamingConfig,
-  MatrixStreamingMode,
-  ReplyToMode,
-} from "../../types.js";
-import { resolveMatrixAccountConfig } from "../account-config.js";
-import { resolveConfiguredMatrixBotUserIds } from "../accounts.js";
-import { setActiveMatrixClient } from "../active-client.js";
-import {
-  backfillMatrixAuthDeviceIdAfterStartup,
-  isBunRuntime,
-  resolveMatrixAuth,
-  resolveMatrixAuthContext,
-  resolveSharedMatrixClient,
-} from "../client.js";
-import { releaseSharedClientInstance } from "../client/shared.js";
-import type { MatrixClient } from "../sdk.js";
-import { isMatrixStartupAbortError } from "../startup-abort.js";
-import {
-  isMatrixDisconnectedSyncState,
-  isMatrixReadySyncState,
-  type MatrixSyncState,
-} from "../sync-state.js";
-import { createMatrixThreadBindingManager } from "../thread-bindings.js";
-import { registerMatrixAutoJoin } from "./auto-join.js";
-import { resolveMatrixMonitorConfig, type MatrixResolvedAllowlistEntry } from "./config.js";
-import { createDirectRoomTracker } from "./direct.js";
-import { registerMatrixMonitorEvents } from "./events.js";
-import { createMatrixRoomMessageHandler } from "./handler.js";
-import {
-  createMatrixInboundEventDeduper,
-  type MatrixInboundEventDeduper,
-} from "./inbound-dedupe.js";
-import { shouldPromoteRecentInviteRoom } from "./recent-invite.js";
-import { createMatrixRoomInfoResolver } from "./room-info.js";
-import { runMatrixStartupMaintenance } from "./startup.js";
-import { createMatrixMonitorStatusController } from "./status.js";
-import { createMatrixMonitorSyncLifecycle } from "./sync-lifecycle.js";
-import { createMatrixMonitorTaskRunner } from "./task-runner.js";
-
-export type MonitorMatrixOpts = {
-  runtime?: RuntimeEnv;
-  channelRuntime?: ChannelRuntimeSurface;
-  abortSignal?: AbortSignal;
-  mediaMaxMb?: number;
-  initialSyncLimit?: number;
-  replyToMode?: ReplyToMode;
-  accountId?: string | null;
-  setStatus?: (next: import("klaw/plugin-sdk/channel-contract").ChannelAccountSnapshot) => void;
-};
-
-function isMatrixStreamingConfig(
-  streaming: MatrixConfig["streaming"],
-): streaming is MatrixStreamingConfig {
-  return Boolean(streaming && typeof streaming === "object" && !Array.isArray(streaming));
-}
-
-function resolveMatrixStreamingMode(streaming: MatrixConfig["streaming"]): MatrixStreamingMode {
-  if (streaming === true || streaming === "partial") {
-    return "partial";
-  }
-  if (streaming === "quiet") {
-    return "quiet";
-  }
-  if (streaming === "progress") {
-    return "progress";
-  }
-  if (isMatrixStreamingConfig(streaming)) {
-    if (
-      streaming.mode === "partial" ||
-      streaming.mode === "quiet" ||
-      streaming.mode === "progress"
-    ) {
-      return streaming.mode;
-    }
-  }
-  return "off";
-}
-
-function resolveMatrixPreviewToolProgress(streaming: MatrixConfig["streaming"]): boolean {
-  if (!isMatrixStreamingConfig(streaming)) {
-    return true;
-  }
-  if (resolveMatrixStreamingMode(streaming) === "progress") {
-    return streaming.progress?.toolProgress ?? streaming.preview?.toolProgress ?? true;
-  }
-  return streaming.preview?.toolProgress ?? true;
-}
-
-function resolveMatrixPreviewToolProgressEnabled(streaming: MatrixConfig["streaming"]): boolean {
-  return (
-    resolveMatrixStreamingMode(streaming) !== "off" && resolveMatrixPreviewToolProgress(streaming)
-  );
-}
-
-export const testing = {
-  resolveMatrixPreviewToolProgress,
-  resolveMatrixPreviewToolProgressEnabled,
-  resolveMatrixStreamingMode,
-};
-
-const DEFAULT_MEDIA_MAX_MB = 20;
-
-export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promise<void> {
-  // Fast-cancel callers should not pay the full Matrix startup/import cost.
-  if (opts.abortSignal?.aborted) {
-    return;
-  }
-  if (isBunRuntime()) {
-    throw new Error("Matrix provider requires Node (bun runtime not supported)");
-  }
-  const core = getMatrixRuntime();
-  let cfg = core.config.current() as CoreConfig;
-  if (cfg.channels?.["matrix"]?.enabled === false) {
-    return;
-  }
-
-  const logger = core.logging.getChildLogger({ module: "matrix-auto-reply" });
-  const formatRuntimeMessage = (...args: Parameters<RuntimeEnv["log"]>) => format(...args);
-  const runtime: RuntimeEnv = opts.runtime ?? {
-    log: (...args) => {
-      logger.info(formatRuntimeMessage(...args));
-    },
-    error: (...args) => {
-      logger.error(formatRuntimeMessage(...args));
-    },
-    exit: (code: number): never => {
-      throw new Error(`exit ${code}`);
-    },
-  };
-  const logVerboseMessage = (message: string) => {
-    if (!core.logging.shouldLogVerbose()) {
-      return;
-    }
-    logger.debug?.(message);
-  };
-
-  const authContext = resolveMatrixAuthContext({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const effectiveAccountId = authContext.accountId;
-
-  // Resolve account-specific config for multi-account support
-  const accountConfig = resolveMatrixAccountConfig({
-    cfg,
-    accountId: effectiveAccountId,
-  });
-
-  const allowlistOnly = accountConfig.allowlistOnly === true;
-  const accountAllowBots = accountConfig.allowBots;
-  let allowFrom: string[] = (accountConfig.dm?.allowFrom ?? []).map(String);
-  let groupAllowFrom: string[] = (accountConfig.groupAllowFrom ?? []).map(String);
-  let allowFromResolvedEntries: MatrixResolvedAllowlistEntry[] = [];
-  let groupAllowFromResolvedEntries: MatrixResolvedAllowlistEntry[] = [];
-  let roomsConfig = accountConfig.groups ?? accountConfig.rooms;
-  let needsRoomAliasesForConfig = false;
-  const configuredBotUserIds = resolveConfiguredMatrixBotUserIds({
-    cfg,
-    accountId: effectiveAccountId,
-  });
-
-  ({
-    allowFrom,
-    allowFromResolvedEntries,
-    groupAllowFrom,
-    groupAllowFromResolvedEntries,
-    roomsConfig,
-  } = await resolveMatrixMonitorConfig({
-    cfg,
-    accountId: effectiveAccountId,
-    allowFrom,
-    groupAllowFrom,
-    roomsConfig,
-    runtime,
-  }));
-  needsRoomAliasesForConfig = Boolean(
-    roomsConfig && Object.keys(roomsConfig).some((key) => key.trim().startsWith("#")),
-  );
-
-  cfg = {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      matrix: {
-        ...cfg.channels?.["matrix"],
-        dm: {
-          ...cfg.channels?.["matrix"]?.dm,
-          allowFrom,
-        },
-        groupAllowFrom,
-        ...(roomsConfig ? { groups: roomsConfig } : {}),
-      },
-    },
-  };
-
-  const auth = await resolveMatrixAuth({ cfg, accountId: effectiveAccountId });
-  const resolvedInitialSyncLimit =
-    typeof opts.initialSyncLimit === "number"
-      ? Math.max(0, Math.floor(opts.initialSyncLimit))
-      : auth.initialSyncLimit;
-  const authWithLimit =
-    resolvedInitialSyncLimit === auth.initialSyncLimit
-      ? auth
-      : { ...auth, initialSyncLimit: resolvedInitialSyncLimit };
-  const statusController = createMatrixMonitorStatusController({
-    accountId: auth.accountId,
-    baseUrl: auth.homeserver,
-    statusSink: opts.setStatus,
-  });
-  let cleanedUp = false;
-  let client: MatrixClient | null = null;
-  let threadBindingManager: { accountId: string; stop: () => void } | null = null;
-  let inboundDeduper: MatrixInboundEventDeduper | null = null;
-  const monitorTaskRunner = createMatrixMonitorTaskRunner({
-    logger,
-    logVerboseMessage,
-  });
-  let syncLifecycle: ReturnType<typeof createMatrixMonitorSyncLifecycle> | null = null;
-  const cleanup = async (mode: "persist" | "stop" = "persist") => {
-    if (cleanedUp) {
-      return;
-    }
-    cleanedUp = true;
-    try {
-      client?.stopSyncWithoutPersist();
-      if (client && mode === "persist") {
-        await client.drainPendingDecryptions("matrix monitor shutdown");
-      }
-      if (mode === "persist") {
-        await monitorTaskRunner.waitForIdle();
-      }
-      threadBindingManager?.stop();
-      await inboundDeduper?.stop();
-      if (client) {
-        await releaseSharedClientInstance(client, mode);
-      }
-    } finally {
-      client?.off("sync.state", onSyncState);
-      syncLifecycle?.dispose();
-      statusController.markStopped();
-      setActiveMatrixClient(null, auth.accountId);
-    }
-  };
-
-  const defaultGroupPolicy = resolveDefaultGroupPolicy(cfg);
-  const { groupPolicy: groupPolicyRaw, providerMissingFallbackApplied } =
-    resolveAllowlistProviderRuntimeGroupPolicy({
-      providerConfigPresent: cfg.channels?.["matrix"] !== undefined,
-      groupPolicy: accountConfig.groupPolicy,
-      defaultGroupPolicy,
-    });
-  warnMissingProviderGroupPolicyFallbackOnce({
-    providerMissingFallbackApplied,
-    providerKey: "matrix",
-    accountId: effectiveAccountId,
-    blockedLabel: GROUP_POLICY_BLOCKED_LABEL.room,
-    log: (message) => logVerboseMessage(message),
-  });
-  const groupPolicy = allowlistOnly && groupPolicyRaw === "open" ? "allowlist" : groupPolicyRaw;
-  const replyToMode = opts.replyToMode ?? accountConfig.replyToMode ?? "off";
-  const threadReplies = accountConfig.threadReplies ?? "inbound";
-  const dmThreadReplies = accountConfig.dm?.threadReplies;
-  const threadBindingIdleTimeoutMs = resolveThreadBindingIdleTimeoutMsForChannel({
-    cfg,
-    channel: "matrix",
-    accountId: effectiveAccountId,
-  });
-  const threadBindingMaxAgeMs = resolveThreadBindingMaxAgeMsForChannel({
-    cfg,
-    channel: "matrix",
-    accountId: effectiveAccountId,
-  });
-  const dmConfig = accountConfig.dm;
-  const dmEnabled = dmConfig?.enabled ?? true;
-  const dmPolicyRaw = dmConfig?.policy ?? "pairing";
-  const dmPolicy = allowlistOnly && dmPolicyRaw !== "disabled" ? "allowlist" : dmPolicyRaw;
-  const dmSessionScope = dmConfig?.sessionScope ?? "per-user";
-  const textLimit = core.channel.text.resolveTextChunkLimit(cfg, "matrix", effectiveAccountId);
-  const globalGroupChatHistoryLimit = (
-    cfg.messages as { groupChat?: { historyLimit?: number } } | undefined
-  )?.groupChat?.historyLimit;
-  const historyLimit = Math.max(0, accountConfig.historyLimit ?? globalGroupChatHistoryLimit ?? 0);
-  const mediaMaxMb = opts.mediaMaxMb ?? accountConfig.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
-  const mediaMaxBytes = Math.max(1, mediaMaxMb) * 1024 * 1024;
-  const streaming = resolveMatrixStreamingMode(accountConfig.streaming);
-  const previewToolProgressEnabled = resolveMatrixPreviewToolProgressEnabled(
-    accountConfig.streaming,
-  );
-  const blockStreamingEnabled = accountConfig.blockStreaming === true;
-  const startupMs = Date.now();
-  const startupGraceMs = 0;
-  const warnedEncryptedRooms = new Set<string>();
-  const warnedCryptoMissingRooms = new Set<string>();
-  let healthySyncSinceMs: number | undefined;
-  const noteSyncHealthState = (state: MatrixSyncState, at = Date.now()) => {
-    if (isMatrixReadySyncState(state)) {
-      healthySyncSinceMs ??= at;
-      return;
-    }
-    if (isMatrixDisconnectedSyncState(state)) {
-      healthySyncSinceMs = undefined;
-    }
-  };
-  const onSyncState = (state: MatrixSyncState) => {
-    noteSyncHealthState(state);
-  };
-
-  try {
-    client = await resolveSharedMatrixClient({
-      cfg,
-      auth: authWithLimit,
-      startClient: false,
-      accountId: auth.accountId,
-    });
-    setActiveMatrixClient(client, auth.accountId);
-    inboundDeduper = await createMatrixInboundEventDeduper({
-      auth,
-      env: process.env,
-    });
-    syncLifecycle = createMatrixMonitorSyncLifecycle({
-      client,
-      statusController,
-      isStopping: () => cleanedUp || opts.abortSignal?.aborted === true,
-    });
-    client.on("sync.state", onSyncState);
-    // Cold starts should ignore old room history, but once we have a persisted
-    // /sync cursor we want restart backlogs to replay just like other channels.
-    const dropPreStartupMessages = !client.hasPersistedSyncState();
-    const { getRoomInfo, getMemberDisplayName } = createMatrixRoomInfoResolver(client);
-    const directTracker = createDirectRoomTracker(client, {
-      log: logVerboseMessage,
-      canPromoteRecentInvite: async (roomId) =>
-        shouldPromoteRecentInviteRoom({
-          roomId,
-          roomInfo: await getRoomInfo(roomId, { includeAliases: true }),
-          rooms: roomsConfig,
-        }),
-      ...(dmSessionScope === "per-room"
-        ? {
-            canPromoteUnmappedStrictRoom: async (roomId) =>
-              shouldPromoteRecentInviteRoom({
-                roomId,
-                roomInfo: await getRoomInfo(roomId, { includeAliases: true }),
-                rooms: roomsConfig,
-              }),
-          }
-        : {}),
-      shouldKeepLocallyPromotedDirectRoom: async (roomId) => {
-        try {
-          const roomInfo = await getRoomInfo(roomId, { includeAliases: true });
-          if (!roomInfo.nameResolved || !roomInfo.aliasesResolved) {
-            return undefined;
-          }
-          return shouldPromoteRecentInviteRoom({
-            roomId,
-            roomInfo,
-            rooms: roomsConfig,
-          });
-        } catch (err) {
-          logVerboseMessage(
-            `matrix: local promotion revalidation failed room=${roomId} (${String(err)})`,
-          );
-          return undefined;
-        }
-      },
-    });
-    registerMatrixAutoJoin({ client, accountConfig, runtime });
-    const handleRoomMessage = createMatrixRoomMessageHandler({
-      client,
-      core,
-      cfg,
-      accountId: effectiveAccountId,
-      accountConfig,
-      runtime,
-      logger,
-      logVerboseMessage,
-      allowFrom,
-      allowFromResolvedEntries,
-      groupAllowFrom,
-      groupAllowFromResolvedEntries,
-      roomsConfig,
-      accountAllowBots,
-      configuredBotUserIds,
-      groupPolicy,
-      replyToMode,
-      threadReplies,
-      dmThreadReplies,
-      dmSessionScope,
-      streaming,
-      previewToolProgressEnabled,
-      blockStreamingEnabled,
-      dmEnabled,
-      dmPolicy,
-      textLimit,
-      mediaMaxBytes,
-      historyLimit,
-      startupMs,
-      startupGraceMs,
-      dropPreStartupMessages,
-      inboundDeduper,
-      directTracker,
-      getRoomInfo,
-      getMemberDisplayName,
-      needsRoomAliasesForConfig,
-    });
-    threadBindingManager = await createMatrixThreadBindingManager({
-      cfg,
-      accountId: effectiveAccountId,
-      auth,
-      client,
-      env: process.env,
-      idleTimeoutMs: threadBindingIdleTimeoutMs,
-      maxAgeMs: threadBindingMaxAgeMs,
-      logVerboseMessage,
-    });
-    logVerboseMessage(
-      `matrix: thread bindings ready account=${threadBindingManager.accountId} idleMs=${threadBindingIdleTimeoutMs} maxAgeMs=${threadBindingMaxAgeMs}`,
-    );
-
-    registerMatrixMonitorEvents({
-      cfg,
-      client,
-      auth,
-      allowFrom,
-      dmEnabled,
-      dmPolicy,
-      readStoreAllowFrom: async () =>
-        await core.channel.pairing
-          .readAllowFromStore({
-            channel: "matrix",
-            env: process.env,
-            accountId: effectiveAccountId,
-          })
-          .catch(() => []),
-      directTracker,
-      logVerboseMessage,
-      warnedEncryptedRooms,
-      warnedCryptoMissingRooms,
-      logger,
-      startupGraceMs,
-      getHealthySyncSinceMs: () => healthySyncSinceMs,
-      formatNativeDependencyHint: core.system.formatNativeDependencyHint,
-      onRoomMessage: handleRoomMessage,
-      runDetachedTask: monitorTaskRunner.runDetachedTask,
-    });
-
-    // Register Matrix thread bindings before the client starts syncing so threaded
-    // commands during startup never observe Matrix as "unavailable".
-    logVerboseMessage("matrix: starting client");
-    await resolveSharedMatrixClient({
-      cfg,
-      auth: authWithLimit,
-      accountId: auth.accountId,
-      abortSignal: opts.abortSignal,
-    });
-    logVerboseMessage("matrix: client started");
-
-    // Shared client is already started via resolveSharedMatrixClient.
-    logger.info(`matrix: logged in as ${auth.userId}`);
-    void backfillMatrixAuthDeviceIdAfterStartup({
-      auth,
-      env: process.env,
-      abortSignal: opts.abortSignal,
-    }).catch((err) => {
-      logVerboseMessage(`matrix: failed to backfill deviceId after startup (${String(err)})`);
-    });
-
-    registerChannelRuntimeContext({
-      channelRuntime: opts.channelRuntime,
-      channelId: "matrix",
-      accountId: effectiveAccountId,
-      capability: CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY,
-      context: {
-        client,
-      },
-      abortSignal: opts.abortSignal,
-    });
-
-    await runMatrixStartupMaintenance({
-      client,
-      auth,
-      accountId: effectiveAccountId,
-      effectiveAccountId,
-      accountConfig,
-      logger,
-      logVerboseMessage,
-      getRuntimeConfig: () => core.config.current() as CoreConfig,
-      replaceConfigFile: async (nextCfg) => {
-        await core.config.replaceConfigFile({
-          nextConfig: nextCfg,
-          afterWrite: { mode: "auto" },
-        });
-      },
-      loadWebMedia: async (url, maxBytes) => await core.media.loadWebMedia(url, maxBytes),
-      env: process.env,
-      abortSignal: opts.abortSignal,
-    });
-
-    await Promise.race([
-      waitUntilAbort(opts.abortSignal, async () => {
-        try {
-          logVerboseMessage("matrix: stopping client");
-          await cleanup();
-        } catch (err) {
-          logger.warn("matrix: failed during monitor shutdown cleanup", {
-            error: String(err),
-          });
-        }
-      }),
-      syncLifecycle.waitForFatalStop(),
-    ]);
-  } catch (err) {
-    if (opts.abortSignal?.aborted === true && isMatrixStartupAbortError(err)) {
-      await cleanup("stop");
-      return;
-    }
-    statusController.noteUnexpectedError(err);
-    await cleanup();
-    throw err;
-  }
-}
-export { testing as __testing };

package/src/matrix/monitor/legacy-crypto-restore.ts

@@ -1,139 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { readJsonFileWithFallback, writeJsonFileAtomically } from "klaw/plugin-sdk/json-store";
-import { getMatrixRuntime } from "../../runtime.js";
-import { resolveMatrixStoragePaths } from "../client/storage.js";
-import type { MatrixAuth } from "../client/types.js";
-import type { MatrixClient } from "../sdk.js";
-
-type MatrixLegacyCryptoMigrationState = {
-  version: 1;
-  accountId: string;
-  roomKeyCounts: {
-    total: number;
-    backedUp: number;
-  } | null;
-  restoreStatus: "pending" | "completed" | "manual-action-required";
-  restoredAt?: string;
-  importedCount?: number;
-  totalCount?: number;
-  lastError?: string | null;
-};
-
-export type MatrixLegacyCryptoRestoreResult =
-  | { kind: "skipped" }
-  | {
-      kind: "restored";
-      imported: number;
-      total: number;
-      localOnlyKeys: number;
-    }
-  | {
-      kind: "failed";
-      error: string;
-      localOnlyKeys: number;
-    };
-
-function isMigrationState(value: unknown): value is MatrixLegacyCryptoMigrationState {
-  return (
-    Boolean(value) && typeof value === "object" && (value as { version?: unknown }).version === 1
-  );
-}
-
-async function resolvePendingMigrationStatePath(params: {
-  stateDir: string;
-  auth: Pick<MatrixAuth, "homeserver" | "userId" | "accessToken" | "accountId" | "deviceId">;
-}): Promise<{
-  statePath: string;
-  value: MatrixLegacyCryptoMigrationState | null;
-}> {
-  const { rootDir } = resolveMatrixStoragePaths({
-    homeserver: params.auth.homeserver,
-    userId: params.auth.userId,
-    accessToken: params.auth.accessToken,
-    accountId: params.auth.accountId,
-    deviceId: params.auth.deviceId,
-    stateDir: params.stateDir,
-  });
-  const directStatePath = path.join(rootDir, "legacy-crypto-migration.json");
-  const { value: directValue } =
-    await readJsonFileWithFallback<MatrixLegacyCryptoMigrationState | null>(directStatePath, null);
-  if (isMigrationState(directValue) && directValue.restoreStatus === "pending") {
-    return { statePath: directStatePath, value: directValue };
-  }
-
-  const accountStorageDir = path.dirname(rootDir);
-  let siblingEntries: string[] = [];
-  try {
-    siblingEntries = (await fs.readdir(accountStorageDir, { withFileTypes: true }))
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-      .filter((entry) => path.join(accountStorageDir, entry) !== rootDir)
-      .toSorted((left, right) => left.localeCompare(right));
-  } catch {
-    return { statePath: directStatePath, value: directValue };
-  }
-
-  for (const sibling of siblingEntries) {
-    const siblingStatePath = path.join(accountStorageDir, sibling, "legacy-crypto-migration.json");
-    const { value } = await readJsonFileWithFallback<MatrixLegacyCryptoMigrationState | null>(
-      siblingStatePath,
-      null,
-    );
-    if (isMigrationState(value) && value.restoreStatus === "pending") {
-      return { statePath: siblingStatePath, value };
-    }
-  }
-  return { statePath: directStatePath, value: directValue };
-}
-
-export async function maybeRestoreLegacyMatrixBackup(params: {
-  client: Pick<MatrixClient, "restoreRoomKeyBackup">;
-  auth: Pick<MatrixAuth, "homeserver" | "userId" | "accessToken" | "accountId" | "deviceId">;
-  env?: NodeJS.ProcessEnv;
-  stateDir?: string;
-}): Promise<MatrixLegacyCryptoRestoreResult> {
-  const env = params.env ?? process.env;
-  const stateDir = params.stateDir ?? getMatrixRuntime().state.resolveStateDir(env, os.homedir);
-  const { statePath, value } = await resolvePendingMigrationStatePath({
-    stateDir,
-    auth: params.auth,
-  });
-  if (!isMigrationState(value) || value.restoreStatus !== "pending") {
-    return { kind: "skipped" };
-  }
-
-  const restore = await params.client.restoreRoomKeyBackup();
-  const localOnlyKeys =
-    value.roomKeyCounts && value.roomKeyCounts.total > value.roomKeyCounts.backedUp
-      ? value.roomKeyCounts.total - value.roomKeyCounts.backedUp
-      : 0;
-
-  if (restore.success) {
-    await writeJsonFileAtomically(statePath, {
-      ...value,
-      restoreStatus: "completed",
-      restoredAt: restore.restoredAt ?? new Date().toISOString(),
-      importedCount: restore.imported,
-      totalCount: restore.total,
-      lastError: null,
-    } satisfies MatrixLegacyCryptoMigrationState);
-    return {
-      kind: "restored",
-      imported: restore.imported,
-      total: restore.total,
-      localOnlyKeys,
-    };
-  }
-
-  await writeJsonFileAtomically(statePath, {
-    ...value,
-    lastError: restore.error ?? "unknown",
-  } satisfies MatrixLegacyCryptoMigrationState);
-  return {
-    kind: "failed",
-    error: restore.error ?? "unknown",
-    localOnlyKeys,
-  };
-}