@gakr-gakr/matrix 0.1.0

package/src/setup-config.ts

@@ -0,0 +1,222 @@
+import {
+  applyAccountNameToChannelSection,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeSecretInputString,
+  type ChannelSetupInput,
+} from "autobot/plugin-sdk/setup";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveMatrixEnvAuthReadiness } from "./matrix/client/env-auth.js";
+import { updateMatrixAccountConfig } from "./matrix/config-update.js";
+import { isSupportedMatrixAvatarSource } from "./matrix/profile.js";
+import {
+  matrixNamedAccountPromotionKeys,
+  resolveSingleAccountPromotionTarget,
+  matrixSingleAccountKeysToMove,
+} from "./setup-contract.js";
+import type { CoreConfig } from "./types.js";
+
+const channel = "matrix" as const;
+const COMMON_SINGLE_ACCOUNT_KEYS_TO_MOVE = new Set([
+  "name",
+  "enabled",
+  "httpPort",
+  "webhookPath",
+  "webhookUrl",
+  "webhookSecret",
+  "service",
+  "region",
+  "homeserver",
+  "userId",
+  "accessToken",
+  "password",
+  "deviceName",
+  "url",
+  "code",
+  "dmPolicy",
+  "allowFrom",
+  "groupPolicy",
+  "groupAllowFrom",
+  "defaultTo",
+]);
+const MATRIX_SINGLE_ACCOUNT_KEYS_TO_MOVE = new Set<string>(matrixSingleAccountKeysToMove);
+const MATRIX_NAMED_ACCOUNT_PROMOTION_KEYS = new Set<string>(matrixNamedAccountPromotionKeys);
+
+function cloneIfObject<T>(value: T): T {
+  if (value && typeof value === "object") {
+    return structuredClone(value);
+  }
+  return value;
+}
+
+function resolveSetupAvatarUrl(input: ChannelSetupInput): string | undefined {
+  const avatarUrl = input.avatarUrl;
+  if (typeof avatarUrl !== "string") {
+    return undefined;
+  }
+  const trimmed = avatarUrl.trim();
+  return trimmed || undefined;
+}
+
+function resolveExistingMatrixAccountKey(
+  accounts: Record<string, Record<string, unknown>>,
+  targetAccountId: string,
+): string {
+  const normalizedTargetAccountId = normalizeAccountId(targetAccountId);
+  return (
+    Object.keys(accounts).find(
+      (accountId) => normalizeAccountId(accountId) === normalizedTargetAccountId,
+    ) ?? targetAccountId
+  );
+}
+
+export function moveSingleMatrixAccountConfigToNamedAccount(cfg: CoreConfig): CoreConfig {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  const baseConfig = channels?.[channel];
+  const base =
+    typeof baseConfig === "object" && baseConfig
+      ? (baseConfig as Record<string, unknown>)
+      : undefined;
+  if (!base) {
+    return cfg;
+  }
+
+  const accounts =
+    typeof base.accounts === "object" && base.accounts
+      ? (base.accounts as Record<string, Record<string, unknown>>)
+      : {};
+  const hasNamedAccounts = Object.keys(accounts).some(Boolean);
+  const keysToMove = Object.entries(base)
+    .filter(([key, value]) => {
+      if (key === "accounts" || key === "enabled" || value === undefined) {
+        return false;
+      }
+      if (
+        !COMMON_SINGLE_ACCOUNT_KEYS_TO_MOVE.has(key) &&
+        !MATRIX_SINGLE_ACCOUNT_KEYS_TO_MOVE.has(key)
+      ) {
+        return false;
+      }
+      if (hasNamedAccounts && !MATRIX_NAMED_ACCOUNT_PROMOTION_KEYS.has(key)) {
+        return false;
+      }
+      return true;
+    })
+    .map(([key]) => key);
+  if (keysToMove.length === 0) {
+    return cfg;
+  }
+
+  const targetAccountId = resolveSingleAccountPromotionTarget({ channel: base });
+  const resolvedTargetAccountId = resolveExistingMatrixAccountKey(accounts, targetAccountId);
+
+  const nextAccount: Record<string, unknown> = { ...accounts[resolvedTargetAccountId] };
+  for (const key of keysToMove) {
+    nextAccount[key] = cloneIfObject(base[key]);
+  }
+  const nextChannel = { ...base };
+  for (const key of keysToMove) {
+    delete nextChannel[key];
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      [channel]: {
+        ...nextChannel,
+        accounts: {
+          ...accounts,
+          [resolvedTargetAccountId]: nextAccount,
+        },
+      },
+    },
+  };
+}
+
+export function validateMatrixSetupInput(params: {
+  accountId: string;
+  input: ChannelSetupInput;
+}): string | null {
+  const avatarUrl = resolveSetupAvatarUrl(params.input);
+  if (avatarUrl && !isSupportedMatrixAvatarSource(avatarUrl)) {
+    return "Matrix avatar URL must be an mxc:// URI or an http(s) URL.";
+  }
+  if (params.input.useEnv) {
+    const envReadiness = resolveMatrixEnvAuthReadiness(params.accountId, process.env);
+    return envReadiness.ready ? null : envReadiness.missingMessage;
+  }
+  if (!params.input.homeserver?.trim()) {
+    return "Matrix requires --homeserver";
+  }
+  const accessToken = params.input.accessToken?.trim();
+  const password = normalizeSecretInputString(params.input.password);
+  const userId = params.input.userId?.trim();
+  if (!accessToken && !password) {
+    return "Matrix requires --access-token or --password";
+  }
+  if (!accessToken) {
+    if (!userId) {
+      return "Matrix requires --user-id when using --password";
+    }
+    if (!password) {
+      return "Matrix requires --password when using --user-id";
+    }
+  }
+  return null;
+}
+
+export function applyMatrixSetupAccountConfig(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  input: ChannelSetupInput;
+}): CoreConfig {
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const migratedCfg =
+    normalizedAccountId !== DEFAULT_ACCOUNT_ID
+      ? moveSingleMatrixAccountConfigToNamedAccount(params.cfg)
+      : params.cfg;
+  const next = applyAccountNameToChannelSection({
+    cfg: migratedCfg,
+    channelKey: channel,
+    accountId: normalizedAccountId,
+    name: params.input.name,
+  }) as CoreConfig;
+  const avatarUrl = resolveSetupAvatarUrl(params.input);
+
+  if (params.input.useEnv) {
+    return updateMatrixAccountConfig(next, normalizedAccountId, {
+      enabled: true,
+      homeserver: null,
+      allowPrivateNetwork: null,
+      proxy: null,
+      userId: null,
+      accessToken: null,
+      password: null,
+      deviceId: null,
+      deviceName: null,
+      avatarUrl,
+    });
+  }
+
+  const accessToken = params.input.accessToken?.trim();
+  const password = normalizeSecretInputString(params.input.password);
+  const userId = params.input.userId?.trim();
+  return updateMatrixAccountConfig(next, normalizedAccountId, {
+    enabled: true,
+    homeserver: params.input.homeserver?.trim(),
+    allowPrivateNetwork:
+      typeof params.input.dangerouslyAllowPrivateNetwork === "boolean"
+        ? params.input.dangerouslyAllowPrivateNetwork
+        : typeof params.input.allowPrivateNetwork === "boolean"
+          ? params.input.allowPrivateNetwork
+          : undefined,
+    proxy: normalizeOptionalString(params.input.proxy),
+    userId: password && !userId ? null : userId,
+    accessToken: accessToken || (password ? null : undefined),
+    password: password || (accessToken ? null : undefined),
+    deviceName: params.input.deviceName?.trim(),
+    avatarUrl,
+    initialSyncLimit: params.input.initialSyncLimit,
+  });
+}

