Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(backup): note engine auth state copied while in use
Yudhi Armyndharis805134ba8e01
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 1401a15d3..6f33a1873 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -357,7 +357,8 @@ docker stats --no-stream# 3. Create a backup in the running container, where the data is mounted, and copy it off the# volume (see Runbook: Database Backup). A host run of ./scripts/backup.sh archives ./data in the-# checkout, which only a bare-metal install or docker-compose.dev.yml reads+# checkout, which only a bare-metal install or docker-compose.dev.yml reads. Engine auth state is+# copied live; stop the sessions first if a restore must not need re-pairingdocker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.shdocker cp openwa-api:/app/data/backups/. ./backups/@@ -436,7 +437,8 @@ curl -H "X-API-Key: $API_KEY" \# files name the container openwa-api. Running ./scripts/backup.sh on the host instead archives# ./data in the checkout, which the production compose never reads (see Runbook: Database Backup).# An image older than 0.19.0 has no scripts/backup.sh, and on PostgreSQL one older than 0.22.0 has-# no pg_dump: see 14 - Known Upgrade Hazards+# no pg_dump: see 14 - Known Upgrade Hazards. Engine auth state is copied live; stop the sessions+# first if a rollback must not need re-pairingexport BACKUP_DIR="/backups/openwa"mkdir -p "$BACKUP_DIR"docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh@@ -590,7 +592,10 @@ curl -H "X-API-Key: $API_KEY" http://localhost:2785/api/health**Trigger:** Daily schedule, before maintenance, before upgrade-**Impact:** None (online backup)+**Impact:** None for the databases, which are snapshotted consistently online (`sqlite3 .backup`,+`pg_dump`). Engine authentication state (`sessions/`, `baileys/`) is copied while the engines write+it, so a restored session can need re-pairing; for a copy that is consistent by construction, stop+the sessions first (`POST /api/sessions/:id/stop`), or stop the container and archive the volume.**Prerequisites:**@@ -626,7 +631,9 @@ User-managed files outside that list (for example the project-level `.env`) must# are NOT derived from OPENWA_DATA_DIR. A missing source database fails the run (no silent empty# backup), the finished archive is checked to contain every configured database, and with the sqlite3# CLI present the databases are snapshotted online via .backup (otherwise plain-copied with a-# CONSISTENCY-WARNING marker inside the archive).+# CONSISTENCY-WARNING marker inside the archive). sessions/ and baileys/ are plain copies: when a+# whatsapp-web.js profile is open or Baileys state is present, the archive carries an+# ENGINE-STATE-NOTE naming them, which restore.sh prints and never refuses.# Run from the repo root (database defaults are ./data/...; state dirs follow OPENWA_DATA_DIR):./scripts/backup.sh@@ -713,7 +720,8 @@ docker compose down# (databases land on MAIN_DATABASE_NAME / DATABASE_NAME, default ./data/... — the same paths# the app reads, as the environment, ./.env or the archive's .env.generated set them; non-DB# state follows OPENWA_DATA_DIR. Pass --strict to refuse an archive-# whose CONSISTENCY-WARNING marker reports plain-copied, possibly-torn database snapshots.+# whose CONSISTENCY-WARNING marker reports plain-copied, possibly-torn database snapshots;+# an ENGINE-STATE-NOTE (engine auth state that may have been copied while the app ran) is only printed.# Restoring over an existing install's live databases requires --force; without it the script# refuses to overwrite them)./scripts/restore.sh ./backups/openwa-backup-<timestamp>.tar.gzdiff --git a/scripts/backup.sh b/scripts/backup.shindex 9bd310f89..2b6fb1541 100755--- a/scripts/backup.sh+++ b/scripts/backup.sh@@ -49,6 +49,12 @@# sqlite3 CLI is unavailable the databases are plain-copied (possibly torn if the app is live) and# the archive carries a CONSISTENCY-WARNING marker that restore.sh surfaces.#+# Engine authentication state (sessions/, baileys/) is copied, not snapshotted: the engines rewrite+# it while they run, so an online backup can hold a copy torn mid-write. When a whatsapp-web.js+# profile is open or Baileys state is present, the archive carries an ENGINE-STATE-NOTE that+# restore.sh prints without refusing (--strict gates only the database marker). For a copy that is+# consistent by construction, stop the sessions (or the container) first.+#set -euo pipefail# The archive now contains bootstrap credentials and generated database secrets. Never inherit a# permissive operator umask for newly-created backup artifacts.@@ -121,6 +127,24 @@ EOFecho "plain-copied: $1" >>"$CONSISTENCY_WARNING"}+ENGINE_STATE_NOTE="$STAGE/ENGINE-STATE-NOTE"++# Marker file shipped INSIDE the archive: engine auth state was copied while an engine may have been+# writing it. Separate from the database marker so restore.sh --strict does not refuse every online+# backup; a torn auth copy costs a re-pair, not data.+record_engine_state_note() {+ if [ ! -f "$ENGINE_STATE_NOTE" ]; then+ cat >"$ENGINE_STATE_NOTE" <<'EOF'+The engine authentication state listed below was copied while the app may have been writing it:+these directories are plain copies. This note does not cover the databases; a CONSISTENCY-WARNING+in the same archive does. If a restored session does not reconnect, pair it again, or re-take the+backup with the sessions (or the container) stopped.+EOF+ fi+ echo "$1" >>"$ENGINE_STATE_NOTE"+ log "WARN: engine auth state may have been written during the copy; a restore may need re-pairing: $1"+}+# Online SQLite backup (consistent without stopping the app) when sqlite3 is present. A missing# source database is FATAL: an archive without the configured databases is not a backup, and a# silent skip is how an empty archive gets reported as "Backup complete".@@ -179,6 +203,13 @@ fiif [ -d "$SESSIONS_DIR" ]; thenlog "Backing up whatsapp-web.js sessions"cp -pRH "$SESSIONS_DIR" "$STAGE/sessions"+ # Chromium holds a SingletonLock (a symlink, so not `-e`) in every profile it has open, and the+ # entrypoint clears stale ones at start, so a lock here means a browser was writing that profile.+ OPEN_PROFILES="$(find -H "$SESSIONS_DIR" -mindepth 2 -maxdepth 2 -name SingletonLock -exec dirname {} \; |+ sed 's|.*/||' | sort | tr '\n' ' ')"+ if [ -n "$OPEN_PROFILES" ]; then+ record_engine_state_note "sessions/ (whatsapp-web.js profiles open in a browser: ${OPEN_PROFILES% })"+ fielselog "WARN: $SESSIONS_DIR not found — skipping sessions"fi@@ -186,6 +217,11 @@ fiif [ -d "$BAILEYS_DIR" ]; thenlog "Backing up Baileys authentication state"cp -pRH "$BAILEYS_DIR" "$STAGE/baileys"+ # Baileys rewrites creds.json and its key files during normal traffic and leaves no sign of being+ # live, so any session's state counts, stopped or not.+ if [ -n "$(find -H "$BAILEYS_DIR" -mindepth 1 -maxdepth 1 -type d -print -quit)" ]; then+ record_engine_state_note "baileys/ (recorded whenever Baileys state exists; it cannot show whether it was live)"+ fielif [ "${ENGINE_TYPE:-}" = "baileys" ]; thenlog "WARN: ENGINE_TYPE=baileys but $BAILEYS_DIR was not found — restored sessions will require pairing"fidiff --git a/scripts/restore.sh b/scripts/restore.shindex becf19660..e4e9c7949 100755--- a/scripts/restore.sh+++ b/scripts/restore.sh@@ -11,7 +11,8 @@# Options:# --strict refuse to restore an archive whose CONSISTENCY-WARNING marker reports# plain-copied (possibly torn) database snapshots; without it the restore-# continues after a loud warning+# continues after a loud warning. An ENGINE-STATE-NOTE (engine auth state that+# may have been copied while the app ran) is printed either way and never refused.# --force overwrite databases that already hold a working install's data; without it# the restore refuses to touch a live target before changing anything# Environment:@@ -345,6 +346,13 @@ if [ -f "$STAGE/CONSISTENCY-WARNING" ]; thenlog "WARN: continuing anyway; verify data integrity after the restore (re-run with --strict to make this fatal)"fi+# Engine auth state copied while an engine may have been writing it. Informational only: every+# online backup of a running install carries it, and the worst case is a re-pair, not lost data.+if [ -f "$STAGE/ENGINE-STATE-NOTE" ]; then+ log "WARN: archive carries ENGINE-STATE-NOTE; engine auth state may have been copied while the app was running:"+ sed 's/^/[restore] /' "$STAGE/ENGINE-STATE-NOTE"+fi+# Refuse to overwrite a live database without --force, BEFORE any existing state is touched (the# same rule the --strict refusal above follows). Only the databases this archive actually carries# are checked — a target the archive omits is left alone either way.diff --git a/scripts/smoke-test-backup-restore.sh b/scripts/smoke-test-backup-restore.shindex 39c656eaf..e3b482c43 100755--- a/scripts/smoke-test-backup-restore.sh+++ b/scripts/smoke-test-backup-restore.sh@@ -39,6 +39,8 @@# (y) plugin packages in the legacy ./plugins, which the archive does not carry, are reported# (z) a leftover ./uploads that was never created, beside an existing ./data/media, resolves there in# both scripts whatever the uid+# (aa) engine auth state copied from a running app (an open whatsapp-web.js profile, Baileys state)+# is noted in the archive and printed by restore, which does not refuse it even with --strict## Usage: ./scripts/smoke-test-backup-restore.sh# Requires: bash, tar, node (restore.sh path resolution). sqlite3 is optional (see (c) and (k)).@@ -1173,5 +1175,58 @@ if [ "$(cat "$Z/dst/data/media/a.jpg" 2>/dev/null || true)" != "zulu-media" ] ||fipass "(z) a never-created ./uploads beside ./data/media resolves to ./data/media without a uid check"+echo ""+echo "==> (aa) engine auth state copied from a running app is noted, and restore does not refuse it"+# The databases are snapshotted consistently online, but sessions/ and baileys/ are plain copies of+# directories the engines keep writing, and the runbook called the online backup impact-free. The+# note has its own marker: --strict gates only the database one, or it would refuse every online backup.+AA="$WORK/aa"+mkdir -p "$AA/src/data/sessions/session-s1" "$AA/src/data/sessions/session-s2" "$AA/src/data/baileys/s1" \+ "$AA/dst" "$AA/quiet/data/sessions/session-s1"+make_fixture "$AA/src/data/main.sqlite" "alpha2-main"+make_fixture "$AA/src/data/openwa.sqlite" "alpha2-data"+printf 'profile\n' >"$AA/src/data/sessions/session-s1/Preferences"+printf 'profile\n' >"$AA/src/data/sessions/session-s2/Preferences"+ln -s host-123 "$AA/src/data/sessions/session-s1/SingletonLock"+printf '{}' >"$AA/src/data/baileys/s1/creds.json"+OUT_AA="$(cd "$AA/src" && BACKUP_DIR="$AA/out" "$BACKUP" 2>&1)"+ARCHIVE_AA="$(ls "$AA"/out/openwa-backup-*.tar.gz)"+NOTE_AA="$(tar -xOzf "$ARCHIVE_AA" ./ENGINE-STATE-NOTE 2>/dev/null || true)"+if ! printf '%s\n' "$NOTE_AA" | grep -q 'open in a browser: session-s1)' ||+ ! printf '%s\n' "$NOTE_AA" | grep -q '^baileys/'; then+ fail "(aa) the archive does not note the open profile and the Baileys state: $NOTE_AA"+fi+# Without sqlite3 the same archive carries CONSISTENCY-WARNING, so the engine note must not vouch+# for the databases.+if printf '%s\n' "$NOTE_AA" | grep -qi 'consistent snapshot'; then+ fail "(aa) the engine note claims the databases are consistent: $NOTE_AA"+fi+if ! printf '%s' "$OUT_AA" | grep -q 'may have been written during the copy'; then+ fail "(aa) backup did not warn that engine auth state may have been written during the copy: $OUT_AA"+fi+if ! tar -tvzf "$ARCHIVE_AA" | grep -q '^l.*session-s1/SingletonLock'; then+ fail "(aa) the profile lock was not archived as the symlink it is"+fi+# Without sqlite3 the databases are plain-copied and --strict rightly refuses on that marker.+if [ "$HAS_SQLITE3" -eq 1 ]; then+ OUT_AA="$(cd "$AA/dst" && "$RESTORE" "$ARCHIVE_AA" --strict 2>&1)" ||+ fail "(aa) restore --strict refused an archive whose only note is the engine one: $OUT_AA"+else+ OUT_AA="$(cd "$AA/dst" && "$RESTORE" "$ARCHIVE_AA" 2>&1)" || fail "(aa) restore failed: $OUT_AA"+fi+if ! printf '%s' "$OUT_AA" | grep -q 'ENGINE-STATE-NOTE; engine auth state may have been copied' ||+ ! printf '%s' "$OUT_AA" | grep -q 'session-s1'; then+ fail "(aa) restore did not print the engine state note: $OUT_AA"+fi+# No open profile and no Baileys state: nothing to note.+make_fixture "$AA/quiet/data/main.sqlite" "alpha2-quiet-main"+make_fixture "$AA/quiet/data/openwa.sqlite" "alpha2-quiet-data"+printf 'profile\n' >"$AA/quiet/data/sessions/session-s1/Preferences"+(cd "$AA/quiet" && BACKUP_DIR="$AA/quiet-out" "$BACKUP" >/dev/null 2>&1)+if tar -tzf "$(ls "$AA"/quiet-out/openwa-backup-*.tar.gz)" | grep -q 'ENGINE-STATE-NOTE'; then+ fail "(aa) an archive with no open profile and no Baileys state carries the engine note"+fi+pass "(aa) live engine auth state is noted in the archive and printed, never refused"+echo ""echo "All smoke tests passed!"diff --git a/src/common/ci-privilege-gate.spec.ts b/src/common/ci-privilege-gate.spec.tsindex dcf8eede6..9650bc4fd 100644--- a/src/common/ci-privilege-gate.spec.ts+++ b/src/common/ci-privilege-gate.spec.ts@@ -345,4 +345,16 @@ describe('deployment docs describe what the entrypoint, probes and backup scriptexpect(text).toMatch(/the chart's startupProbe budget/);}});++ // The note is written for any archive holding engine state, including one taken with sessions stopped.+ it('words the ENGINE-STATE-NOTE as a possibility in the restore.sh header', () => {+ const phrase = 'ENGINE-STATE-NOTE (engine auth state that may have been copied while the app ran)';+ const header = read('scripts/restore.sh')+ .split('\n')+ .filter(line => line.startsWith('#'))+ .map(line => line.replace(/^#\s*/, ''))+ .join(' ');+ expect(header).toContain(phrase);+ expect(read('docs/11-operational-runbooks.md')).toContain(phrase);+ });});