@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/deploy/unraid/ouro-events/install-usenet-guard.sh

@@ -0,0 +1,435 @@
+#!/bin/bash
+set -euo pipefail
+
+SOURCE_ROOT="$(cd "$(dirname "$0")" && pwd -P)"
+INSTALL_ROOT="/boot/config/custom"
+GO_FILE="/boot/config/go"
+CRONTAB_FILE=""
+ACTION="install"
+RESTORE_ROOT=""
+STAGE_PATH=""
+SYSTEM_CRON_PRESENT=false
+
+while (($# > 0)); do
+  case "$1" in
+    --install-only) ACTION="install"; shift ;;
+    --boot) ACTION="boot"; shift ;;
+    --restore-root) ACTION="restore"; RESTORE_ROOT="${2:?missing --restore-root value}"; shift 2 ;;
+    --source-root) SOURCE_ROOT="${2:?missing --source-root value}"; shift 2 ;;
+    --install-root) INSTALL_ROOT="${2:?missing --install-root value}"; shift 2 ;;
+    --go-file) GO_FILE="${2:?missing --go-file value}"; shift 2 ;;
+    --crontab-file) CRONTAB_FILE="${2:?missing --crontab-file value}"; shift 2 ;;
+    *) echo "usenet guard installer: invalid argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+validate_persisted_path() {
+  local value="$1" label="$2"
+  [[ "$value" =~ ^/[A-Za-z0-9._/-]+$ ]] && [[ "$value" != */ ]] && [[ "$value" != *"//"* ]] && [[ "$value" != *"/../"* ]] && [[ "$value" != */.. ]] && [[ "$value" != *"/./"* ]] && [[ "$value" != */. ]] || {
+    echo "usenet guard installer: $label must be a canonical absolute path" >&2
+    exit 2
+  }
+}
+
+validate_persisted_path "$INSTALL_ROOT" "install root"
+if [ -n "$CRONTAB_FILE" ]; then validate_persisted_path "$CRONTAB_FILE" "crontab file"; fi
+if [ -n "$RESTORE_ROOT" ]; then validate_persisted_path "$RESTORE_ROOT" "restore root"; fi
+
+EVENT_ROOT="$INSTALL_ROOT/ouro-events"
+printf -v EVENT_INSTALLER_Q '%q' "$EVENT_ROOT/install-usenet-guard.sh"
+printf -v INSTALL_ROOT_Q '%q' "$INSTALL_ROOT"
+BOOT_HOOK="/bin/bash $EVENT_INSTALLER_Q --boot --install-root $INSTALL_ROOT_Q"
+PREVIOUS_INSTALLER_BOOT_HOOK="/bin/bash $EVENT_INSTALLER_Q --boot"
+if [ -n "$CRONTAB_FILE" ]; then
+  printf -v CRONTAB_FILE_Q '%q' "$CRONTAB_FILE"
+  BOOT_HOOK+=" --crontab-file $CRONTAB_FILE_Q"
+  PREVIOUS_INSTALLER_BOOT_HOOK+=" --crontab-file $CRONTAB_FILE_Q"
+fi
+LEGACY_BOOT_HOOK="/boot/config/custom/ouro-events/bootstrap-spool.sh --mount"
+LEGACY_BASH_BOOT_HOOK="/bin/bash /boot/config/custom/ouro-events/bootstrap-spool.sh --mount"
+CANONICAL_PREVIOUS_BOOT_HOOK="/bin/bash /boot/config/custom/ouro-events/install-usenet-guard.sh --boot"
+CANONICAL_BOOT_HOOK="$CANONICAL_PREVIOUS_BOOT_HOOK --install-root /boot/config/custom"
+LEGACY_CRON_BOOT_HOOK='(crontab -l 2>/dev/null | grep -v usenet_health; echo "*/15 * * * * /bin/bash /boot/config/custom/usenet_health.sh") | crontab -'
+printf -v HEALTH_SCRIPT_Q '%q' "$INSTALL_ROOT/usenet_health.sh"
+CRON_LINE="*/15 * * * * /bin/bash $HEALTH_SCRIPT_Q # ouro:usenet-health"
+LEGACY_CRON_LINE="*/15 * * * * /bin/bash $HEALTH_SCRIPT_Q"
+CANONICAL_CRON_LINE="*/15 * * * * /bin/bash /boot/config/custom/usenet_health.sh # ouro:usenet-health"
+CANONICAL_LEGACY_CRON_LINE="*/15 * * * * /bin/bash /boot/config/custom/usenet_health.sh"
+ASSET_NAMES=(usenet-health.sh bootstrap-spool.sh emit-event.mjs emit-usenet-event.sh install-usenet-guard.sh)
+TARGET_PATHS=("$INSTALL_ROOT/usenet_health.sh" "$EVENT_ROOT/bootstrap-spool.sh" "$EVENT_ROOT/emit-event.mjs" "$EVENT_ROOT/emit-usenet-event.sh" "$EVENT_ROOT/install-usenet-guard.sh")
+
+atomic_install() {
+  local source="$1" target="$2" mode="$3" temporary="${2}.ouro-next.$$" status
+  /bin/mkdir -p "$(dirname "$target")"
+  install -m "$mode" "$source" "$temporary" || { status=$?; /bin/rm -f "$temporary"; return "$status"; }
+  mv "$temporary" "$target" || { status=$?; /bin/rm -f "$temporary"; return "$status"; }
+}
+
+private_transaction_workspace() {
+  local kind="$1" workspace identity status
+  workspace="$(/usr/bin/mktemp -d "/tmp/ouro-usenet-$kind.XXXXXX")" || return $?
+  [ -d "$workspace" ] && [ ! -L "$workspace" ] || { status=$?; /bin/rmdir "$workspace" 2>/dev/null || true; return "$status"; }
+  identity="$(/usr/bin/stat -c '%u:%a' "$workspace" 2>/dev/null || /usr/bin/stat -f '%u:%Lp' "$workspace")" || { status=$?; /bin/rmdir "$workspace"; return "$status"; }
+  [ "$identity" = "$(id -u):700" ] || { /bin/rmdir "$workspace"; return 1; }
+  printf '%s\n' "$workspace"
+}
+
+cleanup_stale_atomic_residue() {
+  local target parent base
+  for target in "${TARGET_PATHS[@]}" "$GO_FILE"; do
+    parent="$(dirname "$target")"
+    base="$(basename "$target")"
+    [ ! -d "$parent" ] || find "$parent" -maxdepth 1 \( -type f -o -type l \) \( -name "$base.ouro-next.*" -o -name "$base.ouro-restore.*" \) -delete
+  done
+  if [ -n "$CRONTAB_FILE" ]; then
+    parent="$(dirname "$CRONTAB_FILE")"
+    base="$(basename "$CRONTAB_FILE")"
+    [ ! -d "$parent" ] || find "$parent" -maxdepth 1 \( -type f -o -type l \) \( -name "$base.ouro-next.*" -o -name "$base.ouro-restore.*" \) -delete
+  fi
+}
+
+is_canonical_butler_cron_line() {
+  case "$1" in
+    "$CRON_LINE"|"$LEGACY_CRON_LINE"|"$CANONICAL_CRON_LINE"|"$CANONICAL_LEGACY_CRON_LINE") return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+render_cron_without_owned() {
+  local source="$1" target="$2" line
+  : > "$target"
+  while IFS= read -r line || [ -n "$line" ]; do
+    if ! is_canonical_butler_cron_line "$line"; then printf '%s\n' "$line" >> "$target"; fi
+  done < "$source"
+}
+
+cron_contains_owned() {
+  local source="$1" line
+  while IFS= read -r line || [ -n "$line" ]; do
+    if is_canonical_butler_cron_line "$line"; then return 0; fi
+  done < "$source"
+  return 1
+}
+
+render_cron() {
+  local source="$1" target="$2"
+  render_cron_without_owned "$source" "$target"
+  printf '%s\n' "$CRON_LINE" >> "$target"
+  /bin/chmod 0600 "$target"
+}
+
+render_inactive_cron() {
+  local source="$1" target="$2"
+  render_cron_without_owned "$source" "$target"
+  /bin/chmod 0600 "$target"
+}
+
+is_canonical_butler_go_hook() {
+  case "$1" in
+    "$LEGACY_BOOT_HOOK"|"$LEGACY_BASH_BOOT_HOOK"|"$CANONICAL_PREVIOUS_BOOT_HOOK"|"$CANONICAL_BOOT_HOOK"|"$PREVIOUS_INSTALLER_BOOT_HOOK"|"$BOOT_HOOK"|"$LEGACY_CRON_BOOT_HOOK") return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+render_go_without_owned() {
+  local source="$1" target="$2" line
+  : > "$target"
+  while IFS= read -r line || [ -n "$line" ]; do
+    if ! is_canonical_butler_go_hook "$line"; then printf '%s\n' "$line" >> "$target"; fi
+  done < "$source"
+}
+
+read_system_cron() {
+  local error_file="${1}.error" status current_user
+  current_user="$(id -un)" || return $?
+  if crontab -l > "$1" 2>"$error_file"; then
+    SYSTEM_CRON_PRESENT=true
+  else
+    status=$?
+    if [ "$status" -eq 1 ] && grep -Fxq "no crontab for $current_user" "$error_file"; then
+      SYSTEM_CRON_PRESENT=false
+      : > "$1"
+    else
+      /bin/rm -f "$1" "$error_file"
+      return "$status"
+    fi
+  fi
+  /bin/rm -f "$error_file"
+}
+
+activate_cron_file() {
+  if [ -n "$CRONTAB_FILE" ]; then
+    atomic_install "$1" "$CRONTAB_FILE" 0600
+  else
+    crontab "$1"
+  fi
+}
+
+preflight_sources() {
+  local name
+  for name in "${ASSET_NAMES[@]}"; do
+    [ -f "$SOURCE_ROOT/$name" ] && [ ! -L "$SOURCE_ROOT/$name" ] && [ -s "$SOURCE_ROOT/$name" ] || { echo "usenet guard installer: source asset is missing or unsafe: $name" >&2; return 1; }
+  done
+  /bin/bash -n "$SOURCE_ROOT/usenet-health.sh" "$SOURCE_ROOT/bootstrap-spool.sh" "$SOURCE_ROOT/emit-usenet-event.sh" "$SOURCE_ROOT/install-usenet-guard.sh"
+  "$(command -v node)" --check "$SOURCE_ROOT/emit-event.mjs"
+}
+
+restore_target() {
+  local target="$1" backup="$2" temporary="${1}.ouro-next.$$"
+  if [ -f "$backup" ]; then
+    /usr/bin/install -m "$(/bin/stat -c '%a' "$backup" 2>/dev/null || /usr/bin/stat -f '%Lp' "$backup")" "$backup" "$temporary"
+    /bin/mv "$temporary" "$target"
+  else
+    /bin/rm -f "$target" "$temporary"
+  fi
+}
+
+rollback_host_state() {
+  local backup="$1" index rollback_status=0 attempt_status
+  for index in "${!TARGET_PATHS[@]}"; do
+    restore_target "${TARGET_PATHS[$index]}" "$backup/asset-$index"
+    attempt_status=$?
+    if [ "$attempt_status" -ne 0 ] && [ "$rollback_status" -eq 0 ]; then rollback_status=$attempt_status; fi
+  done
+  restore_target "$GO_FILE" "$backup/go"
+  attempt_status=$?
+  if [ "$attempt_status" -ne 0 ] && [ "$rollback_status" -eq 0 ]; then rollback_status=$attempt_status; fi
+  if [ -n "$CRONTAB_FILE" ]; then
+    restore_target "$CRONTAB_FILE" "$backup/cron"
+  elif [ "$SYSTEM_CRON_PRESENT" = true ]; then
+    crontab "$backup/cron"
+  else
+    crontab -r >/dev/null 2>&1
+  fi
+  attempt_status=$?
+  if [ "$attempt_status" -ne 0 ] && [ "$rollback_status" -eq 0 ]; then rollback_status=$attempt_status; fi
+  return "$rollback_status"
+}
+
+install_transaction() {
+  preflight_sources
+  /bin/mkdir -p "$INSTALL_ROOT"
+  cleanup_stale_atomic_residue
+  local stage backup cron_original cron_inactive cron_candidate go_candidate status rollback_status index name target
+  stage="$(private_transaction_workspace install)"
+  STAGE_PATH="$stage"
+  backup="$stage/backup"
+  /bin/mkdir "$backup"
+  cleanup() { [ -z "$STAGE_PATH" ] || /bin/rm -rf "$STAGE_PATH"; }
+  trap cleanup EXIT
+
+  for index in "${!ASSET_NAMES[@]}"; do
+    name="${ASSET_NAMES[$index]}"
+    /usr/bin/install -m 0700 "$SOURCE_ROOT/$name" "$stage/$name"
+  done
+  /bin/bash "$stage/bootstrap-spool.sh" --mount
+  /bin/bash "$stage/bootstrap-spool.sh" --self-test
+  /bin/bash "$stage/emit-usenet-event.sh" --self-test "$stage/emit-event.mjs"
+
+  if [ -f "$GO_FILE" ]; then
+    /bin/cp -p "$GO_FILE" "$backup/go"
+    /bin/cp -p "$GO_FILE" "$stage/go.base"
+  else
+    printf '#!/bin/bash\n' > "$stage/go.base"
+  fi
+  go_candidate="$stage/go.candidate"
+  render_go_without_owned "$stage/go.base" "$stage/go.filtered"
+  if [ -s "$stage/go.filtered" ]; then
+    awk -v hook="$BOOT_HOOK" 'NR == 1 && /^#!/ { print; print hook; next } NR == 1 { print hook } { print }' "$stage/go.filtered" > "$go_candidate"
+  else
+    printf '#!/bin/bash\n%s\n' "$BOOT_HOOK" > "$go_candidate"
+  fi
+  /bin/chmod 0700 "$go_candidate"
+
+  cron_original="$stage/cron.original"
+  if [ -n "$CRONTAB_FILE" ]; then
+    if [ -f "$CRONTAB_FILE" ]; then /bin/cp -p "$CRONTAB_FILE" "$backup/cron"; /bin/cp "$CRONTAB_FILE" "$cron_original"; else : > "$cron_original"; fi
+  else
+    read_system_cron "$cron_original"
+    /bin/cp "$cron_original" "$backup/cron"
+  fi
+  cron_candidate="$stage/cron.candidate"
+  render_cron "$cron_original" "$cron_candidate"
+  cron_inactive="$stage/cron.inactive"
+  render_inactive_cron "$cron_original" "$cron_inactive"
+
+  for index in "${!TARGET_PATHS[@]}"; do
+    target="${TARGET_PATHS[$index]}"
+    if [ -e "$target" ]; then
+      [ -f "$target" ] && [ ! -L "$target" ] || { echo "usenet guard installer: live asset is unsafe" >&2; return 1; }
+      /bin/cp -p "$target" "$backup/asset-$index"
+    fi
+  done
+
+  set +e
+  status=0
+  if cron_contains_owned "$cron_original"; then activate_cron_file "$cron_inactive" || status=$?; fi
+  if [ "$status" -eq 0 ]; then
+    for index in "${!TARGET_PATHS[@]}"; do
+      atomic_install "$stage/${ASSET_NAMES[$index]}" "${TARGET_PATHS[$index]}" 0700 || { status=$?; break; }
+    done
+  fi
+  if [ "$status" -eq 0 ]; then atomic_install "$go_candidate" "$GO_FILE" 0700 || status=$?; fi
+  if [ "$status" -eq 0 ]; then activate_cron_file "$cron_candidate" || status=$?; fi
+  set -e
+  if [ "$status" -ne 0 ]; then
+    set +e
+    rollback_host_state "$backup"
+    rollback_status=$?
+    set -e
+    if [ "$rollback_status" -ne 0 ]; then return "$rollback_status"; fi
+    return "$status"
+  fi
+  cleanup
+  STAGE_PATH=""
+  trap - EXIT
+}
+
+boot_activate() {
+  /bin/bash "$EVENT_ROOT/bootstrap-spool.sh" --mount
+  /bin/bash "$EVENT_ROOT/bootstrap-spool.sh" --self-test
+  /bin/bash "$EVENT_ROOT/emit-usenet-event.sh" --self-test "$EVENT_ROOT/emit-event.mjs"
+  local workspace current candidate
+  workspace="$(private_transaction_workspace boot)"
+  STAGE_PATH="$workspace"
+  cleanup() { [ -z "$STAGE_PATH" ] || /bin/rm -rf "$STAGE_PATH"; }
+  trap cleanup EXIT
+  current="$workspace/current"
+  candidate="$workspace/candidate"
+  /usr/bin/install -m 0600 /dev/null "$current"
+  /usr/bin/install -m 0600 /dev/null "$current.error"
+  /usr/bin/install -m 0600 /dev/null "$candidate"
+  if [ -n "$CRONTAB_FILE" ]; then
+    if [ -f "$CRONTAB_FILE" ]; then /bin/cp "$CRONTAB_FILE" "$current"; else : > "$current"; fi
+  else
+    read_system_cron "$current"
+  fi
+  render_cron "$current" "$candidate"
+  activate_cron_file "$candidate"
+  cleanup
+  STAGE_PATH=""
+  trap - EXIT
+}
+
+restore_snapshot() {
+  local expected_inventory stage backup cron_original cron_inactive cron_candidate go_original go_filtered go_candidate status rollback_status index target relative source state global_name global_state global_digest global_count go_state cron_state
+  expected_inventory=$'present\tcustom/usenet_health.sh\npresent\tcustom/ouro-events/bootstrap-spool.sh\npresent\tcustom/ouro-events/emit-event.mjs\npresent\tcustom/ouro-events/emit-usenet-event.sh\npresent\tcustom/ouro-events/install-usenet-guard.sh\npresent\tgo.butler-lines\npresent\tcrontab.butler-lines\npresent\tglobal-state'
+  [ -d "$RESTORE_ROOT" ] && [ ! -L "$RESTORE_ROOT" ] || return 1
+  [ -f "$RESTORE_ROOT/inventory" ] && [ ! -L "$RESTORE_ROOT/inventory" ] || return 1
+  while IFS=$'\t' read -r state relative; do
+    case "$state:$relative" in
+      present:custom/usenet_health.sh|absent:custom/usenet_health.sh|present:custom/ouro-events/bootstrap-spool.sh|absent:custom/ouro-events/bootstrap-spool.sh|present:custom/ouro-events/emit-event.mjs|absent:custom/ouro-events/emit-event.mjs|present:custom/ouro-events/emit-usenet-event.sh|absent:custom/ouro-events/emit-usenet-event.sh|present:custom/ouro-events/install-usenet-guard.sh|absent:custom/ouro-events/install-usenet-guard.sh|present:go.butler-lines|present:crontab.butler-lines|present:global-state) ;;
+      *) return 1 ;;
+    esac
+    if [ "$state" = present ]; then [ -f "$RESTORE_ROOT/$relative" ] && [ ! -L "$RESTORE_ROOT/$relative" ] || return 1; else [ ! -e "$RESTORE_ROOT/$relative" ] && [ ! -L "$RESTORE_ROOT/$relative" ] || return 1; fi
+  done < "$RESTORE_ROOT/inventory"
+  test "$(sed 's/^absent/present/' "$RESTORE_ROOT/inventory")" = "$expected_inventory" || return 1
+  index=0
+  while IFS=$'\t' read -r global_name global_state global_digest global_count; do
+    case "$index:$global_name:$global_state" in
+      0:go:present|0:go:absent) go_state="$global_state" ;;
+      1:crontab:present|1:crontab:absent) cron_state="$global_state" ;;
+      *) return 1 ;;
+    esac
+    if [ "$global_state" = absent ]; then
+      [ "$global_digest" = - ] || return 1
+    else
+      [ "${#global_digest}" -eq 64 ] || return 1
+      case "$global_digest" in *[!0-9a-f]*) return 1 ;; esac
+    fi
+    case "$global_count" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$(awk 'END { print NR + 0 }' "$RESTORE_ROOT/$global_name.butler-lines")" = "$global_count" ] || return 1
+    index=$((index + 1))
+  done < "$RESTORE_ROOT/global-state"
+  [ "$index" -eq 2 ] || return 1
+  while IFS= read -r source || [ -n "$source" ]; do is_canonical_butler_go_hook "$source" || return 1; done < "$RESTORE_ROOT/go.butler-lines"
+  while IFS= read -r source || [ -n "$source" ]; do
+    case "$source" in
+      "*/15 * * * * /bin/bash /boot/config/custom/usenet_health.sh"|"*/15 * * * * /bin/bash /boot/config/custom/usenet_health.sh # ouro:usenet-health") ;;
+      *) return 1 ;;
+    esac
+  done < "$RESTORE_ROOT/crontab.butler-lines"
+
+  /bin/mkdir -p "$INSTALL_ROOT"
+  cleanup_stale_atomic_residue
+  stage="$(private_transaction_workspace restore)"
+  STAGE_PATH="$stage"
+  backup="$stage/backup"
+  /bin/mkdir "$backup"
+  cleanup() { [ -z "$STAGE_PATH" ] || /bin/rm -rf "$STAGE_PATH"; }
+  trap cleanup EXIT
+  for index in "${!TARGET_PATHS[@]}"; do
+    target="${TARGET_PATHS[$index]}"
+    if [ -e "$target" ]; then [ -f "$target" ] && [ ! -L "$target" ] || return 1; /bin/cp -p "$target" "$backup/asset-$index"; fi
+  done
+  if [ -e "$GO_FILE" ]; then [ -f "$GO_FILE" ] && [ ! -L "$GO_FILE" ] || return 1; /bin/cp -p "$GO_FILE" "$backup/go"; fi
+  go_original="$stage/go.original"
+  if [ -f "$GO_FILE" ]; then /bin/cp "$GO_FILE" "$go_original"; else printf '#!/bin/bash\n' > "$go_original"; fi
+  go_filtered="$stage/go.filtered"
+  render_go_without_owned "$go_original" "$go_filtered"
+  go_candidate="$stage/go.candidate"
+  if [ -s "$RESTORE_ROOT/go.butler-lines" ]; then
+    awk -v fragments="$RESTORE_ROOT/go.butler-lines" 'NR == 1 && /^#!/ { print; while ((getline line < fragments) > 0) print line; close(fragments); next } NR == 1 { while ((getline line < fragments) > 0) print line; close(fragments) } { print }' "$go_filtered" > "$go_candidate"
+  else
+    /bin/cp "$go_filtered" "$go_candidate"
+  fi
+  /bin/chmod 0700 "$go_candidate"
+  cron_original="$stage/cron.original"
+  if [ -n "$CRONTAB_FILE" ]; then
+    if [ -f "$CRONTAB_FILE" ]; then /bin/cp -p "$CRONTAB_FILE" "$backup/cron"; /bin/cp "$CRONTAB_FILE" "$cron_original"; else : > "$cron_original"; fi
+  else
+    read_system_cron "$cron_original"
+    /bin/cp "$cron_original" "$backup/cron"
+  fi
+  cron_inactive="$stage/cron.inactive"
+  render_inactive_cron "$cron_original" "$cron_inactive"
+  cron_candidate="$stage/cron.candidate"
+  /bin/cp "$cron_inactive" "$cron_candidate"
+  /bin/cat "$RESTORE_ROOT/crontab.butler-lines" >> "$cron_candidate"
+  /bin/chmod 0600 "$cron_candidate"
+
+  set +e
+  status=0
+  if cron_contains_owned "$cron_original"; then activate_cron_file "$cron_inactive" || status=$?; fi
+  for index in "${!TARGET_PATHS[@]}"; do
+    [ "$status" -eq 0 ] || break
+    target="${TARGET_PATHS[$index]}"
+    case "$index" in
+      0) relative=custom/usenet_health.sh ;;
+      1) relative=custom/ouro-events/bootstrap-spool.sh ;;
+      2) relative=custom/ouro-events/emit-event.mjs ;;
+      3) relative=custom/ouro-events/emit-usenet-event.sh ;;
+      4) relative=custom/ouro-events/install-usenet-guard.sh ;;
+    esac
+    source="$RESTORE_ROOT/$relative"
+    if [ -f "$source" ]; then atomic_install "$source" "$target" 0700 || status=$?; else /bin/rm -f "$target" || status=$?; fi
+  done
+  if [ "$status" -eq 0 ]; then
+    if [ "$go_state" = absent ] && [ "$(awk 'NF && $0 !~ /^#!/ { count++ } END { print count + 0 }' "$go_candidate")" -eq 0 ]; then /bin/rm -f "$GO_FILE" || status=$?; else atomic_install "$go_candidate" "$GO_FILE" 0700 || status=$?; fi
+  fi
+  if [ "$status" -eq 0 ]; then
+    if [ "$cron_state" = absent ] && [ ! -s "$cron_candidate" ]; then
+      if [ -n "$CRONTAB_FILE" ]; then /bin/rm -f "$CRONTAB_FILE" || status=$?; else crontab -r >/dev/null 2>&1 || status=$?; fi
+    else
+      activate_cron_file "$cron_candidate" || status=$?
+    fi
+  fi
+  set -e
+  if [ "$status" -ne 0 ]; then
+    set +e
+    rollback_host_state "$backup"
+    rollback_status=$?
+    set -e
+    if [ "$rollback_status" -ne 0 ]; then return "$rollback_status"; fi
+    return "$status"
+  fi
+  cleanup
+  STAGE_PATH=""
+  trap - EXIT
+}
+
+case "$ACTION" in
+  install) install_transaction ;;
+  boot) boot_activate ;;
+  restore) restore_snapshot ;;
+esac