package/src/setup-contract.ts

@@ -0,0 +1,90 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/routing";
+
+export const matrixSingleAccountKeysToMove = [
+  "deviceId",
+  "avatarUrl",
+  "initialSyncLimit",
+  "encryption",
+  "allowlistOnly",
+  "dangerouslyAllowNameMatching",
+  "allowBots",
+  "blockStreaming",
+  "replyToMode",
+  "threadReplies",
+  "textChunkLimit",
+  "chunkMode",
+  "responsePrefix",
+  "ackReaction",
+  "ackReactionScope",
+  "reactionNotifications",
+  "threadBindings",
+  "startupVerification",
+  "startupVerificationCooldownHours",
+  "mediaMaxMb",
+  "autoJoin",
+  "autoJoinAllowlist",
+  "dm",
+  "groups",
+  "rooms",
+  "actions",
+] as const;
+
+export const matrixNamedAccountPromotionKeys = [
+  // When named accounts already exist, only move auth/bootstrap fields into the
+  // promoted account. Shared delivery-policy fields stay at the top level.
+  "name",
+  "homeserver",
+  "userId",
+  "accessToken",
+  "password",
+  "deviceId",
+  "deviceName",
+  "avatarUrl",
+  "initialSyncLimit",
+  "encryption",
+] as const;
+
+export const singleAccountKeysToMove = [...matrixSingleAccountKeysToMove];
+export const namedAccountPromotionKeys = [...matrixNamedAccountPromotionKeys];
+
+export function resolveSingleAccountPromotionTarget(params: {
+  channel: Record<string, unknown>;
+}): string {
+  const accounts =
+    typeof params.channel.accounts === "object" && params.channel.accounts
+      ? (params.channel.accounts as Record<string, unknown>)
+      : {};
+  const normalizedDefaultAccount =
+    typeof params.channel.defaultAccount === "string" && params.channel.defaultAccount.trim()
+      ? normalizeAccountId(params.channel.defaultAccount)
+      : undefined;
+  const matchedAccountId = normalizedDefaultAccount
+    ? Object.entries(accounts).find(
+        ([accountId, value]) =>
+          accountId &&
+          value &&
+          typeof value === "object" &&
+          normalizeAccountId(accountId) === normalizedDefaultAccount,
+      )?.[0]
+    : undefined;
+  if (matchedAccountId) {
+    return matchedAccountId;
+  }
+  if (normalizedDefaultAccount) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  const namedAccounts = Object.entries(accounts).filter(
+    ([accountId, value]) => accountId && typeof value === "object" && value,
+  );
+  if (namedAccounts.length === 1) {
+    return namedAccounts[0][0];
+  }
+  if (
+    namedAccounts.length > 1 &&
+    accounts[DEFAULT_ACCOUNT_ID] &&
+    typeof accounts[DEFAULT_ACCOUNT_ID] === "object"
+  ) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return DEFAULT_ACCOUNT_ID;
+}

