@openclaw/zalouser 2026.2.25 → 2026.3.2

package/src/group-policy.ts

@@ -0,0 +1,78 @@
+import type { ZalouserGroupConfig } from "./types.js";
+
+type ZalouserGroups = Record<string, ZalouserGroupConfig>;
+
+function toGroupCandidate(value?: string | null): string {
+  return value?.trim() ?? "";
+}
+
+export function normalizeZalouserGroupSlug(raw?: string | null): string {
+  const trimmed = raw?.trim().toLowerCase() ?? "";
+  if (!trimmed) {
+    return "";
+  }
+  return trimmed
+    .replace(/^#/, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function buildZalouserGroupCandidates(params: {
+  groupId?: string | null;
+  groupChannel?: string | null;
+  groupName?: string | null;
+  includeGroupIdAlias?: boolean;
+  includeWildcard?: boolean;
+}): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const push = (value?: string | null) => {
+    const normalized = toGroupCandidate(value);
+    if (!normalized || seen.has(normalized)) {
+      return;
+    }
+    seen.add(normalized);
+    out.push(normalized);
+  };
+
+  const groupId = toGroupCandidate(params.groupId);
+  const groupChannel = toGroupCandidate(params.groupChannel);
+  const groupName = toGroupCandidate(params.groupName);
+
+  push(groupId);
+  if (params.includeGroupIdAlias === true && groupId) {
+    push(`group:${groupId}`);
+  }
+  push(groupChannel);
+  push(groupName);
+  if (groupName) {
+    push(normalizeZalouserGroupSlug(groupName));
+  }
+  if (params.includeWildcard !== false) {
+    push("*");
+  }
+  return out;
+}
+
+export function findZalouserGroupEntry(
+  groups: ZalouserGroups | undefined,
+  candidates: string[],
+): ZalouserGroupConfig | undefined {
+  if (!groups) {
+    return undefined;
+  }
+  for (const candidate of candidates) {
+    const entry = groups[candidate];
+    if (entry) {
+      return entry;
+    }
+  }
+  return undefined;
+}
+
+export function isZalouserGroupEntryAllowed(entry: ZalouserGroupConfig | undefined): boolean {
+  if (!entry) {
+    return false;
+  }
+  return entry.allow !== false && entry.enabled !== false;
+}

package/src/message-sid.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatZalouserMessageSidFull,
+  parseZalouserMessageSidFull,
+  resolveZalouserMessageSid,
+  resolveZalouserReactionMessageIds,
+} from "./message-sid.js";
+
+describe("zalouser message sid helpers", () => {
+  it("parses MessageSidFull pairs", () => {
+    expect(parseZalouserMessageSidFull("111:222")).toEqual({
+      msgId: "111",
+      cliMsgId: "222",
+    });
+    expect(parseZalouserMessageSidFull("111")).toBeNull();
+    expect(parseZalouserMessageSidFull(undefined)).toBeNull();
+  });
+
+  it("resolves reaction ids from explicit params first", () => {
+    expect(
+      resolveZalouserReactionMessageIds({
+        messageId: "m-1",
+        cliMsgId: "c-1",
+        currentMessageId: "x:y",
+      }),
+    ).toEqual({
+      msgId: "m-1",
+      cliMsgId: "c-1",
+    });
+  });
+
+  it("resolves reaction ids from current message sid full", () => {
+    expect(
+      resolveZalouserReactionMessageIds({
+        currentMessageId: "m-2:c-2",
+      }),
+    ).toEqual({
+      msgId: "m-2",
+      cliMsgId: "c-2",
+    });
+  });
+
+  it("falls back to duplicated current id when no pair is available", () => {
+    expect(
+      resolveZalouserReactionMessageIds({
+        currentMessageId: "solo",
+      }),
+    ).toEqual({
+      msgId: "solo",
+      cliMsgId: "solo",
+    });
+  });
+
+  it("formats message sid fields for context payload", () => {
+    expect(formatZalouserMessageSidFull({ msgId: "1", cliMsgId: "2" })).toBe("1:2");
+    expect(formatZalouserMessageSidFull({ msgId: "1" })).toBe("1");
+    expect(formatZalouserMessageSidFull({ cliMsgId: "2" })).toBe("2");
+    expect(formatZalouserMessageSidFull({})).toBeUndefined();
+  });
+
+  it("resolves primary message sid with fallback timestamp", () => {
+    expect(resolveZalouserMessageSid({ msgId: "1", cliMsgId: "2", fallback: "t" })).toBe("1");
+    expect(resolveZalouserMessageSid({ cliMsgId: "2", fallback: "t" })).toBe("2");
+    expect(resolveZalouserMessageSid({ fallback: "t" })).toBe("t");
+  });
+});