package/deploy/unraid/ouro-events/usenet-health.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+set -uo pipefail
+
+LOG="/var/log/usenet_health.log"
+SAB_INI="/mnt/user/appdata/sabnzbd/sabnzbd.ini"
+EVENT_PRODUCER="/boot/config/custom/ouro-events/emit-event.mjs"
+EVENT_ADAPTER="/boot/config/custom/ouro-events/emit-usenet-event.sh"
+BASELINE_STATE="/boot/config/custom/usenet_health_baseline.json"
+BASELINE_STATE_EXPLICIT=0
+
+while (($# > 0)); do
+    case "$1" in
+        --sab-ini) SAB_INI="${2:?missing --sab-ini value}"; shift 2 ;;
+        --log) LOG="${2:?missing --log value}"; shift 2 ;;
+        --producer) EVENT_PRODUCER="${2:?missing --producer value}"; shift 2 ;;
+        --adapter) EVENT_ADAPTER="${2:?missing --adapter value}"; shift 2 ;;
+        --state) BASELINE_STATE="${2:?missing --state value}"; BASELINE_STATE_EXPLICIT=1; shift 2 ;;
+        *) echo "usenet health guard: invalid argument: $1" >&2; exit 2 ;;
+    esac
+done
+if [ "$BASELINE_STATE_EXPLICIT" -eq 0 ] && [ "$LOG" != "/var/log/usenet_health.log" ]; then BASELINE_STATE="${LOG}.baseline.json"; fi
+
+log() { echo "$(date '+%Y-%m-%d %H:%M:%S') $1" >> "$LOG"; }
+
+emit_transition() {
+    if ! /bin/bash "$EVENT_ADAPTER" "$@" >> "$LOG" 2>&1; then
+        log "[EVENT] Canonical Butler event emission failed; Unraid UI and this log retain the observation or verified action."
+    fi
+}
+
+emit_blind_observation() {
+    local reason="$1"
+    local observed_slot verified_at verification_digest
+    observed_slot=$(date -u '+%Y%m%dT%H%M%SZ')
+    verified_at=$(date -u '+%Y-%m-%dT%H:%M:%S.000Z')
+    verification_digest=$(printf 'sabnzbd.health_check=indeterminate\nreason=%s' "$reason" | sha256sum | cut -d' ' -f1)
+    log "[USENET] CRITICAL — the SABnzbd health check is blind (${reason}); no healthy state was inferred."
+    emit_transition "usenet.observe" "provider-health" "indeterminate:${observed_slot}" "usenet:provider-health:${observed_slot}:indeterminate" "The Usenet health check could not verify current state." "A required SABnzbd ${reason} check failed; treat provider health as unknown and investigate the local API path." "false" "$verification_digest" "$verified_at"
+}
+
+sab_request() {
+    local timeout="$1"
+    local url="$2"
+    printf 'get\ndata-urlencode = "apikey=%s"\n' "$SAB_KEY" \
+      | curl --silent --fail --max-time "$timeout" --config - "$url" 2>/dev/null
+}
+
+fetch_sab_json() {
+    local target="$1"
+    local timeout="$2"
+    local url="$3"
+    local schema="$4"
+    local surface="$5"
+    local payload
+    if ! payload=$(sab_request "$timeout" "$url"); then
+        emit_blind_observation "${surface}-transport"
+        return 1
+    fi
+    if ! printf '%s' "$payload" | jq -e 'type == "object" and (.status != false) and ((has("error") | not) or .error == null or .error == "")' >/dev/null 2>&1 \
+      || ! printf '%s' "$payload" | jq -e "$schema" >/dev/null 2>&1; then
+        emit_blind_observation "${surface}-response"
+        return 1
+    fi
+    printf -v "$target" '%s' "$payload"
+}
+
+/usr/local/bin/node "$EVENT_PRODUCER" --maintain >> "$LOG" 2>&1 || log "[EVENT] Spool maintenance failed; unsafe or unparseable artifacts were preserved."
+
+SAB_KEY=$(grep -m1 '^api_key' "$SAB_INI" 2>/dev/null | cut -d= -f2 | tr -d ' ')
+if [ -z "$SAB_KEY" ]; then
+    emit_blind_observation "credential-unavailable"
+    exit 1
+fi
+if [[ ! "$SAB_KEY" =~ ^[[:alnum:]_-]+$ ]]; then
+    emit_blind_observation "credential-invalid"
+    exit 1
+fi
+
+fetch_sab_json WARN 15 "http://localhost:8090/api?mode=warnings&output=json" '(.warnings | type) == "array"' "warnings" || exit 1
+
+fetch_sab_json Q 15 "http://localhost:8090/api?mode=queue&output=json" '(.queue | type) == "object" and (.queue.status | type) == "string" and (.queue.paused | type) == "boolean" and (((.queue.noofslots | type) == "number") or ((.queue.noofslots | type) == "string"))' "queue" || exit 1
+Q_STATUS=$(echo "$Q" | jq -r '.queue.status // "?"' 2>/dev/null)
+Q_SLOTS=$(echo "$Q" | jq -r '.queue.noofslots // 0' 2>/dev/null)
+STALLED=0
+if [ "$Q_STATUS" = "Idle" ] && [ "${Q_SLOTS:-0}" -gt 0 ]; then STALLED=1; fi
+
+# Protected spend-guard logic: volume is allowed; sustained article failure is not.
+MIN_ARTICLES=50000
+MIN_RATE=30
+TODAY=$(date +%Y-%m-%d)
+fetch_sab_json STATS 20 "http://localhost:8090/api?mode=server_stats&output=json" 'def valid_count: ((type == "number" and . >= 0 and . <= 9007199254740991 and floor == .) or (type == "string" and test("^[0-9]+$") and (tonumber <= 9007199254740991))); ((.servers | type) == "array" or (.servers | type) == "object") and (.servers | length) > 0 and all(.servers[]; (type == "object") and (.articles_tried | type) == "object" and (.articles_success | type) == "object" and (.daily | type) == "object" and all(.articles_tried[]; valid_count) and all(.articles_success[]; valid_count) and all(.daily[]; valid_count))' "server-stats" || exit 1
+if ! IFS=$'\t' read -r TRIED OKAY BYTES < <(printf '%s' "$STATS" | jq -er --arg d "$TODAY" 'def count: if type == "number" and . >= 0 and . <= 9007199254740991 and floor == . then . elif type == "string" and test("^[0-9]+$") and (tonumber <= 9007199254740991) then tonumber else error("invalid server count") end; def total($field): ([.servers[] | (.[$field][$d] // 0) | count] | add) as $total | if $total >= 0 and $total <= 9007199254740991 and ($total | floor) == $total then $total else error("invalid aggregate server count") end; [total("articles_tried"), total("articles_success"), total("daily")] | @tsv' 2>/dev/null); then
+    emit_blind_observation "server-stats-response"
+    exit 1
+fi
+GB=$(( ${BYTES:-0} / 1000000000 ))
+
+BASE_DAY=""
+BASE_TRIED=0
+BASE_OKAY=0
+BASE_VALID=0
+if [ -f "$BASELINE_STATE" ] && [ ! -L "$BASELINE_STATE" ]; then
+    BASE_DAY=$(/usr/bin/jq -r '.day // ""' "$BASELINE_STATE" 2>/dev/null)
+    BASE_TRIED=$(/usr/bin/jq -r '.tried // 0' "$BASELINE_STATE" 2>/dev/null)
+    BASE_OKAY=$(/usr/bin/jq -r '.okay // 0' "$BASELINE_STATE" 2>/dev/null)
+fi
+case "$BASE_TRIED" in ''|*[!0-9]*) BASE_TRIED=0 ;; esac
+case "$BASE_OKAY" in ''|*[!0-9]*) BASE_OKAY=0 ;; esac
+if [ "$BASE_DAY" = "$TODAY" ] && [ "$TRIED" -ge "$BASE_TRIED" ] && [ "$OKAY" -ge "$BASE_OKAY" ]; then BASE_VALID=1; fi
+write_baseline() {
+    BASELINE_TMP=$(mktemp "${BASELINE_STATE}.tmp.XXXXXX") || return 1
+    printf '{"day":"%s","tried":%s,"okay":%s}\n' "$TODAY" "$TRIED" "$OKAY" > "$BASELINE_TMP" && chmod 600 "$BASELINE_TMP" && mv "$BASELINE_TMP" "$BASELINE_STATE"
+}
+if [ "$BASE_VALID" -eq 0 ]; then BASE_TRIED=$TRIED; BASE_OKAY=$OKAY; write_baseline || { log "[SPEND] CRITICAL — could not persist the spend baseline."; exit 1; }; fi
+DELTA_TRIED=$(( TRIED - BASE_TRIED ))
+DELTA_OKAY=$(( OKAY - BASE_OKAY ))
+
+# A cleared warning is not recovery. Require bounded evidence that articles succeeded
+# and one download reached Completed during the last two guard intervals.
+fetch_sab_json HISTORY 15 "http://localhost:8090/api?mode=history&limit=20&start=0&output=json" '(.history | type) == "object" and (.history.slots | type) == "array"' "history" || exit 1
+RECENT_SINCE=$(( $(date -u '+%s') - 1800 ))
+RECENT_COMPLETED=$(echo "$HISTORY" | jq -r --argjson since "$RECENT_SINCE" '[.history.slots[]? | select(.status == "Completed" and ((.completed // 0) | tonumber) >= $since)] | length' 2>/dev/null)
+case "$RECENT_COMPLETED" in ''|*[!0-9]*) RECENT_COMPLETED=0 ;; esac
+AUTH_FAIL=$(echo "$WARN" | jq -r --argjson since "$RECENT_SINCE" '[.warnings[]? | select((.text | test("Authentication Failed|Failed login"; "i")) and ((.time // 0) | tonumber) >= $since)] | length' 2>/dev/null)
+case "$AUTH_FAIL" in ''|*[!0-9]*) AUTH_FAIL=0 ;; esac
+
+if [ "${DELTA_TRIED:-0}" -ge "$MIN_ARTICLES" ]; then
+    RATE=$(( DELTA_OKAY * 100 / DELTA_TRIED ))
+    if [ "$RATE" -lt "$MIN_RATE" ]; then
+        fetch_sab_json PAUSE_RESPONSE 15 "http://localhost:8090/api?mode=pause&output=json" '(.status == true)' "pause" || exit 1
+        fetch_sab_json PAUSE_Q 15 "http://localhost:8090/api?mode=queue&output=json" '(.queue | type) == "object" and (.queue.paused | type) == "boolean"' "pause-verification" || exit 1
+        PAUSED_AFTER=$(printf '%s' "$PAUSE_Q" | jq -r '.queue.paused')
+        VERIFIED_AT=$(date -u '+%Y-%m-%dT%H:%M:%S.000Z')
+        VERIFICATION_DIGEST=$(printf 'sabnzbd.queue.paused=%s' "$PAUSED_AFTER" | sha256sum | cut -d' ' -f1)
+        if [ "$PAUSED_AFTER" = "true" ]; then
+            log "[SPEND] CRITICAL — verified the download queue is PAUSED. ${GB} GB fetched today at ${RATE}% article success (threshold ${MIN_RATE}%)."
+            emit_transition "sabnzbd.pause" "spend-guard" "spend-pause:${TODAY}:verified" "sabnzbd:pause:${TODAY}:spend-guard" "Downloads were paused after article success fell below the spend guard." "At least 50,000 articles were attempted at less than 30% success; an independent queue read verified paused=true." "true" "$VERIFICATION_DIGEST" "$VERIFIED_AT"
+        else
+            log "[SPEND] CRITICAL — pause request was not independently verified; only a verification-failure event was emitted."
+            emit_transition "sabnzbd.pause" "spend-guard" "spend-pause:${TODAY}:unverified" "sabnzbd:pause-request:${TODAY}:spend-guard" "The spend guard requested a download pause but could not verify it." "An independent SAB queue read returned paused=false; treat the protective action as unverified and investigate." "false" "$VERIFICATION_DIGEST" "$VERIFIED_AT"
+        fi
+    else
+        log "[SPEND] OK — ${GB} GB today at ${RATE}% article success."
+    fi
+    write_baseline || { log "[SPEND] CRITICAL — could not advance the spend baseline."; exit 1; }
+fi
+
+VERIFIED_AT=$(date -u '+%Y-%m-%dT%H:%M:%S.000Z')
+OBSERVED_SLOT=$(date -u '+%Y%m%dT%H%M%SZ')
+fetch_sab_json FINAL_Q 15 "http://localhost:8090/api?mode=queue&output=json" '(.queue | type) == "object" and (.queue.paused | type) == "boolean"' "final-queue" || exit 1
+FINAL_PAUSED=$(echo "$FINAL_Q" | jq -r '.queue.paused // false' 2>/dev/null)
+if [ "$AUTH_FAIL" -eq 0 ] && [ "$STALLED" -eq 0 ] && [ "$FINAL_PAUSED" = "false" ] && [ "${DELTA_OKAY:-0}" -gt 0 ] && [ "${RECENT_COMPLETED:-0}" -gt 0 ]; then
+    VERIFICATION_DIGEST=$(printf 'sabnzbd.auth_fail=0\nsabnzbd.stalled=0\nsabnzbd.queue.paused=false\nsabnzbd.interval_articles_tried=%s\nsabnzbd.interval_articles_success=%s\nsabnzbd.recent_completed=%s' "$DELTA_TRIED" "$DELTA_OKAY" "$RECENT_COMPLETED" | sha256sum | cut -d' ' -f1)
+    emit_transition "usenet.observe" "provider-health" "recovered:${OBSERVED_SLOT}" "usenet:provider-health:${OBSERVED_SLOT}:recovered" "The download path completed a real job again." "SABnzbd reports ${DELTA_OKAY} successful articles out of ${DELTA_TRIED} newly attempted since the prior check and ${RECENT_COMPLETED} recent completed downloads; a final independent queue read verified paused=false." "true" "$VERIFICATION_DIGEST" "$VERIFIED_AT"
+    tail -300 "$LOG" > "${LOG}.tmp" 2>/dev/null && mv "${LOG}.tmp" "$LOG"
+    exit 0
+fi
+
+if [ "$AUTH_FAIL" -eq 0 ] && [ "$STALLED" -eq 0 ]; then
+    log "[USENET] OK — there is not yet whole-path recovery evidence (${DELTA_OKAY} newly successful articles; ${RECENT_COMPLETED} recent completed downloads; paused=${FINAL_PAUSED})."
+    tail -300 "$LOG" > "${LOG}.tmp" 2>/dev/null && mv "${LOG}.tmp" "$LOG"
+    exit 0
+fi
+
+if [ "$AUTH_FAIL" -gt 0 ]; then
+    SAMPLE=$(echo "$WARN" | jq -r --argjson since "$RECENT_SINCE" '[.warnings[]? | select((.text | test("Authentication Failed|Failed login"; "i")) and ((.time // 0) | tonumber) >= $since)] | last | .text' 2>/dev/null)
+    log "[USENET] CRITICAL — SABnzbd cannot authenticate to the news server: ${SAMPLE:0:120}"
+    VERIFICATION_DIGEST=$(printf 'sabnzbd.auth_fail=1' | sha256sum | cut -d' ' -f1)
+    emit_transition "usenet.observe" "provider-health" "auth-failed:${OBSERVED_SLOT}" "usenet:provider-health:${OBSERVED_SLOT}:auth-failed" "The news provider rejected SABnzbd authentication." "SAB warning history contains an authentication failure; the Butler should investigate credentials, provider status, and next steps." "true" "$VERIFICATION_DIGEST" "$VERIFIED_AT"
+else
+    log "[USENET] CRITICAL — SABnzbd is Idle with $Q_SLOTS job(s) queued and nothing downloading."
+    VERIFICATION_DIGEST=$(printf 'sabnzbd.queue.status=Idle\nsabnzbd.queue.slots=%s' "$Q_SLOTS" | sha256sum | cut -d' ' -f1)
+    emit_transition "usenet.observe" "provider-health" "stalled:${OBSERVED_SLOT}" "usenet:provider-health:${OBSERVED_SLOT}:stalled" "Usenet downloads appear stalled." "SABnzbd is idle with queued jobs; the Butler should investigate the provider and download path before deciding what to do." "true" "$VERIFICATION_DIGEST" "$VERIFIED_AT"
+fi
+
+tail -300 "$LOG" > "${LOG}.tmp" 2>/dev/null && mv "${LOG}.tmp" "$LOG"