hops/TODO.md

# HOPS TODO

Generated by codebase audit (2026-06-10). Ranked by severity.

## Decisions (2026-06-10)

- **Canonical pipeline**: Path A (`hops` -> `install` -> `services`). Path B deleted.
- **Deleted**: `setup`, `privileged-setup`, `user-operations`, `services-improved`,
  `lib/privileges.sh` -- all Path B artifacts, gone.
- **Service catalog**: `services` is the single source of truth. Latest tags kept.
- **`lib/secrets.sh`**: keep and fix. Goal is to encrypt the `.env` file at rest
  (passwords/API keys written by `install`). Fix the broken AES-GCM crypto and
  wire encryption/decryption into the install flow.
- **macOS**: future roadmap. Linux is the target for now.

---

## CRITICAL BUGS (breaks primary use cases)

### B1 -- Infinite recursion in `services` on Linux [CRITICAL]
- File: `services:25-46`
- `get_timezone_mount()` and `get_gpu_devices()` call themselves on the non-Darwin
  branch via `echo "$(get_timezone_mount)"`. Hits bash FUNCNEST limit on every
  Linux compose generation. Main `./hops` install is broken on Linux.
- Fix: replace the recursive calls with the literal YAML strings they should emit.

### B2 -- Brace mismatch in `lib/privileges.sh` [CRITICAL] -- RESOLVED: delete file
- File: `lib/privileges.sh:429,612`
- Moot -- `lib/privileges.sh` is Path B dead code, scheduled for deletion (see A3).

---

## HIGH BUGS

### B3 -- Glob stored as string, directory detection always fails [HIGH]
- Files: `hops:154-166`, `uninstall:127-147`
- `homelab_dirs=( "/home/*/hops" )` stores a literal glob; the quoted for-loop
  never expands it. Multi-user detection is broken, `cd "$HOMELAB_DIR"` fails
  under `set -e`.
- Fix: iterate unquoted or use `compgen -G "/home/*/hops"`.

### B4 -- Missing service definitions file reference [HIGH]
- File: `install:916`
- `setup_firewall()` sources `"$SCRIPT_DIR/hops_service_definitions.sh"` which
  does not exist (the file is named `services`). Per-service firewall rules are
  silently never applied.
- Fix: correct the filename to `services`.

### B5 -- `((x++))` aborts script under `set -e` [HIGH]
- Files: `hops:299,317`, `install:784`, and others
- `((running_count++))` returns exit code 1 when the pre-increment value is 0,
  which kills the script under `set -e`.
- Fix: use `running_count=$((running_count + 1))` or append `|| true`.

### B6 -- `hops` entry point is Linux-only despite macOS library support [HIGH]
- File: `hops:108-136,263`
- `check_dependencies` requires `systemctl`, `check_system_requirements` calls
  `free` and `df -BG`, `show_service_status` calls `systemctl`. All Linux-only.
  The documented entry point fails immediately on macOS.
- Fix: add OS guards or document `hops` as Linux-only.

### B7 -- Port collisions not detected within a selection [HIGH]
- File: `services` (port map)
- sabnzbd and traefik dashboard both use 8080; traefik and nginx-proxy-manager
  both bind 80/443; authelia and transmission both use 9091.
- `check_all_ports` only checks host listeners, not intra-selection conflicts,
  so users can generate an un-startable compose silently.
- Fix: add intra-selection conflict check before compose generation.

---

## MEDIUM BUGS

### B8 -- Watchtower assigned a bogus port [MED]
- Files: `lib/docker.sh:47`, `services-improved:90`
- Watchtower has no web UI. Assigning it port 8080 emits a spurious `ports:`
  block and broken healthcheck in the generated compose.

### B9 -- Update backup copies into itself [MED]
- File: `hops:586-595`
- `update_hops` does `cp -r "$SCRIPT_DIR" "$backup_dir"` where `$backup_dir`
  is inside `$SCRIPT_DIR`. Results in recursive self-copy including `.git/`.
- Fix: create the backup dir outside the script directory.

### B10 -- `secure_delete` `stat` flag wrong on macOS [MED]
- File: `lib/secrets.sh:146`
- Uses `stat -c%s` (GNU) which fails on macOS (`stat -f%z`).
  Manual-overwrite fallback silently no-ops on macOS.

### B11 -- `jellystat` generated with wrong template in `services-improved` [MED]
- File: `services-improved:422`
- Routed through the generic media-server template; gets no postgres DB and no
  JWT_SECRET, so it cannot run. The hand-written `services` version is correct.

