@openclaw/whatsapp 2026.5.1-beta.1

package/src/inbound/access-control.test.ts

@@ -0,0 +1,375 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+  readAllowFromStoreMock,
+  sendMessageMock,
+  getAccessControlTestConfig,
+  setAccessControlTestConfig,
+  setupAccessControlTestHarness,
+  upsertPairingRequestMock,
+} from "./access-control.test-harness.js";
+
+setupAccessControlTestHarness();
+let checkInboundAccessControl: typeof import("./access-control.js").checkInboundAccessControl;
+let resolveWhatsAppCommandAuthorized: typeof import("../inbound-policy.js").resolveWhatsAppCommandAuthorized;
+
+beforeAll(async () => {
+  ({ checkInboundAccessControl } = await import("./access-control.js"));
+  ({ resolveWhatsAppCommandAuthorized } = await import("../inbound-policy.js"));
+});
+
+async function checkUnauthorizedWorkDmSender() {
+  return checkInboundAccessControl({
+    cfg: getAccessControlTestConfig() as never,
+    accountId: "work",
+    from: "+15550001111",
+    selfE164: "+15550009999",
+    senderE164: "+15550001111",
+    group: false,
+    pushName: "Stranger",
+    isFromMe: false,
+    sock: { sendMessage: sendMessageMock },
+    remoteJid: "15550001111@s.whatsapp.net",
+  });
+}
+
+function expectSilentlyBlocked(result: { allowed: boolean }) {
+  expect(result.allowed).toBe(false);
+  expect(upsertPairingRequestMock).not.toHaveBeenCalled();
+  expect(sendMessageMock).not.toHaveBeenCalled();
+}
+
+async function checkCommandAuthorizedForDm(params: {
+  cfg: Record<string, unknown>;
+  accountId?: string;
+  from?: string;
+  senderE164?: string;
+  selfE164?: string;
+}) {
+  return await resolveWhatsAppCommandAuthorized({
+    cfg: params.cfg as never,
+    msg: {
+      accountId: params.accountId ?? "work",
+      chatType: "direct",
+      from: params.from ?? "+15550001111",
+      senderE164: params.senderE164 ?? params.from ?? "+15550001111",
+      selfE164: params.selfE164 ?? "+15550009999",
+      body: "/status",
+      to: params.selfE164 ?? "+15550009999",
+    } as never,
+  });
+}
+
+async function checkCommandAuthorizedForGroup(params: {
+  cfg: Record<string, unknown>;
+  accountId?: string;
+  from?: string;
+  senderE164?: string;
+  selfE164?: string;
+}) {
+  return await resolveWhatsAppCommandAuthorized({
+    cfg: params.cfg as never,
+    msg: {
+      accountId: params.accountId ?? "work",
+      chatType: "group",
+      from: params.from ?? "120363401234567890@g.us",
+      conversationId: params.from ?? "120363401234567890@g.us",
+      chatId: params.from ?? "120363401234567890@g.us",
+      senderE164: params.senderE164 ?? "+15550001111",
+      selfE164: params.selfE164 ?? "+15550009999",
+      body: "/status",
+      to: params.selfE164 ?? "+15550009999",
+    } as never,
+  });
+}
+
+describe("checkInboundAccessControl pairing grace", () => {
+  async function runPairingGraceCase(messageTimestampMs: number) {
+    const connectedAtMs = 1_000_000;
+    return await checkInboundAccessControl({
+      cfg: getAccessControlTestConfig() as never,
+      accountId: "default",
+      from: "+15550001111",
+      selfE164: "+15550009999",
+      senderE164: "+15550001111",
+      group: false,
+      pushName: "Sam",
+      isFromMe: false,
+      messageTimestampMs,
+      connectedAtMs,
+      pairingGraceMs: 30_000,
+      sock: { sendMessage: sendMessageMock },
+      remoteJid: "15550001111@s.whatsapp.net",
+    });
+  }
+
+  it("suppresses pairing replies for historical DMs on connect", async () => {
+    const result = await runPairingGraceCase(1_000_000 - 31_000);
+
+    expect(result.allowed).toBe(false);
+    expect(upsertPairingRequestMock).not.toHaveBeenCalled();
+    expect(sendMessageMock).not.toHaveBeenCalled();
+  });
+
+  it("sends pairing replies for live DMs", async () => {
+    const result = await runPairingGraceCase(1_000_000 - 10_000);
+
+    expect(result.allowed).toBe(false);
+    expect(upsertPairingRequestMock).toHaveBeenCalled();
+    expect(sendMessageMock).toHaveBeenCalled();
+  });
+});
+
+describe("WhatsApp dmPolicy precedence", () => {
+  it("uses account-level dmPolicy instead of channel-level (#8736)", async () => {
+    // Channel-level says "pairing" but the account-level says "allowlist".
+    // The account-level override should take precedence, so an unauthorized
+    // sender should be blocked silently (no pairing reply).
+    const cfg = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "pairing",
+          accounts: {
+            work: {
+              dmPolicy: "allowlist",
+              allowFrom: ["+15559999999"],
+            },
+          },
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkUnauthorizedWorkDmSender();
+    const commandAuthorized = await checkCommandAuthorizedForDm({ cfg });
+    expectSilentlyBlocked(result);
+    expect(commandAuthorized).toBe(false);
+  });
+
+  it("inherits channel-level dmPolicy when account-level dmPolicy is unset", async () => {
+    // Account has allowFrom set, but no dmPolicy override. Should inherit the channel default.
+    // With dmPolicy=allowlist, unauthorized senders are silently blocked.
+    const cfg = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "allowlist",
+          accounts: {
+            work: {
+              allowFrom: ["+15559999999"],
+            },
+          },
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkUnauthorizedWorkDmSender();
+    const commandAuthorized = await checkCommandAuthorizedForDm({ cfg });
+    expectSilentlyBlocked(result);
+    expect(commandAuthorized).toBe(false);
+  });
+
+  it("does not merge persisted pairing approvals in allowlist mode", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "allowlist",
+          accounts: {
+            work: {
+              allowFrom: ["+15559999999"],
+            },
+          },
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+    readAllowFromStoreMock.mockResolvedValue(["+15550001111"]);
+
+    const result = await checkUnauthorizedWorkDmSender();
+    const commandAuthorized = await checkCommandAuthorizedForDm({ cfg });
+
+    expectSilentlyBlocked(result);
+    expect(commandAuthorized).toBe(false);
+    expect(readAllowFromStoreMock).not.toHaveBeenCalled();
+  });
+
+  it("always allows same-phone DMs even when allowFrom is restrictive", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "pairing",
+          allowFrom: ["+15550001111"],
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkInboundAccessControl({
+      cfg: getAccessControlTestConfig() as never,
+      accountId: "default",
+      from: "+15550009999",
+      selfE164: "+15550009999",
+      senderE164: "+15550009999",
+      group: false,
+      pushName: "Owner",
+      isFromMe: false,
+      sock: { sendMessage: sendMessageMock },
+      remoteJid: "15550009999@s.whatsapp.net",
+    });
+    const commandAuthorized = await checkCommandAuthorizedForDm({
+      cfg,
+      accountId: "default",
+      from: "+15550009999",
+      senderE164: "+15550009999",
+      selfE164: "+15550009999",
+    });
+
+    expect(result.allowed).toBe(true);
+    expect(commandAuthorized).toBe(true);
+    expect(upsertPairingRequestMock).not.toHaveBeenCalled();
+    expect(sendMessageMock).not.toHaveBeenCalled();
+  });
+
+  it("allows DMs from generic message sender access groups", async () => {
+    const cfg = {
+      accessGroups: {
+        owners: {
+          type: "message.senders",
+          members: {
+            whatsapp: ["+15550001111"],
+          },
+        },
+      },
+      channels: {
+        whatsapp: {
+          dmPolicy: "allowlist",
+          accounts: {
+            work: {
+              allowFrom: ["accessGroup:owners"],
+            },
+          },
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkInboundAccessControl({
+      cfg: getAccessControlTestConfig() as never,
+      accountId: "work",
+      from: "+15550001111",
+      selfE164: "+15550009999",
+      senderE164: "+15550001111",
+      group: false,
+      pushName: "Sam",
+      isFromMe: false,
+      sock: { sendMessage: sendMessageMock },
+      remoteJid: "15550001111@s.whatsapp.net",
+    });
+    const commandAuthorized = await checkCommandAuthorizedForDm({ cfg });
+
+    expect(result.allowed).toBe(true);
+    expect(commandAuthorized).toBe(true);
+    expect(upsertPairingRequestMock).not.toHaveBeenCalled();
+    expect(sendMessageMock).not.toHaveBeenCalled();
+  });
+
+  it("allows group messages from generic message sender access groups", async () => {
+    const cfg = {
+      accessGroups: {
+        operators: {
+          type: "message.senders",
+          members: {
+            whatsapp: ["+15550001111"],
+          },
+        },
+      },
+      channels: {
+        whatsapp: {
+          dmPolicy: "allowlist",
+          groupPolicy: "allowlist",
+          groupAllowFrom: ["accessGroup:operators"],
+          accounts: {
+            work: {
+              allowFrom: ["+15559999999"],
+            },
+          },
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkInboundAccessControl({
+      cfg: getAccessControlTestConfig() as never,
+      accountId: "work",
+      from: "120363401234567890@g.us",
+      selfE164: "+15550009999",
+      senderE164: "+15550001111",
+      group: true,
+      pushName: "Sam",
+      isFromMe: false,
+      sock: { sendMessage: sendMessageMock },
+      remoteJid: "120363401234567890@g.us",
+    });
+    const commandAuthorized = await checkCommandAuthorizedForGroup({ cfg });
+
+    expect(result.allowed).toBe(true);
+    expect(commandAuthorized).toBe(true);
+    expect(upsertPairingRequestMock).not.toHaveBeenCalled();
+    expect(sendMessageMock).not.toHaveBeenCalled();
+  });
+
+  it("does not broaden self-chat mode to every paired DM when allowFrom is empty", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "pairing",
+          allowFrom: [],
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkInboundAccessControl({
+      cfg: getAccessControlTestConfig() as never,
+      accountId: "default",
+      from: "+15550001111",
+      selfE164: "+15550009999",
+      senderE164: "+15550001111",
+      group: false,
+      pushName: "Sam",
+      isFromMe: false,
+      sock: { sendMessage: sendMessageMock },
+      remoteJid: "15550001111@s.whatsapp.net",
+    });
+
+    expect(result.allowed).toBe(false);
+    expect(result.isSelfChat).toBe(false);
+  });
+
+  it("treats same-phone DMs as self-chat only when explicitly configured", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "pairing",
+          allowFrom: ["+15550009999"],
+        },
+      },
+    };
+    setAccessControlTestConfig(cfg);
+
+    const result = await checkInboundAccessControl({
+      cfg: getAccessControlTestConfig() as never,
+      accountId: "default",
+      from: "+15550009999",
+      selfE164: "+15550009999",
+      senderE164: "+15550009999",
+      group: false,
+      pushName: "Owner",
+      isFromMe: false,
+      sock: { sendMessage: sendMessageMock },
+      remoteJid: "15550009999@s.whatsapp.net",
+    });
+
+    expect(result.allowed).toBe(true);
+    expect(result.isSelfChat).toBe(true);
+  });
+});

