refactor: change security headers default to disabled

Security headers are now disabled by default since most deployments use a reverse proxy (Traefik, Nginx) that already adds these headers. Enable with SECURITY_HEADERS_ENABLED=true for direct deployments.

Changes:
- Set security_headers_enabled default to False in app/config.py
- Update all documentation to reflect new default
- Comment out examples in .env.demo (now showing disabled state)
- Update SECURITY_AUDIT.md to reflect reverse proxy as default deployment
- Tests still pass (3 passed, 8 skipped as expected with headers disabled)

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

.env.demo

@@ -22,29 +22,30 @@ MAX_UPLOAD_SIZE=1073741824
 # MAX_SINGLE_FILE_SIZE=104857600
 
 # **Security Headers** (see SECURITY_AUDIT.md and docs/DeploymentGuide.md)
-# Enable security headers middleware in the application
+# Disabled by default since most deployments use a reverse proxy (Traefik, Nginx, etc.)
-# Set to false if deploying behind a reverse proxy (Traefik, Nginx, etc.) that already adds these headers
+# that already adds these headers. Set to true only if deploying directly without a reverse proxy.
-SECURITY_HEADERS_ENABLED=true
+# SECURITY_HEADERS_ENABLED=false
 
+# If you enable security headers, you can also configure individual headers:
 # Strict-Transport-Security (HSTS) - Forces HTTPS connections
 # Only effective when served over HTTPS. Disable if not using HTTPS or if proxy adds this header
-SECURITY_HEADER_HSTS_ENABLED=true
+# SECURITY_HEADER_HSTS_ENABLED=true
-SECURITY_HEADER_HSTS_VALUE="max-age=31536000; includeSubDomains"
+# SECURITY_HEADER_HSTS_VALUE="max-age=31536000; includeSubDomains"
 
 # Content-Security-Policy (CSP) - Controls resource loading
 # Customize based on your application's resource loading needs
 # Default allows self-hosted resources, inline scripts/styles, and external images
-SECURITY_HEADER_CSP_ENABLED=true
+# SECURITY_HEADER_CSP_ENABLED=true
-SECURITY_HEADER_CSP_VALUE="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;"
+# SECURITY_HEADER_CSP_VALUE="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;"
 
 # X-Frame-Options - Prevents clickjacking attacks
 # Options: DENY (no framing), SAMEORIGIN (same origin framing only), ALLOW-FROM uri
-SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
+# SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
-SECURITY_HEADER_X_FRAME_OPTIONS_VALUE="DENY"
+# SECURITY_HEADER_X_FRAME_OPTIONS_VALUE="DENY"
 
 # X-Content-Type-Options - Prevents MIME sniffing
 # Always set to 'nosniff' when enabled
-SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
+# SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
 
 # **Authentication**
 AUTH_ENABLED=true

SECURITY_AUDIT.md