### B12 -- Empty-password detection regex broken [LOW]
- File: `lib/security.sh:361-384`
- `grep "PASSWORD=\s*$"` without `-E` or `-P` means `\s` is matched literally,
  not as whitespace. Empty-password detection is dead.

---

## SECURITY

### S1 -- Broken/unauthenticated encryption [HIGH]
- File: `lib/secrets.sh:85,115`
- `openssl enc -aes-256-gcm` via the CLI does not handle the GCM auth tag.
  This is not authenticated encryption and round-trips unreliably.
- Fix: use a supported openssl mode or switch to `gpg --symmetric`.

### S2 -- Passphrases/keys exposed in process list [HIGH]
- Files: `lib/secrets.sh:85,115`, `lib/security.sh:140,156,175,204,416,442`
- `-pass pass:"$key"` and `--passphrase "$x"` on the command line are visible
  to any local user via `ps`.
- Fix: use `-pass fd:N` or `--passphrase-fd N` with a file descriptor.

### S3 -- Committed default Authelia credential [HIGH]
- File: `services:1148-1157`
- `users_database.yml` ships a default admin account with a known password hash
  (hash of literal "password"). Every Authelia deploy has this credential.
- Fix: force password change on first login or generate the hash at deploy time.

### S4 -- Traefik dashboard exposed with no auth [MED]
- File: `services:672-673,684`
- `api.insecure=true` exposes the Traefik dashboard on :8080 with no auth.
  Consider disabling or requiring middleware auth.

### S5 -- `eval` on environment-derived value [MED]
- Files: `install:598,671`, `uninstall:136,462`, `lib/system.sh:306`, others
- `eval echo "~$SUDO_USER"` expands an env-sourced value through eval.
- Fix: `getent passwd "$SUDO_USER" | cut -d: -f6`

### S6 -- Predictable temp file paths [MED]
- Files: `lib/secrets.sh:16,188,288`, `uninstall:374`
- `/tmp/hops_env_$$` etc. in world-writable `/tmp` are symlink-race targets
  before the `chmod 600` runs.
- Fix: use `mktemp` and assign before use.

### S7 -- Commands built as strings, run unquoted [MED]
- File: `install:731-736,755,773-779`
- `pull_cmd="sudo -u $SUDO_USER docker compose pull"` run as `$pull_cmd`
  is fragile with unusual usernames and bypasses quoting.
- Fix: use bash arrays.

### S9 -- Non-idempotent sysctl append [LOW]
- File: `privileged-setup:224`
- `echo 'net.ipv4.ip_forward = 1' >> /etc/sysctl.conf` appended every run.
  Accumulates duplicate lines.
- Fix: check before appending (`grep -q ... || echo ... >>`)

---

## ARCHITECTURE / DESIGN

### A1 -- Two divergent install pipelines [HIGH] -- RESOLVED
- Path A chosen. Delete: `setup`, `privileged-setup`, `user-operations`,
  `services-improved`.

### A2 -- Three sources of truth for the service catalog [HIGH] -- DO FIRST
- `services`: `get_service_ports()` + inline image strings (CANONICAL)
- `services-improved`: scheduled for deletion (Path B)
- `lib/docker.sh`: `HOPS_SERVICES` array -- reconcile or remove duplicates
- Fix: `lib/docker.sh` service maps must match `services`; remove anything
  only used by Path B.
- Must be done before port collision fix (B7) so there is one authoritative map.

### A3 -- `lib/privileges.sh` is dead code [MED] -- RESOLVED: delete
- Path B artifact. Delete it.

### A4 -- `lib/secrets.sh` crypto needs fixing and wiring in [MED]
- Goal: encrypt the `.env` file at rest after `install` writes it.
- Fix broken AES-GCM (use `gpg --symmetric` or a supported openssl mode).
- Fix passphrase-on-command-line exposure (S1, S2).
- Wire encrypt/decrypt calls into `install` flow.

### A5 -- `hops` duplicates functions from `lib/common.sh` [HIGH] -- DO FIRST
- `log`, `error_exit`, `warning`, `success`, `info`, `validate_timezone`,
  `validate_password`, `generate_secure_password`, `create_docker_networks`,
  `get_service_port/image` are all defined twice (or three times).
- Fix: source `lib/common.sh` from `hops` and remove local duplicates.
- Must be done before bug fixes to avoid patching the same logic in multiple places.

