@openclaw/matrix 2026.3.12 → 2026.5.9-beta.1

package/src/matrix/client/shared.ts

@@ -1,210 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import type { CoreConfig } from "../../types.js";
-import { getMatrixLogService } from "../sdk-runtime.js";
-import { resolveMatrixAuth } from "./config.js";
-import { createMatrixClient } from "./create-client.js";
-import { startMatrixClientWithGrace } from "./startup.js";
-import { DEFAULT_ACCOUNT_KEY } from "./storage.js";
-import type { MatrixAuth } from "./types.js";
-
-type SharedMatrixClientState = {
-  client: MatrixClient;
-  key: string;
-  started: boolean;
-  cryptoReady: boolean;
-};
-
-// Support multiple accounts with separate clients
-const sharedClientStates = new Map<string, SharedMatrixClientState>();
-const sharedClientPromises = new Map<string, Promise<SharedMatrixClientState>>();
-const sharedClientStartPromises = new Map<string, Promise<void>>();
-
-function buildSharedClientKey(auth: MatrixAuth, accountId?: string | null): string {
-  const normalizedAccountId = normalizeAccountId(accountId);
-  return [
-    auth.homeserver,
-    auth.userId,
-    auth.accessToken,
-    auth.encryption ? "e2ee" : "plain",
-    normalizedAccountId || DEFAULT_ACCOUNT_KEY,
-  ].join("|");
-}
-
-async function createSharedMatrixClient(params: {
-  auth: MatrixAuth;
-  timeoutMs?: number;
-  accountId?: string | null;
-}): Promise<SharedMatrixClientState> {
-  const client = await createMatrixClient({
-    homeserver: params.auth.homeserver,
-    userId: params.auth.userId,
-    accessToken: params.auth.accessToken,
-    encryption: params.auth.encryption,
-    localTimeoutMs: params.timeoutMs,
-    accountId: params.accountId,
-  });
-  return {
-    client,
-    key: buildSharedClientKey(params.auth, params.accountId),
-    started: false,
-    cryptoReady: false,
-  };
-}
-
-async function ensureSharedClientStarted(params: {
-  state: SharedMatrixClientState;
-  timeoutMs?: number;
-  initialSyncLimit?: number;
-  encryption?: boolean;
-}): Promise<void> {
-  if (params.state.started) {
-    return;
-  }
-  const key = params.state.key;
-  const existingStartPromise = sharedClientStartPromises.get(key);
-  if (existingStartPromise) {
-    await existingStartPromise;
-    return;
-  }
-  const startPromise = (async () => {
-    const client = params.state.client;
-
-    // Initialize crypto if enabled
-    if (params.encryption && !params.state.cryptoReady) {
-      try {
-        const joinedRooms = await client.getJoinedRooms();
-        if (client.crypto) {
-          await (client.crypto as { prepare: (rooms?: string[]) => Promise<void> }).prepare(
-            joinedRooms,
-          );
-          params.state.cryptoReady = true;
-        }
-      } catch (err) {
-        const LogService = getMatrixLogService();
-        LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
-      }
-    }
-
-    await startMatrixClientWithGrace({
-      client,
-      onError: (err: unknown) => {
-        params.state.started = false;
-        const LogService = getMatrixLogService();
-        LogService.error("MatrixClientLite", "client.start() error:", err);
-      },
-    });
-    params.state.started = true;
-  })();
-  sharedClientStartPromises.set(key, startPromise);
-  try {
-    await startPromise;
-  } finally {
-    sharedClientStartPromises.delete(key);
-  }
-}
-
-export async function resolveSharedMatrixClient(
-  params: {
-    cfg?: CoreConfig;
-    env?: NodeJS.ProcessEnv;
-    timeoutMs?: number;
-    auth?: MatrixAuth;
-    startClient?: boolean;
-    accountId?: string | null;
-  } = {},
-): Promise<MatrixClient> {
-  const accountId = normalizeAccountId(params.accountId);
-  const auth =
-    params.auth ?? (await resolveMatrixAuth({ cfg: params.cfg, env: params.env, accountId }));
-  const key = buildSharedClientKey(auth, accountId);
-  const shouldStart = params.startClient !== false;
-
-  // Check if we already have a client for this key
-  const existingState = sharedClientStates.get(key);
-  if (existingState) {
-    if (shouldStart) {
-      await ensureSharedClientStarted({
-        state: existingState,
-        timeoutMs: params.timeoutMs,
-        initialSyncLimit: auth.initialSyncLimit,
-        encryption: auth.encryption,
-      });
-    }
-    return existingState.client;
-  }
-
-  // Check if there's a pending creation for this key
-  const existingPromise = sharedClientPromises.get(key);
-  if (existingPromise) {
-    const pending = await existingPromise;
-    if (shouldStart) {
-      await ensureSharedClientStarted({
-        state: pending,
-        timeoutMs: params.timeoutMs,
-        initialSyncLimit: auth.initialSyncLimit,
-        encryption: auth.encryption,
-      });
-    }
-    return pending.client;
-  }
-
-  // Create a new client for this account
-  const createPromise = createSharedMatrixClient({
-    auth,
-    timeoutMs: params.timeoutMs,
-    accountId,
-  });
-  sharedClientPromises.set(key, createPromise);
-  try {
-    const created = await createPromise;
-    sharedClientStates.set(key, created);
-    if (shouldStart) {
-      await ensureSharedClientStarted({
-        state: created,
-        timeoutMs: params.timeoutMs,
-        initialSyncLimit: auth.initialSyncLimit,
-        encryption: auth.encryption,
-      });
-    }
-    return created.client;
-  } finally {
-    sharedClientPromises.delete(key);
-  }
-}
-
-export async function waitForMatrixSync(_params: {
-  client: MatrixClient;
-  timeoutMs?: number;
-  abortSignal?: AbortSignal;
-}): Promise<void> {
-  // @vector-im/matrix-bot-sdk handles sync internally in start()
-  // This is kept for API compatibility but is essentially a no-op now
-}
-
-export function stopSharedClient(key?: string): void {
-  if (key) {
-    // Stop a specific client
-    const state = sharedClientStates.get(key);
-    if (state) {
-      state.client.stop();
-      sharedClientStates.delete(key);
-    }
-  } else {
-    // Stop all clients (backward compatible behavior)
-    for (const state of sharedClientStates.values()) {
-      state.client.stop();
-    }
-    sharedClientStates.clear();
-  }
-}
-
-/**
- * Stop the shared client for a specific account.
- * Use this instead of stopSharedClient() when shutting down a single account
- * to avoid stopping all accounts.
- */
-export function stopSharedClientForAccount(auth: MatrixAuth, accountId?: string | null): void {
-  const key = buildSharedClientKey(auth, normalizeAccountId(accountId));
-  stopSharedClient(key);
-}

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

