@archipelagolab/lobi 1.0.0

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

@@ -0,0 +1,289 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Mock the runtime before importing resolveMentions
+vi.mock("../../runtime.js", () => ({
+  getMatrixRuntime: () => ({
+    channel: {
+      mentions: {
+        matchesMentionPatterns: (text: string, patterns: RegExp[]) =>
+          patterns.some((p) => p.test(text)),
+      },
+    },
+  }),
+}));
+
+import { resolveMentions } from "./mentions.js";
+
+describe("resolveMentions", () => {
+  const userId = "@bot:matrix.org";
+  const mentionRegexes = [/@bot/i];
+
+  describe("m.mentions field", () => {
+    it("detects mention via m.mentions.user_ids when the visible text also mentions the bot", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello @bot",
+          "m.mentions": { user_ids: ["@bot:matrix.org"] },
+        },
+        userId,
+        text: "hello @bot",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(true);
+      expect(result.hasExplicitMention).toBe(true);
+    });
+
+    it("does not trust forged m.mentions.user_ids without a visible mention", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello",
+          "m.mentions": { user_ids: ["@bot:matrix.org"] },
+        },
+        userId,
+        text: "hello",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(false);
+      expect(result.hasExplicitMention).toBe(false);
+    });
+
+    it("detects room mention via visible @room text", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "@room hello everyone",
+          "m.mentions": { room: true },
+        },
+        userId,
+        text: "@room hello everyone",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("does not trust forged m.mentions.room without visible @room text", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello everyone",
+          "m.mentions": { room: true },
+        },
+        userId,
+        text: "hello everyone",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(false);
+      expect(result.hasExplicitMention).toBe(false);
+    });
+  });
+
+  describe("formatted_body matrix.to links", () => {
+    it("detects mention in formatted_body with plain user ID", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">Bot</a>: hello',
+        },
+        userId,
+        text: "Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("detects mention in formatted_body with URL-encoded user ID", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/%40bot%3Amatrix.org">Bot</a>: hello',
+        },
+        userId,
+        text: "Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("detects mention with single quotes in href", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot: hello",
+          formatted_body: "<a href='https://matrix.to/#/@bot:matrix.org'>Bot</a>: hello",
+        },
+        userId,
+        text: "Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("does not detect mention for different user ID", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Other: hello",
+          formatted_body: '<a href="https://matrix.to/#/@other:matrix.org">Other</a>: hello',
+        },
+        userId,
+        text: "Other: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(false);
+    });
+
+    it("does not false-positive on partial user ID match", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot2: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot2:matrix.org">Bot2</a>: hello',
+        },
+        userId: "@bot:matrix.org",
+        text: "Bot2: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(false);
+    });
+
+    it("does not trust hidden matrix.to links behind unrelated visible text", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "click here: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">click here</a>: hello',
+        },
+        userId,
+        text: "click here: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(false);
+    });
+
+    it("detects mention when the visible label still names the bot", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "@bot: hello",
+          formatted_body:
+            '<a href="https://matrix.to/#/@bot:matrix.org"><span>@bot</span></a>: hello',
+        },
+        userId,
+        text: "@bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("detects mention when the visible label matches the bot's displayName", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Wonderful Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">Wonderful Bot</a>: hello',
+        },
+        userId,
+        displayName: "Wonderful Bot",
+        text: "Wonderful Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("detects mention when the visible label encodes the bot's displayName", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "R&D Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">R&amp;D Bot</a>: hello',
+        },
+        userId,
+        displayName: "R&D Bot",
+        text: "R&D Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("ignores out-of-range hexadecimal HTML entities in visible labels", () => {
+      expect(() =>
+        resolveMentions({
+          content: {
+            msgtype: "m.text",
+            body: "hello",
+            formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">&#x110000;</a>: hello',
+          },
+          userId,
+          text: "hello",
+          mentionRegexes: [],
+        }),
+      ).not.toThrow();
+    });
+
+    it("ignores oversized decimal HTML entities in visible labels", () => {
+      expect(() =>
+        resolveMentions({
+          content: {
+            msgtype: "m.text",
+            body: "hello",
+            formatted_body:
+              '<a href="https://matrix.to/#/@bot:matrix.org">&#9999999999999999999999999999999999999999;</a>: hello',
+          },
+          userId,
+          text: "hello",
+          mentionRegexes: [],
+        }),
+      ).not.toThrow();
+    });
+
+    it("does not detect mention when displayName is spoofed", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Spoofed Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">Spoofed Bot</a>: hello',
+        },
+        userId,
+        displayName: "Alice",
+        text: "Spoofed Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(false);
+    });
+  });
+
+  describe("regex patterns", () => {
+    it("detects mention via regex pattern in body text", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hey @bot can you help?",
+        },
+        userId,
+        text: "hey @bot can you help?",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+  });
+
+  describe("no mention", () => {
+    it("returns false when no mention is present", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello world",
+        },
+        userId,
+        text: "hello world",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(false);
+      expect(result.hasExplicitMention).toBe(false);
+    });
+  });
+});

