@archipelagolab/lobi 1.0.0

package/src/migration-config.test.ts

@@ -0,0 +1,228 @@
+import path from "node:path";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
+import { describe, expect, it } from "vitest";
+import { withTempHome } from "../../../test/helpers/temp-home.js";
+import { resolveMatrixMigrationAccountTarget } from "./migration-config.js";
+import {
+  LOBI_OPS_ACCESS_TOKEN,
+  MATRIX_OPS_ACCOUNT_ID,
+  MATRIX_OPS_USER_ID,
+  MATRIX_TEST_HOMESERVER,
+  writeMatrixCredentials,
+} from "./test-helpers.js";
+
+function resolveOpsTarget(cfg: OpenClawConfig, env = process.env) {
+  return resolveMatrixMigrationAccountTarget({
+    cfg,
+    env,
+    accountId: MATRIX_OPS_ACCOUNT_ID,
+  });
+}
+
+describe("resolveMatrixMigrationAccountTarget", () => {
+  it("reuses stored user identity for token-only configs when the access token matches", async () => {
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      writeMatrixCredentials(stateDir, {
+        accountId: MATRIX_OPS_ACCOUNT_ID,
+        deviceId: "DEVICE-OPS",
+        accessToken: LOBI_OPS_ACCESS_TOKEN,
+      });
+
+      const cfg: OpenClawConfig = {
+        channels: {
+          matrix: {
+            accounts: {
+              ops: {
+                homeserver: MATRIX_TEST_HOMESERVER,
+                accessToken: LOBI_OPS_ACCESS_TOKEN,
+              },
+            },
+          },
+        },
+      };
+
+      const target = resolveOpsTarget(cfg);
+
+      expect(target).not.toBeNull();
+      expect(target?.userId).toBe(MATRIX_OPS_USER_ID);
+      expect(target?.storedDeviceId).toBe("DEVICE-OPS");
+    });
+  });
+
+  it("ignores stored device IDs from stale cached Matrix credentials", async () => {
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      writeMatrixCredentials(stateDir, {
+        accountId: MATRIX_OPS_ACCOUNT_ID,
+        userId: "@old-bot:example.org",
+        accessToken: "tok-old",
+        deviceId: "DEVICE-OLD",
+      });
+
+      const cfg: OpenClawConfig = {
+        channels: {
+          matrix: {
+            accounts: {
+              ops: {
+                homeserver: MATRIX_TEST_HOMESERVER,
+                userId: "@new-bot:example.org",
+                accessToken: "tok-new",
+              },
+            },
+          },
+        },
+      };
+
+      const target = resolveOpsTarget(cfg);
+
+      expect(target).not.toBeNull();
+      expect(target?.userId).toBe("@new-bot:example.org");
+      expect(target?.accessToken).toBe("tok-new");
+      expect(target?.storedDeviceId).toBeNull();
+    });
+  });
+
+  it("does not trust stale stored creds on the same homeserver when the token changes", async () => {
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      writeMatrixCredentials(stateDir, {
+        accountId: MATRIX_OPS_ACCOUNT_ID,
+        userId: "@old-bot:example.org",
+        accessToken: "tok-old",
+        deviceId: "DEVICE-OLD",
+      });
+
+      const cfg: OpenClawConfig = {
+        channels: {
+          matrix: {
+            accounts: {
+              ops: {
+                homeserver: MATRIX_TEST_HOMESERVER,
+                accessToken: "tok-new",
+              },
+            },
+          },
+        },
+      };
+
+      const target = resolveOpsTarget(cfg);
+
+      expect(target).toBeNull();
+    });
+  });
+
+  it("does not inherit the base userId for non-default token-only accounts", async () => {
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      writeMatrixCredentials(stateDir, {
+        accountId: MATRIX_OPS_ACCOUNT_ID,
+        deviceId: "DEVICE-OPS",
+        accessToken: LOBI_OPS_ACCESS_TOKEN,
+      });
+
+      const cfg: OpenClawConfig = {
+        channels: {
+          matrix: {
+            homeserver: MATRIX_TEST_HOMESERVER,
+            userId: "@base-bot:example.org",
+            accounts: {
+              ops: {
+                homeserver: MATRIX_TEST_HOMESERVER,
+                accessToken: LOBI_OPS_ACCESS_TOKEN,
+              },
+            },
+          },
+        },
+      };
+
+      const target = resolveOpsTarget(cfg);
+
+      expect(target).not.toBeNull();
+      expect(target?.userId).toBe(MATRIX_OPS_USER_ID);
+      expect(target?.storedDeviceId).toBe("DEVICE-OPS");
+    });
+  });
+
+  it("does not inherit the base access token for non-default accounts", async () => {
+    await withTempHome(async () => {
+      const cfg: OpenClawConfig = {
+        channels: {
+          matrix: {
+            homeserver: MATRIX_TEST_HOMESERVER,
+            userId: "@base-bot:example.org",
+            accessToken: "tok-base",
+            accounts: {
+              ops: {
+                homeserver: MATRIX_TEST_HOMESERVER,
+                userId: MATRIX_OPS_USER_ID,
+              },
+            },
+          },
+        },
+      };
+
+      const target = resolveOpsTarget(cfg);
+
+      expect(target).toBeNull();
+    });
+  });
+
+  it("does not inherit the global Matrix access token for non-default accounts", async () => {
+    await withTempHome(
+      async () => {
+        const cfg: OpenClawConfig = {
+          channels: {
+            matrix: {
+              accounts: {
+                ops: {
+                  homeserver: MATRIX_TEST_HOMESERVER,
+                  userId: MATRIX_OPS_USER_ID,
+                },
+              },
+            },
+          },
+        };
+
+        const target = resolveOpsTarget(cfg);
+
+        expect(target).toBeNull();
+      },
+      {
+        env: {
+          LOBI_ACCESS_TOKEN: "tok-global",
+        },
+      },
+    );
+  });
+
+  it("uses the same scoped env token encoding as runtime account auth", async () => {
+    await withTempHome(async () => {
+      const cfg: OpenClawConfig = {
+        channels: {
+          matrix: {
+            accounts: {
+              "ops-prod": {},
+            },
+          },
+        },
+      };
+      const env = {
+        MATRIX_OPS_X2D_PROD_HOMESERVER: "https://matrix.example.org",
+        MATRIX_OPS_X2D_PROD_USER_ID: "@ops-prod:example.org",
+        MATRIX_OPS_X2D_PROD_ACCESS_TOKEN: "tok-ops-prod",
+      } as NodeJS.ProcessEnv;
+
+      const target = resolveMatrixMigrationAccountTarget({
+        cfg,
+        env,
+        accountId: "ops-prod",
+      });
+
+      expect(target).not.toBeNull();
+      expect(target?.homeserver).toBe("https://matrix.example.org");
+      expect(target?.userId).toBe("@ops-prod:example.org");
+      expect(target?.accessToken).toBe("tok-ops-prod");
+    });
+  });
+});

