@gakr-gakr/whatsapp 0.1.0

package/src/setup-test-helpers.ts

@@ -0,0 +1,217 @@
+import { expect } from "vitest";
+
+type WhatsAppSetupConfig = {
+  channels?: {
+    whatsapp?: {
+      selfChatMode?: boolean;
+      dmPolicy?: string;
+      allowFrom?: string[];
+      accounts?: Record<string, { dmPolicy?: string; allowFrom?: string[]; authDir?: string }>;
+    };
+  };
+};
+
+type WizardPromptHarness = {
+  text: (...args: unknown[]) => unknown;
+  select: (...args: unknown[]) => unknown;
+  note: (...args: unknown[]) => unknown;
+};
+
+type QueuedWizardPrompterFactory<T extends WizardPromptHarness> = (params: {
+  confirmValues?: boolean[];
+  selectValues?: string[];
+  textValues?: string[];
+}) => T;
+
+const WHATSAPP_OWNER_NUMBER_INPUT = "+1 (555) 555-0123";
+const WHATSAPP_OWNER_NUMBER_E164 = "+15555550123";
+const WHATSAPP_OWNER_NUMBER = "15555550123";
+const WHATSAPP_PERSONAL_NUMBER_INPUT = "+1 (555) 111-2222";
+const WHATSAPP_PERSONAL_NUMBER = "15551112222";
+const WHATSAPP_ACCESS_NOTE_TITLE = "WhatsApp DM access";
+const WHATSAPP_LOGIN_NOTE_TITLE = "WhatsApp";
+
+export function createWhatsAppRootAllowFromConfig(): WhatsAppSetupConfig {
+  return {
+    channels: {
+      whatsapp: {
+        allowFrom: [WHATSAPP_OWNER_NUMBER_E164],
+      },
+    },
+  };
+}
+
+export function createWhatsAppOwnerAllowlistHarness<T extends WizardPromptHarness>(
+  createPrompter: QueuedWizardPrompterFactory<T>,
+): T {
+  return createPrompter({
+    confirmValues: [false],
+    textValues: [WHATSAPP_OWNER_NUMBER_INPUT],
+  });
+}
+
+export function createWhatsAppPersonalPhoneHarness<T extends WizardPromptHarness>(
+  createPrompter: QueuedWizardPrompterFactory<T>,
+): T {
+  return createPrompter({
+    confirmValues: [false],
+    selectValues: ["personal"],
+    textValues: [WHATSAPP_PERSONAL_NUMBER_INPUT],
+  });
+}
+
+export function createWhatsAppLinkingHarness<T extends WizardPromptHarness>(
+  createPrompter: QueuedWizardPrompterFactory<T>,
+): T {
+  return createPrompter({
+    confirmValues: [true],
+    selectValues: ["separate", "disabled"],
+  });
+}
+
+export function createWhatsAppWorkAccountConfig(
+  params: {
+    defaultAccount?: string;
+  } = {},
+): WhatsAppSetupConfig {
+  return {
+    channels: {
+      whatsapp: {
+        ...(params.defaultAccount ? { defaultAccount: params.defaultAccount } : {}),
+        dmPolicy: "disabled",
+        allowFrom: [WHATSAPP_OWNER_NUMBER_E164],
+        accounts: {
+          work: {
+            authDir: "/tmp/work",
+          },
+        },
+      },
+    },
+  };
+}
+
+export function createWhatsAppAllowlistModeInput(): {
+  selectValues: string[];
+  textValues: string[];
+} {
+  return {
+    selectValues: ["separate", "allowlist", "list"],
+    textValues: [`${WHATSAPP_OWNER_NUMBER_INPUT}, ${WHATSAPP_OWNER_NUMBER}, *`],
+  };
+}
+
+function expectWhatsAppDmAccess(
+  cfg: WhatsAppSetupConfig,
+  expected: {
+    selfChatMode: boolean;
+    dmPolicy: string;
+    allowFrom?: string[];
+  },
+): void {
+  expect(cfg.channels?.whatsapp?.selfChatMode).toBe(expected.selfChatMode);
+  expect(cfg.channels?.whatsapp?.dmPolicy).toBe(expected.dmPolicy);
+  if ("allowFrom" in expected) {
+    expect(cfg.channels?.whatsapp?.allowFrom).toEqual(expected.allowFrom);
+  } else {
+    expect(cfg.channels?.whatsapp?.allowFrom).toBeUndefined();
+  }
+}
+
+export function expectWhatsAppWorkAccountOpenAccess(cfg: WhatsAppSetupConfig): void {
+  expect(cfg.channels?.whatsapp?.dmPolicy).toBe("disabled");
+  expect(cfg.channels?.whatsapp?.allowFrom).toEqual([WHATSAPP_OWNER_NUMBER_E164]);
+  expect(cfg.channels?.whatsapp?.accounts?.work?.dmPolicy).toBe("open");
+  expect(cfg.channels?.whatsapp?.accounts?.work?.allowFrom).toEqual(["*", WHATSAPP_OWNER_NUMBER]);
+}
+
+function expectWhatsAppOwnerNumberPrompt(harness: WizardPromptHarness): void {
+  expect(harness.text).toHaveBeenCalledWith(
+    expect.objectContaining({
+      message: "Your personal WhatsApp number (the phone you will message from)",
+    }),
+  );
+}
+
+export function expectWhatsAppOwnerAllowlistSetup(
+  cfg: WhatsAppSetupConfig,
+  harness: WizardPromptHarness,
+): void {
+  expectWhatsAppDmAccess(cfg, {
+    selfChatMode: true,
+    dmPolicy: "allowlist",
+    allowFrom: [WHATSAPP_OWNER_NUMBER],
+  });
+  expectWhatsAppOwnerNumberPrompt(harness);
+}
+
+export function expectWhatsAppSeparatePhoneDisabledSetup(
+  cfg: WhatsAppSetupConfig,
+  harness: WizardPromptHarness,
+): void {
+  expectWhatsAppDmAccess(cfg, {
+    selfChatMode: false,
+    dmPolicy: "disabled",
+  });
+  expect(harness.text).not.toHaveBeenCalled();
+}
+
+export function expectWhatsAppAllowlistModeSetup(cfg: WhatsAppSetupConfig): void {
+  expectWhatsAppDmAccess(cfg, {
+    selfChatMode: false,
+    dmPolicy: "allowlist",
+    allowFrom: [WHATSAPP_OWNER_NUMBER, "*"],
+  });
+}
+
+export function expectWhatsAppPersonalPhoneSetup(cfg: WhatsAppSetupConfig): void {
+  expectWhatsAppDmAccess(cfg, {
+    selfChatMode: true,
+    dmPolicy: "allowlist",
+    allowFrom: [WHATSAPP_PERSONAL_NUMBER],
+  });
+}
+
+export function expectWhatsAppOpenPolicySetup(
+  cfg: WhatsAppSetupConfig,
+  harness: WizardPromptHarness,
+): void {
+  expectWhatsAppDmAccess(cfg, {
+    selfChatMode: false,
+    dmPolicy: "open",
+    allowFrom: ["*", WHATSAPP_OWNER_NUMBER],
+  });
+  expect(harness.select).toHaveBeenCalledTimes(2);
+  expect(harness.text).not.toHaveBeenCalled();
+}
+
+export function expectNoWhatsAppLoginFollowup(harness: WizardPromptHarness): void {
+  expect(harness.note).not.toHaveBeenCalledWith(
+    expect.stringContaining("autobot channels login"),
+    WHATSAPP_LOGIN_NOTE_TITLE,
+  );
+}
+
+export function expectWhatsAppLoginFollowup(harness: WizardPromptHarness): void {
+  expect(harness.note).toHaveBeenCalledWith(
+    expect.stringContaining("autobot channels login"),
+    WHATSAPP_LOGIN_NOTE_TITLE,
+  );
+}
+
+export function expectWhatsAppWorkAccountAccessNote(harness: WizardPromptHarness): void {
+  expect(harness.note).toHaveBeenCalledWith(
+    expect.stringContaining(
+      "`channels.whatsapp.accounts.work.dmPolicy` + `channels.whatsapp.accounts.work.allowFrom`",
+    ),
+    WHATSAPP_ACCESS_NOTE_TITLE,
+  );
+}
+
+export function expectWhatsAppDefaultAccountAccessNote(harness: WizardPromptHarness): void {
+  expect(harness.note).toHaveBeenCalledWith(
+    expect.stringContaining(
+      "`channels.whatsapp.accounts.default.dmPolicy` + `channels.whatsapp.accounts.default.allowFrom`",
+    ),
+    WHATSAPP_ACCESS_NOTE_TITLE,
+  );
+}