package/src/message-sid.ts

@@ -0,0 +1,80 @@
+function toMessageSidPart(value?: string | number | null): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(Math.trunc(value));
+  }
+  return "";
+}
+
+export function parseZalouserMessageSidFull(
+  value?: string | number | null,
+): { msgId: string; cliMsgId: string } | null {
+  const raw = toMessageSidPart(value);
+  if (!raw) {
+    return null;
+  }
+  const [msgIdPart, cliMsgIdPart] = raw.split(":").map((entry) => entry.trim());
+  if (!msgIdPart || !cliMsgIdPart) {
+    return null;
+  }
+  return { msgId: msgIdPart, cliMsgId: cliMsgIdPart };
+}
+
+export function resolveZalouserReactionMessageIds(params: {
+  messageId?: string;
+  cliMsgId?: string;
+  currentMessageId?: string | number;
+}): { msgId: string; cliMsgId: string } | null {
+  const explicitMessageId = toMessageSidPart(params.messageId);
+  const explicitCliMsgId = toMessageSidPart(params.cliMsgId);
+  if (explicitMessageId && explicitCliMsgId) {
+    return { msgId: explicitMessageId, cliMsgId: explicitCliMsgId };
+  }
+
+  const parsedFromCurrent = parseZalouserMessageSidFull(params.currentMessageId);
+  if (parsedFromCurrent) {
+    return parsedFromCurrent;
+  }
+
+  const currentRaw = toMessageSidPart(params.currentMessageId);
+  if (!currentRaw) {
+    return null;
+  }
+  if (explicitMessageId && !explicitCliMsgId) {
+    return { msgId: explicitMessageId, cliMsgId: currentRaw };
+  }
+  if (!explicitMessageId && explicitCliMsgId) {
+    return { msgId: currentRaw, cliMsgId: explicitCliMsgId };
+  }
+  return { msgId: currentRaw, cliMsgId: currentRaw };
+}
+
+export function formatZalouserMessageSidFull(params: {
+  msgId?: string | null;
+  cliMsgId?: string | null;
+}): string | undefined {
+  const msgId = toMessageSidPart(params.msgId);
+  const cliMsgId = toMessageSidPart(params.cliMsgId);
+  if (!msgId && !cliMsgId) {
+    return undefined;
+  }
+  if (msgId && cliMsgId) {
+    return `${msgId}:${cliMsgId}`;
+  }
+  return msgId || cliMsgId || undefined;
+}
+
+export function resolveZalouserMessageSid(params: {
+  msgId?: string | null;
+  cliMsgId?: string | null;
+  fallback?: string | null;
+}): string | undefined {
+  const msgId = toMessageSidPart(params.msgId);
+  const cliMsgId = toMessageSidPart(params.cliMsgId);
+  if (msgId || cliMsgId) {
+    return msgId || cliMsgId;
+  }
+  return toMessageSidPart(params.fallback) || undefined;
+}

package/src/monitor.account-scope.test.ts

