@openclaw/whatsapp 2026.5.1-beta.1

package/src/heartbeat-recipients.test.ts

@@ -0,0 +1,203 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { resolveWhatsAppHeartbeatRecipients } from "./heartbeat-recipients.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+
+const loadSessionStoreMock = vi.hoisted(() => vi.fn());
+const readChannelAllowFromStoreSyncMock = vi.hoisted(() => vi.fn<() => string[]>(() => []));
+
+vi.mock("./heartbeat-recipients.runtime.js", () => ({
+  DEFAULT_ACCOUNT_ID: "default",
+  loadSessionStore: loadSessionStoreMock,
+  readChannelAllowFromStoreSync: readChannelAllowFromStoreSyncMock,
+  resolveStorePath: vi.fn(() => "/tmp/test-sessions.json"),
+  normalizeChannelId: (value?: string | null) => {
+    const trimmed = value?.trim().toLowerCase();
+    return trimmed ? (trimmed as "whatsapp") : null;
+  },
+  normalizeE164: (value?: string | null) => {
+    const digits = (value ?? "").replace(/[^\d+]/g, "");
+    if (!digits) {
+      return "";
+    }
+    return digits.startsWith("+") ? digits : `+${digits}`;
+  },
+}));
+
+function makeCfg(overrides?: Partial<OpenClawConfig>): OpenClawConfig {
+  return {
+    bindings: [],
+    channels: {},
+    ...overrides,
+  } as OpenClawConfig;
+}
+
+describe("resolveWhatsAppHeartbeatRecipients", () => {
+  function setSessionStore(store: Record<string, unknown>) {
+    loadSessionStoreMock.mockReturnValue(store);
+  }
+
+  function setAllowFromStore(entries: string[]) {
+    readChannelAllowFromStoreSyncMock.mockReturnValue(entries);
+  }
+
+  function resolveWith(
+    cfgOverrides: Partial<OpenClawConfig> = {},
+    opts?: Parameters<typeof resolveWhatsAppHeartbeatRecipients>[1],
+  ) {
+    return resolveWhatsAppHeartbeatRecipients(makeCfg(cfgOverrides), opts);
+  }
+
+  function setSingleUnauthorizedSessionWithAllowFrom() {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000099", updatedAt: 2, sessionId: "a" },
+    });
+    setAllowFromStore(["+15550000001"]);
+  }
+
+  beforeEach(() => {
+    loadSessionStoreMock.mockReset();
+    readChannelAllowFromStoreSyncMock.mockReset();
+    loadSessionStoreMock.mockReturnValue({});
+    setAllowFromStore([]);
+  });
+
+  it("uses allowFrom store recipients when session recipients are ambiguous", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000001", updatedAt: 2, sessionId: "a" },
+      b: { lastChannel: "whatsapp", lastTo: "+15550000002", updatedAt: 1, sessionId: "b" },
+    });
+    setAllowFromStore(["+15550000001"]);
+
+    const result = resolveWith();
+
+    expect(result).toEqual({ recipients: ["+15550000001"], source: "session-single" });
+  });
+
+  it("falls back to allowFrom when no session recipient is authorized", () => {
+    setSingleUnauthorizedSessionWithAllowFrom();
+
+    const result = resolveWith();
+
+    expect(result).toEqual({ recipients: ["+15550000001"], source: "allowFrom" });
+  });
+
+  it("includes both session and allowFrom recipients when --all is set", () => {
+    setSingleUnauthorizedSessionWithAllowFrom();
+
+    const result = resolveWith({}, { all: true });
+
+    expect(result).toEqual({
+      recipients: ["+15550000099", "+15550000001"],
+      source: "all",
+    });
+  });
+
+  it("returns explicit --to recipient and source flag", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000099", updatedAt: 2, sessionId: "a" },
+    });
+    const result = resolveWith({}, { to: " +1 555 000 7777 " });
+    expect(result).toEqual({ recipients: ["+15550007777"], source: "flag" });
+  });
+
+  it("returns ambiguous session recipients when no allowFrom list exists", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000001", updatedAt: 2, sessionId: "a" },
+      b: { lastChannel: "whatsapp", lastTo: "+15550000002", updatedAt: 1, sessionId: "b" },
+    });
+    const result = resolveWith();
+    expect(result).toEqual({
+      recipients: ["+15550000001", "+15550000002"],
+      source: "session-ambiguous",
+    });
+  });
+
+  it("returns single session recipient when allowFrom is empty", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000001", updatedAt: 2, sessionId: "a" },
+    });
+    const result = resolveWith();
+    expect(result).toEqual({ recipients: ["+15550000001"], source: "session-single" });
+  });
+
+  it("returns all authorized session recipients when allowFrom matches multiple", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000001", updatedAt: 2, sessionId: "a" },
+      b: { lastChannel: "whatsapp", lastTo: "+15550000002", updatedAt: 1, sessionId: "b" },
+      c: { lastChannel: "whatsapp", lastTo: "+15550000003", updatedAt: 0, sessionId: "c" },
+    });
+    setAllowFromStore(["+15550000001", "+15550000002"]);
+    const result = resolveWith();
+    expect(result).toEqual({
+      recipients: ["+15550000001", "+15550000002"],
+      source: "session-ambiguous",
+    });
+  });
+
+  it("ignores session store when session scope is global", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000001", updatedAt: 2, sessionId: "a" },
+    });
+    const result = resolveWith({
+      session: { scope: "global" } as OpenClawConfig["session"],
+      channels: { whatsapp: { allowFrom: ["*", "+15550000009"] } as never },
+    });
+    expect(result).toEqual({ recipients: ["+15550000009"], source: "allowFrom" });
+  });
+
+  it("uses the requested account allowFrom config and pairing store", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000077", updatedAt: 2, sessionId: "a" },
+    });
+    setAllowFromStore(["+15550000002"]);
+
+    const result = resolveWith(
+      {
+        channels: {
+          whatsapp: {
+            allowFrom: ["+15550000001"],
+            accounts: {
+              work: {
+                allowFrom: ["+15550000003"],
+              },
+            },
+          } as never,
+        },
+      },
+      { accountId: "work" },
+    );
+
+    expect(readChannelAllowFromStoreSyncMock).toHaveBeenCalledWith("whatsapp", process.env, "work");
+    expect(result).toEqual({
+      recipients: ["+15550000003", "+15550000002"],
+      source: "allowFrom",
+    });
+  });
+
+  it("uses configured defaultAccount allowFrom config and pairing store when accountId is omitted", () => {
+    setSessionStore({
+      a: { lastChannel: "whatsapp", lastTo: "+15550000077", updatedAt: 2, sessionId: "a" },
+    });
+    setAllowFromStore(["+15550000002"]);
+
+    const result = resolveWith({
+      channels: {
+        whatsapp: {
+          defaultAccount: "work",
+          allowFrom: ["+15550000001"],
+          accounts: {
+            work: {
+              allowFrom: ["+15550000003"],
+            },
+          },
+        } as never,
+      },
+    });
+
+    expect(readChannelAllowFromStoreSyncMock).toHaveBeenCalledWith("whatsapp", process.env, "work");
+    expect(result).toEqual({
+      recipients: ["+15550000003", "+15550000002"],
+      source: "allowFrom",
+    });
+  });
+});