@@ -1,49 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { MATRIX_CLIENT_STARTUP_GRACE_MS, startMatrixClientWithGrace } from "./startup.js";
-
-describe("startMatrixClientWithGrace", () => {
-  it("resolves after grace when start loop keeps running", async () => {
-    vi.useFakeTimers();
-    const client = {
-      start: vi.fn().mockReturnValue(new Promise<void>(() => {})),
-    };
-    const startPromise = startMatrixClientWithGrace({ client });
-    await vi.advanceTimersByTimeAsync(MATRIX_CLIENT_STARTUP_GRACE_MS);
-    await expect(startPromise).resolves.toBeUndefined();
-    vi.useRealTimers();
-  });
-
-  it("rejects when startup fails during grace", async () => {
-    vi.useFakeTimers();
-    const startError = new Error("invalid token");
-    const client = {
-      start: vi.fn().mockRejectedValue(startError),
-    };
-    const startPromise = startMatrixClientWithGrace({ client });
-    const startupExpectation = expect(startPromise).rejects.toBe(startError);
-    await vi.advanceTimersByTimeAsync(MATRIX_CLIENT_STARTUP_GRACE_MS);
-    await startupExpectation;
-    vi.useRealTimers();
-  });
-
-  it("calls onError for late failures after startup returns", async () => {
-    vi.useFakeTimers();
-    const lateError = new Error("late disconnect");
-    let rejectStart: ((err: unknown) => void) | undefined;
-    const startLoop = new Promise<void>((_resolve, reject) => {
-      rejectStart = reject;
-    });
-    const onError = vi.fn();
-    const client = {
-      start: vi.fn().mockReturnValue(startLoop),
-    };
-    const startPromise = startMatrixClientWithGrace({ client, onError });
-    await vi.advanceTimersByTimeAsync(MATRIX_CLIENT_STARTUP_GRACE_MS);
-    await expect(startPromise).resolves.toBeUndefined();
-
-    rejectStart?.(lateError);
-    await Promise.resolve();
-    expect(onError).toHaveBeenCalledWith(lateError);
-    vi.useRealTimers();
-  });
-});