package/src/shared.ts

@@ -0,0 +1,291 @@
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-core";
+import { describeAccountSnapshot } from "autobot/plugin-sdk/account-helpers";
+import { normalizeE164 } from "autobot/plugin-sdk/account-resolution";
+import {
+  adaptScopedAccountAccessor,
+  createScopedChannelConfigAdapter,
+  createScopedDmSecurityResolver,
+} from "autobot/plugin-sdk/channel-config-helpers";
+import {
+  collectOpenGroupPolicyRouteAllowlistWarnings,
+  createAllowlistProviderGroupPolicyWarningCollector,
+} from "autobot/plugin-sdk/channel-policy";
+import type { ChannelPlugin } from "autobot/plugin-sdk/core";
+import { createChannelPluginBase, getChatChannelMeta } from "autobot/plugin-sdk/core";
+import {
+  createDelegatedSetupWizardProxy,
+  type ChannelSetupWizard,
+} from "autobot/plugin-sdk/setup-runtime";
+import {
+  hasAnyWhatsAppAuth,
+  listWhatsAppAccountIds,
+  resolveDefaultWhatsAppAccountId,
+  resolveWhatsAppAccount,
+  type ResolvedWhatsAppAccount,
+} from "./accounts.js";
+import { formatWhatsAppConfigAllowFromEntries } from "./config-accessors.js";
+import { WhatsAppChannelConfigSchema } from "./config-schema.js";
+import { whatsappDoctor } from "./doctor.js";
+import { resolveLegacyGroupSessionKey } from "./group-session-contract.js";
+import {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./security-contract.js";
+import { applyWhatsAppSecurityConfigFixes } from "./security-fix.js";
+import {
+  canonicalizeLegacySessionKey,
+  deriveLegacySessionChatType,
+  isLegacyGroupSessionKey,
+} from "./session-contract.js";
+
+const WHATSAPP_CHANNEL = "whatsapp" as const;
+
+const WHATSAPP_GROUP_SCOPE_FIELDS = ["groupPolicy", "groupAllowFrom", "groups"] as const;
+
+type WhatsAppGroupScopeField = (typeof WHATSAPP_GROUP_SCOPE_FIELDS)[number];
+
+function resolveWhatsAppAccountKey(
+  accounts: Record<string, unknown> | undefined,
+  accountId: string,
+): string | undefined {
+  if (!accounts) {
+    return undefined;
+  }
+  if (Object.hasOwn(accounts, accountId)) {
+    return accountId;
+  }
+  const normalizedAccountId = accountId.trim().toLowerCase();
+  return Object.keys(accounts).find((key) => key.trim().toLowerCase() === normalizedAccountId);
+}
+
+function resolveWhatsAppGroupScopeBasePath(params: {
+  cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
+  accountId?: string | null;
+}): string {
+  const accountId =
+    typeof params.accountId === "string"
+      ? params.accountId.trim() || DEFAULT_ACCOUNT_ID
+      : DEFAULT_ACCOUNT_ID;
+  const accounts = params.cfg.channels?.whatsapp?.accounts;
+  const accountKey = resolveWhatsAppAccountKey(accounts, accountId);
+  const defaultAccountKey = resolveWhatsAppAccountKey(accounts, DEFAULT_ACCOUNT_ID);
+  const accountConfig = accountKey ? accounts?.[accountKey] : undefined;
+  const defaultAccountConfig = defaultAccountKey ? accounts?.[defaultAccountKey] : undefined;
+  const matchesAnyGroupScopeField = (config: Record<string, unknown> | undefined): boolean =>
+    WHATSAPP_GROUP_SCOPE_FIELDS.some((field) => config?.[field] !== undefined);
+  if (matchesAnyGroupScopeField(accountConfig)) {
+    return `channels.whatsapp.accounts.${accountKey}`;
+  }
+  if (accountId !== DEFAULT_ACCOUNT_ID && matchesAnyGroupScopeField(defaultAccountConfig)) {
+    return `channels.whatsapp.accounts.${defaultAccountKey}`;
+  }
+  return "channels.whatsapp";
+}
+
+function resolveWhatsAppConfigPath(params: {
+  cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
+  accountId?: string | null;
+  field: WhatsAppGroupScopeField;
+}): string {
+  return `${resolveWhatsAppGroupScopeBasePath(params)}.${params.field}`;
+}
+
+export async function loadWhatsAppChannelRuntime() {
+  return await import("./channel.runtime.js");
+}
+
+async function loadWhatsAppSetupSurface() {
+  return await import("./setup-surface.js");
+}
+
+export const whatsappSetupWizardProxy = createWhatsAppSetupWizardProxy(
+  async () => (await loadWhatsAppSetupSurface()).whatsappSetupWizard,
+);
+
+const whatsappConfigAdapter = createScopedChannelConfigAdapter<ResolvedWhatsAppAccount>({
+  sectionKey: WHATSAPP_CHANNEL,
+  listAccountIds: listWhatsAppAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveWhatsAppAccount),
+  defaultAccountId: resolveDefaultWhatsAppAccountId,
+  clearBaseFields: [],
+  allowTopLevel: false,
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: (allowFrom) => formatWhatsAppConfigAllowFromEntries(allowFrom),
+  resolveDefaultTo: (account) => account.defaultTo,
+});
+
+const whatsappResolveDmPolicy = createScopedDmSecurityResolver<ResolvedWhatsAppAccount>({
+  channelKey: WHATSAPP_CHANNEL,
+  resolvePolicy: (account) => account.dmPolicy,
+  resolveAllowFrom: (account) => account.allowFrom,
+  policyPathSuffix: "dmPolicy",
+  normalizeEntry: (raw) => normalizeE164(raw),
+  inheritSharedDefaultsFromDefaultAccount: true,
+});
+
+function createWhatsAppSetupWizardProxy(
+  loadWizard: () => Promise<ChannelSetupWizard>,
+): ChannelSetupWizard {
+  return createDelegatedSetupWizardProxy({
+    channel: WHATSAPP_CHANNEL,
+    loadWizard,
+    status: {
+      configuredLabel: "linked",
+      unconfiguredLabel: "not linked",
+      configuredHint: "linked",
+      unconfiguredHint: "not linked",
+      configuredScore: 5,
+      unconfiguredScore: 4,
+    },
+    resolveShouldPromptAccountIds: (params) => params.shouldPromptAccountIds,
+    credentials: [],
+    delegateFinalize: true,
+    disable: (cfg) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        whatsapp: {
+          ...cfg.channels?.whatsapp,
+          enabled: false,
+        },
+      },
+    }),
+    onAccountRecorded: (accountId, options) => {
+      options?.onAccountId?.(WHATSAPP_CHANNEL, accountId);
+    },
+  });
+}
+
+export function createWhatsAppPluginBase(params: {
+  groups: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["groups"]>;
+  setupWizard: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["setupWizard"]>;
+  setup: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["setup"]>;
+  isConfigured: NonNullable<ChannelPlugin<ResolvedWhatsAppAccount>["config"]>["isConfigured"];
+}) {
+  const collectWhatsAppSecurityWarnings = createAllowlistProviderGroupPolicyWarningCollector<{
+    account: ResolvedWhatsAppAccount;
+    cfg: Parameters<typeof resolveWhatsAppAccount>[0]["cfg"];
+    accountId?: string | null;
+  }>({
+    providerConfigPresent: (cfg) => cfg.channels?.whatsapp !== undefined,
+    resolveGroupPolicy: ({ account }) => account.groupPolicy,
+    collect: ({ account, accountId, cfg, groupPolicy }) =>
+      collectOpenGroupPolicyRouteAllowlistWarnings({
+        groupPolicy,
+        routeAllowlistConfigured:
+          Boolean(account.groups) && Object.keys(account.groups ?? {}).length > 0,
+        restrictSenders: {
+          surface: "WhatsApp groups",
+          openScope: "any member in allowed groups",
+          groupPolicyPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groupPolicy" }),
+          groupAllowFromPath: resolveWhatsAppConfigPath({
+            cfg,
+            accountId,
+            field: "groupAllowFrom",
+          }),
+        },
+        noRouteAllowlist: {
+          surface: "WhatsApp groups",
+          routeAllowlistPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groups" }),
+          routeScope: "group",
+          groupPolicyPath: resolveWhatsAppConfigPath({ cfg, accountId, field: "groupPolicy" }),
+          groupAllowFromPath: resolveWhatsAppConfigPath({
+            cfg,
+            accountId,
+            field: "groupAllowFrom",
+          }),
+        },
+      }),
+  });
+  const base = createChannelPluginBase({
+    id: WHATSAPP_CHANNEL,
+    meta: {
+      ...getChatChannelMeta(WHATSAPP_CHANNEL),
+      showConfigured: false,
+      quickstartAllowFrom: true,
+      forceAccountBinding: true,
+      preferSessionLookupForAnnounceTarget: true,
+    },
+    setupWizard: params.setupWizard,
+    capabilities: {
+      chatTypes: ["direct", "group", "channel"],
+      polls: true,
+      reactions: true,
+      media: true,
+      tts: {
+        voice: {
+          synthesisTarget: "voice-note",
+          transcodesAudio: true,
+        },
+      },
+    },
+    reload: { configPrefixes: ["web"], noopPrefixes: ["channels.whatsapp"] },
+    gatewayMethodDescriptors: [{ name: "web.login.start" }, { name: "web.login.wait" }],
+    configSchema: WhatsAppChannelConfigSchema,
+    config: {
+      ...whatsappConfigAdapter,
+      isEnabled: (account, cfg) => account.enabled && cfg.web?.enabled !== false,
+      disabledReason: () => "disabled",
+      isConfigured: params.isConfigured,
+      hasPersistedAuthState: ({ cfg }) => hasAnyWhatsAppAuth(cfg),
+      unconfiguredReason: () => "not linked",
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured: Boolean(account.authDir),
+          extra: {
+            linked: Boolean(account.authDir),
+            dmPolicy: account.dmPolicy,
+            allowFrom: account.allowFrom,
+          },
+        }),
+    },
+    security: {
+      applyConfigFixes: applyWhatsAppSecurityConfigFixes,
+      resolveDmPolicy: whatsappResolveDmPolicy,
+      collectWarnings: collectWhatsAppSecurityWarnings,
+    },
+    doctor: whatsappDoctor,
+    setup: params.setup,
+    groups: params.groups,
+  });
+  return {
+    ...base,
+    setupWizard: base.setupWizard!,
+    capabilities: base.capabilities!,
+    reload: base.reload!,
+    gatewayMethodDescriptors: base.gatewayMethodDescriptors!,
+    configSchema: base.configSchema!,
+    config: base.config!,
+    messaging: {
+      defaultMarkdownTableMode: "bullets",
+      deriveLegacySessionChatType,
+      resolveLegacyGroupSessionKey,
+      isLegacyGroupSessionKey,
+      canonicalizeLegacySessionKey: (params) =>
+        canonicalizeLegacySessionKey({ key: params.key, agentId: params.agentId }),
+    },
+    secrets: {
+      unsupportedSecretRefSurfacePatterns,
+      collectUnsupportedSecretRefConfigCandidates,
+    },
+    security: base.security!,
+    groups: base.groups!,
+  } satisfies Pick<
+    ChannelPlugin<ResolvedWhatsAppAccount>,
+    | "id"
+    | "meta"
+    | "setupWizard"
+    | "capabilities"
+    | "reload"
+    | "gatewayMethodDescriptors"
+    | "configSchema"
+    | "config"
+    | "messaging"
+    | "secrets"
+    | "security"
+    | "doctor"
+    | "setup"
+    | "groups"
+  >;
+}