package/src/setup-core.ts

@@ -0,0 +1,146 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  DEFAULT_ACCOUNT_ID,
+  type DmPolicy,
+  normalizeAccountId,
+  prepareScopedSetupConfig,
+  type ChannelSetupAdapter,
+  type ChannelSetupWizardAdapter,
+} from "autobot/plugin-sdk/setup";
+import { resolveDefaultMatrixAccountId, resolveMatrixAccountConfig } from "./matrix/accounts.js";
+import { resolveMatrixConfigFieldPath, updateMatrixAccountConfig } from "./matrix/config-update.js";
+import { applyMatrixSetupAccountConfig, validateMatrixSetupInput } from "./setup-config.js";
+import { resolveMatrixSetupDmAllowFrom } from "./setup-dm-policy.js";
+import type { CoreConfig } from "./types.js";
+
+const channel = "matrix" as const;
+type MatrixSetupWizardModule = { matrixSetupWizard: ChannelSetupWizardAdapter };
+
+function resolveMatrixSetupAccountId(params: { accountId?: string; name?: string }): string {
+  return normalizeAccountId(params.accountId?.trim() || params.name?.trim() || DEFAULT_ACCOUNT_ID);
+}
+
+function resolveMatrixSetupWizardAccountId(cfg: CoreConfig, accountId?: string): string {
+  return normalizeAccountId(
+    accountId?.trim() || resolveDefaultMatrixAccountId(cfg) || DEFAULT_ACCOUNT_ID,
+  );
+}
+
+function setMatrixDmPolicy(cfg: CoreConfig, policy: DmPolicy, accountId?: string): CoreConfig {
+  const resolvedAccountId = resolveMatrixSetupWizardAccountId(cfg, accountId);
+  const existing = resolveMatrixAccountConfig({
+    cfg,
+    accountId: resolvedAccountId,
+  });
+  const allowFrom = resolveMatrixSetupDmAllowFrom(policy, existing.dm?.allowFrom);
+  return updateMatrixAccountConfig(cfg, resolvedAccountId, {
+    dm: {
+      ...existing.dm,
+      policy,
+      allowFrom,
+    },
+  });
+}
+
+export function createMatrixSetupWizardProxy(
+  loadWizardModule: () => Promise<MatrixSetupWizardModule>,
+): ChannelSetupWizardAdapter {
+  let wizardPromise: Promise<ChannelSetupWizardAdapter> | null = null;
+  const loadWizard = () => {
+    wizardPromise ??= loadWizardModule().then((module) => module.matrixSetupWizard);
+    return wizardPromise;
+  };
+  return {
+    channel,
+    getStatus: async (ctx) => await (await loadWizard()).getStatus(ctx),
+    configure: async (ctx) => await (await loadWizard()).configure(ctx),
+    configureInteractive: async (ctx) => {
+      const wizard = await loadWizard();
+      return await (wizard.configureInteractive ?? wizard.configure)(ctx);
+    },
+    configureWhenConfigured: async (ctx) => {
+      const wizard = await loadWizard();
+      return await (
+        wizard.configureWhenConfigured ??
+        wizard.configureInteractive ??
+        wizard.configure
+      )(ctx);
+    },
+    afterConfigWritten: async (ctx) => await (await loadWizard()).afterConfigWritten?.(ctx),
+    dmPolicy: {
+      label: "Matrix",
+      channel,
+      policyKey: "channels.matrix.dm.policy",
+      allowFromKey: "channels.matrix.dm.allowFrom",
+      resolveConfigKeys: (cfg, accountId) => {
+        const resolvedAccountId = resolveMatrixSetupWizardAccountId(cfg as CoreConfig, accountId);
+        return {
+          policyKey: resolveMatrixConfigFieldPath(
+            cfg as CoreConfig,
+            resolvedAccountId,
+            "dm.policy",
+          ),
+          allowFromKey: resolveMatrixConfigFieldPath(
+            cfg as CoreConfig,
+            resolvedAccountId,
+            "dm.allowFrom",
+          ),
+        };
+      },
+      getCurrent: (cfg, accountId) =>
+        resolveMatrixAccountConfig({
+          cfg: cfg as CoreConfig,
+          accountId: resolveMatrixSetupWizardAccountId(cfg as CoreConfig, accountId),
+        }).dm?.policy ?? "pairing",
+      setPolicy: (cfg, policy, accountId) =>
+        setMatrixDmPolicy(cfg as CoreConfig, policy, accountId) as AutoBotConfig,
+      promptAllowFrom: async (params) => {
+        const promptAllowFrom = (await loadWizard()).dmPolicy?.promptAllowFrom;
+        return promptAllowFrom ? await promptAllowFrom(params) : params.cfg;
+      },
+    },
+    disable: (cfg) => ({
+      ...(cfg as CoreConfig),
+      channels: {
+        ...(cfg as CoreConfig).channels,
+        matrix: { ...(cfg as CoreConfig).channels?.matrix, enabled: false },
+      },
+    }),
+  };
+}
+
+export const matrixSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ accountId, input }) =>
+    resolveMatrixSetupAccountId({
+      accountId,
+      name: input?.name,
+    }),
+  resolveBindingAccountId: ({ accountId, agentId }) =>
+    resolveMatrixSetupAccountId({
+      accountId,
+      name: agentId,
+    }),
+  applyAccountName: ({ cfg, accountId, name }) =>
+    prepareScopedSetupConfig({
+      cfg: cfg as CoreConfig,
+      channelKey: channel,
+      accountId,
+      name,
+    }) as CoreConfig,
+  validateInput: ({ accountId, input }) => validateMatrixSetupInput({ accountId, input }),
+  applyAccountConfig: ({ cfg, accountId, input }) =>
+    applyMatrixSetupAccountConfig({
+      cfg: cfg as CoreConfig,
+      accountId,
+      input,
+    }),
+  afterAccountConfigWritten: async ({ previousCfg, cfg, accountId, runtime }) => {
+    const { runMatrixSetupBootstrapAfterConfigWrite } = await import("./setup-bootstrap.js");
+    await runMatrixSetupBootstrapAfterConfigWrite({
+      previousCfg: previousCfg as CoreConfig,
+      cfg: cfg as CoreConfig,
+      accountId,
+      runtime,
+    });
+  },
+};