package/src/heartbeat-recipients.ts

@@ -0,0 +1,104 @@
+import { resolveDefaultWhatsAppAccountId, resolveWhatsAppAccount } from "./accounts.js";
+import {
+  DEFAULT_ACCOUNT_ID,
+  loadSessionStore,
+  normalizeChannelId,
+  normalizeE164,
+  readChannelAllowFromStoreSync,
+  resolveStorePath,
+  type OpenClawConfig,
+} from "./heartbeat-recipients.runtime.js";
+
+type HeartbeatRecipientsResult = { recipients: string[]; source: string };
+type HeartbeatRecipientsOpts = { to?: string; all?: boolean; accountId?: string };
+
+function getSessionRecipients(cfg: OpenClawConfig) {
+  const sessionCfg = cfg.session;
+  const scope = sessionCfg?.scope ?? "per-sender";
+  if (scope === "global") {
+    return [];
+  }
+  const storePath = resolveStorePath(cfg.session?.store);
+  const store = loadSessionStore(storePath);
+  const isGroupKey = (key: string) =>
+    key.includes(":group:") || key.includes(":channel:") || key.includes("@g.us");
+  const isCronKey = (key: string) => key.startsWith("cron:");
+
+  const recipients = Object.entries(store)
+    .filter(([key]) => key !== "global" && key !== "unknown")
+    .filter(([key]) => !isGroupKey(key) && !isCronKey(key))
+    .map(([_, entry]) => ({
+      to:
+        normalizeChannelId(entry?.lastChannel) === "whatsapp" && entry?.lastTo
+          ? normalizeE164(entry.lastTo)
+          : "",
+      updatedAt: entry?.updatedAt ?? 0,
+    }))
+    .filter(({ to }) => to.length > 1)
+    .toSorted((a, b) => b.updatedAt - a.updatedAt);
+
+  const seen = new Set<string>();
+  return recipients.filter((recipient) => {
+    if (seen.has(recipient.to)) {
+      return false;
+    }
+    seen.add(recipient.to);
+    return true;
+  });
+}
+
+export function resolveWhatsAppHeartbeatRecipients(
+  cfg: OpenClawConfig,
+  opts: HeartbeatRecipientsOpts = {},
+): HeartbeatRecipientsResult {
+  if (opts.to) {
+    return { recipients: [normalizeE164(opts.to)], source: "flag" };
+  }
+
+  const sessionRecipients = getSessionRecipients(cfg);
+  const resolvedAccountId =
+    opts.accountId?.trim() || resolveDefaultWhatsAppAccountId(cfg) || DEFAULT_ACCOUNT_ID;
+  const configuredAllowFrom = (
+    resolveWhatsAppAccount({ cfg, accountId: resolvedAccountId }).allowFrom ?? []
+  )
+    .filter((value) => value !== "*")
+    .map(normalizeE164);
+  const storeAllowFrom = readChannelAllowFromStoreSync(
+    "whatsapp",
+    process.env,
+    resolvedAccountId,
+  ).map(normalizeE164);
+
+  const unique = (list: string[]) => [...new Set(list.filter(Boolean))];
+  const allowFrom = unique([...configuredAllowFrom, ...storeAllowFrom]);
+
+  if (opts.all) {
+    return {
+      recipients: unique([...sessionRecipients.map((entry) => entry.to), ...allowFrom]),
+      source: "all",
+    };
+  }
+
+  if (allowFrom.length > 0) {
+    const allowSet = new Set(allowFrom);
+    const authorizedSessionRecipients = sessionRecipients
+      .map((entry) => entry.to)
+      .filter((recipient) => allowSet.has(recipient));
+    if (authorizedSessionRecipients.length === 1) {
+      return { recipients: [authorizedSessionRecipients[0]], source: "session-single" };
+    }
+    if (authorizedSessionRecipients.length > 1) {
+      return { recipients: authorizedSessionRecipients, source: "session-ambiguous" };
+    }
+    return { recipients: allowFrom, source: "allowFrom" };
+  }
+
+  if (sessionRecipients.length === 1) {
+    return { recipients: [sessionRecipients[0].to], source: "session-single" };
+  }
+  if (sessionRecipients.length > 1) {
+    return { recipients: sessionRecipients.map((entry) => entry.to), source: "session-ambiguous" };
+  }
+
+  return { recipients: allowFrom, source: "allowFrom" };
+}