package/src/socket-timing.ts

@@ -0,0 +1,38 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+
+export type WhatsAppSocketTimingOptions = {
+  keepAliveIntervalMs?: number;
+  connectTimeoutMs?: number;
+  defaultQueryTimeoutMs?: number;
+};
+
+export const DEFAULT_WHATSAPP_SOCKET_TIMING: Required<WhatsAppSocketTimingOptions> = {
+  keepAliveIntervalMs: 25_000,
+  connectTimeoutMs: 60_000,
+  defaultQueryTimeoutMs: 60_000,
+};
+
+function positiveInteger(value: number | undefined): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function resolveWhatsAppSocketTiming(
+  cfg: AutoBotConfig,
+  overrides?: WhatsAppSocketTimingOptions,
+): Required<WhatsAppSocketTimingOptions> {
+  const configured = cfg.web?.whatsapp;
+  return {
+    keepAliveIntervalMs:
+      positiveInteger(overrides?.keepAliveIntervalMs) ??
+      positiveInteger(configured?.keepAliveIntervalMs) ??
+      DEFAULT_WHATSAPP_SOCKET_TIMING.keepAliveIntervalMs,
+    connectTimeoutMs:
+      positiveInteger(overrides?.connectTimeoutMs) ??
+      positiveInteger(configured?.connectTimeoutMs) ??
+      DEFAULT_WHATSAPP_SOCKET_TIMING.connectTimeoutMs,
+    defaultQueryTimeoutMs:
+      positiveInteger(overrides?.defaultQueryTimeoutMs) ??
+      positiveInteger(configured?.defaultQueryTimeoutMs) ??
+      DEFAULT_WHATSAPP_SOCKET_TIMING.defaultQueryTimeoutMs,
+  };
+}