package/src/matrix/client/startup.ts

@@ -1,29 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
-export const MATRIX_CLIENT_STARTUP_GRACE_MS = 2000;
-
-export async function startMatrixClientWithGrace(params: {
-  client: Pick<MatrixClient, "start">;
-  graceMs?: number;
-  onError?: (err: unknown) => void;
-}): Promise<void> {
-  const graceMs = params.graceMs ?? MATRIX_CLIENT_STARTUP_GRACE_MS;
-  let startFailed = false;
-  let startError: unknown = undefined;
-  let startPromise: Promise<unknown>;
-  try {
-    startPromise = params.client.start();
-  } catch (err) {
-    params.onError?.(err);
-    throw err;
-  }
-  void startPromise.catch((err: unknown) => {
-    startFailed = true;
-    startError = err;
-    params.onError?.(err);
-  });
-  await new Promise((resolve) => setTimeout(resolve, graceMs));
-  if (startFailed) {
-    throw startError;
-  }
-}

package/src/matrix/client/storage.ts

@@ -1,131 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { getMatrixRuntime } from "../../runtime.js";
-import type { MatrixStoragePaths } from "./types.js";
-
-export const DEFAULT_ACCOUNT_KEY = "default";
-const STORAGE_META_FILENAME = "storage-meta.json";
-
-function sanitizePathSegment(value: string): string {
-  const cleaned = value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "_")
-    .replace(/^_+|_+$/g, "");
-  return cleaned || "unknown";
-}
-
-function resolveHomeserverKey(homeserver: string): string {
-  try {
-    const url = new URL(homeserver);
-    if (url.host) {
-      return sanitizePathSegment(url.host);
-    }
-  } catch {
-    // fall through
-  }
-  return sanitizePathSegment(homeserver);
-}
-
-function hashAccessToken(accessToken: string): string {
-  return crypto.createHash("sha256").update(accessToken).digest("hex").slice(0, 16);
-}
-
-function resolveLegacyStoragePaths(env: NodeJS.ProcessEnv = process.env): {
-  storagePath: string;
-  cryptoPath: string;
-} {
-  const stateDir = getMatrixRuntime().state.resolveStateDir(env, os.homedir);
-  return {
-    storagePath: path.join(stateDir, "matrix", "bot-storage.json"),
-    cryptoPath: path.join(stateDir, "matrix", "crypto"),
-  };
-}
-
-export function resolveMatrixStoragePaths(params: {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  accountId?: string | null;
-  env?: NodeJS.ProcessEnv;
-}): MatrixStoragePaths {
-  const env = params.env ?? process.env;
-  const stateDir = getMatrixRuntime().state.resolveStateDir(env, os.homedir);
-  const accountKey = sanitizePathSegment(params.accountId ?? DEFAULT_ACCOUNT_KEY);
-  const userKey = sanitizePathSegment(params.userId);
-  const serverKey = resolveHomeserverKey(params.homeserver);
-  const tokenHash = hashAccessToken(params.accessToken);
-  const rootDir = path.join(
-    stateDir,
-    "matrix",
-    "accounts",
-    accountKey,
-    `${serverKey}__${userKey}`,
-    tokenHash,
-  );
-  return {
-    rootDir,
-    storagePath: path.join(rootDir, "bot-storage.json"),
-    cryptoPath: path.join(rootDir, "crypto"),
-    metaPath: path.join(rootDir, STORAGE_META_FILENAME),
-    accountKey,
-    tokenHash,
-  };
-}
-
-export function maybeMigrateLegacyStorage(params: {
-  storagePaths: MatrixStoragePaths;
-  env?: NodeJS.ProcessEnv;
-}): void {
-  const legacy = resolveLegacyStoragePaths(params.env);
-  const hasLegacyStorage = fs.existsSync(legacy.storagePath);
-  const hasLegacyCrypto = fs.existsSync(legacy.cryptoPath);
-  const hasNewStorage =
-    fs.existsSync(params.storagePaths.storagePath) || fs.existsSync(params.storagePaths.cryptoPath);
-
-  if (!hasLegacyStorage && !hasLegacyCrypto) {
-    return;
-  }
-  if (hasNewStorage) {
-    return;
-  }
-
-  fs.mkdirSync(params.storagePaths.rootDir, { recursive: true });
-  if (hasLegacyStorage) {
-    try {
-      fs.renameSync(legacy.storagePath, params.storagePaths.storagePath);
-    } catch {
-      // Ignore migration failures; new store will be created.
-    }
-  }
-  if (hasLegacyCrypto) {
-    try {
-      fs.renameSync(legacy.cryptoPath, params.storagePaths.cryptoPath);
-    } catch {
-      // Ignore migration failures; new store will be created.
-    }
-  }
-}
-
-export function writeStorageMeta(params: {
-  storagePaths: MatrixStoragePaths;
-  homeserver: string;
-  userId: string;
-  accountId?: string | null;
-}): void {
-  try {
-    const payload = {
-      homeserver: params.homeserver,
-      userId: params.userId,
-      accountId: params.accountId ?? DEFAULT_ACCOUNT_KEY,
-      accessTokenHash: params.storagePaths.tokenHash,
-      createdAt: new Date().toISOString(),
-    };
-    fs.mkdirSync(params.storagePaths.rootDir, { recursive: true });
-    fs.writeFileSync(params.storagePaths.metaPath, JSON.stringify(payload, null, 2), "utf-8");
-  } catch {
-    // ignore meta write failures
-  }
-}

