Refactor backend configuration and authentication

- Add comprehensive documentation for backend development
- Improve client IP detection with utility functions and tests
- Update auth router with better error handling
- Refactor config module with environment-based settings

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/tests/test_config.py

@@ -158,3 +158,157 @@ def test_session_secret_error_message_includes_guidance() -> None:
     error_msg = str(exc_info.value)
     # Verify the error mentions the constraint
     assert "session_secret" in error_msg
+
+
+# ---------------------------------------------------------------------------
+# trusted_proxies configuration tests
+# ---------------------------------------------------------------------------
+
+
+def test_trusted_proxies_default_is_empty_list() -> None:
+    """By default, trusted_proxies is an empty list (no trusted proxies)."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+    )
+    assert settings.trusted_proxies == []
+
+
+def test_trusted_proxies_accepts_single_ip() -> None:
+    """Single IP address is accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="192.168.1.1",
+    )
+    assert settings.trusted_proxies == ["192.168.1.1"]
+
+
+def test_trusted_proxies_accepts_single_cidr() -> None:
+    """Single CIDR range is accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="10.0.0.0/8",
+    )
+    assert settings.trusted_proxies == ["10.0.0.0/8"]
+
+
+def test_trusted_proxies_accepts_comma_separated_list() -> None:
+    """Comma-separated list of IPs and CIDRs is accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="192.168.1.1,10.0.0.0/8,172.16.0.0/12",
+    )
+    assert settings.trusted_proxies == ["192.168.1.1", "10.0.0.0/8", "172.16.0.0/12"]
+
+
+def test_trusted_proxies_accepts_list() -> None:
+    """List of IPs and CIDRs is accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies=["192.168.1.1", "10.0.0.0/8"],
+    )
+    assert settings.trusted_proxies == ["192.168.1.1", "10.0.0.0/8"]
+
+
+def test_trusted_proxies_strips_whitespace() -> None:
+    """Whitespace around IPs is stripped."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="  192.168.1.1  ,  10.0.0.0/8  ",
+    )
+    assert settings.trusted_proxies == ["192.168.1.1", "10.0.0.0/8"]
+
+
+def test_trusted_proxies_rejects_invalid_ip() -> None:
+    """Invalid IP address is rejected."""
+    with pytest.raises(ValidationError) as exc_info:
+        Settings(
+            database_path="/tmp/test.db",
+            fail2ban_socket="/tmp/fake_fail2ban.sock",
+            fail2ban_config_dir="/tmp/fail2ban",
+            session_secret="a" * 32,
+            trusted_proxies="not-an-ip",
+        )
+    error_msg = str(exc_info.value)
+    assert "trusted_proxies" in error_msg or "Invalid IP" in error_msg
+
+
+def test_trusted_proxies_rejects_invalid_cidr() -> None:
+    """Invalid CIDR range is rejected."""
+    with pytest.raises(ValidationError) as exc_info:
+        Settings(
+            database_path="/tmp/test.db",
+            fail2ban_socket="/tmp/fake_fail2ban.sock",
+            fail2ban_config_dir="/tmp/fail2ban",
+            session_secret="a" * 32,
+            trusted_proxies="10.0.0.0/33",  # Invalid - /33 is out of range for IPv4
+        )
+    error_msg = str(exc_info.value)
+    assert "trusted_proxies" in error_msg or "Invalid IP" in error_msg
+
+
+def test_trusted_proxies_rejects_one_invalid_in_list() -> None:
+    """One invalid IP in a list causes entire list to be rejected."""
+    with pytest.raises(ValidationError) as exc_info:
+        Settings(
+            database_path="/tmp/test.db",
+            fail2ban_socket="/tmp/fake_fail2ban.sock",
+            fail2ban_config_dir="/tmp/fail2ban",
+            session_secret="a" * 32,
+            trusted_proxies="192.168.1.1,invalid-ip,10.0.0.0/8",
+        )
+    error_msg = str(exc_info.value)
+    assert "trusted_proxies" in error_msg or "Invalid IP" in error_msg
+
+
+def test_trusted_proxies_accepts_ipv6_address() -> None:
+    """IPv6 address is accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="2001:db8::1",
+    )
+    assert settings.trusted_proxies == ["2001:db8::1"]
+
+
+def test_trusted_proxies_accepts_ipv6_cidr() -> None:
+    """IPv6 CIDR range is accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="2001:db8::/32",
+    )
+    assert settings.trusted_proxies == ["2001:db8::/32"]
+
+
+def test_trusted_proxies_accepts_mixed_ipv4_and_ipv6() -> None:
+    """Mixed IPv4 and IPv6 addresses and ranges are accepted."""
+    settings = Settings(
+        database_path="/tmp/test.db",
+        fail2ban_socket="/tmp/fake_fail2ban.sock",
+        fail2ban_config_dir="/tmp/fail2ban",
+        session_secret="a" * 32,
+        trusted_proxies="192.168.1.0/24,2001:db8::/32,10.0.0.1",
+    )
+    assert settings.trusted_proxies == ["192.168.1.0/24", "2001:db8::/32", "10.0.0.1"]