From fa5bd4da0ed93dee92ff114db7ce60e970349a8f Mon Sep 17 00:00:00 2001
From: Pulse Monitor <pulse@pulse-monitor.dev>
Date: Thu, 14 Aug 2025 20:59:25 +0000
Subject: [PATCH] fix: allow quick-setup endpoint to check if already
 configured

- ProxmoxVE script can now check if auth is already set without credentials
- Quick-setup endpoint is now public but handler checks if setup should be skipped
- Prevents duplicate auth configuration attempts
- Critical for automated setup scripts
---
 README.md              | 15 ++++++++++++++-
 docs/CONFIGURATION.md  | 11 ++++++++++-
 docs/SECURITY.md       |  4 +++-
 internal/api/router.go |  6 ++++++
 4 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 005e72ddf..b486b09ac 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ services:
       
       # Security (all optional - runs open by default)
       # - PULSE_AUTH_USER=admin             # Username for web UI login
-      # - PULSE_AUTH_PASS='$2a$12$...'      # Bcrypt hash (MUST use quotes! Use Quick Security Setup)
+      # - PULSE_AUTH_PASS='$2a$12$...'      # Bcrypt hash - MUST be 60 chars in single quotes!
       # - API_TOKEN=<sha3-256-hash>         # SHA3-256 hashed API token (64 hex chars)
       # - ALLOW_UNPROTECTED_EXPORT=false    # Allow export without auth (default: false)
       
@@ -251,6 +251,19 @@ See [Reverse Proxy Configuration Guide](docs/REVERSE_PROXY.md) for nginx, Caddy,
 
 ## Troubleshooting
 
+### Authentication Issues
+
+#### Cannot login after setting up security
+- **Docker**: Ensure bcrypt hash is exactly 60 characters and wrapped in single quotes
+- **Example**: `PULSE_AUTH_PASS='$2a$12$YTZXOCEylj4TaevZ0DCeI.notayQZ..b0OZ97lUZ.Q24fljLiMQHK'`
+- If hash is truncated, authentication will fail
+- Use Quick Security Setup in the UI to avoid manual configuration errors
+
+#### .env file not created (Docker)
+- Check container logs: `docker logs <container-name>`
+- Verify `/data` volume is mounted and writable
+- Manually create `/data/.env` with proper format if needed
+
 ### Connection Issues
 - Check Proxmox API is accessible (port 8006/8007)
 - Verify credentials have PVEAuditor role minimum
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 6838019d0..bf9c0dfd9 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -74,6 +74,15 @@ Pulse uses two different file types for configuration, each serving a specific p
 - **Contents**: Only auth-related variables (PULSE_AUTH_USER, PULSE_AUTH_PASS, API_TOKEN)
 - **Security**: Passwords and tokens are bcrypt-hashed, not plaintext
 
+**Example .env file:**
+```bash
+PULSE_AUTH_USER='admin'
+PULSE_AUTH_PASS='$2a$12$YTZXOCEylj4TaevZ0DCeI.notayQZ..b0OZ97lUZ.Q24fljLiMQHK'
+API_TOKEN='e6e9fcfb4662d2b485000cc5faf2f7e5d8b75e0492b4877c36dadb085f12e57b'
+```
+
+**CRITICAL**: The bcrypt hash MUST be exactly 60 characters and enclosed in single quotes!
+
 ### .enc Files (Sensitive Configuration)
 - **Purpose**: Store sensitive configuration like Proxmox node credentials
 - **Format**: Encrypted JSON using AES-256-GCM
@@ -97,7 +106,7 @@ Variables that ALWAYS override UI settings:
 - `FRONTEND_PORT` or `PORT` - Web UI port (default: 7655)
 - `API_TOKEN` - Token for API authentication (overrides UI)
 - `PULSE_AUTH_USER` - Username for web UI authentication (overrides UI)
-- `PULSE_AUTH_PASS` - Password for web UI authentication (overrides UI)
+- `PULSE_AUTH_PASS` - Bcrypt password hash - MUST be 60 chars in single quotes! (overrides UI)
 - `UPDATE_CHANNEL` - stable or rc (overrides UI)
 - `AUTO_UPDATE_ENABLED` - true/false (overrides UI)
 - `AUTO_UPDATE_CHECK_INTERVAL` - Hours between checks (overrides UI)
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 435b8fffb..5ee9ad691 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -94,9 +94,11 @@ docker run -e ALLOW_UNPROTECTED_EXPORT=true rcourtman/pulse:latest
 
 ### Enterprise Security (When Authentication Enabled)
 - **Password Security**: 
-  - Bcrypt hashing with cost factor 12
+  - Bcrypt hashing with cost factor 12 (60-character hash)
   - Passwords NEVER stored in plain text
   - Automatic hashing on security setup
+  - **CRITICAL**: Bcrypt hashes MUST be exactly 60 characters
+  - **Docker Users**: Always wrap hash in single quotes to prevent shell expansion
 - **API Token Security**:
   - SHA3-256 hashing for all tokens
   - 64-character hex format when hashed
diff --git a/internal/api/router.go b/internal/api/router.go
index 0e6d67615..463492984 100644
--- a/internal/api/router.go
+++ b/internal/api/router.go
@@ -678,6 +678,12 @@ func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 			isPublic = true
 		}
 		
+		// Special case: quick-setup should be accessible to check if already configured
+		// The handler itself will verify if setup should be skipped
+		if req.URL.Path == "/api/security/quick-setup" && req.Method == http.MethodPost {
+			isPublic = true
+		}
+		
 		// Check auth for protected routes
 		if !isPublic && !CheckAuth(r.config, w, req) {
 			// Never send WWW-Authenticate - use custom login page