package/src/matrix/client/types.ts

@@ -1,34 +0,0 @@
-export type MatrixResolvedConfig = {
-  homeserver: string;
-  userId: string;
-  accessToken?: string;
-  password?: string;
-  deviceName?: string;
-  initialSyncLimit?: number;
-  encryption?: boolean;
-};
-
-/**
- * Authenticated Matrix configuration.
- * Note: deviceId is NOT included here because it's implicit in the accessToken.
- * The crypto storage assumes the device ID (and thus access token) does not change
- * between restarts. If the access token becomes invalid or crypto storage is lost,
- * both will need to be recreated together.
- */
-export type MatrixAuth = {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  deviceName?: string;
-  initialSyncLimit?: number;
-  encryption?: boolean;
-};
-
-export type MatrixStoragePaths = {
-  rootDir: string;
-  storagePath: string;
-  cryptoPath: string;
-  metaPath: string;
-  accountKey: string;
-  tokenHash: string;
-};

package/src/matrix/client-bootstrap.ts

@@ -1,47 +0,0 @@
-import { createMatrixClient } from "./client/create-client.js";
-import { startMatrixClientWithGrace } from "./client/startup.js";
-import { getMatrixLogService } from "./sdk-runtime.js";
-
-type MatrixClientBootstrapAuth = {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  encryption?: boolean;
-};
-
-type MatrixCryptoPrepare = {
-  prepare: (rooms?: string[]) => Promise<void>;
-};
-
-type MatrixBootstrapClient = Awaited<ReturnType<typeof createMatrixClient>>;
-
-export async function createPreparedMatrixClient(opts: {
-  auth: MatrixClientBootstrapAuth;
-  timeoutMs?: number;
-  accountId?: string;
-}): Promise<MatrixBootstrapClient> {
-  const client = await createMatrixClient({
-    homeserver: opts.auth.homeserver,
-    userId: opts.auth.userId,
-    accessToken: opts.auth.accessToken,
-    encryption: opts.auth.encryption,
-    localTimeoutMs: opts.timeoutMs,
-    accountId: opts.accountId,
-  });
-  if (opts.auth.encryption && client.crypto) {
-    try {
-      const joinedRooms = await client.getJoinedRooms();
-      await (client.crypto as MatrixCryptoPrepare).prepare(joinedRooms);
-    } catch {
-      // Ignore crypto prep failures for one-off requests.
-    }
-  }
-  await startMatrixClientWithGrace({
-    client,
-    onError: (err: unknown) => {
-      const LogService = getMatrixLogService();
-      LogService.error("MatrixClientBootstrap", "client.start() error:", err);
-    },
-  });
-  return client;
-}

