Bring script headers onto the template and close safeguard gaps

Headers claimed protections the code never had, and several destructive paths had no
guard against a collapsed config value.

Arrs_Stack/upgrade_webhook_handler.sh

@@ -15,6 +15,30 @@
 # begin searching — a search it will never win because we already have it.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# Invoked per import by webhook_listener.js with <arr_type> <item_path>:
+#
+#   1. Validate
+#        → arr_type must be sonarr|radarr|lidarr; item_path must exist and be a safe
+#          absolute path
+#
+#   2. Resolve arr specifics
+#        → API port, API version and rescan command for that arr type
+#
+#   3. Discover remote nodes
+#        → discover_remote_nodes(); no remotes configured means exit cleanly
+#
+#   4. Per remote node, independently:
+#        a. Resolve its Tailscale IP — unresolvable skips that node
+#        b. rsync the single item to the same absolute path (--no-delete)
+#        c. Skip the rescan if rsync failed — never scan a partial file
+#        d. Trigger the arr's refresh command, cache-first API key with SSH fallback
+#
+# One failing node is counted and skipped; the rest still receive the upgrade.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -38,13 +62,47 @@
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
-#   Arg validation      — exits with usage message if arr_type or item_path missing
-#   Path existence      — exits if item_path is not a directory on disk
-#   Tailscale resolution — skips a node if its Tailscale IP cannot be resolved
-#   rsync exit check    — rescan is only triggered if rsync succeeded; a failed
-#                         transfer does not cause the remote arr to scan a partial file
-#   SSH fallback        — if no cached API key, falls back to SSH to read config.xml
-#                         on the remote rather than failing the rescan step
+# Root Enforcement
+#   rsync runs over SSH as root and writes to root@remote at the same absolute path.
+#
+# Argument Validation
+#   Exits with a usage message if arr_type or item_path is missing, and rejects an
+#   arr_type outside sonarr|radarr|lidarr rather than defaulting to one.
+#
+# Path Existence
+#   Exits if item_path is not a directory on disk.
+#
+# Item Path Depth Guard
+#   item_path must be an absolute path at least three levels deep. It arrives from the
+#   arr's webhook payload and is rsynced to the same path on the partner, so a truncated
+#   or malformed value would push a system directory — or the filesystem root — onto the
+#   remote. The existence check alone does not catch this, because / is a directory.
+#
+# No Lock — Deliberate
+#   This is an event handler invoked per import by webhook_listener.js. Concurrent
+#   upgrades are normal and expected. A default lock would silently drop overlapping
+#   events, and a waiting lock would queue them behind a slow transfer, so neither is
+#   used: each invocation rsyncs a different item path and they do not contend.
+#
+# Tailscale Resolution
+#   Skips a node if its Tailscale IP cannot be resolved, rather than attempting the
+#   transfer against an unresolved or stale address.
+#
+# rsync Exit Check
+#   The rescan is only triggered if rsync succeeded. A failed transfer never causes the
+#   remote arr to scan a partial file into its library.
+#
+# No Delete on Push
+#   rsync runs with --no-delete. This pushes one upgraded item; it is not a mirror, and
+#   must never remove content on the partner that this run does not know about.
+#
+# SSH Fallback
+#   If no cached API key is available, falls back to SSH to read config.xml on the
+#   remote rather than failing the rescan step.
+#
+# Per-Node Isolation
+#   One unreachable or failing node is counted and skipped; the remaining nodes still
+#   receive the upgrade.
 #
 # ==============================================================================================
 # CONFIGURATION
@@ -90,6 +148,21 @@ ITEM_PATH="${2:-}"
 
 [[ -d "$ITEM_PATH" ]] || { echo "Path not found: $ITEM_PATH" >&2; exit 1; }
 
+if [[ "$EUID" -ne 0 ]]; then
+    echo "Must be run as root" >&2
+    exit 1
+fi
+
+# ITEM_PATH is rsynced to root@remote at the same absolute path. It arrives from the arr's
+# webhook payload, so a malformed or truncated value would push a system directory — or the
+# filesystem root — onto the partner. -d alone does not catch that: / is a directory.
+_depth="${ITEM_PATH//[^\/]/}"
+if [[ "$ITEM_PATH" != /* || "${#_depth}" -lt 3 ]]; then
+    echo "Refusing unsafe item path: '$ITEM_PATH' — expected an absolute path at least 3 levels deep" >&2
+    exit 1
+fi
+unset _depth
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../load_config.sh"
 detect_hosts