Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(scripts): follow BOOTSTRAP_KEY_FILE for the plaintext admin key

Yudhi Armyndharisc48ae0b8c672
diff --git a/charts/openwa/templates/NOTES.txt b/charts/openwa/templates/NOTES.txt
index 5e90c23ad..8182d633e 100644
--- a/charts/openwa/templates/NOTES.txt
+++ b/charts/openwa/templates/NOTES.txt
@@ -9,7 +9,7 @@ OpenWA has been installed as release "{{ .Release.Name }}".
2. Get the API key. If secretEnv.API_MASTER_KEY was left empty, the app generated
one on first boot and stored it on the PVC:
- kubectl -n {{ .Release.Namespace }} exec {{ include "openwa.fullname" . }}-0 -- cat /app/data/.api-key
+ kubectl -n {{ .Release.Namespace }} exec {{ include "openwa.fullname" . }}-0 -- cat {{ (.Values.env | default dict).BOOTSTRAP_KEY_FILE | default "/app/data/.api-key" }}
3. Reach the API + dashboard:
kubectl -n {{ .Release.Namespace }} port-forward svc/{{ include "openwa.fullname" . }} 2785:{{ .Values.service.port }}
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index 004bec6cb..01d20f536 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -609,6 +609,7 @@ User-managed files outside that list (for example the project-level `.env`) must
# - plugin-packages/ — installed plugin code from PLUGINS_DIR
# - plugin-state/ — registry + ctx.storage state under OPENWA_DATA_DIR
# - .env.generated / .api-key — generated configuration and bootstrap secret
+# (.api-key from BOOTSTRAP_KEY_FILE when that is set)
#
# The database paths resolve exactly like the app: the explicit MAIN_DATABASE_NAME /
# DATABASE_NAME env path wins, otherwise the fixed ./data defaults — they are NOT derived from
diff --git a/scripts/backup.sh b/scripts/backup.sh
index f43a44662..a145f340d 100755
--- a/scripts/backup.sh
+++ b/scripts/backup.sh
@@ -32,6 +32,7 @@
# DATABASE_TYPE sqlite (default) | postgres
# SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH, PLUGINS_DIR
# override the corresponding state directories
+# BOOTSTRAP_KEY_FILE the plaintext admin key to archive (default: <data dir>/.api-key)
# For postgres: DATABASE_URL, or DATABASE_HOST/PORT/USERNAME/PASSWORD/NAME
# DATABASE_URL is read by this script only (the app uses the DATABASE_* keys)
# and wins over them when set. It is passed to pg_dump as an argument, which
@@ -81,7 +82,8 @@ PLUGIN_PACKAGES_DIR="$(openwa_resolve PLUGINS_DIR "$DATA_DIR/plugins")"
PLUGIN_STATE_ROOT="$(openwa_resolve PLUGIN_STATE_DIR "$DATA_DIR")"
PLUGIN_STATE_DIR="$PLUGIN_STATE_ROOT/plugins"
GENERATED_ENV="$DATA_DIR/.env.generated"
-ADMIN_KEY_FILE="$DATA_DIR/.api-key"
+# The app writes the generated admin key to BOOTSTRAP_KEY_FILE when that is set.
+ADMIN_KEY_FILE="$(openwa_resolve BOOTSTRAP_KEY_FILE "$DATA_DIR/.api-key")"
log() { echo "[backup] $*"; }
diff --git a/scripts/restore.sh b/scripts/restore.sh
index b6c74ce31..a01eae4df 100755
--- a/scripts/restore.sh
+++ b/scripts/restore.sh
@@ -24,6 +24,7 @@
# OPENWA_DATA_DIR data directory to restore non-DB state into (default: ./data)
# SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH, PLUGINS_DIR
# override the corresponding state directories
+# BOOTSTRAP_KEY_FILE where the plaintext admin key goes (default: <data dir>/.api-key)
# OPENWA_RESTORE_SNAPSHOT_DIR
# where the safety snapshots go (default: next to the data dir, and next to
# each target outside it); needed when a parent is read-only, as in the
@@ -176,8 +177,8 @@ replace_tree() {
}
# The data-dir safety snapshot below cannot cover a target that lives OUTSIDE it (a custom
-# MAIN_DATABASE_NAME / DATABASE_NAME, SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH or
-# PLUGINS_DIR). Preserve such a target separately, so a restore pointed at the wrong archive remains
+# MAIN_DATABASE_NAME / DATABASE_NAME, SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH,
+# PLUGINS_DIR or BOOTSTRAP_KEY_FILE). Preserve such a target separately, so a restore pointed at the wrong archive remains
# recoverable. OPENWA_RESTORE_SNAPSHOT_DIR takes these snapshots too when it is set: a target on its
# own mount under a read-only root has no writable place next to it.
snapshot_external() {
@@ -313,6 +314,8 @@ PLUGIN_PACKAGES_DIR="$(openwa_resolve PLUGINS_DIR "$DATA_DIR/plugins")"
# not the plugins directory inside it.
PLUGIN_STATE_ROOT="$(openwa_resolve PLUGIN_STATE_DIR "$DATA_DIR")"
PLUGIN_STATE_DIR="$PLUGIN_STATE_ROOT/plugins"
+# The app reads the plaintext admin key from BOOTSTRAP_KEY_FILE when that is set.
+ADMIN_KEY_FILE="$(openwa_resolve BOOTSTRAP_KEY_FILE "$DATA_DIR/.api-key")"
# backup.sh archives state directories by content. An archive from before it followed symlinks
# carries a link instead, which on this host may point at the very directory the restore empties
@@ -415,6 +418,23 @@ restore_targets() {
replace_tree "$STAGE/plugin-state" "$PLUGIN_STATE_DIR" "plugin registry and persisted state"
fi
fi
+ if [ -f "$STAGE/.api-key" ]; then
+ restore_admin_key
+ fi
+}
+
+# The plaintext admin key goes where the app reads it. Checked and, outside the data dir, snapshotted
+# with the other targets: it may be the only plaintext copy of a key the replaced main.sqlite accepts.
+restore_admin_key() {
+ if [ "$PHASE" = snapshot ]; then
+ openwa_writable "$ADMIN_KEY_FILE" || refuse_unwritable "$ADMIN_KEY_FILE" "admin key (BOOTSTRAP_KEY_FILE)"
+ snapshot_external "$ADMIN_KEY_FILE"
+ return
+ fi
+ log "Restoring plaintext admin key -> $ADMIN_KEY_FILE"
+ mkdir -p "$(dirname "$ADMIN_KEY_FILE")"
+ cp "$STAGE/.api-key" "$ADMIN_KEY_FILE"
+ chmod 0600 "$ADMIN_KEY_FILE"
}
PHASE=snapshot
@@ -428,12 +448,6 @@ if [ -f "$STAGE/.env.generated" ]; then
chmod 0600 "$DATA_DIR/.env.generated"
fi
-if [ -f "$STAGE/.api-key" ]; then
- log "Restoring plaintext admin key"
- cp "$STAGE/.api-key" "$DATA_DIR/.api-key"
- chmod 0600 "$DATA_DIR/.api-key"
-fi
-
if [ -f "$STAGE/database.sql" ]; then
cp "$STAGE/database.sql" "$DATA_DIR/database.sql"
log "Postgres dump present: load it into an EMPTY database, as docs/11-operational-runbooks.md"
diff --git a/scripts/smoke-test-backup-restore.sh b/scripts/smoke-test-backup-restore.sh
index 0d962f777..a1b1d59cd 100755
--- a/scripts/smoke-test-backup-restore.sh
+++ b/scripts/smoke-test-backup-restore.sh
@@ -34,6 +34,8 @@
# (v) a leftover STORAGE_LOCAL_PATH=./uploads the app cannot create falls back to ./data/media in
# both scripts, and a missing media dir is reported (skipped as root)
# (w) the default colocated plugins dir is rebuilt from both archive members, even when they differ
+# (x) a relocated BOOTSTRAP_KEY_FILE is archived and restored there, and an unwritable one is refused
+# before any database is written (that half skipped as root)
#
# Usage: ./scripts/smoke-test-backup-restore.sh
# Requires: bash, tar, node (restore.sh path resolution). sqlite3 is optional (see (c) and (k)).
@@ -43,7 +45,7 @@ set -euo pipefail
# would aim a case at a real install, and restore replaces the state directories wholesale, so every
# case starts from none of them and sets exactly the paths it uses.
unset OPENWA_DATA_DIR BACKUP_DIR DATABASE_TYPE MAIN_DATABASE_NAME DATABASE_NAME SESSION_DATA_PATH \
- BAILEYS_AUTH_DIR STORAGE_LOCAL_PATH PLUGINS_DIR PLUGIN_STATE_DIR OPENWA_RESTORE_SNAPSHOT_DIR
+ BAILEYS_AUTH_DIR STORAGE_LOCAL_PATH PLUGINS_DIR PLUGIN_STATE_DIR OPENWA_RESTORE_SNAPSHOT_DIR BOOTSTRAP_KEY_FILE
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
BACKUP="$REPO_ROOT/scripts/backup.sh"
@@ -1062,5 +1064,53 @@ mkdir -p "$W/dst2"
check_plugins "$W/dst2/data/plugins" "default round trip"
pass "(w) the colocated plugins dir gets packages and state, and loses what the archive does not carry"
+echo ""
+echo "==> (x) a BOOTSTRAP_KEY_FILE outside the data dir is archived and restored there"
+# The app writes and reads the generated admin key at BOOTSTRAP_KEY_FILE. The scripts only looked at
+# <data dir>/.api-key, so a relocated key was left out of the archive without a word, and an archived
+# one went back to a path the app never reads.
+X="$WORK/x"
+mkdir -p "$X/src/data" "$X/src/secrets" "$X/dst" "$X/ro/data"
+make_fixture "$X/src/data/main.sqlite" "xray-main"
+make_fixture "$X/src/data/openwa.sqlite" "xray-data"
+printf 'xray-key\n' >"$X/src/secrets/admin.key"
+printf 'BOOTSTRAP_KEY_FILE=%s\n' "$X/src/secrets/admin.key" >"$X/src/.env"
+(
+ cd "$X/src"
+ BACKUP_DIR="$X/out" "$BACKUP" >/dev/null
+)
+ARCHIVE_X="$(ls "$X"/out/openwa-backup-*.tar.gz)"
+if [ "$(tar -xOzf "$ARCHIVE_X" ./.api-key 2>/dev/null || true)" != "xray-key" ]; then
+ fail "(x) backup left out the admin key BOOTSTRAP_KEY_FILE names"
+fi
+(
+ cd "$X/dst"
+ BOOTSTRAP_KEY_FILE="$X/dst/secrets/admin.key" "$RESTORE" "$ARCHIVE_X" >/dev/null
+)
+if [ "$(cat "$X/dst/secrets/admin.key" 2>/dev/null || true)" != "xray-key" ]; then
+ fail "(x) restore did not put the admin key where BOOTSTRAP_KEY_FILE points"
+fi
+if [ -e "$X/dst/data/.api-key" ]; then
+ fail "(x) restore also wrote the admin key to the data dir, where the app does not read it"
+fi
+if [ "$(id -u)" -ne 0 ]; then
+ # A key path the restore cannot write is refused with the other targets, before any database.
+ make_fixture "$X/ro/data/main.sqlite" "xray-live-main"
+ mkdir -p "$X/ro/secrets"
+ chmod a-w "$X/ro/secrets"
+ set +e
+ OUT_X="$(cd "$X/ro" && BOOTSTRAP_KEY_FILE="$X/ro/secrets/admin.key" "$RESTORE" "$ARCHIVE_X" --force 2>&1)"
+ RC_X=$?
+ set -e
+ chmod u+w "$X/ro/secrets"
+ if [ "$RC_X" -eq 0 ] || ! printf '%s' "$OUT_X" | grep -q 'cannot write'; then
+ fail "(x) an unwritable BOOTSTRAP_KEY_FILE was not refused: $OUT_X"
+ fi
+ if [ "$(db_fingerprint "$X/ro/data/main.sqlite")" != "xray-live-main" ]; then
+ fail "(x) the main DB was overwritten before the unwritable key path stopped the restore"
+ fi
+fi
+pass "(x) BOOTSTRAP_KEY_FILE is honoured by backup and by restore"
+
echo ""
echo "All smoke tests passed!"