package/src/matrix/client.test.ts

@@ -1,56 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { CoreConfig } from "../types.js";
-import { resolveMatrixConfig } from "./client.js";
-
-describe("resolveMatrixConfig", () => {
-  it("prefers config over env", () => {
-    const cfg = {
-      channels: {
-        matrix: {
-          homeserver: "https://cfg.example.org",
-          userId: "@cfg:example.org",
-          accessToken: "cfg-token",
-          password: "cfg-pass",
-          deviceName: "CfgDevice",
-          initialSyncLimit: 5,
-        },
-      },
-    } as CoreConfig;
-    const env = {
-      MATRIX_HOMESERVER: "https://env.example.org",
-      MATRIX_USER_ID: "@env:example.org",
-      MATRIX_ACCESS_TOKEN: "env-token",
-      MATRIX_PASSWORD: "env-pass",
-      MATRIX_DEVICE_NAME: "EnvDevice",
-    } as NodeJS.ProcessEnv;
-    const resolved = resolveMatrixConfig(cfg, env);
-    expect(resolved).toEqual({
-      homeserver: "https://cfg.example.org",
-      userId: "@cfg:example.org",
-      accessToken: "cfg-token",
-      password: "cfg-pass",
-      deviceName: "CfgDevice",
-      initialSyncLimit: 5,
-      encryption: false,
-    });
-  });
-
-  it("uses env when config is missing", () => {
-    const cfg = {} as CoreConfig;
-    const env = {
-      MATRIX_HOMESERVER: "https://env.example.org",
-      MATRIX_USER_ID: "@env:example.org",
-      MATRIX_ACCESS_TOKEN: "env-token",
-      MATRIX_PASSWORD: "env-pass",
-      MATRIX_DEVICE_NAME: "EnvDevice",
-    } as NodeJS.ProcessEnv;
-    const resolved = resolveMatrixConfig(cfg, env);
-    expect(resolved.homeserver).toBe("https://env.example.org");
-    expect(resolved.userId).toBe("@env:example.org");
-    expect(resolved.accessToken).toBe("env-token");
-    expect(resolved.password).toBe("env-pass");
-    expect(resolved.deviceName).toBe("EnvDevice");
-    expect(resolved.initialSyncLimit).toBeUndefined();
-    expect(resolved.encryption).toBe(false);
-  });
-});

package/src/matrix/client.ts

@@ -1,14 +0,0 @@
-export type { MatrixAuth, MatrixResolvedConfig } from "./client/types.js";
-export { isBunRuntime } from "./client/runtime.js";
-export {
-  resolveMatrixConfig,
-  resolveMatrixConfigForAccount,
-  resolveMatrixAuth,
-} from "./client/config.js";
-export { createMatrixClient } from "./client/create-client.js";
-export {
-  resolveSharedMatrixClient,
-  waitForMatrixSync,
-  stopSharedClient,
-  stopSharedClientForAccount,
-} from "./client/shared.js";

package/src/matrix/credentials.ts

