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:
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user