@moxxy/plugin-channel-whatsapp 0.27.0

package/src/index.ts

@@ -0,0 +1,284 @@
+import { defineChannel, definePlugin, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { createFileAuthStorage, hasStoredCreds } from './auth-state.js';
+import { WhatsAppChannel, type WhatsAppChannelOptions } from './channel.js';
+import { CONSENT_REQUIRED_MESSAGE, hasConsent } from './consent.js';
+import {
+  WHATSAPP_ALLOWED_JIDS_KEY,
+  WHATSAPP_AUTH_DIR,
+  WHATSAPP_CONSENT_KEY,
+  WHATSAPP_OWNER_JID_KEY,
+  parseAllowedJids,
+} from './keys.js';
+import { runWhatsAppWizard, unpairLocal } from './setup-wizard.js';
+import { runWhatsAppPairFlow } from './pair-flow.js';
+
+export { WhatsAppChannel, type WhatsAppChannelOptions, type WhatsAppStartOpts } from './channel.js';
+export {
+  createWhatsAppPermissionController,
+  parsePermissionReply,
+  formatPermissionPrompt,
+  type WhatsAppPermissionController,
+} from './permission.js';
+export {
+  createFileAuthStorage,
+  createWhatsAppAuthState,
+  hasStoredCreds,
+  sanitizeAuthKey,
+  type WhatsAppAuthStorage,
+  type BaileysAuthBridge,
+} from './auth-state.js';
+export {
+  gateInboundMessage,
+  MAX_AUDIO_BYTES,
+  MAX_TEXT_CHARS,
+  type GateVerdict,
+} from './message-gate.js';
+export {
+  runWhatsAppTurn,
+  splitWhatsAppText,
+  WHATSAPP_MAX_MESSAGE_CHARS,
+} from './channel/turn-runner.js';
+export { CONSENT_WARNING, CONSENT_REQUIRED_MESSAGE, hasConsent, recordConsent } from './consent.js';
+export {
+  WHATSAPP_CONSENT_KEY,
+  WHATSAPP_OWNER_JID_KEY,
+  WHATSAPP_ALLOWED_JIDS_KEY,
+  WHATSAPP_CONSENT_ENV,
+  WHATSAPP_AUTH_DIR,
+  normalizeJid,
+  parseAllowedJids,
+  isConsentValue,
+} from './keys.js';
+export {
+  disconnectStatusCode,
+  WA_DISCONNECT,
+  type WhatsAppSocket,
+  type WhatsAppSocketFactory,
+} from './socket.js';
+
+export interface BuildWhatsAppPluginOptions {
+  /** Host-injected encrypted secret store (available immediately). */
+  readonly vault: VaultStore;
+}
+
+/** Build the WhatsApp channel plugin with a host-injected vault (mirrors the
+ *  Telegram/Slack plugins' dual-export pattern). */
+export function buildWhatsAppPlugin(opts: BuildWhatsAppPluginOptions): Plugin {
+  return makeWhatsAppPlugin(() => opts.vault);
+}
+
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`).
+ */
+export const whatsappPlugin: Plugin = (() => {
+  let resolved: VaultStore | null = null;
+  const getVault = (): VaultStore => {
+    if (!resolved) {
+      throw new Error(
+        '@moxxy/plugin-channel-whatsapp: the "vault" service is unavailable — @moxxy/plugin-vault must load first',
+      );
+    }
+    return resolved;
+  };
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      resolved = ctx.services.require<VaultStore>('vault');
+    },
+  };
+  return makeWhatsAppPlugin(getVault, hooks);
+})();
+
+export default whatsappPlugin;
+
+function readAllowedJids(options: Record<string, unknown> | undefined): string[] | undefined {
+  const raw = options?.['allowedJids'];
+  if (Array.isArray(raw)) return raw.map((x) => String(x));
+  if (typeof raw === 'string' && raw.trim().length > 0) return parseAllowedJids(raw);
+  return undefined;
+}
+
+function makeWhatsAppPlugin(getVault: () => VaultStore, hooks?: LifecycleHooks): Plugin {
+  return definePlugin({
+    name: '@moxxy/plugin-channel-whatsapp',
+    version: '0.0.0',
+    ...(hooks ? { hooks } : {}),
+    channels: [
+      defineChannel({
+        name: 'whatsapp',
+        description:
+          'WhatsApp channel via Baileys — UNOFFICIAL API (violates WhatsApp ToS; the number ' +
+          'can be banned — use a secondary number). QR device-link pairing, JID allow-list.',
+        // Like Slack/Telegram: its own dedicated, isolated runner (separate
+        // socket + sticky session) so the bot keeps a persistent history apart
+        // from the user's desktop/TUI work. Baileys is an outbound WebSocket —
+        // no tunnel, no tunnelProvider registration.
+        dedicatedRunner: true,
+        sessionSource: 'whatsapp',
+        config: {
+          fields: [
+            {
+              name: 'tosAcknowledged',
+              label: "Risk acknowledgment — type 'yes'",
+              vaultKey: WHATSAPP_CONSENT_KEY,
+              required: true,
+              help:
+                'Unofficial WhatsApp API: violates the ToS and can get the number banned. ' +
+                "Typing anything other than 'yes' keeps the channel disarmed.",
+            },
+            {
+              name: 'allowedJids',
+              label: 'Extra allowed JIDs (comma-separated)',
+              vaultKey: WHATSAPP_ALLOWED_JIDS_KEY,
+              required: false,
+              placeholder: '15551234567@s.whatsapp.net',
+              help: 'Your own Note-to-Self chat is always allowed once linked.',
+            },
+          ],
+          hasRequestUrl: false,
+          runHint:
+            'On your phone: WhatsApp -> Settings -> Linked devices -> Link a device, then scan the QR.',
+          connect: {
+            kind: 'qr',
+            title: 'Link WhatsApp',
+            hint:
+              'Scan with the phone that owns the account: WhatsApp -> Settings -> Linked devices ' +
+              '-> Link a device. The QR refreshes periodically until scanned.',
+          },
+        },
+        create: (deps) => {
+          const options = deps.options;
+          const allowedJids = readAllowedJids(options);
+          const editFrameMs = options?.['editFrameMs'];
+          const channelOpts: WhatsAppChannelOptions = {
+            vault: getVault(),
+            ...(allowedJids ? { allowedJids } : {}),
+            ...(typeof editFrameMs === 'number' ? { editFrameMs } : {}),
+            logger: deps.logger as never,
+          };
+          return new WhatsAppChannel(channelOpts);
+        },
+        isAvailable: async () => {
+          // Cheap probes only: one vault read + one stat-shaped file read.
+          let consent = false;
+          try {
+            consent = await hasConsent(getVault());
+          } catch {
+            // Vault unavailable in a probe/listing context; the env override
+            // inside hasConsent(undefined) still counts.
+            consent = await hasConsent(undefined);
+          }
+          if (!consent) return { ok: false, reason: CONSENT_REQUIRED_MESSAGE };
+          const linked = await hasStoredCreds(
+            createFileAuthStorage(moxxyPath(WHATSAPP_AUTH_DIR)),
+          );
+          if (!linked) {
+            return {
+              ok: false,
+              reason:
+                'No WhatsApp account linked (or the phone logged this device out). Run ' +
+                '`moxxy channels whatsapp pair` to scan the QR.',
+            };
+          }
+          return { ok: true };
+        },
+        interactiveCommand: 'setup',
+        subcommands: {
+          setup: {
+            description:
+              'Interactive setup: acknowledge the unofficial-API risk (required first step), ' +
+              'link via QR, manage the allow-list, then start. Shown by default for ' +
+              '`moxxy whatsapp` on a TTY.',
+            run: async (ctx) => {
+              if (process.stdin.isTTY !== true) {
+                // Headless: the consent gate still holds — start refuses without
+                // an acknowledgment (vault receipt or MOXXY_WHATSAPP_TOS_ACK).
+                const vault = ctx.deps.vault as VaultStore | undefined;
+                if (!(await hasConsent(vault))) {
+                  process.stderr.write(`${CONSENT_REQUIRED_MESSAGE}\n`);
+                  return 1;
+                }
+                return ctx.startChannel();
+              }
+              return runWhatsAppWizard(ctx);
+            },
+          },
+          pair: {
+            description:
+              'Link a WhatsApp account: renders the rotating QR in the terminal; scan it from ' +
+              'WhatsApp -> Settings -> Linked devices. Requires the typed risk acknowledgment.',
+            run: async (ctx) => {
+              if (process.stdin.isTTY !== true) {
+                process.stderr.write(
+                  'Pairing needs a TTY to show the QR. Run `moxxy channels whatsapp pair` on a ' +
+                    'workstation, or pair from the desktop Channels panel.\n',
+                );
+                return 1;
+              }
+              return runWhatsAppPairFlow(ctx);
+            },
+          },
+          status: {
+            description:
+              'Report consent/link/allow-list state as JSON (with re-pair guidance after a logout).',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const consentAcknowledged = await hasConsent(vault);
+              const linked = await hasStoredCreds(
+                createFileAuthStorage(moxxyPath(WHATSAPP_AUTH_DIR)),
+              );
+              const ownerJid = await vault.get(WHATSAPP_OWNER_JID_KEY);
+              const allowedJids = parseAllowedJids(await vault.get(WHATSAPP_ALLOWED_JIDS_KEY));
+              const state = !consentAcknowledged
+                ? 'needs-consent'
+                : !linked
+                  ? 'needs-pairing'
+                  : 'ready';
+              const guidance = !consentAcknowledged
+                ? 'Run `moxxy whatsapp setup` and type yes to acknowledge the unofficial-API risk.'
+                : !linked
+                  ? ownerJid
+                    ? 'The phone logged this device out (or credentials were cleared) — run `moxxy channels whatsapp pair` to re-link.'
+                    : 'Run `moxxy channels whatsapp pair` to link an account.'
+                  : null;
+              process.stdout.write(
+                JSON.stringify(
+                  { state, consentAcknowledged, linked, ownerJid, allowedJids, guidance },
+                  null,
+                  2,
+                ) + '\n',
+              );
+              return 0;
+            },
+          },
+          unpair: {
+            description:
+              'Forget the local WhatsApp credentials (also remove the device on the phone under Linked devices).',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const removed = await unpairLocal(vault);
+              process.stdout.write(
+                removed
+                  ? 'unpaired — also remove the device on your phone: WhatsApp -> Settings -> Linked devices\n'
+                  : 'no linked account was stored\n',
+              );
+              return 0;
+            },
+          },
+        },
+      }),
+    ],
+  });
+}

package/src/keys.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { isConsentValue, normalizeJid, parseAllowedJids } from './keys.js';
+
+describe('normalizeJid', () => {
+  it('strips device + agent suffixes off the user part', () => {
+    expect(normalizeJid('15551234567:12@s.whatsapp.net')).toBe('15551234567@s.whatsapp.net');
+    expect(normalizeJid('15551234567_1:3@s.whatsapp.net')).toBe('15551234567@s.whatsapp.net');
+  });
+
+  it('lowercases the server and keeps a bare jid', () => {
+    expect(normalizeJid('15551234567@S.Whatsapp.Net')).toBe('15551234567@s.whatsapp.net');
+    expect(normalizeJid('12345@g.us')).toBe('12345@g.us');
+  });
+
+  it('rejects garbage and malformed values', () => {
+    expect(normalizeJid('')).toBeNull();
+    expect(normalizeJid('   ')).toBeNull();
+    expect(normalizeJid('nope')).toBeNull();
+    expect(normalizeJid('@s.whatsapp.net')).toBeNull();
+    expect(normalizeJid('a@@b')).toBeNull();
+    expect(normalizeJid('u@bad server')).toBeNull();
+    expect(normalizeJid(null)).toBeNull();
+    expect(normalizeJid(undefined)).toBeNull();
+  });
+});
+
+describe('parseAllowedJids', () => {
+  it('parses comma/space-separated JIDs and de-dupes/normalizes', () => {
+    expect(parseAllowedJids('15551234567@s.whatsapp.net, 15551234567:9@s.whatsapp.net')).toEqual([
+      '15551234567@s.whatsapp.net',
+    ]);
+    expect(parseAllowedJids('a@g.us b@g.us')).toEqual(['a@g.us', 'b@g.us']);
+  });
+
+  it('parses a JSON array and drops non-JIDs', () => {
+    expect(parseAllowedJids('["1@s.whatsapp.net", "garbage", 42]')).toEqual(['1@s.whatsapp.net']);
+  });
+
+  it('returns [] for empty / broken input', () => {
+    expect(parseAllowedJids(null)).toEqual([]);
+    expect(parseAllowedJids('')).toEqual([]);
+    expect(parseAllowedJids('[not json')).toEqual([]);
+  });
+});
+
+describe('isConsentValue', () => {
+  it('accepts an explicit yes or a dated receipt', () => {
+    expect(isConsentValue('yes')).toBe(true);
+    expect(isConsentValue('YES')).toBe(true);
+    expect(isConsentValue('acknowledged@2026-07-03T00:00:00.000Z')).toBe(true);
+  });
+
+  it('rejects anything else', () => {
+    expect(isConsentValue('no')).toBe(false);
+    expect(isConsentValue('')).toBe(false);
+    expect(isConsentValue(null)).toBe(false);
+    expect(isConsentValue('maybe')).toBe(false);
+  });
+});

package/src/keys.ts

@@ -0,0 +1,78 @@
+/**
+ * Vault keys + pure JID helpers shared by the channel, its subcommands, and the
+ * interactive setup wizard. Kept in their own module so the wizard / pair-flow
+ * helpers can import them without pulling in the plugin's full index (or, worse,
+ * Baileys — which stays behind a lazy import in `baileys-socket.ts`).
+ */
+
+/** Vault key holding the user's typed acknowledgment of the ToS/ban risk. */
+export const WHATSAPP_CONSENT_KEY = 'whatsapp_tos_acknowledged';
+/** Vault key holding the linked account's own (normalized) JID. */
+export const WHATSAPP_OWNER_JID_KEY = 'whatsapp_owner_jid';
+/** Vault key holding extra allow-listed JIDs (JSON array or comma-separated). */
+export const WHATSAPP_ALLOWED_JIDS_KEY = 'whatsapp_allowed_jids';
+/** Env override for the consent gate (headless/dedicated runners). */
+export const WHATSAPP_CONSENT_ENV = 'MOXXY_WHATSAPP_TOS_ACK';
+/** Directory (under the moxxy home) holding the rotating Baileys auth state. */
+export const WHATSAPP_AUTH_DIR = 'whatsapp-auth';
+
+/**
+ * Normalize a WhatsApp JID for identity comparison: the user part of a
+ * multi-device JID carries `:device` (and historically `_agent`) suffixes that
+ * vary per login (`1234567890:12@s.whatsapp.net`), so equality checks must
+ * compare the bare `user@server` form. Returns null for values that don't look
+ * like a JID at all, so callers treat garbage as "no identity" instead of
+ * silently allow-listing it.
+ */
+export function normalizeJid(raw: string | null | undefined): string | null {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0 || trimmed.length > 256) return null;
+  const at = trimmed.indexOf('@');
+  if (at <= 0 || at !== trimmed.lastIndexOf('@')) return null;
+  const server = trimmed.slice(at + 1).toLowerCase();
+  if (!/^[a-z0-9.-]+$/.test(server)) return null;
+  // Strip the device (`:NN`) and legacy agent (`_N`) suffixes off the user part.
+  const user = trimmed.slice(0, at).split(':')[0]!.split('_')[0]!;
+  if (user.length === 0) return null;
+  return `${user}@${server}`;
+}
+
+/**
+ * Parse a stored/configured allow-list. Accepts a JSON string array or a
+ * comma/whitespace-separated string; every entry is normalized and non-JIDs are
+ * dropped (never silently allow-listed). Returns a de-duplicated array.
+ */
+export function parseAllowedJids(raw: string | null | undefined): string[] {
+  if (raw == null) return [];
+  let entries: unknown[] = [];
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('[')) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) entries = parsed;
+    } catch {
+      return [];
+    }
+  } else {
+    entries = trimmed.split(/[,\s]+/);
+  }
+  const out = new Set<string>();
+  for (const entry of entries) {
+    const jid = normalizeJid(typeof entry === 'string' ? entry : null);
+    if (jid) out.add(jid);
+  }
+  return [...out];
+}
+
+/**
+ * Whether a stored consent value counts as an actual acknowledgment. The setup
+ * wizard stores `acknowledged@<ISO date>`; the desktop panel / `moxxy init`
+ * declarative field stores whatever the user typed — only an affirmative "yes"
+ * counts, so typing "no" into the form does NOT arm the channel.
+ */
+export function isConsentValue(raw: string | null | undefined): boolean {
+  if (typeof raw !== 'string') return false;
+  const v = raw.trim().toLowerCase();
+  return v === 'yes' || v.startsWith('acknowledged@');
+}

package/src/message-gate.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import { gateInboundMessage, MAX_TEXT_CHARS, type GateState } from './message-gate.js';
+import type { WaInboundMessage } from './socket.js';
+
+const OWNER = '15550000000@s.whatsapp.net';
+const FRIEND = '15551111111@s.whatsapp.net';
+const STRANGER = '15559999999@s.whatsapp.net';
+
+function state(overrides: Partial<GateState> = {}): GateState {
+  return {
+    ownJid: OWNER,
+    allowedJids: new Set([OWNER, FRIEND]),
+    isOwnSend: () => false,
+    ...overrides,
+  };
+}
+
+function textMsg(remoteJid: string, text: string, fromMe = false, id = 'm1'): WaInboundMessage {
+  return { key: { remoteJid, fromMe, id }, message: { conversation: text } };
+}
+
+describe('gateInboundMessage', () => {
+  it('accepts an allow-listed sender text message', () => {
+    const v = gateInboundMessage(state(), 'notify', textMsg(FRIEND, 'hi there'));
+    expect(v).toEqual({ ok: true, kind: 'text', jid: FRIEND, text: 'hi there' });
+  });
+
+  it("accepts the owner's own Note-to-Self message (fromMe in own chat)", () => {
+    const v = gateInboundMessage(state(), 'notify', textMsg(OWNER, 'note to self', true));
+    expect(v.ok && v.kind === 'text' && v.jid).toBe(OWNER);
+  });
+
+  it('drops a fromMe message in a FOREIGN chat (owner talking to others)', () => {
+    const v = gateInboundMessage(state(), 'notify', textMsg(FRIEND, 'private reply', true));
+    expect(v).toEqual({ ok: false, reason: 'own message in a foreign chat' });
+  });
+
+  it("drops the bot's OWN outbound echo by message id (loop protection)", () => {
+    const st = state({ isOwnSend: (id) => id === 'echo-1' });
+    const v = gateInboundMessage(st, 'notify', textMsg(FRIEND, 'my own send', false, 'echo-1'));
+    expect(v).toEqual({ ok: false, reason: 'own outbound echo' });
+  });
+
+  it('drops an un-allow-listed sender', () => {
+    const v = gateInboundMessage(state(), 'notify', textMsg(STRANGER, 'let me in'));
+    expect(v).toEqual({ ok: false, reason: 'sender not allow-listed' });
+  });
+
+  it('drops non-notify upserts (history sync / append)', () => {
+    expect(gateInboundMessage(state(), 'append', textMsg(FRIEND, 'x')).ok).toBe(false);
+    expect(gateInboundMessage(state(), 'history', textMsg(FRIEND, 'x')).ok).toBe(false);
+  });
+
+  it('drops status broadcasts', () => {
+    const v = gateInboundMessage(state(), 'notify', textMsg('status@broadcast', 'x'));
+    expect(v.ok).toBe(false);
+  });
+
+  it('validates the key shape (missing remoteJid rejected)', () => {
+    const v = gateInboundMessage(state(), 'notify', { key: { fromMe: false }, message: { conversation: 'x' } });
+    expect(v).toEqual({ ok: false, reason: 'invalid message key shape' });
+  });
+
+  it('caps oversized text', () => {
+    const big = 'a'.repeat(MAX_TEXT_CHARS + 1);
+    const v = gateInboundMessage(state(), 'notify', textMsg(FRIEND, big));
+    expect(v).toEqual({ ok: false, reason: 'text over size cap' });
+  });
+
+  it('unwraps ephemeral + extendedText messages', () => {
+    const msg: WaInboundMessage = {
+      key: { remoteJid: FRIEND, fromMe: false, id: 'e1' },
+      message: {
+        ephemeralMessage: { message: { extendedTextMessage: { text: 'ephemeral hi' } } },
+      },
+    };
+    const v = gateInboundMessage(state(), 'notify', msg);
+    expect(v).toEqual({ ok: true, kind: 'text', jid: FRIEND, text: 'ephemeral hi' });
+  });
+
+  it('accepts a voice/audio message and reports mime + declared size', () => {
+    const msg: WaInboundMessage = {
+      key: { remoteJid: FRIEND, fromMe: false, id: 'a1' },
+      message: { audioMessage: { mimetype: 'audio/ogg; codecs=opus', fileLength: '2048', ptt: true } },
+    };
+    const v = gateInboundMessage(state(), 'notify', msg);
+    expect(v).toEqual({
+      ok: true,
+      kind: 'audio',
+      jid: FRIEND,
+      mimeType: 'audio/ogg; codecs=opus',
+      declaredBytes: 2048,
+    });
+  });
+
+  it('rejects an audio message whose declared size exceeds the cap', () => {
+    const msg: WaInboundMessage = {
+      key: { remoteJid: FRIEND, fromMe: false, id: 'a2' },
+      message: { audioMessage: { mimetype: 'audio/ogg', fileLength: 999_999_999 } },
+    };
+    const v = gateInboundMessage(state(), 'notify', msg);
+    expect(v).toEqual({ ok: false, reason: 'audio over size cap' });
+  });
+
+  it('drops empty/unsupported content', () => {
+    expect(gateInboundMessage(state(), 'notify', textMsg(FRIEND, '   ')).ok).toBe(false);
+    const image: WaInboundMessage = {
+      key: { remoteJid: FRIEND, fromMe: false, id: 'i1' },
+      message: { imageMessage: { url: 'x' } },
+    };
+    expect(gateInboundMessage(state(), 'notify', image)).toEqual({
+      ok: false,
+      reason: 'unsupported message type',
+    });
+  });
+
+  it('drops a fromMe self-chat message when ownJid is not yet known', () => {
+    const v = gateInboundMessage(state({ ownJid: null }), 'notify', textMsg(OWNER, 'x', true));
+    expect(v).toEqual({ ok: false, reason: 'own message in a foreign chat' });
+  });
+});