@openclaw/matrix 2026.3.13 → 2026.5.9-beta.1

package/src/matrix/deps.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { ensureMatrixCryptoRuntime } from "./deps.js";
-
-const logStub = vi.fn();
-
-describe("ensureMatrixCryptoRuntime", () => {
-  it("returns immediately when matrix SDK loads", async () => {
-    const runCommand = vi.fn();
-    const requireFn = vi.fn(() => ({}));
-
-    await ensureMatrixCryptoRuntime({
-      log: logStub,
-      requireFn,
-      runCommand,
-      resolveFn: () => "/tmp/download-lib.js",
-      nodeExecutable: "/usr/bin/node",
-    });
-
-    expect(requireFn).toHaveBeenCalledTimes(1);
-    expect(runCommand).not.toHaveBeenCalled();
-  });
-
-  it("bootstraps missing crypto runtime and retries matrix SDK load", async () => {
-    let bootstrapped = false;
-    const requireFn = vi.fn(() => {
-      if (!bootstrapped) {
-        throw new Error(
-          "Cannot find module '@matrix-org/matrix-sdk-crypto-nodejs-linux-x64-gnu' (required by matrix sdk)",
-        );
-      }
-      return {};
-    });
-    const runCommand = vi.fn(async () => {
-      bootstrapped = true;
-      return { code: 0, stdout: "", stderr: "" };
-    });
-
-    await ensureMatrixCryptoRuntime({
-      log: logStub,
-      requireFn,
-      runCommand,
-      resolveFn: () => "/tmp/download-lib.js",
-      nodeExecutable: "/usr/bin/node",
-    });
-
-    expect(runCommand).toHaveBeenCalledWith({
-      argv: ["/usr/bin/node", "/tmp/download-lib.js"],
-      cwd: "/tmp",
-      timeoutMs: 300_000,
-      env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
-    });
-    expect(requireFn).toHaveBeenCalledTimes(2);
-  });
-
-  it("rethrows non-crypto module errors without bootstrapping", async () => {
-    const runCommand = vi.fn();
-    const requireFn = vi.fn(() => {
-      throw new Error("Cannot find module '@vector-im/matrix-bot-sdk'");
-    });
-
-    await expect(
-      ensureMatrixCryptoRuntime({
-        log: logStub,
-        requireFn,
-        runCommand,
-        resolveFn: () => "/tmp/download-lib.js",
-        nodeExecutable: "/usr/bin/node",
-      }),
-    ).rejects.toThrow("Cannot find module '@vector-im/matrix-bot-sdk'");
-
-    expect(runCommand).not.toHaveBeenCalled();
-    expect(requireFn).toHaveBeenCalledTimes(1);
-  });
-});

package/src/matrix/deps.ts

