User Story: 5.4

[humanauction]

Secure User Authentication with Session Tokens

---

AS A network security administrator managing a production monitoring system
I WANT a secure login system with hashed passwords and session tokens stored in a database
SO THAT I can ensure only authorized personnel access the network dashboard, maintain an audit trail of user activity and prevent API credential exposure in client-side code

---

Acceptance criteria

Given the dashboard is loaded in a browser
When the user is not authenticated
Then they should see a login form (username + password)

Given a user submits valid credentials to /login
When the server validates the bcrypt-hashed password
Then it generates a UUID session token, stores it in SQLite with metadata (user, IP, login timestamp), and returns it to the client

Given a user has a valid session token
When they request /metrics or other protected endpoints
Then the API validates the session token against SQLite and returns data

Given a session token expires (1 hour of inactivity)
When the user tries to access protected endpoints
Then they receive a 401 Unauthorized response and are prompted to log in again

Given a user logs out
When they click "Logout"
Then their session token is deleted from SQLite and removed from the browser

Additional acceptance criteria:

• Passwords are hashed with bcrypt (work factor: 12) before storage in config
• Session tokens are UUIDs stored in SQLite sessions table
• Session table includes: token, username, created_at, last_activity, ip_address
• Sessions expire after 1 hour of inactivity (configurable)
• Failed login attempts are rate-limited (3 attempts per minute per IP)
• API token remains server-side only, never exposed to client
• Dashboard shows "Logged in as: [username]" in header
• Session history is retained for forensic audit (configurable retention period)

---

Tasks

Backend (C++ Daemon):

• Install bcrypt C++ library (bcrypt-cpp or libbcrypt)
• Add /login POST endpoint (accepts {"username":"...", "password":"..."})
• Implement bcrypt password verification against hashed config passwords
• Generate UUID session tokens (libuuid or boost::uuid)
• Create SQLite sessions table schema
• Store session metadata (token, username, created_at, last_activity, ip_address)
• Add session validation middleware for protected endpoints
• Add /logout POST endpoint to delete session from SQLite
• Add rate limiting for /login endpoint (track by IP)
• Add session cleanup task (delete expired sessions every 5 minutes)

Frontend (Dashboard):

• Create login form HTML (www/login.html or modal overlay)
• Add CSS for login form (styled like main dashboard)
• Add JavaScript to handle login form submission
• Store session token in localStorage (not API token)
• Update fetchMetrics() to use session token in Authorization: Bearer <token> header
• Add logout button and handler
• Redirect to login on 401 responses
• Show "Logged in as: [username]" in header

Configuration:

• Add users section to sample-config.yaml with bcrypt-hashed passwords
• Add session.expiry_seconds config option (default: 3600)
• Add session.cleanup_interval_seconds config option (default: 300)
• Add session.retention_days config option (default: 30)

Database Schema:

• Create sessions table: (token TEXT PRIMARY KEY, username TEXT, created_at INTEGER, last_activity INTEGER, ip_address TEXT)
• Add index on last_activity for efficient cleanup queries

Testing:

• Unit test: bcrypt password hashing and verification
• Unit test: UUID session token generation
• Integration test: successful login returns session token
• Integration test: expired token returns 401
• Integration test: logout deletes session from SQLite
• Integration test: rate limiting blocks excessive login attempts
• Manual test: full login/logout flow in browser
• Manual test: session persists after daemon restart