### A6 -- Caddy is unreachable via the menu [LOW]
- `services` defines `generate_caddy` but the `select_services` menu in
  `install` never lists caddy as a selectable option.

### A7 -- Committed dev artifacts [LOW]
- `summary7-19.txt` and `discord-header.md` should not be in the repo.
  Add to `.gitignore` or delete.

---

## MISSING / INCOMPLETE

### M1 -- RESOLVED (Path B deleted)

### M2 -- RESOLVED (Path B deleted)

### M3 -- RESOLVED (Path B deleted)

### M4 -- RESOLVED (`lib/privileges.sh` deleted)

### M5 -- Review Huntarr inclusion -- switch to elfhosted rebuild [MED]
- The current `services` definition uses the original plexguide/Huntarr.io image.
  The project has been rebuilt by elfhosted under a new image/repo.
- Review the new elfhosted image name, default port, and any config changes.
- Update the service definition in `services` and the entry in SERVICES.md.
- Verify the new image is actively maintained before shipping 1.0.0.

---

## PLATFORM SUPPORT

### P2 -- `uninstall` is Linux-only [HIGH] -- deferred (Linux-first)
- Unconditional `apt-get`, `dpkg`, `systemctl`, `groupdel`, `ufw` with no
  OS branching. Acceptable for now; revisit when macOS support is scoped.

### P3 -- RESOLVED (Path B deleted)

### P4 -- No WSL2 detection [MED]
- README claims WSL2 support but there is no WSL2 detection.
  `systemctl`-based service management fails on WSL distros without systemd.

### P5 -- Inconsistent port-check tools [MED]
- `lib/common.sh` uses `ss`; `install` uses `lsof`. `ss` is absent on macOS.

### P6 -- Hardcoded render GID for Jellyfin GPU [LOW]
- File: `services:435`
- `group_add: "109"` is the render GID on a specific distro, wrong on most
  systems and meaningless on macOS.

---

## CODE QUALITY

### Q1 -- Three separate error-handling implementations [HIGH] -- DO FIRST
- `hops`, `uninstall`, and `lib/common.sh` each define their own `error_exit`
  and `log` with different formats. Consolidate in `lib/common.sh`.
- Covered by A5; tracked here for completeness.

### Q2 -- `set -e` + intentional non-zero returns is a minefield [MED]
- `validate_password` returns 1/2/3, `check_port` returns 1 -- these work only
  because they happen to be in conditionals. Combined with B5 this is fragile.
  Consider `set -euo pipefail` with explicit `|| true` where non-zero is intended.

### Q3 -- Debug `echo` statements left in production code [MED] -- DO FIRST
- Files: `lib/system.sh:605,823,1043,1046,1084,1089,1149-1156`
- `DEBUG:` prefixed echo lines should be removed or gated behind a `$DEBUG` flag.
- Clean these before bug fixes so signal isn't buried in debug noise.

### Q4 -- `services-improved` leaks `set -e` when sourced [LOW]
- File: `services-improved` top of file
- File sets `set -e` then is sourced by `user-operations` and `privileges`,
  leaking the option into the caller's shell.

---

## SUGGESTED ORDER OF ATTACK

### Cleanup first (do before any bug fixes)
1. [DONE] Delete Path B files (A1/A3)
2. Consolidate duplicate functions into `lib/common.sh` (A5, Q1) -- one copy to fix
3. Reconcile `lib/docker.sh` service maps with `services` (A2) -- one catalog to fix
4. Remove debug echo statements from `lib/system.sh` (Q3) -- reduce noise

### Bug fixes
5. Fix B1 (infinite recursion in `services`) -- unblocks all Linux installs
6. Fix B5 (`((x++))` under `set -e`) -- prevents silent aborts
7. Fix B3 (glob directory detection) -- fixes multi-user and uninstall
8. Fix B4 (wrong filename in firewall setup)
9. Fix B7 (intra-selection port collision detection)

### Security pass
10. S3 (default Authelia cred), S5 (eval on env var), S6 (mktemp),
    S7 (string-built commands), S2 (passphrase on cmdline)
11. Fix and wire in `lib/secrets.sh`: replace broken crypto, hook into install
    flow to encrypt `.env` at rest (A4/S1/S2)

### Remaining
12. Fix B12 empty-password regex, B8 watchtower port, B9 backup self-copy
13. macOS / WSL2 support (B6, P4) -- future roadmap