From b5d57f5c8a3af1749aba94e6935c13dd5b8b8a50 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Thu, 29 Jan 2026 09:21:49 -0500
Subject: [PATCH] docs(readme): update security features documentation

- Document password complexity requirements
- Document account lockout mechanism (5 attempts, 15 min)
- Update JWT expiration to 1 hour
- Add refresh token documentation (7-day expiration)
- Add token management endpoints
- Enhance security features section
- Document standardized error responses
---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 563334d..6373922 100644
--- a/README.md
+++ b/README.md
@@ -16,14 +16,23 @@ A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and T
 
 ### 🔒 Authentication & Security
 - **Multi-User Support**: Complete user registration and authentication system
-- **JWT-Based Sessions**: Secure token-based authentication with localStorage persistence
+- **JWT-Based Sessions**: Secure token-based authentication with 1-hour expiration and refresh token support
 - **Role-Based Access**: Admin and user roles with granular permission control
-- **Password Security**: bcrypt hashing with secure password requirements (min 6 characters)
+- **Password Security**: bcrypt hashing with complex password requirements:
+  - Minimum 8 characters
+  - At least one uppercase letter (A-Z)
+  - At least one lowercase letter (a-z)
+  - At least one number (0-9)
+  - At least one special character (!@#$%^&*()_+-=[]{}|;':\",./<>?)
+- **Account Lockout**: Automatic account lockout after 5 failed login attempts (15-minute lockout period)
 - **Rate Limiting**: Built-in rate limiting on auth endpoints (10 requests/minute) to prevent brute force attacks
+- **Refresh Tokens**: Secure refresh token mechanism (7-day expiration) for seamless token renewal
 - **Input Validation**: Comprehensive validation including username whitespace checks, email format validation
 - **Pagination Protection**: Maximum pagination limits (1000 items) to prevent DoS attacks
 - **Path Validation**: Library folder paths are validated for existence and accessibility
 - **Case-Insensitive Roles**: Role values automatically normalized to lowercase
+- **Database Transactions**: Multi-step database operations use transaction support for data consistency
+- **Standardized Error Responses**: Consistent error format across all API endpoints
 
 ### 🎨 Beautiful UI
 - **11 Dark Themes**: Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, Catppuccin variants
@@ -174,6 +183,10 @@ GET /api/media-items/{id}/rating       # Get user rating
 POST /api/media-items/{id}/rating      # Create/update rating
 PUT /api/media-items/{id}/rating       # Update rating
 DELETE /api/media-items/{id}/rating   # Delete rating
+
+# Token Management
+POST /api/auth/refresh                 # Refresh access token
+POST /api/auth/logout                  # Logout (revokes refresh token)
 ```
 
 ## 📖 Media Support
@@ -258,19 +271,42 @@ bruno/
 3. **Protected Routes**: Use `Authorization: Bearer {token}` header
 
 ### Error Handling
+All API endpoints return standardized error responses:
+```json
+{
+  "error": "Error message",
+  "message": "Detailed error information (if available)",
+  "code": "Error code (if applicable)"
+}
+```
+
+HTTP Status Codes:
 - **400**: Bad request (validation errors)
 - **401**: Unauthorized (invalid/missing token)
 - **403**: Forbidden (insufficient permissions)
 - **404**: Resource not found
+- **429**: Too many requests (rate limit exceeded)
 - **500**: Internal server error
 
 ## 🛡 Security Features
 
-### Authentication
-- **JWT Tokens**: Secure, expiring tokens with localStorage persistence
-- **Password Hashing**: bcrypt with cost factor 12
-- **Input Validation**: Comprehensive server-side validation
+### Authentication & Authorization
+- **JWT Tokens**: 
+  - Short-lived access tokens (1-hour expiration)
+  - Refresh tokens (7-day expiration) for seamless session renewal
+  - Secure token storage and transmission
+- **Password Security**:
+  - bcrypt hashing with cost factor 12
+  - Complex password requirements enforced
+  - Password validation on registration and updates
+- **Account Protection**:
+  - Automatic lockout after 5 failed login attempts
+  - 15-minute lockout period with countdown
+  - IP-based and username-based attempt tracking
+- **Rate Limiting**: 10 requests per minute on authentication endpoints
+- **Input Validation**: Comprehensive server-side validation for all inputs
 - **CSRF Protection**: Built-in with HTMX
+- **Role-Based Access Control**: Admin and user roles enforced on all endpoints
 
 ### Authorization
 - **Role-Based Access**: Admin vs user permissions
@@ -279,10 +315,13 @@ bruno/
 - **Content Security**: XSS protection and secure headers
 
 ### Database Security
-- **Parameterized Queries**: SQL injection prevention
-- **pgx v5**: Modern database driver with connection pooling
+- **Parameterized Queries**: SQL injection prevention with pgx v5
+- **Connection Pooling**: Efficient database connection management
+- **Transaction Support**: Multi-step operations wrapped in transactions
 - **Environment Variables**: Secure secret management
 - **Row-Level Security**: User data isolation
+- **Secure Refresh Token Storage**: Encrypted token storage in database
+- **Automatic Token Cleanup**: Expired tokens cleaned up periodically
 
 ## 🔧 Configuration