feat: [#14] implement sudo cache management for infrastructure operations

- Add sudo cache management functions to scripts/shell-utils.sh
  - is_sudo_cached(): Check if sudo credentials are cached
  - ensure_sudo_cached(): Warn user and cache sudo credentials upfront
  - run_with_sudo(): Run commands with pre-cached sudo
  - clear_sudo_cache(): Clear sudo cache for testing

- Update infrastructure scripts to use proactive sudo caching
  - infrastructure/scripts/fix-volume-permissions.sh: Cache sudo before operations
  - infrastructure/scripts/provision-infrastructure.sh: Cache sudo before tofu apply
  - tests/test-e2e.sh: Prepare sudo cache before infrastructure provisioning

- Improve user experience for 'make test' command
  - Password prompt now appears clearly at the beginning
  - No more mixed output with OpenTofu verbose logs
  - Clear messaging about when and why sudo is needed
  - Leverages standard sudo timeout (~15 minutes)

- Add comprehensive documentation
  - ADR-005: Sudo Cache Management for Infrastructure Operations
  - Documents chosen approach and 7 alternatives considered
  - Updated .github/copilot-instructions.md with implementation details
  - Updated docs/README.md with new ADR reference

- Update Makefile with improved user guidance for sudo operations

Resolves password prompt mixing issue during infrastructure testing while
maintaining security through standard sudo timeout mechanism.

Author: josecelano

.github/copilot-instructions.md

@@ -354,6 +354,28 @@ For verifying the functionality of the tracker from an end-user's perspective (e
 - **Guide**: [Smoke Testing Guide](../docs/guides/smoke-testing-guide.md)
 - **When to use**: After a deployment (`make infra-apply` + `make app-deploy`) or to validate that all services are working together correctly.
 
+#### Sudo Cache Management
+
+The project implements intelligent sudo cache management to improve the user experience during infrastructure provisioning:
+
+- **Automatic prompting**: Scripts will warn users before operations requiring sudo
+- **Cache preparation**: Sudo credentials are cached upfront to prevent interruptions
+- **Clean output**: Password prompts occur before main operations, not mixed with output
+- **Safe commands**: Uses `sudo -v` to cache credentials without executing privileged operations
+
+**Implementation details:**
+
+- Functions in `scripts/shell-utils.sh`: `ensure_sudo_cached()`, `is_sudo_cached()`, `run_with_sudo()`
+- Used in: `infrastructure/scripts/fix-volume-permissions.sh`, `infrastructure/scripts/provision-infrastructure.sh`, `tests/test-e2e.sh`
+- Cache duration: ~15 minutes (system default)
+
+**Testing the sudo cache:**
+
+```bash
+# Test sudo cache management functions
+./test-sudo-cache.sh
+```
+
 ### Security Guidelines
 
 #### Secrets Management

Makefile

@@ -59,6 +59,7 @@ infra-plan: ## Plan infrastructure changes
 
 infra-apply: ## Provision infrastructure (platform setup)
 	@echo "Provisioning infrastructure for $(ENVIRONMENT)..."
+	@echo "⚠️  This command may prompt for your password for sudo operations"
 	$(SCRIPTS_DIR)/provision-infrastructure.sh $(ENVIRONMENT) apply
 
 infra-destroy: ## Destroy infrastructure

docs/README.md

@@ -22,6 +22,12 @@ This directory currently contains cross-cutting documentation:
   to use Docker for all services including UDP tracker
 - [ADR-003: Use MySQL Over MariaDB](adr/003-use-mysql-over-mariadb.md) - Decision
   to use MySQL instead of MariaDB for database backend
+- [ADR-004: Configuration Approach Files vs Environment Variables]
+  (adr/004-configuration-approach-files-vs-environment-variables.md) -
+  Configuration approach decision for application settings
+- [ADR-005: Sudo Cache Management for Infrastructure Operations]
+  (adr/005-sudo-cache-management-for-infrastructure-operations.md) -
+  Proactive sudo cache management for better UX during testing
 
 ### 📅 [`plans/`](plans/) (Ongoing Plans and Roadmaps)
 

docs/adr/005-sudo-cache-management-for-infrastructure-operations.md

@@ -0,0 +1,213 @@
+# ADR-005: Sudo Cache Management for Infrastructure Operations
+
+## Status
+
+Accepted
+
+## Context
+
+During infrastructure testing, specifically when running `make test`, users experienced poor UX due to
+sudo password prompts being mixed with other command output. This created several problems:
+
+1. **Mixed Output**: The sudo password prompt appeared in the middle of verbose OpenTofu output,
+   making it difficult to notice
+2. **Test Hangs**: Users would miss the password prompt, causing tests to hang indefinitely
+3. **Unclear Timing**: Users didn't know when sudo access would be needed during the test process
+4. **Interrupted Flow**: Password prompts appeared at unpredictable times during infrastructure
+   provisioning
+
+### Technical Root Cause
+
+The issue occurred during OpenTofu's `local-exec` provisioner execution in
+`infrastructure/terraform/main.tf`:
+
+```hcl
+# Fix permissions after creation
+provisioner "local-exec" {
+  command = "${path.module}/../scripts/fix-volume-permissions.sh"
+}
+```
+
+This script runs `sudo` commands for libvirt volume permission management, but the password prompt
+was buried in OpenTofu's verbose output.
+
+## Decision
+
+We chose **Option 1: Pre-authorize sudo with timeout and clear user messaging**.
+
+### Implemented Solution
+
+1. **Sudo Cache Management Functions** in `scripts/shell-utils.sh`:
+
+   - `is_sudo_cached()` - Check if sudo credentials are cached
+   - `ensure_sudo_cached(description)` - Warn user and cache sudo credentials
+   - `run_with_sudo(description, command)` - Run command with pre-cached sudo
+   - `clear_sudo_cache()` - Clear sudo cache for testing
+
+2. **Proactive Sudo Preparation**:
+
+   - Cache sudo credentials before infrastructure operations begin
+   - Clear user messaging about when and why sudo is needed
+   - Use harmless `sudo -v` command to cache without executing privileged operations
+
+3. **Integration Points**:
+   - `tests/test-e2e.sh`: Prepare sudo cache before infrastructure provisioning
+   - `infrastructure/scripts/provision-infrastructure.sh`: Cache sudo before `tofu apply`
+   - `infrastructure/scripts/fix-volume-permissions.sh`: Use cached sudo for operations
+
+### User Experience Improvement
+
+**Before:**
+
+```bash
+make test
+# ... lots of OpenTofu output ...
+libvirt_volume.base_image (local-exec): Fixing libvirt volume permissions...
+[sudo] password for user: # <- Hidden in output, easy to miss
+```
+
+**After:**
+
+```bash
+make test
+⚠️  SUDO PREPARATION
+Infrastructure provisioning requires administrator privileges
+[sudo] password for user: # <- Clear, upfront prompt
+✓ Administrator privileges confirmed and cached
+# ... rest runs without interruption ...
+```
+
+## Alternatives Considered
+
+### Option 1: Pre-authorize sudo with timeout ⭐ (CHOSEN)
+
+- **Pros**: Safe, minimal changes, clear UX, leverages existing sudo timeout
+- **Cons**: Still requires password entry once
+
+### Option 2: Passwordless sudo configuration
+
+- **Pros**: No password prompts during tests
+- **Cons**: Security risk, requires system configuration changes, complex setup
+
+### Option 3: Replace local-exec with null_resource
+
+- **Pros**: Better output control
+- **Cons**: Still needs sudo password, more complex Terraform
+
+### Option 4: Move permission fixes to cloud-init
+
+- **Pros**: No host sudo needed
+- **Cons**: Complex implementation, may not solve all permission issues
+
+### Option 5: Enhanced messaging only
+
+- **Pros**: Simple implementation
+- **Cons**: Doesn't solve the core mixing problem
+
+### Option 6: Use polkit/pkexec
+
+- **Pros**: GUI prompts, better UX
+- **Cons**: Complex setup, environment dependencies
+
+### Option 7: Automated passwordless sudo setup
+
+- **Pros**: One-time setup eliminates problem
+- **Cons**: Security implications, system configuration complexity
+
+## Rationale
+
+Option 1 was chosen because it:
+
+1. **Maintains Security**: Uses standard sudo timeout without permanent passwordless access
+2. **Minimal Risk**: Uses safe `sudo -v` command that doesn't execute privileged operations
+3. **Clear UX**: Users know exactly when and why password is needed
+4. **Simple Implementation**: Leverages existing sudo cache mechanism (~15 minutes)
+5. **Backwards Compatible**: Doesn't require system configuration changes
+6. **Universal**: Works across different Linux distributions and environments
+
+## Implementation Details
+
+### Core Functions (`scripts/shell-utils.sh`)
+
+```bash
+# Check if sudo credentials are cached
+is_sudo_cached() {
+    sudo -n true 2>/dev/null
+}
+
+# Warn user and ensure sudo is cached
+ensure_sudo_cached() {
+    local operation_description="${1:-the operation}"
+
+    if is_sudo_cached; then
+        return 0
+    fi
+
+    log_warning "The next step requires administrator privileges"
+    log_info "You may be prompted for your password to ${operation_description}"
+
+    # Use harmless sudo command to cache credentials
+    if sudo -v; then
+        log_success "Administrator privileges confirmed"
+        return 0
+    else
+        log_error "Failed to obtain administrator privileges"
+        return 1
+    fi
+}
+```
+
+### Integration Pattern
+
+```bash
+# Before any infrastructure operation that needs sudo
+if ! ensure_sudo_cached "provision libvirt infrastructure"; then
+    log_error "Cannot proceed without administrator privileges"
+    exit 1
+fi
+
+# Now run operations that need sudo - no prompts expected
+sudo chown -R libvirt-qemu:libvirt /var/lib/libvirt/images/
+```
+
+## Consequences
+
+### Positive
+
+- **Better UX**: Clear, predictable password prompts
+- **No Mixed Output**: Password prompt happens before verbose operations
+- **Faster Tests**: No hanging due to missed prompts
+- **Security Maintained**: Uses standard sudo timeout mechanism
+- **Universal**: Works in all environments without special setup
+
+### Negative
+
+- **Still Requires Password**: Users must enter password once per test session
+- **Cache Dependency**: Relies on system sudo timeout (usually 15 minutes)
+- **Additional Code**: Added complexity in shell utilities
+
+### Neutral
+
+- **Test Duration**: No impact on test execution time
+- **Security Posture**: Maintains existing security model
+- **Maintenance**: Minimal ongoing maintenance required
+
+## Monitoring
+
+Success of this decision can be measured by:
+
+1. **Reduced Support Issues**: Fewer reports of hanging tests or missed prompts
+2. **Contributor Feedback**: Improved developer experience feedback
+3. **Test Reliability**: More consistent test execution without manual intervention
+
+## Related Decisions
+
+- [ADR-001: Makefile Location](001-makefile-location.md) - Central automation interface
+- [ADR-002: Docker for All Services](002-docker-for-all-services.md) - Service architecture
+
+## References
+
+- Original issue discussion with password prompt mixing
+- Shell utilities implementation in `scripts/shell-utils.sh`
+- Integration testing guide documentation
+- Sudo cache timeout documentation: `man sudo`

infrastructure/scripts/fix-volume-permissions.sh

@@ -4,13 +4,27 @@
 
 set -euo pipefail
 
-echo "Fixing libvirt volume permissions..."
+# Get script directory and source shell utilities
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../scripts/shell-utils.sh"
+
+log_info "Fixing libvirt volume permissions..."
+
+# Ensure sudo credentials are cached before running permission fixes
+if ! ensure_sudo_cached "fix libvirt volume permissions"; then
+    log_error "Cannot proceed without administrator privileges"
+    exit 1
+fi
 
 # Fix ownership of all files in libvirt images directory
+log_debug "Setting ownership for /var/lib/libvirt/images/"
 sudo chown -R libvirt-qemu:libvirt /var/lib/libvirt/images/ 2>/dev/null || true
+
+log_debug "Setting permissions for /var/lib/libvirt/images/"
 sudo chmod -R 755 /var/lib/libvirt/images/ 2>/dev/null || true
 
 # Also fix qemu directory
+log_debug "Setting ownership for /var/lib/libvirt/qemu/"
 sudo chown -R libvirt-qemu:kvm /var/lib/libvirt/qemu/ 2>/dev/null || true
 
-echo "✓ Volume permissions fixed"
+log_success "Volume permissions fixed"

infrastructure/scripts/provision-infrastructure.sh

@@ -94,6 +94,16 @@ provision_infrastructure() {
         tofu plan -var-file="local.tfvars"
         ;;
     "apply")
+        log_info "Preparing to apply infrastructure changes"
+
+        # Ensure sudo credentials are cached for libvirt operations
+        log_warning "Infrastructure provisioning requires administrator privileges for libvirt operations"
+        if ! ensure_sudo_cached "provision libvirt infrastructure"; then
+            log_error "Cannot proceed without administrator privileges"
+            log_error "Infrastructure provisioning requires sudo access for libvirt volume management"
+            exit 1
+        fi
+
         log_info "Applying infrastructure changes"
         init_terraform
         tofu apply -auto-approve -var-file="local.tfvars"

project-words.txt

@@ -60,9 +60,12 @@ nullglob
 NUXT
 opentofu
 pacman
+Passwordless
 pasteable
 pipefail
+pkexec
 plugdev
+polkit
 poweroff
 prereq
 privkey

scripts/shell-utils.sh

@@ -224,3 +224,53 @@ ${BLUE}EXAMPLES:${NC}
 
 EOF
 }
