Baileys depends on libsignal (GPL-3.0), which the sidecar bundled. The WhatsApp adapter now drives WhatsApp Web through whatsapp-web.js and keeps its public shape: start, stop, status with the pairing QR, send and inbound text. LocalAuth stores the session as a browser profile in <dataDir>/channels/whatsapp; the old Baileys state is left untouched. The browser comes from whatsapp-browser.ts: CHROME_PATH or PUPPETEER_EXECUTABLE_PATH, then an installed Chrome, Edge or Chromium (Windows, macOS, Linux), then a Chrome for Testing build downloaded on the first start into <dataDir>/browsers, with progress in the status. The root .puppeteerrc.cjs stops npm install from downloading a browser. The sidecar build keeps whatsapp-web.js external: bundled, it fails on __dirname and would inline LGPL node-webpmux. Text only, so ffmpeg is never needed. New dependencies, pinned: whatsapp-web.js 1.34.7 (Apache-2.0) and @puppeteer/browsers 2.13.0 (Apache-2.0). Transitive: puppeteer, puppeteer-core, chromium-bidi, webdriver-bidi-protocol (Apache-2.0), devtools-protocol (BSD-3-Clause), extract-zip (BSD-2-Clause), fluent-ffmpeg and the rest (MIT or ISC), and node-webpmux (LGPL-3.0-or-later, shipped as a separate package; needs the license review). Removed: @whiskeysockets/baileys and libsignal. UF-020 is now Fixed; ADR-0005 records the consequences.
66 lines
3.9 KiB
Markdown
66 lines
3.9 KiB
Markdown
# ADR-0005: The WhatsApp channel uses whatsapp-web.js
|
|
|
|
- Status: Accepted, one open item (browser source)
|
|
- Date: 2026-10-14
|
|
|
|
## Context
|
|
|
|
The WhatsApp channel (`packages/server/src/local/channels/whatsapp-adapter.ts`) uses Baileys.
|
|
Baileys itself is MIT, but it depends on `libsignal`, which is GPL-3.0. The sidecar build
|
|
bundles both, which would put GPL code into the shipped community edition.
|
|
|
|
## Decision
|
|
|
|
Replace Baileys with `whatsapp-web.js` (Apache-2.0) and remove Baileys from the dependencies
|
|
of `server` and `launcher`.
|
|
|
|
## Consequences
|
|
|
|
Implemented in P1.7 with `whatsapp-web.js` 1.34.7 (Puppeteer 24).
|
|
|
|
- The adapter keeps its public shape: start, stop, status with the pairing QR, send and
|
|
inbound text. `LocalAuth` keeps the session as a browser profile in
|
|
`<dataDir>/channels/whatsapp/session`, next to the WhatsApp Web page cache.
|
|
- The session is no longer encrypted at rest. Baileys state lived in the encrypted vault; the
|
|
browser profile is protected only by file permissions.
|
|
- Baileys pairings are not migrated: whatsapp-web.js cannot use them. The old vault entry and
|
|
`<dataDir>/channels/whatsapp-auth` are left untouched because the data directory may still
|
|
be shared with the commercial edition. Users scan the QR once more.
|
|
- Installing dependencies does not download a browser: the root `.puppeteerrc.cjs` sets
|
|
`skipDownload`. This covers `npm install` and `npm ci` in this repository (development,
|
|
`install.sh`, Tauri staging). It does not cover `npx @waggle-ai/waggle`: there npm runs
|
|
Puppeteer's install script with no config in reach, and it downloads Chrome unless
|
|
`PUPPETEER_SKIP_DOWNLOAD=1` is set.
|
|
- Open item, implemented as proposed and still awaiting the owner: the browser source. The
|
|
order is `CHROME_PATH` or `PUPPETEER_EXECUTABLE_PATH`, an installed Chrome, Edge or Chromium
|
|
in the standard Windows, macOS and Linux locations, then a browser downloaded earlier.
|
|
Only when none is found does starting WhatsApp download the current stable Chrome for
|
|
Testing (about 170 MB) into `<dataDir>/browsers` with `@puppeteer/browsers`. Settings
|
|
shows the progress, or an error that asks the user to install Chrome or set `CHROME_PATH`.
|
|
Linux on ARM has no Chrome for Testing build, so users there install Chromium.
|
|
- The Tauri sidecar build keeps `whatsapp-web.js` and `@puppeteer/browsers` external.
|
|
Bundled into the ESM sidecar, whatsapp-web.js fails at runtime (`__dirname` is not defined).
|
|
- The channel handles text only. whatsapp-web.js needs ffmpeg only to turn videos into
|
|
stickers, which Waggle never sends, so ffmpeg is not bundled, downloaded or looked up.
|
|
Voice, video and other media messages are ignored and logged.
|
|
- New licenses: Apache-2.0 (`whatsapp-web.js`, `puppeteer`, `puppeteer-core`,
|
|
`@puppeteer/browsers`, `chromium-bidi`, `webdriver-bidi-protocol`), BSD (`devtools-protocol`,
|
|
`extract-zip`), MIT and ISC for the rest, and LGPL-3.0-or-later for `node-webpmux`, a
|
|
required dependency of whatsapp-web.js that it loads on startup for sticker metadata. It
|
|
ships as a separate, unmodified package. The licensing review has to accept it.
|
|
- The client is unofficial. Settings warns that WhatsApp may block the account and
|
|
recommends a secondary number.
|
|
- Risk: whatsapp-web.js awaits page work inside browser event listeners (for example
|
|
`inject()` after a navigation, which throws "auth timeout" when WhatsApp Web loads slowly).
|
|
Such a failure is an unhandled promise rejection, and the sidecar has no handler for those,
|
|
so Node stops the process.
|
|
|
|
## Alternatives considered
|
|
|
|
- whatsmeow (Go, MPL-2.0): no browser, but needs a separate Go binary per platform.
|
|
- WPPConnect (LGPL-3.0): also browser-based, stricter license.
|
|
- venom-bot: no npm release since November 2024.
|
|
- open-wa: Hippocratic license, not an open-source license in the OSI sense.
|
|
- WhatsApp Business Cloud API: needs a business account and a public webhook, so it does not
|
|
fit a local app.
|