package/src/migration-config.ts

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import os from "node:os";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import {
+  findMatrixAccountEntry,
+  requiresExplicitMatrixDefaultAccount,
+  resolveConfiguredMatrixAccountIds,
+  resolveMatrixChannelConfig,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "./account-selection.js";
+import { resolveMatrixAccountStringValues } from "./auth-precedence.js";
+import {
+  resolveGlobalMatrixEnvConfig,
+  resolveScopedMatrixEnvConfig,
+} from "./matrix/client/env-auth.js";
+import { resolveMatrixAccountStorageRoot, resolveMatrixCredentialsPath } from "./storage-paths.js";
+
+export type MatrixStoredCredentials = {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  deviceId?: string;
+};
+
+export type MatrixMigrationAccountTarget = {
+  accountId: string;
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  rootDir: string;
+  storedDeviceId: string | null;
+};
+
+export type MatrixLegacyFlatStoreTarget = MatrixMigrationAccountTarget & {
+  selectionNote?: string;
+};
+
+type MatrixLegacyFlatStoreKind = "state" | "encrypted state";
+
+function clean(value: unknown): string {
+  return normalizeOptionalString(value) ?? "";
+}
+
+function resolveMatrixAccountConfigEntry(
+  cfg: OpenClawConfig,
+  accountId: string,
+): Record<string, unknown> | null {
+  return findMatrixAccountEntry(cfg, accountId);
+}
+
+function resolveMatrixFlatStoreSelectionNote(
+  cfg: OpenClawConfig,
+  accountId: string,
+): string | undefined {
+  if (resolveConfiguredMatrixAccountIds(cfg).length <= 1) {
+    return undefined;
+  }
+  return (
+    `Legacy Matrix flat store uses one shared on-disk state, so it will be migrated into ` +
+    `account "${accountId}".`
+  );
+}
+
+export function resolveMatrixMigrationConfigFields(params: {
+  cfg: OpenClawConfig;
+  env: NodeJS.ProcessEnv;
+  accountId: string;
+}): {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+} {
+  const channel = resolveMatrixChannelConfig(params.cfg);
+  const account = resolveMatrixAccountConfigEntry(params.cfg, params.accountId);
+  const scopedEnv = resolveScopedMatrixEnvConfig(params.accountId, params.env);
+  const globalEnv = resolveGlobalMatrixEnvConfig(params.env);
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const resolvedStrings = resolveMatrixAccountStringValues({
+    accountId: normalizedAccountId,
+    account: {
+      homeserver: clean(account?.homeserver),
+      userId: clean(account?.userId),
+      accessToken: clean(account?.accessToken),
+    },
+    scopedEnv,
+    channel: {
+      homeserver: clean(channel?.homeserver),
+      userId: clean(channel?.userId),
+      accessToken: clean(channel?.accessToken),
+    },
+    globalEnv,
+  });
+
+  return {
+    homeserver: resolvedStrings.homeserver,
+    userId: resolvedStrings.userId,
+    accessToken: resolvedStrings.accessToken,
+  };
+}
+
+export function loadStoredMatrixCredentials(
+  env: NodeJS.ProcessEnv,
+  accountId: string,
+): MatrixStoredCredentials | null {
+  const stateDir = resolveStateDir(env, os.homedir);
+  const credentialsPath = resolveMatrixCredentialsPath({
+    stateDir,
+    accountId: normalizeAccountId(accountId),
+  });
+  try {
+    if (!fs.existsSync(credentialsPath)) {
+      return null;
+    }
+    const parsed = JSON.parse(
+      fs.readFileSync(credentialsPath, "utf8"),
+    ) as Partial<MatrixStoredCredentials>;
+    if (
+      typeof parsed.homeserver !== "string" ||
+      typeof parsed.userId !== "string" ||
+      typeof parsed.accessToken !== "string"
+    ) {
+      return null;
+    }
+    return {
+      homeserver: parsed.homeserver,
+      userId: parsed.userId,
+      accessToken: parsed.accessToken,
+      deviceId: typeof parsed.deviceId === "string" ? parsed.deviceId : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function credentialsMatchResolvedIdentity(
+  stored: MatrixStoredCredentials | null,
+  identity: {
+    homeserver: string;
+    userId: string;
+    accessToken: string;
+  },
+): stored is MatrixStoredCredentials {
+  if (!stored || !identity.homeserver) {
+    return false;
+  }
+  if (!identity.userId) {
+    if (!identity.accessToken) {
+      return false;
+    }
+    return stored.homeserver === identity.homeserver && stored.accessToken === identity.accessToken;
+  }
+  return stored.homeserver === identity.homeserver && stored.userId === identity.userId;
+}
+
+export function resolveMatrixMigrationAccountTarget(params: {
+  cfg: OpenClawConfig;
+  env: NodeJS.ProcessEnv;
+  accountId: string;
+}): MatrixMigrationAccountTarget | null {
+  const stored = loadStoredMatrixCredentials(params.env, params.accountId);
+  const resolved = resolveMatrixMigrationConfigFields(params);
+  const matchingStored = credentialsMatchResolvedIdentity(stored, {
+    homeserver: resolved.homeserver,
+    userId: resolved.userId,
+    accessToken: resolved.accessToken,
+  })
+    ? stored
+    : null;
+  const homeserver = resolved.homeserver;
+  const userId = resolved.userId || matchingStored?.userId || "";
+  const accessToken = resolved.accessToken || matchingStored?.accessToken || "";
+  if (!homeserver || !userId || !accessToken) {
+    return null;
+  }
+
+  const stateDir = resolveStateDir(params.env, os.homedir);
+  const { rootDir } = resolveMatrixAccountStorageRoot({
+    stateDir,
+    homeserver,
+    userId,
+    accessToken,
+    accountId: params.accountId,
+  });
+
+  return {
+    accountId: params.accountId,
+    homeserver,
+    userId,
+    accessToken,
+    rootDir,
+    storedDeviceId: matchingStored?.deviceId ?? null,
+  };
+}
+
+export function resolveLegacyMatrixFlatStoreTarget(params: {
+  cfg: OpenClawConfig;
+  env: NodeJS.ProcessEnv;
+  detectedPath: string;
+  detectedKind: MatrixLegacyFlatStoreKind;
+}): MatrixLegacyFlatStoreTarget | { warning: string } {
+  const channel = resolveMatrixChannelConfig(params.cfg);
+  if (!channel) {
+    return {
+      warning:
+        `Legacy Matrix ${params.detectedKind} detected at ${params.detectedPath}, but channels.lobi is not configured yet. ` +
+        'Configure Matrix, then rerun "openclaw doctor --fix" or restart the gateway.',
+    };
+  }
+  if (requiresExplicitMatrixDefaultAccount(params.cfg)) {
+    return {
+      warning:
+        `Legacy Matrix ${params.detectedKind} detected at ${params.detectedPath}, but multiple Matrix accounts are configured and channels.lobi.defaultAccount is not set. ` +
+        'Set "channels.lobi.defaultAccount" to the intended target account before rerunning "openclaw doctor --fix" or restarting the gateway.',
+    };
+  }
+
+  const accountId = resolveMatrixDefaultOrOnlyAccountId(params.cfg);
+  const target = resolveMatrixMigrationAccountTarget({
+    cfg: params.cfg,
+    env: params.env,
+    accountId,
+  });
+  if (!target) {
+    const targetDescription =
+      params.detectedKind === "state"
+        ? "the new account-scoped target"
+        : "the account-scoped target";
+    return {
+      warning:
+        `Legacy Matrix ${params.detectedKind} detected at ${params.detectedPath}, but ${targetDescription} could not be resolved yet ` +
+        `(need homeserver, userId, and access token for channels.lobi${accountId === DEFAULT_ACCOUNT_ID ? "" : `.accounts.${accountId}`}). ` +
+        'Start the gateway once with a working Matrix login, or rerun "openclaw doctor --fix" after cached credentials are available.',
+    };
+  }
+
+  return {
+    ...target,
+    selectionNote: resolveMatrixFlatStoreSelectionNote(params.cfg, accountId),
+  };
+}

package/src/migration-snapshot-backup.ts

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
+import { resolveRequiredHomeDir } from "openclaw/plugin-sdk/provider-auth";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+
+const MATRIX_MIGRATION_SNAPSHOT_DIRNAME = "openclaw-migrations";
+
+type MatrixMigrationSnapshotMarker = {
+  version: 1;
+  createdAt: string;
+  archivePath: string;
+  trigger: string;
+  includeWorkspace: boolean;
+};
+
+export type MatrixMigrationSnapshotResult = {
+  created: boolean;
+  archivePath: string;
+  markerPath: string;
+};
+
+function loadSnapshotMarker(filePath: string): MatrixMigrationSnapshotMarker | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const parsed = JSON.parse(
+      fs.readFileSync(filePath, "utf8"),
+    ) as Partial<MatrixMigrationSnapshotMarker>;
+    if (
+      parsed.version !== 1 ||
+      typeof parsed.createdAt !== "string" ||
+      typeof parsed.archivePath !== "string" ||
+      typeof parsed.trigger !== "string"
+    ) {
+      return null;
+    }
+    return {
+      version: 1,
+      createdAt: parsed.createdAt,
+      archivePath: parsed.archivePath,
+      trigger: parsed.trigger,
+      includeWorkspace: parsed.includeWorkspace === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function resolveMatrixMigrationSnapshotMarkerPath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const stateDir = resolveStateDir(env, os.homedir);
+  return path.join(stateDir, "matrix", "migration-snapshot.json");
+}
+
+export function resolveMatrixMigrationSnapshotOutputDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const homeDir = resolveRequiredHomeDir(env, os.homedir);
+  return path.join(homeDir, "Backups", MATRIX_MIGRATION_SNAPSHOT_DIRNAME);
+}
+
+export async function maybeCreateMatrixMigrationSnapshot(params: {
+  trigger: string;
+  env?: NodeJS.ProcessEnv;
+  outputDir?: string;
+  createBackupArchive?: typeof import("openclaw/plugin-sdk/runtime").createBackupArchive;
+  log?: { info?: (message: string) => void; warn?: (message: string) => void };
+}): Promise<MatrixMigrationSnapshotResult> {
+  const env = params.env ?? process.env;
+  const createBackupArchive =
+    params.createBackupArchive ?? (await import("openclaw/plugin-sdk/runtime")).createBackupArchive;
+  const markerPath = resolveMatrixMigrationSnapshotMarkerPath(env);
+  const existingMarker = loadSnapshotMarker(markerPath);
+  if (existingMarker?.archivePath && fs.existsSync(existingMarker.archivePath)) {
+    params.log?.info?.(
+      `matrix: reusing existing pre-migration backup snapshot: ${existingMarker.archivePath}`,
+    );
+    return {
+      created: false,
+      archivePath: existingMarker.archivePath,
+      markerPath,
+    };
+  }
+  if (existingMarker?.archivePath && !fs.existsSync(existingMarker.archivePath)) {
+    params.log?.warn?.(
+      `matrix: previous migration snapshot is missing (${existingMarker.archivePath}); creating a replacement backup before continuing`,
+    );
+  }
+
+  const snapshot = await createBackupArchive({
+    output: (() => {
+      const outputDir = params.outputDir ?? resolveMatrixMigrationSnapshotOutputDir(env);
+      fs.mkdirSync(outputDir, { recursive: true });
+      return outputDir;
+    })(),
+    includeWorkspace: false,
+  });
+
+  const marker: MatrixMigrationSnapshotMarker = {
+    version: 1,
+    createdAt: snapshot.createdAt,
+    archivePath: snapshot.archivePath,
+    trigger: params.trigger,
+    includeWorkspace: snapshot.includeWorkspace,
+  };
+  await writeJsonFileAtomically(markerPath, marker);
+  params.log?.info?.(`matrix: created pre-migration backup snapshot: ${snapshot.archivePath}`);
+  return {
+    created: true,
+    archivePath: snapshot.archivePath,
+    markerPath,
+  };
+}