@@ -1,126 +0,0 @@
-import fs from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { runPluginCommandWithTimeout, type RuntimeEnv } from "openclaw/plugin-sdk/matrix";
-
-const MATRIX_SDK_PACKAGE = "@vector-im/matrix-bot-sdk";
-const MATRIX_CRYPTO_DOWNLOAD_HELPER = "@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js";
-
-function formatCommandError(result: { stderr: string; stdout: string }): string {
-  const stderr = result.stderr.trim();
-  if (stderr) {
-    return stderr;
-  }
-  const stdout = result.stdout.trim();
-  if (stdout) {
-    return stdout;
-  }
-  return "unknown error";
-}
-
-function isMissingMatrixCryptoRuntimeError(err: unknown): boolean {
-  const message = err instanceof Error ? err.message : String(err ?? "");
-  return (
-    message.includes("Cannot find module") &&
-    message.includes("@matrix-org/matrix-sdk-crypto-nodejs-")
-  );
-}
-
-export function isMatrixSdkAvailable(): boolean {
-  try {
-    const req = createRequire(import.meta.url);
-    req.resolve(MATRIX_SDK_PACKAGE);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function resolvePluginRoot(): string {
-  const currentDir = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(currentDir, "..", "..");
-}
-
-export async function ensureMatrixCryptoRuntime(
-  params: {
-    log?: (message: string) => void;
-    requireFn?: (id: string) => unknown;
-    resolveFn?: (id: string) => string;
-    runCommand?: typeof runPluginCommandWithTimeout;
-    nodeExecutable?: string;
-  } = {},
-): Promise<void> {
-  const req = createRequire(import.meta.url);
-  const requireFn = params.requireFn ?? ((id: string) => req(id));
-  const resolveFn = params.resolveFn ?? ((id: string) => req.resolve(id));
-  const runCommand = params.runCommand ?? runPluginCommandWithTimeout;
-  const nodeExecutable = params.nodeExecutable ?? process.execPath;
-
-  try {
-    requireFn(MATRIX_SDK_PACKAGE);
-    return;
-  } catch (err) {
-    if (!isMissingMatrixCryptoRuntimeError(err)) {
-      throw err;
-    }
-  }
-
-  const scriptPath = resolveFn(MATRIX_CRYPTO_DOWNLOAD_HELPER);
-  params.log?.("matrix: crypto runtime missing; downloading platform library…");
-  const result = await runCommand({
-    argv: [nodeExecutable, scriptPath],
-    cwd: path.dirname(scriptPath),
-    timeoutMs: 300_000,
-    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
-  });
-  if (result.code !== 0) {
-    throw new Error(`Matrix crypto runtime bootstrap failed: ${formatCommandError(result)}`);
-  }
-
-  try {
-    requireFn(MATRIX_SDK_PACKAGE);
-  } catch (err) {
-    throw new Error(
-      `Matrix crypto runtime remains unavailable after bootstrap: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-}
-
-export async function ensureMatrixSdkInstalled(params: {
-  runtime: RuntimeEnv;
-  confirm?: (message: string) => Promise<boolean>;
-}): Promise<void> {
-  if (isMatrixSdkAvailable()) {
-    return;
-  }
-  const confirm = params.confirm;
-  if (confirm) {
-    const ok = await confirm("Matrix requires @vector-im/matrix-bot-sdk. Install now?");
-    if (!ok) {
-      throw new Error("Matrix requires @vector-im/matrix-bot-sdk (install dependencies first).");
-    }
-  }
-
-  const root = resolvePluginRoot();
-  const command = fs.existsSync(path.join(root, "pnpm-lock.yaml"))
-    ? ["pnpm", "install"]
-    : ["npm", "install", "--omit=dev", "--silent"];
-  params.runtime.log?.(`matrix: installing dependencies via ${command[0]} (${root})…`);
-  const result = await runPluginCommandWithTimeout({
-    argv: command,
-    cwd: root,
-    timeoutMs: 300_000,
-    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
-  });
-  if (result.code !== 0) {
-    throw new Error(
-      result.stderr.trim() || result.stdout.trim() || "Matrix dependency install failed.",
-    );
-  }
-  if (!isMatrixSdkAvailable()) {
-    throw new Error(
-      "Matrix dependency install completed but @vector-im/matrix-bot-sdk is still missing.",
-    );
-  }
-}

package/src/matrix/format.test.ts

@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { markdownToMatrixHtml } from "./format.js";
-
-describe("markdownToMatrixHtml", () => {
-  it("renders basic inline formatting", () => {
-    const html = markdownToMatrixHtml("hi _there_ **boss** `code`");
-    expect(html).toContain("<em>there</em>");
-    expect(html).toContain("<strong>boss</strong>");
-    expect(html).toContain("<code>code</code>");
-  });
-
-  it("renders links as HTML", () => {
-    const html = markdownToMatrixHtml("see [docs](https://example.com)");
-    expect(html).toContain('<a href="https://example.com">docs</a>');
-  });
-
-  it("escapes raw HTML", () => {
-    const html = markdownToMatrixHtml("<b>nope</b>");
-    expect(html).toContain("&lt;b&gt;nope&lt;/b&gt;");
-    expect(html).not.toContain("<b>nope</b>");
-  });
-
-  it("flattens images into alt text", () => {
-    const html = markdownToMatrixHtml("![alt](https://example.com/img.png)");
-    expect(html).toContain("alt");
-    expect(html).not.toContain("<img");
-  });
-
-  it("preserves line breaks", () => {
-    const html = markdownToMatrixHtml("line1\nline2");
-    expect(html).toContain("<br");
-  });
-});

package/src/matrix/format.ts

@@ -1,22 +0,0 @@
-import MarkdownIt from "markdown-it";
-
-const md = new MarkdownIt({
-  html: false,
-  linkify: true,
-  breaks: true,
-  typographer: false,
-});
-
-md.enable("strikethrough");
-
-const { escapeHtml } = md.utils;
-
-md.renderer.rules.image = (tokens, idx) => escapeHtml(tokens[idx]?.content ?? "");
-
-md.renderer.rules.html_block = (tokens, idx) => escapeHtml(tokens[idx]?.content ?? "");
-md.renderer.rules.html_inline = (tokens, idx) => escapeHtml(tokens[idx]?.content ?? "");
-
-export function markdownToMatrixHtml(markdown: string): string {
-  const rendered = md.render(markdown ?? "");
-  return rendered.trimEnd();
-}

package/src/matrix/index.ts

@@ -1,11 +0,0 @@
-export { monitorMatrixProvider } from "./monitor/index.js";
-export { probeMatrix } from "./probe.js";
-export {
-  reactMatrixMessage,
-  resolveMatrixRoomId,
-  sendReadReceiptMatrix,
-  sendMessageMatrix,
-  sendPollMatrix,
-  sendTypingMatrix,
-} from "./send.js";
-export { resolveMatrixAuth, resolveSharedMatrixClient } from "./client.js";

package/src/matrix/monitor/access-policy.ts

@@ -1,126 +0,0 @@
-import {
-  formatAllowlistMatchMeta,
-  issuePairingChallenge,
-  readStoreAllowFromForDmPolicy,
-  resolveDmGroupAccessWithLists,
-  resolveSenderScopedGroupPolicy,
-} from "openclaw/plugin-sdk/matrix";
-import {
-  normalizeMatrixAllowList,
-  resolveMatrixAllowListMatch,
-  resolveMatrixAllowListMatches,
-} from "./allowlist.js";
-
-type MatrixDmPolicy = "open" | "pairing" | "allowlist" | "disabled";
-type MatrixGroupPolicy = "open" | "allowlist" | "disabled";
-
-export async function resolveMatrixAccessState(params: {
-  isDirectMessage: boolean;
-  resolvedAccountId: string;
-  dmPolicy: MatrixDmPolicy;
-  groupPolicy: MatrixGroupPolicy;
-  allowFrom: string[];
-  groupAllowFrom: Array<string | number>;
-  senderId: string;
-  readStoreForDmPolicy: (provider: string, accountId: string) => Promise<string[]>;
-}) {
-  const storeAllowFrom = params.isDirectMessage
-    ? await readStoreAllowFromForDmPolicy({
-        provider: "matrix",
-        accountId: params.resolvedAccountId,
-        dmPolicy: params.dmPolicy,
-        readStore: params.readStoreForDmPolicy,
-      })
-    : [];
-  const normalizedGroupAllowFrom = normalizeMatrixAllowList(params.groupAllowFrom);
-  const senderGroupPolicy = resolveSenderScopedGroupPolicy({
-    groupPolicy: params.groupPolicy,
-    groupAllowFrom: normalizedGroupAllowFrom,
-  });
-  const access = resolveDmGroupAccessWithLists({
-    isGroup: !params.isDirectMessage,
-    dmPolicy: params.dmPolicy,
-    groupPolicy: senderGroupPolicy,
-    allowFrom: params.allowFrom,
-    groupAllowFrom: normalizedGroupAllowFrom,
-    storeAllowFrom,
-    groupAllowFromFallbackToAllowFrom: false,
-    isSenderAllowed: (allowFrom) =>
-      resolveMatrixAllowListMatches({
-        allowList: normalizeMatrixAllowList(allowFrom),
-        userId: params.senderId,
-      }),
-  });
-  const effectiveAllowFrom = normalizeMatrixAllowList(access.effectiveAllowFrom);
-  const effectiveGroupAllowFrom = normalizeMatrixAllowList(access.effectiveGroupAllowFrom);
-  return {
-    access,
-    effectiveAllowFrom,
-    effectiveGroupAllowFrom,
-    groupAllowConfigured: effectiveGroupAllowFrom.length > 0,
-  };
-}
-
-export async function enforceMatrixDirectMessageAccess(params: {
-  dmEnabled: boolean;
-  dmPolicy: MatrixDmPolicy;
-  accessDecision: "allow" | "block" | "pairing";
-  senderId: string;
-  senderName: string;
-  effectiveAllowFrom: string[];
-  upsertPairingRequest: (input: {
-    id: string;
-    meta?: Record<string, string | undefined>;
-  }) => Promise<{
-    code: string;
-    created: boolean;
-  }>;
-  sendPairingReply: (text: string) => Promise<void>;
-  logVerboseMessage: (message: string) => void;
-}): Promise<boolean> {
-  if (!params.dmEnabled) {
-    return false;
-  }
-  if (params.accessDecision === "allow") {
-    return true;
-  }
-  const allowMatch = resolveMatrixAllowListMatch({
-    allowList: params.effectiveAllowFrom,
-    userId: params.senderId,
-  });
-  const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
-  if (params.accessDecision === "pairing") {
-    await issuePairingChallenge({
-      channel: "matrix",
-      senderId: params.senderId,
-      senderIdLine: `Matrix user id: ${params.senderId}`,
-      meta: { name: params.senderName },
-      upsertPairingRequest: params.upsertPairingRequest,
-      buildReplyText: ({ code }) =>
-        [
-          "OpenClaw: access not configured.",
-          "",
-          `Pairing code: ${code}`,
-          "",
-          "Ask the bot owner to approve with:",
-          "openclaw pairing approve matrix <code>",
-        ].join("\n"),
-      sendPairingReply: params.sendPairingReply,
-      onCreated: () => {
-        params.logVerboseMessage(
-          `matrix pairing request sender=${params.senderId} name=${params.senderName ?? "unknown"} (${allowMatchMeta})`,
-        );
-      },
-      onReplyError: (err) => {
-        params.logVerboseMessage(
-          `matrix pairing reply failed for ${params.senderId}: ${String(err)}`,
-        );
-      },
-    });
-    return false;
-  }
-  params.logVerboseMessage(
-    `matrix: blocked dm sender ${params.senderId} (dmPolicy=${params.dmPolicy}, ${allowMatchMeta})`,
-  );
-  return false;
-}

package/src/matrix/monitor/allowlist.test.ts

@@ -1,45 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeMatrixAllowList, resolveMatrixAllowListMatch } from "./allowlist.js";
-
-describe("resolveMatrixAllowListMatch", () => {
-  it("matches full user IDs and prefixes", () => {
-    const userId = "@Alice:Example.org";
-    const direct = resolveMatrixAllowListMatch({
-      allowList: normalizeMatrixAllowList(["@alice:example.org"]),
-      userId,
-    });
-    expect(direct.allowed).toBe(true);
-    expect(direct.matchSource).toBe("id");
-
-    const prefixedMatrix = resolveMatrixAllowListMatch({
-      allowList: normalizeMatrixAllowList(["matrix:@alice:example.org"]),
-      userId,
-    });
-    expect(prefixedMatrix.allowed).toBe(true);
-    expect(prefixedMatrix.matchSource).toBe("prefixed-id");
-
-    const prefixedUser = resolveMatrixAllowListMatch({
-      allowList: normalizeMatrixAllowList(["user:@alice:example.org"]),
-      userId,
-    });
-    expect(prefixedUser.allowed).toBe(true);
-    expect(prefixedUser.matchSource).toBe("prefixed-user");
-  });
-
-  it("ignores display names and localparts", () => {
-    const match = resolveMatrixAllowListMatch({
-      allowList: normalizeMatrixAllowList(["alice", "Alice"]),
-      userId: "@alice:example.org",
-    });
-    expect(match.allowed).toBe(false);
-  });
-
-  it("matches wildcard", () => {
-    const match = resolveMatrixAllowListMatch({
-      allowList: normalizeMatrixAllowList(["*"]),
-      userId: "@alice:example.org",
-    });
-    expect(match.allowed).toBe(true);
-    expect(match.matchSource).toBe("wildcard");
-  });
-});

package/src/matrix/monitor/allowlist.ts

@@ -1,94 +0,0 @@
-import {
-  compileAllowlist,
-  normalizeStringEntries,
-  resolveCompiledAllowlistMatch,
-  type AllowlistMatch,
-} from "openclaw/plugin-sdk/matrix";
-
-function normalizeAllowList(list?: Array<string | number>) {
-  return normalizeStringEntries(list);
-}
-
-function normalizeMatrixUser(raw?: string | null): string {
-  const value = (raw ?? "").trim();
-  if (!value) {
-    return "";
-  }
-  if (!value.startsWith("@") || !value.includes(":")) {
-    return value.toLowerCase();
-  }
-  const withoutAt = value.slice(1);
-  const splitIndex = withoutAt.indexOf(":");
-  if (splitIndex === -1) {
-    return value.toLowerCase();
-  }
-  const localpart = withoutAt.slice(0, splitIndex).toLowerCase();
-  const server = withoutAt.slice(splitIndex + 1).toLowerCase();
-  if (!server) {
-    return value.toLowerCase();
-  }
-  return `@${localpart}:${server.toLowerCase()}`;
-}
-
-export function normalizeMatrixUserId(raw?: string | null): string {
-  const trimmed = (raw ?? "").trim();
-  if (!trimmed) {
-    return "";
-  }
-  const lowered = trimmed.toLowerCase();
-  if (lowered.startsWith("matrix:")) {
-    return normalizeMatrixUser(trimmed.slice("matrix:".length));
-  }
-  if (lowered.startsWith("user:")) {
-    return normalizeMatrixUser(trimmed.slice("user:".length));
-  }
-  return normalizeMatrixUser(trimmed);
-}
-
-function normalizeMatrixAllowListEntry(raw: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    return "";
-  }
-  if (trimmed === "*") {
-    return trimmed;
-  }
-  const lowered = trimmed.toLowerCase();
-  if (lowered.startsWith("matrix:")) {
-    return `matrix:${normalizeMatrixUser(trimmed.slice("matrix:".length))}`;
-  }
-  if (lowered.startsWith("user:")) {
-    return `user:${normalizeMatrixUser(trimmed.slice("user:".length))}`;
-  }
-  return normalizeMatrixUser(trimmed);
-}
-
-export function normalizeMatrixAllowList(list?: Array<string | number>) {
-  return normalizeAllowList(list).map((entry) => normalizeMatrixAllowListEntry(entry));
-}
-
-export type MatrixAllowListMatch = AllowlistMatch<
-  "wildcard" | "id" | "prefixed-id" | "prefixed-user"
->;
-type MatrixAllowListSource = Exclude<MatrixAllowListMatch["matchSource"], undefined>;
-
-export function resolveMatrixAllowListMatch(params: {
-  allowList: string[];
-  userId?: string;
-}): MatrixAllowListMatch {
-  const compiledAllowList = compileAllowlist(params.allowList);
-  const userId = normalizeMatrixUser(params.userId);
-  const candidates: Array<{ value?: string; source: MatrixAllowListSource }> = [
-    { value: userId, source: "id" },
-    { value: userId ? `matrix:${userId}` : "", source: "prefixed-id" },
-    { value: userId ? `user:${userId}` : "", source: "prefixed-user" },
-  ];
-  return resolveCompiledAllowlistMatch({
-    compiledAllowlist: compiledAllowList,
-    candidates,
-  });
-}
-
-export function resolveMatrixAllowListMatches(params: { allowList: string[]; userId?: string }) {
-  return resolveMatrixAllowListMatch(params).allowed;
-}

package/src/matrix/monitor/auto-join.ts

@@ -1,72 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import type { RuntimeEnv } from "openclaw/plugin-sdk/matrix";
-import { getMatrixRuntime } from "../../runtime.js";
-import type { CoreConfig } from "../../types.js";
-import { loadMatrixSdk } from "../sdk-runtime.js";
-
-export function registerMatrixAutoJoin(params: {
-  client: MatrixClient;
-  cfg: CoreConfig;
-  runtime: RuntimeEnv;
-}) {
-  const { client, cfg, runtime } = params;
-  const core = getMatrixRuntime();
-  const logVerbose = (message: string) => {
-    if (!core.logging.shouldLogVerbose()) {
-      return;
-    }
-    runtime.log?.(message);
-  };
-  const autoJoin = cfg.channels?.matrix?.autoJoin ?? "always";
-  const autoJoinAllowlist = cfg.channels?.matrix?.autoJoinAllowlist ?? [];
-
-  if (autoJoin === "off") {
-    return;
-  }
-
-  if (autoJoin === "always") {
-    // Use the built-in autojoin mixin for "always" mode
-    const { AutojoinRoomsMixin } = loadMatrixSdk();
-    AutojoinRoomsMixin.setupOnClient(client);
-    logVerbose("matrix: auto-join enabled for all invites");
-    return;
-  }
-
-  // For "allowlist" mode, handle invites manually
-  client.on("room.invite", async (roomId: string, _inviteEvent: unknown) => {
-    if (autoJoin !== "allowlist") {
-      return;
-    }
-
-    // Get room alias if available
-    let alias: string | undefined;
-    let altAliases: string[] = [];
-    try {
-      const aliasState = await client
-        .getRoomStateEvent(roomId, "m.room.canonical_alias", "")
-        .catch(() => null);
-      alias = aliasState?.alias;
-      altAliases = Array.isArray(aliasState?.alt_aliases) ? aliasState.alt_aliases : [];
-    } catch {
-      // Ignore errors
-    }
-
-    const allowed =
-      autoJoinAllowlist.includes("*") ||
-      autoJoinAllowlist.includes(roomId) ||
-      (alias ? autoJoinAllowlist.includes(alias) : false) ||
-      altAliases.some((value) => autoJoinAllowlist.includes(value));
-
-    if (!allowed) {
-      logVerbose(`matrix: invite ignored (not in allowlist) room=${roomId}`);
-      return;
-    }
-
-    try {
-      await client.joinRoom(roomId);
-      logVerbose(`matrix: joined room ${roomId}`);
-    } catch (err) {
-      runtime.error?.(`matrix: failed to join room ${roomId}: ${String(err)}`);
-    }
-  });
-}