feat: configurable ProxyFix trusted-hop count (#115)

Make the number of trusted reverse-proxy hops configurable via the
PROXY_FIX_HOPS env var (default 1, unchanged behaviour). With two hops in
front (e.g. Cloudflare then Traefik) the app's own login and audit logs
would otherwise record the intermediate proxy's IP.

The value is clamped to >= 0 (0 ignores X-Forwarded-For entirely), logged
at startup as Trusted Hops, and surfaced by the client IP diagnostic.

Author: fbnlrz

app.py

@@ -37,8 +37,14 @@
 logger = logging.getLogger("traefik-manager")
 
 
+def _proxy_fix_hops() -> int:
+    try:
+        return max(0, int(os.environ.get('PROXY_FIX_HOPS', '1')))
+    except ValueError:
+        return 1
+
 app = Flask(__name__)
-PROXY_FIX_HOPS = 1
+PROXY_FIX_HOPS = _proxy_fix_hops()
 app.wsgi_app = ProxyFix(app.wsgi_app, x_for=PROXY_FIX_HOPS, x_proto=1, x_host=1)
 
 _CONFIG_DIR      = os.path.dirname(os.environ.get('SETTINGS_PATH', '/app/config/manager.yml'))
@@ -1240,6 +1246,7 @@ def _read_traefik_labels():
 logger.info(f"Backup Dir:     {BACKUP_DIR}")
 logger.info(f"Traefik API:    {_s['traefik_api_url']}")
 logger.info(f"Restart Method: {_restart_meth}")
+logger.info(f"Trusted Hops:   {PROXY_FIX_HOPS}")
 logger.info(f"Static Config:  {_static_path if _static_path else 'not configured'}")
 logger.info(f"Domains:        {_s['domains']}")
 logger.info(f"Cert Resolver:  {_s['cert_resolver'] or 'not set'}")

docs/env-vars.md

@@ -80,6 +80,7 @@ Variables marked ✅ **override** the corresponding `manager.yml` field on every
 |---|---|---|---|
 | `SECRET_KEY` | _(auto-generated)_ | - | Flask session signing key |
 | `OTP_ENCRYPTION_KEY` | _(auto-generated)_ | - | Fernet key for encrypting TOTP secrets |
+| `PROXY_FIX_HOPS` | `1` | - | Number of trusted proxy hops in front of Traefik Manager for `X-Forwarded-For` |
 
 ---
 
@@ -694,3 +695,29 @@ python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().
 ::: warning
 If you lose this key, existing TOTP secrets become unreadable and 2FA must be re-enrolled. Back up `.otp_key` alongside your config volume.
 :::
+
+---
+
+### `PROXY_FIX_HOPS`
+
+**Default:** `1`
+
+How many trusted reverse-proxy hops sit in front of Traefik Manager. The app runs behind `ProxyFix`, which reads the client IP from the right of `X-Forwarded-For`; this value is how many positions it trusts. With a single proxy in front (Traefik → app) the default of `1` is correct. With two hops (e.g. Cloudflare → Traefik → app) the app's own login and audit logs would otherwise record the intermediate proxy's IP - set it to `2`.
+
+The active value is shown in the startup log as `Trusted Hops` and in the Client IP Diagnostic.
+
+:::tabs
+== Docker / Podman
+```yaml
+environment:
+  - PROXY_FIX_HOPS=2
+```
+== Linux (systemd)
+```ini
+Environment=PROXY_FIX_HOPS=2
+```
+:::
+
+::: warning
+Only count hops you actually control. Each trusted hop is one more `X-Forwarded-For` entry a client could forge, so setting this higher than your real proxy chain lets callers spoof their source IP past the login rate-limiter and audit log. Set it to `0` to ignore `X-Forwarded-For` entirely and use the direct connection IP.
+:::