+
+# Sudo cache management functions
+
+# Check if sudo credentials are cached
+is_sudo_cached() {
+    sudo -n true 2>/dev/null
+}
+
+# Warn user about upcoming sudo operations and ensure sudo is cached
+ensure_sudo_cached() {
+    local operation_description="${1:-the operation}"
+
+    if is_sudo_cached; then
+        log_debug "Sudo credentials already cached"
+        return 0
+    fi
+
+    log_warning "The next step requires administrator privileges"
+    log_info "You may be prompted for your password to ${operation_description}"
+    echo ""
+
+    # Use a harmless sudo command to cache credentials
+    # This will prompt for password if needed, but won't actually do anything
+    if sudo -v; then
+        log_success "Administrator privileges confirmed"
+        return 0
+    else
+        log_error "Failed to obtain administrator privileges"
+        return 1
+    fi
+}
+
+# Run a command with sudo, ensuring credentials are cached first
+run_with_sudo() {
+    local description="$1"
+    shift
+
+    if ! ensure_sudo_cached "$description"; then
+        return 1
+    fi
+
+    # Now run the actual command - no password prompt expected
+    sudo "$@"
+}
+
+# Clear sudo cache (useful for testing or security)
+clear_sudo_cache() {
+    sudo -k
+    log_debug "Sudo credentials cache cleared"
+}