@@ -0,0 +1,123 @@
+import type { OpenClawConfig, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { __testing } from "./monitor.js";
+import { setZalouserRuntime } from "./runtime.js";
+import type { ResolvedZalouserAccount, ZaloInboundMessage } from "./types.js";
+
+const sendMessageZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+const sendTypingZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+const sendDeliveredZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+const sendSeenZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+
+vi.mock("./send.js", () => ({
+  sendMessageZalouser: sendMessageZalouserMock,
+  sendTypingZalouser: sendTypingZalouserMock,
+  sendDeliveredZalouser: sendDeliveredZalouserMock,
+  sendSeenZalouser: sendSeenZalouserMock,
+}));
+
+describe("zalouser monitor pairing account scoping", () => {
+  it("scopes DM pairing-store reads and pairing requests to accountId", async () => {
+    const readAllowFromStore = vi.fn(
+      async (
+        channelOrParams:
+          | string
+          | {
+              channel?: string;
+              accountId?: string;
+            },
+        _env?: NodeJS.ProcessEnv,
+        accountId?: string,
+      ) => {
+        const scopedAccountId =
+          typeof channelOrParams === "object" && channelOrParams !== null
+            ? channelOrParams.accountId
+            : accountId;
+        return scopedAccountId === "beta" ? [] : ["attacker"];
+      },
+    );
+    const upsertPairingRequest = vi.fn(async () => ({ code: "PAIRME88", created: true }));
+
+    setZalouserRuntime({
+      logging: {
+        shouldLogVerbose: () => false,
+      },
+      channel: {
+        pairing: {
+          readAllowFromStore,
+          upsertPairingRequest,
+          buildPairingReply: vi.fn(() => "pairing reply"),
+        },
+        commands: {
+          shouldComputeCommandAuthorized: vi.fn(() => false),
+          resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false),
+          isControlCommandMessage: vi.fn(() => false),
+        },
+      },
+    } as unknown as PluginRuntime);
+
+    const account: ResolvedZalouserAccount = {
+      accountId: "beta",
+      enabled: true,
+      profile: "beta",
+      authenticated: true,
+      config: {
+        dmPolicy: "pairing",
+        allowFrom: [],
+      },
+    };
+
+    const config: OpenClawConfig = {
+      channels: {
+        zalouser: {
+          accounts: {
+            alpha: { dmPolicy: "pairing", allowFrom: [] },
+            beta: { dmPolicy: "pairing", allowFrom: [] },
+          },
+        },
+      },
+    };
+
+    const message: ZaloInboundMessage = {
+      threadId: "chat-1",
+      isGroup: false,
+      senderId: "attacker",
+      senderName: "Attacker",
+      groupName: undefined,
+      timestampMs: Date.now(),
+      msgId: "msg-1",
+      content: "hello",
+      raw: { source: "test" },
+    };
+
+    const runtime: RuntimeEnv = {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: ((code: number): never => {
+        throw new Error(`exit ${code}`);
+      }) as RuntimeEnv["exit"],
+    };
+
+    await __testing.processMessage({
+      message,
+      account,
+      config,
+      runtime,
+    });
+
+    expect(readAllowFromStore).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "zalouser",
+        accountId: "beta",
+      }),
+    );
+    expect(upsertPairingRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "zalouser",
+        id: "attacker",
+        accountId: "beta",
+      }),
+    );
+    expect(sendMessageZalouserMock).toHaveBeenCalled();
+  });
+});

package/src/monitor.group-gating.test.ts