package/src/heartbeat.ts

@@ -0,0 +1,34 @@
+import { resolveWhatsAppAccount } from "./accounts.js";
+import { readWebAuthExistsForDecision, WHATSAPP_AUTH_UNSTABLE_CODE } from "./auth-store.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+import { loadWhatsAppChannelRuntime } from "./shared.js";
+
+export async function checkWhatsAppHeartbeatReady(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+  deps?: {
+    readWebAuthExistsForDecision?: typeof readWebAuthExistsForDecision;
+    hasActiveWebListener?: (accountId?: string) => boolean;
+  };
+}) {
+  if (params.cfg.web?.enabled === false) {
+    return { ok: false as const, reason: "whatsapp-disabled" as const };
+  }
+  const account = resolveWhatsAppAccount({ cfg: params.cfg, accountId: params.accountId });
+  const authState = await (
+    params.deps?.readWebAuthExistsForDecision ?? readWebAuthExistsForDecision
+  )(account.authDir);
+  if (authState.outcome === "unstable") {
+    return { ok: false as const, reason: WHATSAPP_AUTH_UNSTABLE_CODE };
+  }
+  if (!authState.exists) {
+    return { ok: false as const, reason: "whatsapp-not-linked" as const };
+  }
+  const listenerActive = params.deps?.hasActiveWebListener
+    ? params.deps.hasActiveWebListener(account.accountId)
+    : Boolean((await loadWhatsAppChannelRuntime()).getActiveWebListener(account.accountId));
+  if (!listenerActive) {
+    return { ok: false as const, reason: "whatsapp-not-running" as const };
+  }
+  return { ok: true as const, reason: "ok" as const };
+}