package/src/matrix/monitor/mentions.ts

@@ -0,0 +1,177 @@
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import { getMatrixRuntime } from "../../runtime.js";
+import type { RoomMessageEventContent } from "./types.js";
+
+const HTML_ENTITY_REPLACEMENTS: Readonly<Record<string, string>> = {
+  amp: "&",
+  apos: "'",
+  gt: ">",
+  lt: "<",
+  nbsp: " ",
+  quot: '"',
+};
+const MAX_UNICODE_SCALAR_VALUE = 0x10ffff;
+
+function decodeNumericHtmlEntity(match: string, rawValue: string, radix: 10 | 16): string {
+  const codePoint = Number.parseInt(rawValue, radix);
+  if (
+    !Number.isSafeInteger(codePoint) ||
+    codePoint < 0 ||
+    codePoint > MAX_UNICODE_SCALAR_VALUE ||
+    (codePoint >= 0xd800 && codePoint <= 0xdfff)
+  ) {
+    return match;
+  }
+  return String.fromCodePoint(codePoint);
+}
+
+function decodeHtmlEntities(value: string): string {
+  return value.replace(/&(#x?[0-9a-f]+|\w+);/gi, (match, entity: string) => {
+    const normalized = normalizeLowercaseStringOrEmpty(entity);
+    if (normalized.startsWith("#x")) {
+      return decodeNumericHtmlEntity(match, normalized.slice(2), 16);
+    }
+    if (normalized.startsWith("#")) {
+      return decodeNumericHtmlEntity(match, normalized.slice(1), 10);
+    }
+    return HTML_ENTITY_REPLACEMENTS[normalized] ?? match;
+  });
+}
+
+function normalizeVisibleMentionText(value: string): string {
+  return normalizeLowercaseStringOrEmpty(
+    decodeHtmlEntities(
+      value.replace(/<[^>]+>/g, " ").replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, ""),
+    ).replace(/\s+/g, " "),
+  );
+}
+
+function extractVisibleMentionText(value?: string): string {
+  return normalizeVisibleMentionText(value ?? "");
+}
+
+function resolveMatrixUserLocalpart(userId: string): string | null {
+  const trimmed = userId.trim();
+  if (!trimmed.startsWith("@")) {
+    return null;
+  }
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex <= 1) {
+    return null;
+  }
+  return trimmed.slice(1, colonIndex).trim() || null;
+}
+
+function isVisibleMentionLabel(params: {
+  text: string;
+  userId: string;
+  mentionRegexes: RegExp[];
+  displayName?: string | null;
+}): boolean {
+  const cleaned = extractVisibleMentionText(params.text);
+  if (!cleaned) {
+    return false;
+  }
+  if (params.mentionRegexes.some((pattern) => pattern.test(cleaned))) {
+    return true;
+  }
+  const localpart = resolveMatrixUserLocalpart(params.userId);
+  const candidates = [
+    extractVisibleMentionText(params.userId),
+    localpart ? extractVisibleMentionText(localpart) : null,
+    localpart ? extractVisibleMentionText(`@${localpart}`) : null,
+    params.displayName ? extractVisibleMentionText(params.displayName) : null,
+  ].filter((value): value is string => Boolean(value));
+  return candidates.includes(cleaned);
+}
+
+function hasVisibleRoomMention(value?: string): boolean {
+  const cleaned = extractVisibleMentionText(value);
+  return /(^|[^a-z0-9_])@room\b/i.test(cleaned);
+}
+
+/**
+ * Check if formatted_body contains a matrix.to link whose visible label still
+ * looks like a real mention for the given user. Do not trust href alone, since
+ * senders can hide arbitrary matrix.to links behind unrelated link text.
+ * Many Matrix clients (including Element) use HTML links in formatted_body instead of
+ * or in addition to the m.mentions field.
+ */
+function checkFormattedBodyMention(params: {
+  formattedBody?: string;
+  userId: string;
+  displayName?: string | null;
+  mentionRegexes: RegExp[];
+}): boolean {
+  if (!params.formattedBody || !params.userId) {
+    return false;
+  }
+  const anchorPattern = /<a\b[^>]*href=(["'])(https:\/\/matrix\.to\/#[^"']+)\1[^>]*>(.*?)<\/a>/gis;
+  for (const match of params.formattedBody.matchAll(anchorPattern)) {
+    const href = match[2];
+    const visibleLabel = match[3] ?? "";
+    if (!href) {
+      continue;
+    }
+    try {
+      const parsed = new URL(href);
+      const fragmentTarget = decodeURIComponent(parsed.hash.replace(/^#\/?/, "").trim());
+      if (fragmentTarget !== params.userId.trim()) {
+        continue;
+      }
+      if (
+        isVisibleMentionLabel({
+          text: visibleLabel,
+          userId: params.userId,
+          mentionRegexes: params.mentionRegexes,
+          displayName: params.displayName,
+        })
+      ) {
+        return true;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+
+export function resolveMentions(params: {
+  content: RoomMessageEventContent;
+  userId?: string | null;
+  displayName?: string | null;
+  text?: string;
+  mentionRegexes: RegExp[];
+}) {
+  const mentions = params.content["m.mentions"];
+  const mentionedUsers = Array.isArray(mentions?.user_ids)
+    ? new Set(mentions.user_ids)
+    : new Set<string>();
+  const textMentioned = getMatrixRuntime().channel.mentions.matchesMentionPatterns(
+    params.text ?? "",
+    params.mentionRegexes,
+  );
+  const visibleRoomMention =
+    hasVisibleRoomMention(params.text) || hasVisibleRoomMention(params.content.formatted_body);
+
+  // Check formatted_body for matrix.to mention links (legacy/alternative mention format)
+  const mentionedInFormattedBody = params.userId
+    ? checkFormattedBodyMention({
+        formattedBody: params.content.formatted_body,
+        userId: params.userId,
+        displayName: params.displayName,
+        mentionRegexes: params.mentionRegexes,
+      })
+    : false;
+  const metadataBackedUserMention = Boolean(
+    params.userId &&
+    mentionedUsers.has(params.userId) &&
+    (mentionedInFormattedBody || textMentioned),
+  );
+  const metadataBackedRoomMention = Boolean(mentions?.room) && visibleRoomMention;
+  const explicitMention =
+    mentionedInFormattedBody || metadataBackedUserMention || metadataBackedRoomMention;
+
+  const wasMentioned = explicitMention || textMentioned || visibleRoomMention;
+  return { wasMentioned, hasExplicitMention: explicitMention };
+}