package/src/setup-dm-policy.ts

@@ -0,0 +1,15 @@
+import type { DmPolicy } from "autobot/plugin-sdk/config-contracts";
+import { addWildcardAllowFrom, normalizeAllowFromEntries } from "autobot/plugin-sdk/setup";
+import type { MatrixConfig } from "./types.js";
+
+type MatrixDmAllowFrom = NonNullable<MatrixConfig["dm"]>["allowFrom"];
+
+export function resolveMatrixSetupDmAllowFrom(
+  policy: DmPolicy,
+  allowFrom: MatrixDmAllowFrom,
+): string[] {
+  if (policy === "open") {
+    return addWildcardAllowFrom(allowFrom);
+  }
+  return normalizeAllowFromEntries(allowFrom ?? []).filter((entry) => entry !== "*");
+}

package/src/setup-surface.ts

@@ -0,0 +1,4 @@
+export {
+  matrixOnboardingAdapter,
+  matrixOnboardingAdapter as matrixSetupWizard,
+} from "./onboarding.js";

package/src/startup-maintenance.ts

@@ -0,0 +1,114 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  autoMigrateLegacyMatrixState,
+  autoPrepareLegacyMatrixCrypto,
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationStatus,
+  type MatrixMigrationStatus,
+} from "./matrix-migration.runtime.js";
+
+type MatrixStartupLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+function logWarningOnlyMatrixMigrationReasons(params: {
+  status: MatrixMigrationStatus;
+  log: MatrixStartupLogger;
+}): void {
+  if (params.status.legacyState && "warning" in params.status.legacyState) {
+    params.log.warn?.(`matrix: ${params.status.legacyState.warning}`);
+  }
+
+  if (params.status.legacyCrypto.warnings.length > 0) {
+    params.log.warn?.(
+      `matrix: legacy encrypted-state warnings:\n${params.status.legacyCrypto.warnings.map((entry) => `- ${entry}`).join("\n")}`,
+    );
+  }
+}
+
+async function runBestEffortMatrixMigrationStep(params: {
+  label: string;
+  log: MatrixStartupLogger;
+  logPrefix?: string;
+  run: () => Promise<unknown>;
+}): Promise<void> {
+  try {
+    await params.run();
+  } catch (err) {
+    params.log.warn?.(
+      `${params.logPrefix?.trim() || "gateway"}: ${params.label} failed during Matrix migration; continuing startup: ${String(err)}`,
+    );
+  }
+}
+
+export async function runMatrixStartupMaintenance(params: {
+  cfg: AutoBotConfig;
+  env?: NodeJS.ProcessEnv;
+  log: MatrixStartupLogger;
+  trigger?: string;
+  logPrefix?: string;
+  deps?: {
+    maybeCreateMatrixMigrationSnapshot?: typeof maybeCreateMatrixMigrationSnapshot;
+    autoMigrateLegacyMatrixState?: typeof autoMigrateLegacyMatrixState;
+    autoPrepareLegacyMatrixCrypto?: typeof autoPrepareLegacyMatrixCrypto;
+  };
+}): Promise<void> {
+  const env = params.env ?? process.env;
+  const createSnapshot =
+    params.deps?.maybeCreateMatrixMigrationSnapshot ?? maybeCreateMatrixMigrationSnapshot;
+  const migrateLegacyState =
+    params.deps?.autoMigrateLegacyMatrixState ?? autoMigrateLegacyMatrixState;
+  const prepareLegacyCrypto =
+    params.deps?.autoPrepareLegacyMatrixCrypto ?? autoPrepareLegacyMatrixCrypto;
+  const trigger = params.trigger?.trim() || "gateway-startup";
+  const logPrefix = params.logPrefix?.trim() || "gateway";
+  const migrationStatus = resolveMatrixMigrationStatus({ cfg: params.cfg, env });
+
+  if (!migrationStatus.pending) {
+    return;
+  }
+  if (!migrationStatus.actionable) {
+    params.log.info?.(
+      "matrix: migration remains in a warning-only state; no pre-migration snapshot was needed yet",
+    );
+    logWarningOnlyMatrixMigrationReasons({ status: migrationStatus, log: params.log });
+    return;
+  }
+
+  try {
+    await createSnapshot({
+      trigger,
+      env,
+      log: params.log,
+    });
+  } catch (err) {
+    params.log.warn?.(
+      `${logPrefix}: failed creating a Matrix migration snapshot; skipping Matrix migration for now: ${String(err)}`,
+    );
+    return;
+  }
+
+  await runBestEffortMatrixMigrationStep({
+    label: "legacy Matrix state migration",
+    log: params.log,
+    logPrefix,
+    run: () =>
+      migrateLegacyState({
+        cfg: params.cfg,
+        env,
+        log: params.log,
+      }),
+  });
+  await runBestEffortMatrixMigrationStep({
+    label: "legacy Matrix encrypted-state preparation",
+    log: params.log,
+    logPrefix,
+    run: () =>
+      prepareLegacyCrypto({
+        cfg: params.cfg,
+        env,
+        log: params.log,
+      }),
+  });
+}