package/src/inbound/access-control.ts

@@ -0,0 +1,237 @@
+import { createChannelPairingChallengeIssuer } from "openclaw/plugin-sdk/channel-pairing";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { upsertChannelPairingRequest } from "openclaw/plugin-sdk/conversation-runtime";
+import { defaultRuntime } from "openclaw/plugin-sdk/runtime-env";
+import { warnMissingProviderGroupPolicyFallbackOnce } from "openclaw/plugin-sdk/runtime-group-policy";
+import {
+  expandAllowFromWithAccessGroups,
+  readStoreAllowFromForDmPolicy,
+  resolveDmGroupAccessWithLists,
+} from "openclaw/plugin-sdk/security-runtime";
+import { resolveWhatsAppInboundPolicy } from "../inbound-policy.js";
+
+export type InboundAccessControlResult = {
+  allowed: boolean;
+  shouldMarkRead: boolean;
+  isSelfChat: boolean;
+  resolvedAccountId: string;
+};
+
+const PAIRING_REPLY_HISTORY_GRACE_MS = 30_000;
+
+function logWhatsAppVerbose(enabled: boolean | undefined, message: string) {
+  if (!enabled) {
+    return;
+  }
+  defaultRuntime.log(message);
+}
+
+export async function checkInboundAccessControl(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  from: string;
+  selfE164: string | null;
+  senderE164: string | null;
+  group: boolean;
+  pushName?: string;
+  isFromMe: boolean;
+  messageTimestampMs?: number;
+  connectedAtMs?: number;
+  pairingGraceMs?: number;
+  verbose?: boolean;
+  sock: {
+    sendMessage: (jid: string, content: { text: string }) => Promise<unknown>;
+  };
+  remoteJid: string;
+}): Promise<InboundAccessControlResult> {
+  const policy = resolveWhatsAppInboundPolicy({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    selfE164: params.selfE164,
+  });
+  const storeAllowFrom = params.group
+    ? []
+    : await readStoreAllowFromForDmPolicy({
+        provider: "whatsapp",
+        accountId: policy.account.accountId,
+        dmPolicy: policy.dmPolicy,
+        shouldRead: policy.shouldReadStorePairingApprovals,
+      });
+  const pairingGraceMs =
+    typeof params.pairingGraceMs === "number" && params.pairingGraceMs > 0
+      ? params.pairingGraceMs
+      : PAIRING_REPLY_HISTORY_GRACE_MS;
+  const suppressPairingReply =
+    typeof params.connectedAtMs === "number" &&
+    typeof params.messageTimestampMs === "number" &&
+    params.messageTimestampMs < params.connectedAtMs - pairingGraceMs;
+
+  // Group policy filtering:
+  // - "open": groups bypass allowFrom, only mention-gating applies
+  // - "disabled": block all group messages entirely
+  // - "allowlist": only allow group messages from senders in groupAllowFrom/allowFrom
+  warnMissingProviderGroupPolicyFallbackOnce({
+    providerMissingFallbackApplied: policy.providerMissingFallbackApplied,
+    providerKey: "whatsapp",
+    accountId: policy.account.accountId,
+    log: (message) => logWhatsAppVerbose(params.verbose, message),
+  });
+  const accessGroupSenderId = params.group ? (params.senderE164 ?? params.from) : params.from;
+  const isAccessGroupSenderAllowed = (senderId: string, allowEntries: string[]) => {
+    return params.group
+      ? policy.isGroupSenderAllowed(allowEntries, senderId)
+      : policy.isDmSenderAllowed(allowEntries, senderId);
+  };
+  const [allowFrom, groupAllowFrom] = await Promise.all([
+    expandAllowFromWithAccessGroups({
+      cfg: params.cfg,
+      allowFrom: params.group ? policy.configuredAllowFrom : policy.dmAllowFrom,
+      channel: "whatsapp",
+      accountId: policy.account.accountId,
+      senderId: accessGroupSenderId,
+      isSenderAllowed: isAccessGroupSenderAllowed,
+    }),
+    expandAllowFromWithAccessGroups({
+      cfg: params.cfg,
+      allowFrom: policy.groupAllowFrom,
+      channel: "whatsapp",
+      accountId: policy.account.accountId,
+      senderId: accessGroupSenderId,
+      isSenderAllowed: isAccessGroupSenderAllowed,
+    }),
+  ]);
+  const dmStoreAllowFrom = params.group
+    ? []
+    : await expandAllowFromWithAccessGroups({
+        cfg: params.cfg,
+        allowFrom: storeAllowFrom,
+        channel: "whatsapp",
+        accountId: policy.account.accountId,
+        senderId: accessGroupSenderId,
+        isSenderAllowed: isAccessGroupSenderAllowed,
+      });
+  const access = resolveDmGroupAccessWithLists({
+    isGroup: params.group,
+    dmPolicy: policy.dmPolicy,
+    groupPolicy: policy.groupPolicy,
+    allowFrom,
+    groupAllowFrom,
+    storeAllowFrom: dmStoreAllowFrom,
+    isSenderAllowed: (allowEntries) => {
+      return params.group
+        ? policy.isGroupSenderAllowed(allowEntries, params.senderE164)
+        : policy.isDmSenderAllowed(allowEntries, params.from);
+    },
+  });
+  if (params.group && access.decision !== "allow") {
+    if (access.reason === "groupPolicy=disabled") {
+      logWhatsAppVerbose(params.verbose, "Blocked group message (groupPolicy: disabled)");
+    } else if (access.reason === "groupPolicy=allowlist (empty allowlist)") {
+      logWhatsAppVerbose(
+        params.verbose,
+        "Blocked group message (groupPolicy: allowlist, no groupAllowFrom)",
+      );
+    } else {
+      logWhatsAppVerbose(
+        params.verbose,
+        `Blocked group message from ${params.senderE164 ?? "unknown sender"} (groupPolicy: allowlist)`,
+      );
+    }
+    return {
+      allowed: false,
+      shouldMarkRead: false,
+      isSelfChat: policy.isSelfChat,
+      resolvedAccountId: policy.account.accountId,
+    };
+  }
+
+  // DM access control (secure defaults): "pairing" (default) / "allowlist" / "open" / "disabled".
+  if (!params.group) {
+    if (params.isFromMe && !policy.isSamePhone(params.from)) {
+      logWhatsAppVerbose(params.verbose, "Skipping outbound DM (fromMe); no pairing reply needed.");
+      return {
+        allowed: false,
+        shouldMarkRead: false,
+        isSelfChat: policy.isSelfChat,
+        resolvedAccountId: policy.account.accountId,
+      };
+    }
+    if (access.decision === "block" && access.reason === "dmPolicy=disabled") {
+      logWhatsAppVerbose(params.verbose, "Blocked dm (dmPolicy: disabled)");
+      return {
+        allowed: false,
+        shouldMarkRead: false,
+        isSelfChat: policy.isSelfChat,
+        resolvedAccountId: policy.account.accountId,
+      };
+    }
+    if (access.decision === "pairing" && !policy.isSamePhone(params.from)) {
+      const candidate = params.from;
+      if (suppressPairingReply) {
+        logWhatsAppVerbose(
+          params.verbose,
+          `Skipping pairing reply for historical DM from ${candidate}.`,
+        );
+      } else {
+        await createChannelPairingChallengeIssuer({
+          channel: "whatsapp",
+          upsertPairingRequest: async ({ id, meta }) =>
+            await upsertChannelPairingRequest({
+              channel: "whatsapp",
+              id,
+              accountId: policy.account.accountId,
+              meta,
+            }),
+        })({
+          senderId: candidate,
+          senderIdLine: `Your WhatsApp phone number: ${candidate}`,
+          meta: { name: (params.pushName ?? "").trim() || undefined },
+          onCreated: () => {
+            logWhatsAppVerbose(
+              params.verbose,
+              `whatsapp pairing request sender=${candidate} name=${params.pushName ?? "unknown"}`,
+            );
+          },
+          sendPairingReply: async (text) => {
+            await params.sock.sendMessage(params.remoteJid, { text });
+          },
+          onReplyError: (err) => {
+            logWhatsAppVerbose(
+              params.verbose,
+              `whatsapp pairing reply failed for ${candidate}: ${String(err)}`,
+            );
+          },
+        });
+      }
+      return {
+        allowed: false,
+        shouldMarkRead: false,
+        isSelfChat: policy.isSelfChat,
+        resolvedAccountId: policy.account.accountId,
+      };
+    }
+    if (access.decision !== "allow") {
+      logWhatsAppVerbose(
+        params.verbose,
+        `Blocked unauthorized sender ${params.from} (dmPolicy=${policy.dmPolicy})`,
+      );
+      return {
+        allowed: false,
+        shouldMarkRead: false,
+        isSelfChat: policy.isSelfChat,
+        resolvedAccountId: policy.account.accountId,
+      };
+    }
+  }
+
+  return {
+    allowed: true,
+    shouldMarkRead: true,
+    isSelfChat: policy.isSelfChat,
+    resolvedAccountId: policy.account.accountId,
+  };
+}
+
+export const __testing = {
+  resolveWhatsAppInboundPolicy,
+};