package/src/state-migrations.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-id";
+import type { ChannelLegacyStateMigrationPlan } from "autobot/plugin-sdk/channel-contract";
+import { statRegularFileSync } from "autobot/plugin-sdk/security-runtime";
+
+function fileExists(pathValue: string): boolean {
+  try {
+    return !statRegularFileSync(pathValue).missing;
+  } catch {
+    return false;
+  }
+}
+
+function isLegacyWhatsAppAuthFile(name: string): boolean {
+  if (name === "creds.json" || name === "creds.json.bak") {
+    return true;
+  }
+  if (!name.endsWith(".json")) {
+    return false;
+  }
+  return /^(app-state-sync|session|sender-key|pre-key)-/.test(name);
+}
+
+export function detectWhatsAppLegacyStateMigrations(params: {
+  oauthDir: string;
+}): ChannelLegacyStateMigrationPlan[] {
+  const targetDir = path.join(params.oauthDir, "whatsapp", DEFAULT_ACCOUNT_ID);
+  const entries = (() => {
+    try {
+      return fs.readdirSync(params.oauthDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+  })();
+
+  return entries.flatMap((entry) => {
+    if (!entry.isFile() || entry.name === "oauth.json" || !isLegacyWhatsAppAuthFile(entry.name)) {
+      return [];
+    }
+    const sourcePath = path.join(params.oauthDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (fileExists(targetPath)) {
+      return [];
+    }
+    return [
+      {
+        kind: "move" as const,
+        label: `WhatsApp auth ${entry.name}`,
+        sourcePath,
+        targetPath,
+      },
+    ];
+  });
+}