@@ -0,0 +1,216 @@
+import type { OpenClawConfig, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { __testing } from "./monitor.js";
+import { setZalouserRuntime } from "./runtime.js";
+import type { ResolvedZalouserAccount, ZaloInboundMessage } from "./types.js";
+
+const sendMessageZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+const sendTypingZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+const sendDeliveredZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+const sendSeenZalouserMock = vi.hoisted(() => vi.fn(async () => {}));
+
+vi.mock("./send.js", () => ({
+  sendMessageZalouser: sendMessageZalouserMock,
+  sendTypingZalouser: sendTypingZalouserMock,
+  sendDeliveredZalouser: sendDeliveredZalouserMock,
+  sendSeenZalouser: sendSeenZalouserMock,
+}));
+
+function createAccount(): ResolvedZalouserAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    profile: "default",
+    authenticated: true,
+    config: {
+      groupPolicy: "open",
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  };
+}
+
+function createConfig(): OpenClawConfig {
+  return {
+    channels: {
+      zalouser: {
+        enabled: true,
+        groups: {
+          "*": { requireMention: true },
+        },
+      },
+    },
+  };
+}
+
+function createRuntimeEnv(): RuntimeEnv {
+  return {
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: ((code: number): never => {
+      throw new Error(`exit ${code}`);
+    }) as RuntimeEnv["exit"],
+  };
+}
+
+function installRuntime(params: { commandAuthorized: boolean }) {
+  const dispatchReplyWithBufferedBlockDispatcher = vi.fn(async ({ dispatcherOptions, ctx }) => {
+    await dispatcherOptions.typingCallbacks?.onReplyStart?.();
+    return { queuedFinal: false, counts: { tool: 0, block: 0, final: 0 }, ctx };
+  });
+
+  setZalouserRuntime({
+    logging: {
+      shouldLogVerbose: () => false,
+    },
+    channel: {
+      pairing: {
+        readAllowFromStore: vi.fn(async () => []),
+        upsertPairingRequest: vi.fn(async () => ({ code: "PAIR", created: true })),
+        buildPairingReply: vi.fn(() => "pair"),
+      },
+      commands: {
+        shouldComputeCommandAuthorized: vi.fn((body: string) => body.trim().startsWith("/")),
+        resolveCommandAuthorizedFromAuthorizers: vi.fn(() => params.commandAuthorized),
+        isControlCommandMessage: vi.fn((body: string) => body.trim().startsWith("/")),
+        shouldHandleTextCommands: vi.fn(() => true),
+      },
+      mentions: {
+        buildMentionRegexes: vi.fn(() => []),
+        matchesMentionWithExplicit: vi.fn(
+          (input) => input.explicit?.isExplicitlyMentioned === true,
+        ),
+      },
+      groups: {
+        resolveRequireMention: vi.fn((input) => {
+          const cfg = input.cfg as OpenClawConfig;
+          const groupCfg = cfg.channels?.zalouser?.groups ?? {};
+          const groupEntry = input.groupId ? groupCfg[input.groupId] : undefined;
+          const defaultEntry = groupCfg["*"];
+          if (typeof groupEntry?.requireMention === "boolean") {
+            return groupEntry.requireMention;
+          }
+          if (typeof defaultEntry?.requireMention === "boolean") {
+            return defaultEntry.requireMention;
+          }
+          return true;
+        }),
+      },
+      routing: {
+        resolveAgentRoute: vi.fn(() => ({
+          agentId: "main",
+          sessionKey: "agent:main:zalouser:group:1",
+          accountId: "default",
+          mainSessionKey: "agent:main:main",
+        })),
+      },
+      session: {
+        resolveStorePath: vi.fn(() => "/tmp"),
+        readSessionUpdatedAt: vi.fn(() => undefined),
+        recordInboundSession: vi.fn(async () => {}),
+      },
+      reply: {
+        resolveEnvelopeFormatOptions: vi.fn(() => undefined),
+        formatAgentEnvelope: vi.fn(({ body }) => body),
+        finalizeInboundContext: vi.fn((ctx) => ctx),
+        dispatchReplyWithBufferedBlockDispatcher,
+      },
+      text: {
+        resolveMarkdownTableMode: vi.fn(() => "code"),
+        convertMarkdownTables: vi.fn((text: string) => text),
+        resolveChunkMode: vi.fn(() => "line"),
+        chunkMarkdownTextWithMode: vi.fn((text: string) => [text]),
+      },
+    },
+  } as unknown as PluginRuntime);
+
+  return { dispatchReplyWithBufferedBlockDispatcher };
+}
+
+function createGroupMessage(overrides: Partial<ZaloInboundMessage> = {}): ZaloInboundMessage {
+  return {
+    threadId: "g-1",
+    isGroup: true,
+    senderId: "123",
+    senderName: "Alice",
+    groupName: "Team",
+    content: "hello",
+    timestampMs: Date.now(),
+    msgId: "m-1",
+    hasAnyMention: false,
+    wasExplicitlyMentioned: false,
+    canResolveExplicitMention: true,
+    implicitMention: false,
+    raw: { source: "test" },
+    ...overrides,
+  };
+}
+
+describe("zalouser monitor group mention gating", () => {
+  beforeEach(() => {
+    sendMessageZalouserMock.mockClear();
+    sendTypingZalouserMock.mockClear();
+    sendDeliveredZalouserMock.mockClear();
+    sendSeenZalouserMock.mockClear();
+  });
+
+  it("skips unmentioned group messages when requireMention=true", async () => {
+    const { dispatchReplyWithBufferedBlockDispatcher } = installRuntime({
+      commandAuthorized: false,
+    });
+    await __testing.processMessage({
+      message: createGroupMessage(),
+      account: createAccount(),
+      config: createConfig(),
+      runtime: createRuntimeEnv(),
+    });
+
+    expect(dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendTypingZalouserMock).not.toHaveBeenCalled();
+  });
+
+  it("dispatches explicitly-mentioned group messages and marks WasMentioned", async () => {
+    const { dispatchReplyWithBufferedBlockDispatcher } = installRuntime({
+      commandAuthorized: false,
+    });
+    await __testing.processMessage({
+      message: createGroupMessage({
+        hasAnyMention: true,
+        wasExplicitlyMentioned: true,
+        content: "ping @bot",
+      }),
+      account: createAccount(),
+      config: createConfig(),
+      runtime: createRuntimeEnv(),
+    });
+
+    expect(dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1);
+    const callArg = dispatchReplyWithBufferedBlockDispatcher.mock.calls[0]?.[0];
+    expect(callArg?.ctx?.WasMentioned).toBe(true);
+    expect(sendTypingZalouserMock).toHaveBeenCalledWith("g-1", {
+      profile: "default",
+      isGroup: true,
+    });
+  });
+
+  it("allows authorized control commands to bypass mention gating", async () => {
+    const { dispatchReplyWithBufferedBlockDispatcher } = installRuntime({
+      commandAuthorized: true,
+    });
+    await __testing.processMessage({
+      message: createGroupMessage({
+        content: "/status",
+        hasAnyMention: false,
+        wasExplicitlyMentioned: false,
+      }),
+      account: createAccount(),
+      config: createConfig(),
+      runtime: createRuntimeEnv(),
+    });
+
+    expect(dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1);
+    const callArg = dispatchReplyWithBufferedBlockDispatcher.mock.calls[0]?.[0];
+    expect(callArg?.ctx?.WasMentioned).toBe(true);
+  });
+});