package/src/identity.ts

@@ -0,0 +1,164 @@
+import { jidToE164, normalizeE164 } from "./text-runtime.js";
+
+const WHATSAPP_LID_RE = /@(lid|hosted\.lid)$/i;
+
+export type WhatsAppIdentity = {
+  jid?: string | null;
+  lid?: string | null;
+  e164?: string | null;
+  name?: string | null;
+  label?: string | null;
+};
+
+export type WhatsAppSelfIdentity = {
+  jid?: string | null;
+  lid?: string | null;
+  e164?: string | null;
+};
+
+export type WhatsAppReplyContext = {
+  id?: string;
+  body: string;
+  sender?: WhatsAppIdentity | null;
+};
+
+type LegacySenderLike = {
+  sender?: WhatsAppIdentity;
+  senderJid?: string;
+  senderE164?: string;
+  senderName?: string;
+};
+
+type LegacySelfLike = {
+  self?: WhatsAppSelfIdentity;
+  selfJid?: string | null;
+  selfLid?: string | null;
+  selfE164?: string | null;
+};
+
+type LegacyReplyLike = {
+  replyTo?: WhatsAppReplyContext;
+  replyToId?: string;
+  replyToBody?: string;
+  replyToSender?: string;
+  replyToSenderJid?: string;
+  replyToSenderE164?: string;
+};
+
+type LegacyMentionsLike = {
+  mentions?: string[];
+  mentionedJids?: string[];
+};
+
+function normalizeDeviceScopedJid(jid: string | null | undefined): string | null {
+  return jid ? jid.replace(/:\d+/, "") : null;
+}
+
+function isLidJid(jid: string | null | undefined): boolean {
+  return Boolean(jid && WHATSAPP_LID_RE.test(jid));
+}
+
+export function resolveComparableIdentity(
+  identity: WhatsAppIdentity | WhatsAppSelfIdentity | null | undefined,
+  authDir?: string,
+): WhatsAppIdentity {
+  const rawJid = normalizeDeviceScopedJid(identity?.jid);
+  const rawLid = normalizeDeviceScopedJid(identity?.lid);
+  const lid = rawLid ?? (isLidJid(rawJid) ? rawJid : null);
+  const jid = rawJid && !isLidJid(rawJid) ? rawJid : null;
+  const e164 =
+    identity?.e164 != null
+      ? normalizeE164(identity.e164)
+      : ((jid ? jidToE164(jid, authDir ? { authDir } : undefined) : null) ??
+        (lid ? jidToE164(lid, authDir ? { authDir } : undefined) : null));
+  return {
+    ...identity,
+    jid,
+    lid,
+    e164,
+  };
+}
+
+export function getComparableIdentityValues(
+  identity: WhatsAppIdentity | WhatsAppSelfIdentity | null | undefined,
+): string[] {
+  const resolved = resolveComparableIdentity(identity);
+  return [resolved.e164, resolved.jid, resolved.lid].filter((value): value is string =>
+    Boolean(value),
+  );
+}
+
+export function identitiesOverlap(
+  left: WhatsAppIdentity | WhatsAppSelfIdentity | null | undefined,
+  right: WhatsAppIdentity | WhatsAppSelfIdentity | null | undefined,
+): boolean {
+  const leftValues = new Set(getComparableIdentityValues(left));
+  if (leftValues.size === 0) {
+    return false;
+  }
+  return getComparableIdentityValues(right).some((value) => leftValues.has(value));
+}
+
+export function getSenderIdentity(msg: LegacySenderLike, authDir?: string): WhatsAppIdentity {
+  return resolveComparableIdentity(
+    msg.sender ?? {
+      jid: msg.senderJid ?? null,
+      e164: msg.senderE164 ?? null,
+      name: msg.senderName ?? null,
+    },
+    authDir,
+  );
+}
+
+export function getSelfIdentity(msg: LegacySelfLike, authDir?: string): WhatsAppSelfIdentity {
+  return resolveComparableIdentity(
+    msg.self ?? {
+      jid: msg.selfJid ?? null,
+      lid: msg.selfLid ?? null,
+      e164: msg.selfE164 ?? null,
+    },
+    authDir,
+  );
+}
+
+export function getReplyContext(
+  msg: LegacyReplyLike,
+  authDir?: string,
+): WhatsAppReplyContext | null {
+  if (msg.replyTo) {
+    return {
+      ...msg.replyTo,
+      sender: resolveComparableIdentity(msg.replyTo.sender, authDir),
+    };
+  }
+  if (!msg.replyToBody) {
+    return null;
+  }
+  return {
+    id: msg.replyToId,
+    body: msg.replyToBody,
+    sender: resolveComparableIdentity(
+      {
+        jid: msg.replyToSenderJid ?? null,
+        e164: msg.replyToSenderE164 ?? null,
+        label: msg.replyToSender ?? null,
+      },
+      authDir,
+    ),
+  };
+}
+
+function getMentionJids(msg: LegacyMentionsLike): string[] {
+  return msg.mentions ?? msg.mentionedJids ?? [];
+}
+
+export function getMentionIdentities(
+  msg: LegacyMentionsLike,
+  authDir?: string,
+): WhatsAppIdentity[] {
+  return getMentionJids(msg).map((jid) => resolveComparableIdentity({ jid }, authDir));
+}
+
+export function getPrimaryIdentityId(identity: WhatsAppIdentity | null | undefined): string | null {
+  return identity?.e164 || identity?.jid?.trim() || identity?.lid || null;
+}

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

@@ -0,0 +1,37 @@
+import { beforeEach, vi } from "vitest";
+import {
+  type AsyncMock,
+  loadConfigMock,
+  readAllowFromStoreMock,
+  resetPairingSecurityMocks,
+  upsertPairingRequestMock,
+} from "../pairing-security.test-harness.js";
+
+export const sendMessageMock = vi.fn() as AsyncMock;
+export { readAllowFromStoreMock, upsertPairingRequestMock };
+
+let config: Record<string, unknown> = {};
+
+export function setAccessControlTestConfig(next: Record<string, unknown>): void {
+  config = next;
+  loadConfigMock.mockReturnValue(config);
+}
+
+export function getAccessControlTestConfig(): Record<string, unknown> {
+  return config;
+}
+
+export function setupAccessControlTestHarness(): void {
+  beforeEach(() => {
+    config = {
+      channels: {
+        whatsapp: {
+          dmPolicy: "pairing",
+          allowFrom: [],
+        },
+      },
+    };
+    sendMessageMock.mockReset().mockResolvedValue(undefined);
+    resetPairingSecurityMocks(config);
+  });
+}