@openclaw/matrix 2026.1.29 → 2026.2.2

package/src/matrix/monitor/allowlist.ts

@@ -4,40 +4,89 @@ function normalizeAllowList(list?: Array<string | number>) {
   return (list ?? []).map((entry) => String(entry).trim()).filter(Boolean);
 }
 
-export function normalizeAllowListLower(list?: Array<string | number>) {
-  return normalizeAllowList(list).map((entry) => entry.toLowerCase());
+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()}`;
 }
 
-function normalizeMatrixUser(raw?: string | null): string {
-  return (raw ?? "").trim().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" | "name" | "localpart"
+  "wildcard" | "id" | "prefixed-id" | "prefixed-user"
 >;
 
 export function resolveMatrixAllowListMatch(params: {
   allowList: string[];
   userId?: string;
-  userName?: string;
 }): MatrixAllowListMatch {
   const allowList = params.allowList;
-  if (allowList.length === 0) return { allowed: false };
+  if (allowList.length === 0) {
+    return { allowed: false };
+  }
   if (allowList.includes("*")) {
     return { allowed: true, matchKey: "*", matchSource: "wildcard" };
   }
   const userId = normalizeMatrixUser(params.userId);
-  const userName = normalizeMatrixUser(params.userName);
-  const localPart = userId.startsWith("@") ? (userId.slice(1).split(":")[0] ?? "") : "";
   const candidates: Array<{ value?: string; source: MatrixAllowListMatch["matchSource"] }> = [
     { value: userId, source: "id" },
     { value: userId ? `matrix:${userId}` : "", source: "prefixed-id" },
     { value: userId ? `user:${userId}` : "", source: "prefixed-user" },
-    { value: userName, source: "name" },
-    { value: localPart, source: "localpart" },
   ];
   for (const candidate of candidates) {
-    if (!candidate.value) continue;
+    if (!candidate.value) {
+      continue;
+    }
     if (allowList.includes(candidate.value)) {
       return {
         allowed: true,
@@ -49,10 +98,6 @@ export function resolveMatrixAllowListMatch(params: {
   return { allowed: false };
 }
 
-export function resolveMatrixAllowListMatches(params: {
-  allowList: string[];
-  userId?: string;
-  userName?: string;
-}) {
+export function resolveMatrixAllowListMatches(params: { allowList: string[]; userId?: string }) {
   return resolveMatrixAllowListMatch(params).allowed;
 }

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

@@ -1,7 +1,6 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import { AutojoinRoomsMixin } from "@vector-im/matrix-bot-sdk";
-
 import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { AutojoinRoomsMixin } from "@vector-im/matrix-bot-sdk";
 import type { CoreConfig } from "../../types.js";
 import { getMatrixRuntime } from "../../runtime.js";
 
@@ -13,7 +12,9 @@ export function registerMatrixAutoJoin(params: {
   const { client, cfg, runtime } = params;
   const core = getMatrixRuntime();
   const logVerbose = (message: string) => {
-    if (!core.logging.shouldLogVerbose()) return;
+    if (!core.logging.shouldLogVerbose()) {
+      return;
+    }
     runtime.log?.(message);
   };
   const autoJoin = cfg.channels?.matrix?.autoJoin ?? "always";
@@ -32,7 +33,9 @@ export function registerMatrixAutoJoin(params: {
 
   // For "allowlist" mode, handle invites manually
   client.on("room.invite", async (roomId: string, _inviteEvent: unknown) => {
-    if (autoJoin !== "allowlist") return;
+    if (autoJoin !== "allowlist") {
+      return;
+    }
 
     // Get room alias if available
     let alias: string | undefined;

package/src/matrix/monitor/direct.ts

@@ -12,17 +12,16 @@ type DirectRoomTrackerOptions = {
 
 const DM_CACHE_TTL_MS = 30_000;
 
-export function createDirectRoomTracker(
-  client: MatrixClient,
-  opts: DirectRoomTrackerOptions = {},
-) {
+export function createDirectRoomTracker(client: MatrixClient, opts: DirectRoomTrackerOptions = {}) {
   const log = opts.log ?? (() => {});
   let lastDmUpdateMs = 0;
   let cachedSelfUserId: string | null = null;
   const memberCountCache = new Map<string, { count: number; ts: number }>();
 
   const ensureSelfUserId = async (): Promise<string | null> => {
-    if (cachedSelfUserId) return cachedSelfUserId;
+    if (cachedSelfUserId) {
+      return cachedSelfUserId;
+    }
     try {
       cachedSelfUserId = await client.getUserId();
     } catch {
@@ -33,7 +32,9 @@ export function createDirectRoomTracker(
 
   const refreshDmCache = async (): Promise<void> => {
     const now = Date.now();
-    if (now - lastDmUpdateMs < DM_CACHE_TTL_MS) return;
+    if (now - lastDmUpdateMs < DM_CACHE_TTL_MS) {
+      return;
+    }
     lastDmUpdateMs = now;
     try {
       await client.dms.update();
@@ -61,7 +62,9 @@ export function createDirectRoomTracker(
 
   const hasDirectFlag = async (roomId: string, userId?: string): Promise<boolean> => {
     const target = userId?.trim();
-    if (!target) return false;
+    if (!target) {
+      return false;
+    }
     try {
       const state = await client.getRoomStateEvent(roomId, "m.room.member", target);
       return state?.is_direct === true;
@@ -94,11 +97,7 @@ export function createDirectRoomTracker(
         return true;
       }
 
-      log(
-        `matrix: dm check room=${roomId} result=group members=${
-          memberCount ?? "unknown"
-        }`,
-      );
+      log(`matrix: dm check room=${roomId} result=group members=${memberCount ?? "unknown"}`);
       return false;
     },
   };

package/src/matrix/monitor/events.ts

@@ -1,6 +1,5 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
 import type { PluginRuntime } from "openclaw/plugin-sdk";
-
 import type { MatrixAuth } from "../client.js";
 import type { MatrixRawEvent } from "./types.js";
 import { EventType } from "./types.js";
@@ -84,8 +83,7 @@ export function registerMatrixMonitorEvents(params: {
         const hint = formatNativeDependencyHint({
           packageName: "@matrix-org/matrix-sdk-crypto-nodejs",
           manager: "pnpm",
-          downloadCommand:
-            "node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js",
+          downloadCommand: "node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js",
         });
         const warning = `matrix: encryption enabled but crypto is unavailable; ${hint}`;
         logger.warn({ roomId }, warning);

package/src/matrix/monitor/handler.ts

@@ -1,5 +1,4 @@
 import type { LocationMessageEventContent, MatrixClient } from "@vector-im/matrix-bot-sdk";
-
 import {
   createReplyPrefixContext,
   createTypingCallbacks,
@@ -10,25 +9,30 @@ import {
   type RuntimeEnv,
 } from "openclaw/plugin-sdk";
 import type { CoreConfig, ReplyToMode } from "../../types.js";
+import type { MatrixRawEvent, RoomMessageEventContent } from "./types.js";
 import {
   formatPollAsText,
   isPollStartType,
   parsePollStartContent,
   type PollStartContent,
 } from "../poll-types.js";
-import { reactMatrixMessage, sendMessageMatrix, sendReadReceiptMatrix, sendTypingMatrix } from "../send.js";
 import {
+  reactMatrixMessage,
+  sendMessageMatrix,
+  sendReadReceiptMatrix,
+  sendTypingMatrix,
+} from "../send.js";
+import {
+  normalizeMatrixAllowList,
   resolveMatrixAllowListMatch,
   resolveMatrixAllowListMatches,
-  normalizeAllowListLower,
 } from "./allowlist.js";
+import { resolveMatrixLocation, type MatrixLocationPayload } from "./location.js";
 import { downloadMatrixMedia } from "./media.js";
 import { resolveMentions } from "./mentions.js";
 import { deliverMatrixReplies } from "./replies.js";
 import { resolveMatrixRoomConfig } from "./rooms.js";
 import { resolveMatrixThreadRootId, resolveMatrixThreadTarget } from "./threads.js";
-import { resolveMatrixLocation, type MatrixLocationPayload } from "./location.js";
-import type { MatrixRawEvent, RoomMessageEventContent } from "./types.js";
 import { EventType, RelationType } from "./types.js";
 
 export type MatrixMonitorHandlerParams = {
@@ -37,7 +41,7 @@ export type MatrixMonitorHandlerParams = {
     logging: {
       shouldLogVerbose: () => boolean;
     };
-    channel: typeof import("openclaw/plugin-sdk")["channel"];
+    channel: (typeof import("openclaw/plugin-sdk"))["channel"];
     system: {
       enqueueSystemEvent: (
         text: string,
@@ -59,7 +63,7 @@ export type MatrixMonitorHandlerParams = {
       : Record<string, unknown> | undefined
     : Record<string, unknown> | undefined;
   mentionRegexes: ReturnType<
-    typeof import("openclaw/plugin-sdk")["channel"]["mentions"]["buildMentionRegexes"]
+    (typeof import("openclaw/plugin-sdk"))["channel"]["mentions"]["buildMentionRegexes"]
   >;
   groupPolicy: "open" | "allowlist" | "disabled";
   replyToMode: ReplyToMode;
@@ -77,7 +81,9 @@ export type MatrixMonitorHandlerParams = {
       selfUserId: string;
     }) => Promise<boolean>;
   };
-  getRoomInfo: (roomId: string) => Promise<{ name?: string; canonicalAlias?: string; altAliases: string[] }>;
+  getRoomInfo: (
+    roomId: string,
+  ) => Promise<{ name?: string; canonicalAlias?: string; altAliases: string[] }>;
   getMemberDisplayName: (roomId: string, userId: string) => Promise<string>;
 };
 
@@ -118,17 +124,24 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       const locationContent = event.content as LocationMessageEventContent;
       const isLocationEvent =
         eventType === EventType.Location ||
-        (eventType === EventType.RoomMessage &&
-          locationContent.msgtype === EventType.Location);
-      if (eventType !== EventType.RoomMessage && !isPollEvent && !isLocationEvent) return;
+        (eventType === EventType.RoomMessage && locationContent.msgtype === EventType.Location);
+      if (eventType !== EventType.RoomMessage && !isPollEvent && !isLocationEvent) {
+        return;
+      }
       logVerboseMessage(
         `matrix: room.message recv room=${roomId} type=${eventType} id=${event.event_id ?? "unknown"}`,
       );
-      if (event.unsigned?.redacted_because) return;
+      if (event.unsigned?.redacted_because) {
+        return;
+      }
       const senderId = event.sender;
-      if (!senderId) return;
+      if (!senderId) {
+        return;
+      }
       const selfUserId = await client.getUserId();
-      if (senderId === selfUserId) return;
+      if (senderId === selfUserId) {
+        return;
+      }
       const eventTs = event.origin_server_ts;
       const eventAge = event.unsigned?.age;
       if (typeof eventTs === "number" && eventTs < startupMs - startupGraceMs) {
@@ -144,10 +157,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
 
       const roomInfo = await getRoomInfo(roomId);
       const roomName = roomInfo.name;
-      const roomAliases = [
-        roomInfo.canonicalAlias ?? "",
-        ...roomInfo.altAliases,
-      ].filter(Boolean);
+      const roomAliases = [roomInfo.canonicalAlias ?? "", ...roomInfo.altAliases].filter(Boolean);
 
       let content = event.content as RoomMessageEventContent;
       if (isPollEvent) {
@@ -176,7 +186,9 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
 
       const relates = content["m.relates_to"];
       if (relates && "rel_type" in relates) {
-        if (relates.rel_type === RelationType.Replace) return;
+        if (relates.rel_type === RelationType.Replace) {
+          return;
+        }
       }
 
       const isDirectMessage = await directTracker.isDirectMessage({
@@ -186,7 +198,9 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       });
       const isRoom = !isDirectMessage;
 
-      if (isRoom && groupPolicy === "disabled") return;
+      if (isRoom && groupPolicy === "disabled") {
+        return;
+      }
 
       const roomConfigInfo = isRoom
         ? resolveMatrixRoomConfig({
@@ -219,22 +233,22 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       }
 
       const senderName = await getMemberDisplayName(roomId, senderId);
-      const storeAllowFrom = await core.channel.pairing.readAllowFromStore("matrix").catch(() => []);
-      const effectiveAllowFrom = normalizeAllowListLower([...allowFrom, ...storeAllowFrom]);
+      const storeAllowFrom = await core.channel.pairing
+        .readAllowFromStore("matrix")
+        .catch(() => []);
+      const effectiveAllowFrom = normalizeMatrixAllowList([...allowFrom, ...storeAllowFrom]);
       const groupAllowFrom = cfg.channels?.matrix?.groupAllowFrom ?? [];
-      const effectiveGroupAllowFrom = normalizeAllowListLower([
-        ...groupAllowFrom,
-        ...storeAllowFrom,
-      ]);
+      const effectiveGroupAllowFrom = normalizeMatrixAllowList(groupAllowFrom);
       const groupAllowConfigured = effectiveGroupAllowFrom.length > 0;
 
       if (isDirectMessage) {
-        if (!dmEnabled || dmPolicy === "disabled") return;
+        if (!dmEnabled || dmPolicy === "disabled") {
+          return;
+        }
         if (dmPolicy !== "open") {
           const allowMatch = resolveMatrixAllowListMatch({
             allowList: effectiveAllowFrom,
             userId: senderId,
-            userName: senderName,
           });
           const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
           if (!allowMatch.allowed) {
@@ -279,9 +293,8 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       const roomUsers = roomConfig?.users ?? [];
       if (isRoom && roomUsers.length > 0) {
         const userMatch = resolveMatrixAllowListMatch({
-          allowList: normalizeAllowListLower(roomUsers),
+          allowList: normalizeMatrixAllowList(roomUsers),
           userId: senderId,
-          userName: senderName,
         });
         if (!userMatch.allowed) {
           logVerboseMessage(
@@ -296,7 +309,6 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         const groupAllowMatch = resolveMatrixAllowListMatch({
           allowList: effectiveGroupAllowFrom,
           userId: senderId,
-          userName: senderName,
         });
         if (!groupAllowMatch.allowed) {
           logVerboseMessage(
@@ -311,8 +323,8 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         logVerboseMessage(`matrix: allow room ${roomId} (${roomMatchMeta})`);
       }
 
-      const rawBody = locationPayload?.text
-        ?? (typeof content.body === "string" ? content.body.trim() : "");
+      const rawBody =
+        locationPayload?.text ?? (typeof content.body === "string" ? content.body.trim() : "");
       let media: {
         path: string;
         contentType?: string;
@@ -334,8 +346,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
           ? (content.info as { mimetype?: string; size?: number })
           : undefined;
       const contentType = contentInfo?.mimetype;
-      const contentSize =
-        typeof contentInfo?.size === "number" ? contentInfo.size : undefined;
+      const contentSize = typeof contentInfo?.size === "number" ? contentInfo.size : undefined;
       if (mediaUrl?.startsWith("mxc://")) {
         try {
           media = await downloadMatrixMedia({
@@ -352,7 +363,9 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       }
 
       const bodyText = rawBody || media?.placeholder || "";
-      if (!bodyText) return;
+      if (!bodyText) {
+        return;
+      }
 
       const { wasMentioned, hasExplicitMention } = resolveMentions({
         content,
@@ -368,21 +381,18 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       const senderAllowedForCommands = resolveMatrixAllowListMatches({
         allowList: effectiveAllowFrom,
         userId: senderId,
-        userName: senderName,
       });
       const senderAllowedForGroup = groupAllowConfigured
         ? resolveMatrixAllowListMatches({
             allowList: effectiveGroupAllowFrom,
             userId: senderId,
-            userName: senderName,
           })
         : false;
       const senderAllowedForRoomUsers =
         isRoom && roomUsers.length > 0
           ? resolveMatrixAllowListMatches({
-              allowList: normalizeAllowListLower(roomUsers),
+              allowList: normalizeMatrixAllowList(roomUsers),
               userId: senderId,
-              userName: senderName,
             })
           : false;
       const hasControlCommandInMessage = core.channel.text.hasControlCommand(bodyText, cfg);
@@ -493,7 +503,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         MediaPath: media?.path,
         MediaType: media?.contentType,
         MediaUrl: media?.path,
-        ...(locationPayload?.context ?? {}),
+        ...locationPayload?.context,
         CommandAuthorized: commandAuthorized,
         CommandSource: "text" as const,
         OriginatingChannel: "matrix" as const,
@@ -514,7 +524,11 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
           : undefined,
         onRecordError: (err) => {
           logger.warn(
-            { error: String(err), storePath, sessionKey: ctxPayload.SessionKey ?? route.sessionKey },
+            {
+              error: String(err),
+              storePath,
+              sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+            },
             "failed updating session meta",
           );
         },
@@ -528,16 +542,16 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       const shouldAckReaction = () =>
         Boolean(
           ackReaction &&
-            core.channel.reactions.shouldAckReaction({
-              scope: ackScope,
-              isDirect: isDirectMessage,
-              isGroup: isRoom,
-              isMentionableGroup: isRoom,
-              requireMention: Boolean(shouldRequireMention),
-              canDetectMention,
-              effectiveWasMentioned: wasMentioned || shouldBypassMention,
-              shouldBypassMention,
-            }),
+          core.channel.reactions.shouldAckReaction({
+            scope: ackScope,
+            isDirect: isDirectMessage,
+            isGroup: isRoom,
+            isMentionableGroup: isRoom,
+            requireMention: Boolean(shouldRequireMention),
+            canDetectMention,
+            effectiveWasMentioned: wasMentioned || shouldBypassMention,
+            shouldBypassMention,
+          }),
         );
       if (shouldAckReaction() && messageId) {
         reactMatrixMessage(roomId, messageId, ackReaction, client).catch((err) => {
@@ -625,7 +639,9 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         },
       });
       markDispatchIdle();
-      if (!queuedFinal) return;
+      if (!queuedFinal) {
+        return;
+      }
       didSendReply = true;
       const finalCount = counts.final;
       logVerboseMessage(