package/src/storage-paths.ts

@@ -0,0 +1,92 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+export function sanitizeMatrixPathSegment(value: string): string {
+  const cleaned = normalizeLowercaseStringOrEmpty(value)
+    .replace(/[^a-z0-9._-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return cleaned || "unknown";
+}
+
+export function resolveMatrixHomeserverKey(homeserver: string): string {
+  try {
+    const url = new URL(homeserver);
+    if (url.host) {
+      return sanitizeMatrixPathSegment(url.host);
+    }
+  } catch {
+    // fall through
+  }
+  return sanitizeMatrixPathSegment(homeserver);
+}
+
+export function hashMatrixAccessToken(accessToken: string): string {
+  return crypto.createHash("sha256").update(accessToken).digest("hex").slice(0, 16);
+}
+
+export function resolveMatrixCredentialsFilename(accountId?: string | null): string {
+  const normalized = normalizeAccountId(accountId);
+  return normalized === DEFAULT_ACCOUNT_ID ? "credentials.json" : `credentials-${normalized}.json`;
+}
+
+export function resolveMatrixCredentialsDir(stateDir: string): string {
+  return path.join(stateDir, "credentials", "matrix");
+}
+
+export function resolveMatrixCredentialsPath(params: {
+  stateDir: string;
+  accountId?: string | null;
+}): string {
+  return path.join(
+    resolveMatrixCredentialsDir(params.stateDir),
+    resolveMatrixCredentialsFilename(params.accountId),
+  );
+}
+
+export function resolveMatrixLegacyFlatStoreRoot(stateDir: string): string {
+  return path.join(stateDir, "matrix");
+}
+
+export function resolveMatrixLegacyFlatStoragePaths(stateDir: string): {
+  rootDir: string;
+  storagePath: string;
+  cryptoPath: string;
+} {
+  const rootDir = resolveMatrixLegacyFlatStoreRoot(stateDir);
+  return {
+    rootDir,
+    storagePath: path.join(rootDir, "bot-storage.json"),
+    cryptoPath: path.join(rootDir, "crypto"),
+  };
+}
+
+export function resolveMatrixAccountStorageRoot(params: {
+  stateDir: string;
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  accountId?: string | null;
+}): {
+  rootDir: string;
+  accountKey: string;
+  tokenHash: string;
+} {
+  const accountKey = sanitizeMatrixPathSegment(params.accountId ?? DEFAULT_ACCOUNT_ID);
+  const userKey = sanitizeMatrixPathSegment(params.userId);
+  const serverKey = resolveMatrixHomeserverKey(params.homeserver);
+  const tokenHash = hashMatrixAccessToken(params.accessToken);
+  return {
+    rootDir: path.join(
+      params.stateDir,
+      "matrix",
+      "accounts",
+      accountKey,
+      `${serverKey}__${userKey}`,
+      tokenHash,
+    ),
+    accountKey,
+    tokenHash,
+  };
+}