feat(server): run the WhatsApp channel on whatsapp-web.js (P1.7)

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.
This commit is contained in:
shumeiko.it
2026-10-24 11:51:25 +02:00
parent f046a20b34
commit 625545aa0f
12 changed files with 1628 additions and 1102 deletions

View File

@@ -16,13 +16,44 @@ of `server` and `launcher`.
## Consequences
- `whatsapp-web.js` drives a Chrome browser through Puppeteer. The installer does not bundle a
browser, and installing dependencies does not download one.
- Open item, proposed and awaiting the owner: use an installed Edge or Chrome, and download a
browser (about 170 MB) only if none is found when the user enables WhatsApp.
- Voice and video messages go through ffmpeg, which is not bundled because ffmpeg builds carry
their own LGPL or GPL terms. Use an installed ffmpeg or download it on demand.
- The client is unofficial. The UI warns that WhatsApp may block the account.
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

View File

@@ -48,7 +48,7 @@ Baseline: commit `b20b138` of `git.os-dev.tech/oleg.m/waggle-os`.
| UF-017 | Startup text is invisible in the light theme | Open | Web UI |
| UF-018 | Default model shown in the top bar disagrees with Model Pilot | Open | Web UI, models |
| UF-019 | Memory count pluralization: "1 Memories" | Open | Web UI |
| UF-020 | WhatsApp connector bundles GPL-3.0 code into the sidecar | Open | Licensing |
| UF-020 | WhatsApp connector bundles GPL-3.0 code into the sidecar | Fixed | Licensing |
| UF-021 | Settings visual-regression baseline is ignored by git | Fixed | Tests, git |
| UF-022 | Unit tests write into the developer's real `~/.waggle` | Fixed | Tests |
| UF-023 | Four unit-test files fail on macOS | Open | Tests, macOS |
@@ -206,12 +206,12 @@ Entries UF-010 to UF-019 come from the UI audit `anti-slop/audit-001-2026-10-14.
- Recommendation: pluralize by count.
### UF-020. WhatsApp connector bundles GPL-3.0 code into the sidecar
- Status: Open
- Status: Fixed
- Found: 2026-10-15
- Where: `packages/server/package.json:30` and `packages/launcher/package.json:42` (`@whiskeysockets/baileys` ^7.0.0-rc13); `packages/server/src/local/channels/whatsapp-adapter.ts:118,260`; `scripts/build-sidecar.mjs` (`EXTERNAL` list)
- Symptom: Baileys itself is MIT, but it depends on `libsignal` 6.0.0 (`WhiskeySockets/libsignal-node`), which is GPL-3.0. Baileys is not in the esbuild `EXTERNAL` list, so the sidecar build bundles Baileys together with `libsignal` into `service.js`, which ships inside the desktop installer. This follows from the build configuration; we have not inspected a built installer.
- Cause: the licenses of transitive dependencies are not checked.
- What we did: nothing in the main project code. The OSS edition replaces Baileys with `whatsapp-web.js` (Apache-2.0), per Egzakta decision Q5.
- What we did: the OSS edition replaces Baileys with `whatsapp-web.js` (Apache-2.0), per Egzakta decision Q5 (P1.7, ADR-0005). `libsignal` and Baileys are gone from the lockfile, and `whatsapp-web.js` stays outside the esbuild bundle. Its own dependency `node-webpmux` is LGPL-3.0-or-later and ships as a separate package; that is for the license review.
- Recommendation: include this in the license review (Q6). Shipping GPL-3.0 code inside a binary distributed under other terms is a compliance risk that needs a legal opinion. Options: replace Baileys in the main product as well, or move the WhatsApp connector into a separately installed component. Add a license check for transitive dependencies to CI.
### UF-021. Settings visual-regression baseline is ignored by git