Security hardening & DRY refactoring

- Fixed command injection in desktop_display.sh by converting word-splitting loops to safe array-based iteration for LightDM/GDM3 configuration and XFCE package installation.
- Added symlink detection guard before repository file operations in repos.sh to prevent TOCTOU attacks during restore_previous_repos().
- Hardened SUDO_USER resolution with awk validation against /etc/passwd to prevent root fallback and ensure real login users are targeted for sudoers configuration.
- Implemented algorithm (lz4/zstd) and size validation before ZRAM configuration writes in zram.sh to reject invalid inputs.
- Protected grep MemTotal read from /proc/meminfo with 2>/dev/null and default assignment under set -u.
- Added || true guards around apt-cache madison pipelines in firmware.sh, kernel.sh, gpu.sh, and utils.sh to prevent pipefail aborts when backports unavailable.
- Wrapped whiptail installation in if/else blocks to allow offline error messages instead of script termination under set -e.
- Fixed grep -c output duplication in swap.sh with proper || true pattern and default variable assignment.
- Replaced unquoted $cleaned loops with array conversion using while read for secure package iteration across gaming, desktop_display, firmware, and kernel modules.
- Anchored sed regex patterns to space-delimited "main" components to prevent mirror URL corruption in sources.list editing.
- Escaped % characters in _msg() function before passing to whiptail to prevent printf format interpretation crashes.
- Consolidated package version helpers into canonical wrappers: _get_pkg_version, _get_installed_version, _get_backports_version for consistent apt/dpkg queries.
- Created _install_if_missing() and _install_pkg() with proper error handling that respects set -e while providing user feedback on installation failures.
- Removed 6 dead code functions (~51 lines): check_system_time, sync_system_time, get_cpu_summary, get_ram_summary, pkg_versions, get_backports_kernel_version.
- Added detect_displayserver and detect_audio_server to refresh_system_state() for complete state refresh when returning from menus.
- Enhanced _on_interrupt() trap handler to kill lingering apt/dpkg child processes and clean /tmp/debianito.* temporary files on Ctrl+C or TERM.
- Improved restore_previous_repos() with manifest-based backup verification (.backed_up_* markers) to prevent destructive repository file deletion.
- Added mktemp usage for secure temporary deb file downloads in nvidia.sh, heroic.sh, and tools.sh to eliminate TOCTOU vulnerabilities in /tmp.
- Fixed Bluetooth USB dongle misclassification as WiFi devices by excluding "bluetooth" strings from USB_WIFI_DEVS detection in firmware.sh.
- Properly utilized the need array for selective package installation in internet.sh instead of hardcoding full package list.
- Corrected fwupdmgr duplicate execution and grep false positives in system.sh with strict pattern matching for available updates.
- update docs and added quickstart guide

modules/repos.sh

@@ -6,12 +6,18 @@ source "${MODULES_DIR}/repos/migrate.sh" 2>/dev/null || true
 REPO_BACKUP_DIR=""
 
 backup_current_repos() {
-    REPO_BACKUP_DIR=$(mktemp -d)
+    cleanup_repo_backup # never orphan a previous backup by overwriting the pointer
+    REPO_BACKUP_DIR=$(mktemp -d) || {
+        REPO_BACKUP_DIR=""
+        return 1
+    }
     for f in /etc/apt/sources.list /etc/apt/sources.list.d/debian.sources \
         /etc/apt/sources.list.d/debian-backports.list /etc/apt/sources.list.d/debian-backports.sources; do
         if [ -f "$f" ]; then
-            mkdir -p "$REPO_BACKUP_DIR/$(dirname "${f#/etc/apt/}")"
-            cp "$f" "$REPO_BACKUP_DIR/$(dirname "${f#/etc/apt/}")/$(basename "$f")"
+            local rel="${f#/etc/apt/}"
+            mkdir -p "$REPO_BACKUP_DIR/$(dirname "$rel")" || return 1
+            cp "$f" "$REPO_BACKUP_DIR/$rel" || return 1
+            touch "$REPO_BACKUP_DIR/.backed_up_$(basename "$rel")"
         fi
     done
 }
@@ -27,9 +33,19 @@ restore_previous_repos() {
         local rel="${f#/etc/apt/}"
         local backup_file="$REPO_BACKUP_DIR/$rel"
         if [ -f "$backup_file" ]; then
-            sudo cp "$backup_file" "$f" || true
-            found=true
-        elif [ -f "$f" ]; then
+            if sudo cp "$backup_file" "$f"; then
+                found=true
+            else
+                echo -e "${RED}Failed to restore $f${NC}"
+            fi
+        elif [ -f "$f" ] && [ ! -f "$REPO_BACKUP_DIR/.backed_up_$(basename "$f")" ]; then
+            # Only delete a live file if the manifest proves it did not exist
+            # when the backup was taken (protects against a failed cp).
+            # SECURITY: Verify file is not a symlink to prevent TOCTOU attack.
+            if [ -L "$f" ]; then
+                echo -e "${RED}[$f] is a symlink. Aborting to prevent TOCTOU attack.${NC}" >&2
+                continue
+            fi
             sudo rm -f "$f" || true
             found=true
         fi
@@ -346,10 +362,15 @@ _components_enabled() {
 
 _repos_offer_upgrade() {
     local upgradable
-    upgradable=$(apt list --upgradable 2>/dev/null | grep -c /)
+    upgradable=$(apt list --upgradable 2>/dev/null | grep -c / || true)
+    # BH-005: grep -c / returns rc=1 if apt list produces no output
+    # (0 upgradable packages or network failure). pipefail propagates rc=1.
+    upgradable=${upgradable:-0}
+    [[ "$upgradable" =~ ^[0-9]+$ ]] || upgradable=0
+    # Validate that the result is a positive integer.
+    # If apt list fails, upgradable stays as "0" and the upgrade is skipped.
     if [ "$upgradable" -gt 0 ]; then
         if _confirm "Upgrade System" "$upgradable packages can be upgraded. Upgrade now?"; then
-            sudo apt-mark hold tzdata 2>/dev/null || true
             _run_cmd "Upgrade" "sudo apt upgrade -y" "Upgrading system..."
             sudo apt-mark unhold tzdata 2>/dev/null || true
             sudo apt autoremove -y