@@ -245,8 +245,8 @@ ftp = ftplib.FTP()  # nosec B321 - Plaintext FTP intentional when configured
 - ✅ ProxyHeadersMiddleware for reverse proxy setup (X-Forwarded-* headers)
 - ✅ SessionMiddleware with strong secret validation
 - ✅ **Security headers middleware implemented** - Configurable HSTS, CSP, X-Frame-Options, X-Content-Type-Options ([#174](https://github.com/christianlouis/DocuElevate/issues/174))
-  - Enabled by default for direct deployment
+  - Disabled by default (typical deployment uses reverse proxy that adds headers)
-  - Configurable to disable when reverse proxy handles headers
+  - Can be enabled for direct deployment without reverse proxy
   - Individual header control and customization
   - Documented in DeploymentGuide.md and ConfigurationGuide.md
 - ⏳ **TODO:** Implement proper CORS configuration (currently not configured) ([#175](https://github.com/christianlouis/DocuElevate/issues/175))
@@ -656,27 +656,12 @@ SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
 
 ### Deployment Scenarios
 
-#### Direct Deployment (No Reverse Proxy)
+#### Reverse Proxy Deployment (Traefik, Nginx, etc.) - DEFAULT
 
-Security headers are **enabled by default** for direct deployments:
+**Most deployments use a reverse proxy**, which is why security headers are **disabled by default** in DocuElevate. The reverse proxy should add these headers.
 
 ```bash
-# .env configuration
+# .env configuration (or omit - this is the default)
-SECURITY_HEADERS_ENABLED=true
-SECURITY_HEADER_HSTS_ENABLED=true
-SECURITY_HEADER_CSP_ENABLED=true
-SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
-SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
-```
-
-All headers are added by the application middleware.
-
-#### Reverse Proxy Deployment (Traefik, Nginx, etc.)
-
-When deploying behind a reverse proxy that already adds security headers, **disable the middleware** to avoid duplication:
-
-```bash
-# .env configuration
 SECURITY_HEADERS_ENABLED=false
 ```
 
@@ -697,13 +682,28 @@ add_header X-Frame-Options "DENY" always;
 add_header X-Content-Type-Options "nosniff" always;
 ```
 
+#### Direct Deployment (No Reverse Proxy)
+
+If deploying directly without a reverse proxy, **enable security headers**:
+
+```bash
+# .env configuration
+SECURITY_HEADERS_ENABLED=true
+SECURITY_HEADER_HSTS_ENABLED=true
+SECURITY_HEADER_CSP_ENABLED=true
+SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
+SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
+```
+
+All headers are added by the application middleware.
+
 ### Configuration Options
 
 All security headers are configurable via environment variables:
 
 | Setting | Purpose | Default |
 |---------|---------|---------|
-| `SECURITY_HEADERS_ENABLED` | Master enable/disable | `true` |
+| `SECURITY_HEADERS_ENABLED` | Master enable/disable | `false` |
 | `SECURITY_HEADER_HSTS_ENABLED` | Enable HSTS | `true` |
 | `SECURITY_HEADER_HSTS_VALUE` | HSTS configuration | `max-age=31536000; includeSubDomains` |
 | `SECURITY_HEADER_CSP_ENABLED` | Enable CSP | `true` |
@@ -738,8 +738,8 @@ All security headers are configurable via environment variables:
 1. **Defense in Depth:** Multiple layers of browser-side security
 2. **Flexible Configuration:** Adapts to different deployment scenarios
 3. **Industry Best Practices:** Follows OWASP security recommendations
-4. **Easy Deployment:** Works out-of-the-box with sensible defaults
+4. **Smart Defaults:** Disabled by default for typical reverse proxy deployments
-5. **Reverse Proxy Compatible:** Can be disabled when proxy handles headers
+5. **Reverse Proxy Compatible:** Works seamlessly with Traefik, Nginx, etc.
 6. **Well Documented:** Comprehensive documentation for all scenarios
 
 ### Testing

app/config.py

@@ -175,11 +175,11 @@ class Settings(BaseSettings):
     )
 
     # Security Headers Configuration (see SECURITY_AUDIT.md and docs/DeploymentGuide.md)
-    # When deploying behind a reverse proxy (Traefik, Nginx, etc.), disable these headers
+    # Disabled by default since most deployments use a reverse proxy (Traefik, Nginx, etc.)
-    # if your proxy already adds them to avoid duplication
+    # that already adds these headers. Enable if deploying directly without a reverse proxy.
     security_headers_enabled: bool = Field(
-        default=True,
+        default=False,
-        description="Enable security headers middleware. Set to False if reverse proxy handles headers.",
+        description="Enable security headers middleware. Set to True if deploying without reverse proxy.",
     )
 
     # Strict-Transport-Security (HSTS) - Forces HTTPS connections

docs/ConfigurationGuide.md

@@ -100,13 +100,13 @@ DocuElevate can monitor multiple IMAP mailboxes for document attachments. Each m
 
 ### Security Headers
 
-DocuElevate supports HTTP security headers to improve browser-side security. These headers are enabled by default but should be disabled if your reverse proxy (Traefik, Nginx, etc.) already adds them. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples.
+DocuElevate supports HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds them. Enable only if deploying directly without a reverse proxy. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples.
 
 #### Master Control
 
 | **Variable**                | **Description**                                                         | **Default** |
 |-----------------------------|-------------------------------------------------------------------------|-------------|
-| `SECURITY_HEADERS_ENABLED`  | Enable/disable security headers middleware. Set to `false` if reverse proxy handles headers. | `true` |
+| `SECURITY_HEADERS_ENABLED`  | Enable/disable security headers middleware. Set to `true` if deploying without reverse proxy. | `false` |
 
 #### Strict-Transport-Security (HSTS)
 
@@ -173,9 +173,15 @@ Prevents browsers from MIME-sniffing responses away from the declared content-ty
 
 #### Configuration Examples
 
+**Reverse Proxy Deployment (Default - Traefik, Nginx):**
+```bash
+# Headers disabled by default - reverse proxy handles them
+# SECURITY_HEADERS_ENABLED=false  # Can be omitted
+```
+
 **Direct Deployment (No Reverse Proxy):**
 ```bash
-# Enable all security headers (default)
+# Enable all security headers
 SECURITY_HEADERS_ENABLED=true
 SECURITY_HEADER_HSTS_ENABLED=true
 SECURITY_HEADER_CSP_ENABLED=true
@@ -183,12 +189,6 @@ SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
 SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
 ```
 
-**Behind Reverse Proxy (Traefik, Nginx):**
-```bash
-# Disable security headers (let proxy handle them)
-SECURITY_HEADERS_ENABLED=false
-```
-
 **Custom Configuration:**
 ```bash
 # Enable headers but customize values

docs/DeploymentGuide.md

@@ -56,7 +56,7 @@ Access the web interface at `http://localhost:8000` and the API documentation at
 
 ### Security Headers
 
-DocuElevate includes built-in support for HTTP security headers to improve browser-side security. These headers are enabled by default but can be configured based on your deployment scenario.
+DocuElevate includes built-in support for HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds these headers.
 
 #### Supported Security Headers
 
@@ -65,31 +65,12 @@ DocuElevate includes built-in support for HTTP security headers to improve brows
 - **X-Frame-Options**: Prevents the page from being loaded in frames (clickjacking protection)
 - **X-Content-Type-Options**: Prevents browsers from MIME-sniffing responses
 
-#### Direct Deployment (No Reverse Proxy)
+#### Reverse Proxy Deployment (Traefik, Nginx, etc.) - DEFAULT
 
-If you're running DocuElevate directly without a reverse proxy, security headers are enabled by default:
+**Most deployments use a reverse proxy**, which is why security headers are disabled by default in DocuElevate. The reverse proxy should add these headers.
 
 ```bash
-# In .env file
+# In .env file (or omit - this is the default)
-SECURITY_HEADERS_ENABLED=true
-SECURITY_HEADER_HSTS_ENABLED=true
-SECURITY_HEADER_CSP_ENABLED=true
-SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
-SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
-```
-
-**Note**: HSTS only works when serving content over HTTPS. If using HTTP for development, you can disable it:
-
-```bash
-SECURITY_HEADER_HSTS_ENABLED=false
-```
-
-#### Reverse Proxy Deployment (Traefik, Nginx, etc.)
-
-When deploying behind a reverse proxy that adds security headers, **disable the built-in headers** to avoid duplication:
-
-```bash
-# In .env file
 SECURITY_HEADERS_ENABLED=false
 ```
 
@@ -146,11 +127,35 @@ server {
 }
 ```
 
-Then set `SECURITY_HEADERS_ENABLED=false` in your `.env` file.
+Then keep `SECURITY_HEADERS_ENABLED=false` in your `.env` file (or omit it, as this is the default).
+
+#### Direct Deployment (No Reverse Proxy)
+
+If you're running DocuElevate **directly without a reverse proxy**, enable security headers:
+
+```bash
+# In .env file
+SECURITY_HEADERS_ENABLED=true
+```
+
+You can also configure individual headers:
+
+```bash
+SECURITY_HEADER_HSTS_ENABLED=true
+SECURITY_HEADER_CSP_ENABLED=true
+SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED=true
+SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS_ENABLED=true
+```
+
+**Note**: HSTS only works when serving content over HTTPS. If using HTTP for development, you can disable it:
+
+```bash
+SECURITY_HEADER_HSTS_ENABLED=false
+```
 
 #### Customizing Security Headers
 
-You can customize individual header values in your `.env` file:
+If you enable security headers, you can customize individual header values in your `.env` file:
 
 ```bash
 # Customize HSTS (e.g., shorter duration for testing)