@openclaw-channel/socket-chat 1.0.2 → 1.0.3

package/README.md

@@ -39,11 +39,63 @@ channels:
   socket-chat:
     apiKey: "your-api-key"
     enabled: true
-    dmPolicy: "pairing"   # pairing | open | allowlist
-    allowFrom: []         # 允许触发 AI 的发送者 ID 白名单
-    requireMention: true  # 群组消息是否需要 @提及机器人
+
+    # DM（私聊）访问策略
+    dmPolicy: "pairing"       # pairing | open | allowlist
+    allowFrom: []             # DM 白名单（dmPolicy=allowlist/pairing 时生效）
+
+    # 群组访问策略
+    requireMention: true      # 群消息是否需要 @提及机器人
+    groupPolicy: "open"       # open | allowlist | disabled（见下方说明）
+    groups: []                # 允许的群 ID 列表（groupPolicy=allowlist 时生效）
+    groupAllowFrom: []        # 群内允许触发 AI 的发送者 ID/昵称列表
+```
+
+### 群组访问控制
+
+群消息经过**三层**依次检查，任意一层不通过则丢弃该消息：
+
+#### 第一层：群级（哪些群允许触发 AI）
+
+| `groupPolicy` | 行为 |
+|--------------|------|
+| `open`（默认）| bot 所在所有群均可触发 |
+| `allowlist` | 仅 `groups` 列表中的群可触发；首次被拦截时向该群发一条提醒（进程内只发一次） |
+| `disabled` | 禁止所有群消息触发 AI，静默丢弃 |
+
+```yaml
+channels:
+  socket-chat:
+    groupPolicy: allowlist
+    groups:
+      - "R:10804599808581977"
+      - "R:another_group_id"
 ```
 
+#### 第二层：sender 级（群内哪些人可以触发 AI）
+
+`groupAllowFrom` 为空时不限制（允许群内所有成员）。支持按 `senderId` 或 `senderName` 匹配，大小写不敏感，支持通配符 `*`。
+
+```yaml
+channels:
+  socket-chat:
+    groupAllowFrom:
+      - "wxid_123456"   # 按 senderId 精确匹配
+      - "Alice"         # 按 senderName 匹配
+      - "*"             # 允许所有成员
+```
+
+被拦截的 sender 静默丢弃，不向群发任何提示。
+
+#### 第三层：@提及检查
+
+`requireMention: true`（默认）时，群消息必须满足以下任意条件之一：
+- 平台传来 `isGroupMention: true`
+- 消息内容包含 `@{robotId}`
+
+> **注意**：媒体消息（图片、视频等）无法携带 @，若平台侧开启了 `forwardMediaMsg`，
+> 应在发布 MQTT 消息时主动将 `isGroupMention` 设为 `true`，避免被此层拦截。
+
 ### 多账号配置
 
 ```yaml
@@ -62,6 +114,12 @@ channels:
 
 | 字段 | 默认值 | 说明 |
 |------|--------|------|
+| `dmPolicy` | `pairing` | DM 访问策略：`pairing` / `open` / `allowlist` |
+| `allowFrom` | `[]` | DM 白名单，senderId 或 senderName 列表 |
+| `requireMention` | `true` | 群消息是否需要 @提及机器人 |
+| `groupPolicy` | `open` | 群访问策略：`open` / `allowlist` / `disabled` |
+| `groups` | `[]` | 允许的群 ID 列表（`groupPolicy=allowlist` 时生效） |
+| `groupAllowFrom` | `[]` | 群内允许触发 AI 的发送者 ID/昵称列表，空=不限制 |
 | `mqttConfigTtlSec` | `300` | MQTT 配置缓存时间（秒） |
 | `maxReconnectAttempts` | `10` | MQTT 断线最大重连次数 |
 | `reconnectBaseDelayMs` | `2000` | 重连基础延迟（毫秒，指数退避） |
@@ -70,6 +128,8 @@ channels:
 
 ## 通过 CLI 添加账号
 