@@ -1,125 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { getMatrixRuntime } from "../runtime.js";
-
-export type MatrixStoredCredentials = {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  deviceId?: string;
-  createdAt: string;
-  lastUsedAt?: string;
-};
-
-function credentialsFilename(accountId?: string | null): string {
-  const normalized = normalizeAccountId(accountId);
-  if (normalized === DEFAULT_ACCOUNT_ID) {
-    return "credentials.json";
-  }
-  // normalizeAccountId produces lowercase [a-z0-9-] strings, already filesystem-safe.
-  // Different raw IDs that normalize to the same value are the same logical account.
-  return `credentials-${normalized}.json`;
-}
-
-export function resolveMatrixCredentialsDir(
-  env: NodeJS.ProcessEnv = process.env,
-  stateDir?: string,
-): string {
-  const resolvedStateDir = stateDir ?? getMatrixRuntime().state.resolveStateDir(env, os.homedir);
-  return path.join(resolvedStateDir, "credentials", "matrix");
-}
-
-export function resolveMatrixCredentialsPath(
-  env: NodeJS.ProcessEnv = process.env,
-  accountId?: string | null,
-): string {
-  const dir = resolveMatrixCredentialsDir(env);
-  return path.join(dir, credentialsFilename(accountId));
-}
-
-export function loadMatrixCredentials(
-  env: NodeJS.ProcessEnv = process.env,
-  accountId?: string | null,
-): MatrixStoredCredentials | null {
-  const credPath = resolveMatrixCredentialsPath(env, accountId);
-  try {
-    if (!fs.existsSync(credPath)) {
-      return null;
-    }
-    const raw = fs.readFileSync(credPath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<MatrixStoredCredentials>;
-    if (
-      typeof parsed.homeserver !== "string" ||
-      typeof parsed.userId !== "string" ||
-      typeof parsed.accessToken !== "string"
-    ) {
-      return null;
-    }
-    return parsed as MatrixStoredCredentials;
-  } catch {
-    return null;
-  }
-}
-
-export function saveMatrixCredentials(
-  credentials: Omit<MatrixStoredCredentials, "createdAt" | "lastUsedAt">,
-  env: NodeJS.ProcessEnv = process.env,
-  accountId?: string | null,
-): void {
-  const dir = resolveMatrixCredentialsDir(env);
-  fs.mkdirSync(dir, { recursive: true });
-
-  const credPath = resolveMatrixCredentialsPath(env, accountId);
-
-  const existing = loadMatrixCredentials(env, accountId);
-  const now = new Date().toISOString();
-
-  const toSave: MatrixStoredCredentials = {
-    ...credentials,
-    createdAt: existing?.createdAt ?? now,
-    lastUsedAt: now,
-  };
-
-  fs.writeFileSync(credPath, JSON.stringify(toSave, null, 2), "utf-8");
-}
-
-export function touchMatrixCredentials(
-  env: NodeJS.ProcessEnv = process.env,
-  accountId?: string | null,
-): void {
-  const existing = loadMatrixCredentials(env, accountId);
-  if (!existing) {
-    return;
-  }
-
-  existing.lastUsedAt = new Date().toISOString();
-  const credPath = resolveMatrixCredentialsPath(env, accountId);
-  fs.writeFileSync(credPath, JSON.stringify(existing, null, 2), "utf-8");
-}
-
-export function clearMatrixCredentials(
-  env: NodeJS.ProcessEnv = process.env,
-  accountId?: string | null,
-): void {
-  const credPath = resolveMatrixCredentialsPath(env, accountId);
-  try {
-    if (fs.existsSync(credPath)) {
-      fs.unlinkSync(credPath);
-    }
-  } catch {
-    // ignore
-  }
-}
-
-export function credentialsMatchConfig(
-  stored: MatrixStoredCredentials,
-  config: { homeserver: string; userId: string },
-): boolean {
-  // If userId is empty (token-based auth), only match homeserver
-  if (!config.userId) {
-    return stored.homeserver === config.homeserver;
-  }
-  return stored.homeserver === config.homeserver && stored.userId === config.userId;
-}