+apiKey 从微秘书平台[个人中心](https://wechat.aibotk.com/user/info)获取
+
 ```bash
 openclaw channels add socket-chat --token <apiKey>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-channel/socket-chat",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "OpenClaw Socket Chat channel plugin — MQTT-based IM bridge",
   "type": "module",
   "publishConfig": {

package/src/config-schema.ts

@@ -32,12 +32,30 @@ export const SocketChatAccountConfigSchema = z.object({
   enabled: z.boolean().optional(),
   /** DM 安全策略 */
   dmPolicy: z.enum(["pairing", "open", "allowlist"]).optional(),
-  /** 允许触发 AI 的发送者 ID 列表 */
+  /** 允许触发 AI 的发送者 ID 列表（DM 用） */
   allowFrom: z.array(z.string()).optional(),
   /** 默认发消息目标（contactId 或 group:groupId） */
   defaultTo: z.string().optional(),
   /** 群组消息是否需要 @提及 bot 才触发 */
   requireMention: z.boolean().optional(),
+  /**
+   * 群组访问策略（第一层：哪些群允许触发 AI）
+   *   - "open"（默认）：bot 所在所有群均可触发
+   *   - "allowlist"：仅 groups 列表中的群可触发
+   *   - "disabled"：禁止所有群消息触发 AI
+   */
+  groupPolicy: z.enum(["open", "allowlist", "disabled"]).optional(),
+  /**
+   * 允许触发 AI 的群 ID 列表（第一层群级白名单）
+   * groupPolicy="allowlist" 时生效；groupPolicy="open" 时忽略
+   * 示例：["R:10804599808581977", "R:xxx"]
+   */
+  groups: z.array(z.string()).optional(),
+  /**
+   * 群内允许触发 AI 的发送者 ID 列表（第二层 sender 级白名单）
+   * 不配置或为空则允许群内所有成员触发（受 requireMention 约束）
+   */
+  groupAllowFrom: z.array(z.string()).optional(),
   /** MQTT 连接配置缓存 TTL（秒），默认 300 */
   mqttConfigTtlSec: z.number().optional(),
   /** MQTT 重连最大次数，默认 10 */

package/src/inbound.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, it, vi } from "vitest";
-import { handleInboundMessage } from "./inbound.js";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { handleInboundMessage, _resetNotifiedGroupsForTest } from "./inbound.js";
 import type { SocketChatInboundMessage } from "./types.js";
 import type { CoreConfig } from "./config.js";
 
@@ -737,3 +737,176 @@ describe("handleInboundMessage — edge cases", () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// Group access control — tier 1 (groupId) + tier 2 (sender)
+// ---------------------------------------------------------------------------
+
+describe("handleInboundMessage — group access control (tier 1: groupId)", () => {
+  beforeEach(() => {
+    _resetNotifiedGroupsForTest();
+  });
+
+  it("allows all groups when groupPolicy=open (default)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", robotId: "robot_abc", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("blocks all groups when groupPolicy=disabled (no notification)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "disabled" } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("allows group in allowlist when groupPolicy=allowlist", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: {
+        "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"], requireMention: false },
+      },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:allowed_group", robotId: "robot_abc", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("blocks unlisted group and sends one-time notification", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"] } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:other_group", groupName: "测试群", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).toHaveBeenCalledOnce();
+    expect(sendReply.mock.calls[0]?.[0]).toBe("group:R:other_group");
+    expect(sendReply.mock.calls[0]?.[1]).toContain("R:other_group");
+  });
+
+  it("does NOT send second notification for same blocked group", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"] } },
+    });
+    const sendReply = vi.fn(async () => {});
+    const msg = makeMsg({ isGroup: true, groupId: "R:notify_once_group", isGroupMention: true });
+    await handleInboundMessage({ msg, accountId: "default", ctx: ctx as never, log: ctx.log, sendReply });
+    await handleInboundMessage({ msg, accountId: "default", ctx: ctx as never, log: ctx.log, sendReply });
+    expect(sendReply).toHaveBeenCalledOnce();
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+  });
+
+  it("blocks when groupPolicy=allowlist and groups is empty (no notification)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: [] } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("allows wildcard '*' in groups list", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["*"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", robotId: "robot_abc", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+});
+
+describe("handleInboundMessage — group access control (tier 2: sender)", () => {
+  beforeEach(() => {
+    _resetNotifiedGroupsForTest();
+  });
+
+  it("allows all senders when groupAllowFrom is empty", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_anyone", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("allows sender matching groupAllowFrom by ID", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["wxid_allowed"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_allowed", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("allows sender matching groupAllowFrom by name (case-insensitive)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["alice"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_unknown", senderName: "Alice", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("blocks sender not in groupAllowFrom (silent drop)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["wxid_allowed"], requireMention: false } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_stranger", senderName: "Stranger", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("allows wildcard '*' in groupAllowFrom", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["*"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_anyone", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+});

package/src/inbound.ts

@@ -113,6 +113,114 @@ async function enforceDmAccess(params: {
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// 群组访问控制 — 第一层（groupId 级别）+ 第二层（sender 级别）
+// ---------------------------------------------------------------------------
+
+/**
+ * 记录已发送过"群未授权"提醒的群，键为 `${accountId}:${groupId}`。
+ * 进程内只提醒一次，避免每条消息都重复发送。
+ */
+const notifiedGroups = new Set<string>();
+
+/** 仅供测试使用：重置一次性提醒状态。 */
+export function _resetNotifiedGroupsForTest(): void {
+  notifiedGroups.clear();
+}
+
+/**
+ * 规范化群/发送者 ID，去除前缀、空格、转小写，便于白名单对比。
+ */
+function normalizeSocketChatId(raw: string): string {
+  return raw.replace(/^(socket-chat|sc):/i, "").trim().toLowerCase();
+}
+
+/**
+ * 第一层：检查当前群是否被允许触发 AI。
+ *
+ * - groupPolicy="open"（默认）：所有群均可触发
+ * - groupPolicy="allowlist"：仅 groups 列表中的群可触发，不在列表的群收到一次提醒
+ * - groupPolicy="disabled"：禁止所有群消息触发 AI
+ *
+ * 返回 `{ allowed, notify }`:
+ *   - allowed=false + notify=true 表示首次拦截，调用方应发送提醒消息
+ *   - allowed=false + notify=false 表示已提醒过，静默忽略
+ */
+function checkGroupAccess(params: {
+  groupId: string;
+  account: ResolvedSocketChatAccount;
+  log: LogSink;
+  accountId: string;
+}): { allowed: boolean; notify: boolean } {
+  const { groupId, account, log, accountId } = params;
+  const groupPolicy = account.config.groupPolicy ?? "open";
+
+  if (groupPolicy === "disabled") {
+    log.info(`[${accountId}] group msg blocked (groupPolicy=disabled)`);
+    return { allowed: false, notify: false };
+  }
+
+  if (groupPolicy === "open") {
+    return { allowed: true, notify: false };
+  }
+
+  // allowlist：检查 groupId 是否在 groups 名单中
+  const groups = (account.config.groups ?? []).map(normalizeSocketChatId);
+  if (groups.length === 0) {
+    log.info(`[${accountId}] group ${groupId} blocked (groupPolicy=allowlist, groups is empty)`);
+    return { allowed: false, notify: false };
+  }
+
+  const normalizedGroupId = normalizeSocketChatId(groupId);
+  if (groups.includes("*") || groups.includes(normalizedGroupId)) {
+    return { allowed: true, notify: false };
+  }
+
+  log.info(`[${accountId}] group ${groupId} not in groups allowlist (groupPolicy=allowlist)`);
+
+  // 判断是否需要发送一次性提醒
+  const notifyKey = `${accountId}:${groupId}`;
+  if (notifiedGroups.has(notifyKey)) {
+    return { allowed: false, notify: false };
+  }
+  notifiedGroups.add(notifyKey);
+  return { allowed: false, notify: true };
+}
+
+/**
+ * 第二层：检查群内发送者是否被允许触发 AI。
+ *
+ * 仅当 groupAllowFrom 非空时生效；为空则允许群内所有成员。
+ */
+function checkGroupSenderAccess(params: {
+  senderId: string;
+  senderName: string | undefined;
+  account: ResolvedSocketChatAccount;
+  log: LogSink;
+  accountId: string;
+}): boolean {
+  const { senderId, senderName, account, log, accountId } = params;
+  const groupAllowFrom = (account.config.groupAllowFrom ?? []).map(normalizeSocketChatId);
+
+  // 未配置 sender 白名单 → 不限制
+  if (groupAllowFrom.length === 0) return true;
+  if (groupAllowFrom.includes("*")) return true;
+
+  const normalizedSenderId = normalizeSocketChatId(senderId);
+  const normalizedSenderName = senderName ? senderName.trim().toLowerCase() : undefined;
+
+  const allowed =
+    groupAllowFrom.includes(normalizedSenderId) ||
+    (normalizedSenderName !== undefined && groupAllowFrom.includes(normalizedSenderName));
+
+  if (!allowed) {
+    log.info(
+      `[${accountId}] group sender ${senderId} not in groupAllowFrom`,
+    );
+  }
+  return allowed;
+}
+
 // ---------------------------------------------------------------------------
 // 群组消息 @提及检查
 // ---------------------------------------------------------------------------
@@ -208,7 +316,34 @@ export async function handleInboundMessage(params: {
     return;
   }
 
-  // ---- 2. 群组 @提及检查 ----
+  // ---- 2. 群组访问控制（第一层：群级 + 第二层：sender 级）----
+  if (msg.isGroup) {
+    const groupId = msg.groupId ?? msg.senderId;
+
+    // 第一层：groupId 是否在允许列表中
+    const groupAccess = checkGroupAccess({ groupId, account, log, accountId });
+    if (!groupAccess.allowed) {
+      if (groupAccess.notify) {
+        await sendReply(
+          `group:${groupId}`,
+          `此群（${msg.groupName ?? groupId}）未获授权使用 AI 服务。如需开启，请联系管理员将群 ID "${groupId}" 加入 groups 配置。`,
+        );
+      }
+      return;
+    }
+
+    // 第二层：群内发送者是否被允许
+    const senderAccessAllowed = checkGroupSenderAccess({
+      senderId: msg.senderId,
+      senderName: msg.senderName,
+      account,
+      log,
+      accountId,
+    });
+    if (!senderAccessAllowed) return;
+  }
+
+  // ---- 3. 群组 @提及检查 ----
   // robotId 从 MQTT config 传入（由 mqtt-client.ts 调用时提供）
   // 此处从 msg.robotId 字段取（平台在每条消息中会带上 robotId）
   const mentionAllowed = checkGroupMention({