Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

refactor(security): move web middleware classes into security module (#3967)

LearningCircuit4eeeeabea66c
diff --git a/src/local_deep_research/security/web_middleware.py b/src/local_deep_research/security/web_middleware.py
new file mode 100644
index 0000000000..2fb8b2c562
--- /dev/null
+++ b/src/local_deep_research/security/web_middleware.py
@@ -0,0 +1,92 @@
+"""WSGI middleware classes for web-layer security.
+
+These wrap the Flask WSGI app to enforce cookie security and strip
+information-disclosure headers. Wired into the middleware stack by
+``local_deep_research.web.app_factory.create_app``.
+"""
+
+from loguru import logger
+
+from .network_utils import is_private_ip
+
+
+class SecureCookieMiddleware:
+ """WSGI middleware that adds the Secure flag to Set-Cookie iff the
+ request is HTTPS.
+
+ The Secure flag tells the browser to send the cookie only over HTTPS.
+ Setting it on a response served over HTTP causes the browser to drop
+ the cookie entirely, so it must only be added when the user's
+ connection is actually HTTPS. ``ProxyFix`` (with ``x_proto=1``)
+ translates ``X-Forwarded-Proto`` into ``wsgi.url_scheme`` before this
+ middleware runs.
+
+ Side effect: logs a one-shot warning when the app serves HTTP to a
+ non-private end-user IP, signalling a likely missing HTTPS proxy
+ configuration. Skipped in ``LDR_TESTING_MODE``.
+ """
+
+ def __init__(self, wsgi_app, flask_app):
+ self.wsgi_app = wsgi_app
+ self.flask_app = flask_app
+ self._warned_insecure_public = False
+
+ def __call__(self, environ, start_response):
+ self._maybe_warn_insecure_public(environ)
+ should_add_secure = self._should_add_secure_flag(environ)
+
+ def custom_start_response(status, headers, exc_info=None):
+ if should_add_secure:
+ new_headers = []
+ for name, value in headers:
+ if name.lower() == "set-cookie":
+ if "; Secure" not in value and "; secure" not in value:
+ value = value + "; Secure"
+ new_headers.append((name, value))
+ headers = new_headers
+ return start_response(status, headers, exc_info)
+
+ return self.wsgi_app(environ, custom_start_response)
+
+ def _should_add_secure_flag(self, environ):
+ if self.flask_app.config.get("LDR_TESTING_MODE"):
+ return False
+ return environ.get("wsgi.url_scheme") == "https"
+
+ def _maybe_warn_insecure_public(self, environ):
+ if self._warned_insecure_public:
+ return
+ if self.flask_app.config.get("LDR_TESTING_MODE"):
+ return
+ if environ.get("wsgi.url_scheme") == "https":
+ return
+ remote_addr = environ.get("REMOTE_ADDR", "")
+ if is_private_ip(remote_addr):
+ return
+ self._warned_insecure_public = True
+ logger.warning(
+ f"Serving HTTP to non-private client {remote_addr}. "
+ f"Session cookies will be sent in plaintext. Configure HTTPS "
+ f"at the reverse proxy and ensure X-Forwarded-Proto is set."
+ )
+
+
+class ServerHeaderMiddleware:
+ """WSGI middleware that strips the Server header from responses to
+ prevent information disclosure about the underlying web server.
+ Applied as the outermost wrapper.
+ """
+
+ def __init__(self, wsgi_app):
+ self.wsgi_app = wsgi_app
+
+ def __call__(self, environ, start_response):
+ def custom_start_response(status, headers, exc_info=None):
+ filtered_headers = [
+ (name, value)
+ for name, value in headers
+ if name.lower() != "server"
+ ]
+ return start_response(status, filtered_headers, exc_info)
+
+ return self.wsgi_app(environ, custom_start_response)
diff --git a/src/local_deep_research/web/app_factory.py b/src/local_deep_research/web/app_factory.py
index 10cbc6c607..82b2573267 100644
--- a/src/local_deep_research/web/app_factory.py
+++ b/src/local_deep_research/web/app_factory.py
@@ -1,5 +1,4 @@
# import logging - replaced with loguru
-import ipaddress
import os
from pathlib import Path
from importlib import resources as importlib_resources
@@ -22,107 +21,15 @@ from ..utilities.log_utils import InterceptHandler
from ..security import SecurityHeaders, get_security_default
from ..security.rate_limiter import limiter
from ..security.file_upload_validator import FileUploadValidator
+from ..security.web_middleware import (
+ SecureCookieMiddleware,
+ ServerHeaderMiddleware,
+)
# Removed DB_PATH import - using per-user databases now
from .services.socket_service import SocketIOService
-def _is_private_ip(ip_str: str) -> bool:
- """Check if IP is a private/local network address (RFC 1918 + localhost).
-
- This allows LAN access over HTTP without requiring HTTPS, matching the
- behavior of other self-hosted applications like Jellyfin and Home Assistant.
-
- Private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, plus localhost.
- """
- try:
- ip = ipaddress.ip_address(ip_str)
- return ip.is_private or ip.is_loopback
- except ValueError:
- return False
-
-
-class SecureCookieMiddleware:
- """WSGI middleware that adds the Secure flag to Set-Cookie iff the
- request is HTTPS.
-
- The Secure flag tells the browser to send the cookie only over HTTPS.
- Setting it on a response served over HTTP causes the browser to drop
- the cookie entirely, so it must only be added when the user's
- connection is actually HTTPS. ProxyFix (with x_proto=1) translates
- X-Forwarded-Proto into wsgi.url_scheme before this middleware runs.
-
- Side effect: logs a one-shot warning when the app serves HTTP to a
- non-private end-user IP, signalling a likely missing HTTPS proxy
- configuration. Skipped in LDR_TESTING_MODE.
- """
-
- def __init__(self, wsgi_app, flask_app):
- self.wsgi_app = wsgi_app
- self.flask_app = flask_app
- self._warned_insecure_public = False
-
- def __call__(self, environ, start_response):
- self._maybe_warn_insecure_public(environ)
- should_add_secure = self._should_add_secure_flag(environ)
-
- def custom_start_response(status, headers, exc_info=None):
- if should_add_secure:
- new_headers = []
- for name, value in headers:
- if name.lower() == "set-cookie":
- if "; Secure" not in value and "; secure" not in value:
- value = value + "; Secure"
- new_headers.append((name, value))
- headers = new_headers
- return start_response(status, headers, exc_info)
-
- return self.wsgi_app(environ, custom_start_response)
-
- def _should_add_secure_flag(self, environ):
- if self.flask_app.config.get("LDR_TESTING_MODE"):
- return False
- return environ.get("wsgi.url_scheme") == "https"
-
- def _maybe_warn_insecure_public(self, environ):
- if self._warned_insecure_public:
- return
- if self.flask_app.config.get("LDR_TESTING_MODE"):
- return
- if environ.get("wsgi.url_scheme") == "https":
- return
- remote_addr = environ.get("REMOTE_ADDR", "")
- if _is_private_ip(remote_addr):
- return
- self._warned_insecure_public = True
- logger.warning(
- f"Serving HTTP to non-private client {remote_addr}. "
- f"Session cookies will be sent in plaintext. Configure HTTPS "
- f"at the reverse proxy and ensure X-Forwarded-Proto is set."
- )
-
-
-class ServerHeaderMiddleware:
- """WSGI middleware that strips the Server header from responses to
- prevent information disclosure about the underlying web server.
- Applied as the outermost wrapper.
- """
-
- def __init__(self, wsgi_app):
- self.wsgi_app = wsgi_app
-
- def __call__(self, environ, start_response):
- def custom_start_response(status, headers, exc_info=None):
- filtered_headers = [
- (name, value)
- for name, value in headers
- if name.lower() != "server"
- ]
- return start_response(status, filtered_headers, exc_info)
-
- return self.wsgi_app(environ, custom_start_response)
-
-
class DiskSpoolingRequest(Request):
"""Custom Request class that spools large file uploads to disk.
diff --git a/tests/web/test_app_factory.py b/tests/web/test_app_factory.py
index 08f6dfb11b..04148e5a70 100644
--- a/tests/web/test_app_factory.py
+++ b/tests/web/test_app_factory.py
@@ -2,7 +2,7 @@
Tests for the Flask application factory.
Tests cover:
-- _is_private_ip function
+- is_private_ip helper (re-imported from security.network_utils)
- DiskSpoolingRequest class
- create_app function
- CSRF protection
@@ -16,56 +16,56 @@ from flask import Flask
class TestIsPrivateIp:
- """Tests for _is_private_ip function."""
+ """Tests for the is_private_ip helper used by SecureCookieMiddleware."""
def test_localhost_ipv4(self):
"""127.0.0.1 is private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("127.0.0.1") is True
+ assert is_private_ip("127.0.0.1") is True
def test_localhost_ipv6(self):
"""::1 is private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("::1") is True
+ assert is_private_ip("::1") is True
def test_private_class_a(self):
"""10.x.x.x is private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("10.0.0.1") is True
- assert _is_private_ip("10.255.255.255") is True
+ assert is_private_ip("10.0.0.1") is True
+ assert is_private_ip("10.255.255.255") is True
def test_private_class_b(self):
"""172.16.x.x - 172.31.x.x is private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("172.16.0.1") is True
- assert _is_private_ip("172.31.255.255") is True
+ assert is_private_ip("172.16.0.1") is True
+ assert is_private_ip("172.31.255.255") is True
def test_private_class_c(self):
"""192.168.x.x is private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("192.168.0.1") is True
- assert _is_private_ip("192.168.255.255") is True
+ assert is_private_ip("192.168.0.1") is True
+ assert is_private_ip("192.168.255.255") is True
def test_public_ip(self):
"""Public IPs are not private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("8.8.8.8") is False
- assert _is_private_ip("1.1.1.1") is False
- assert _is_private_ip("142.250.190.78") is False
+ assert is_private_ip("8.8.8.8") is False
+ assert is_private_ip("1.1.1.1") is False
+ assert is_private_ip("142.250.190.78") is False
def test_invalid_ip(self):
"""Invalid IP returns False."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("invalid") is False
- assert _is_private_ip("256.256.256.256") is False
- assert _is_private_ip("") is False
+ assert is_private_ip("invalid") is False
+ assert is_private_ip("256.256.256.256") is False
+ assert is_private_ip("") is False
class TestDiskSpoolingRequest:
@@ -354,7 +354,7 @@ class TestSecureCookieMiddleware:
"""
def _make_middleware(self, testing_mode=False):
- from local_deep_research.web.app_factory import (
+ from local_deep_research.security.web_middleware import (
SecureCookieMiddleware,
)
@@ -419,7 +419,9 @@ class TestSecureCookieMiddleware:
"""The HTTP-to-public-IP warning is one-shot per middleware instance."""
mw = self._make_middleware()
env = {"REMOTE_ADDR": "8.8.8.8", "wsgi.url_scheme": "http"}
- with patch("local_deep_research.web.app_factory.logger") as mock_logger:
+ with patch(
+ "local_deep_research.security.web_middleware.logger"
+ ) as mock_logger:
self._capture_headers(mw, env)
self._capture_headers(mw, env)
self._capture_headers(mw, env)
@@ -433,7 +435,9 @@ class TestSecureCookieMiddleware:
def test_warning_does_not_fire_for_private_ip(self):
"""No warning when end-user IP is in a private range."""
mw = self._make_middleware()
- with patch("local_deep_research.web.app_factory.logger") as mock_logger:
+ with patch(
+ "local_deep_research.security.web_middleware.logger"
+ ) as mock_logger:
self._capture_headers(
mw,
{
diff --git a/tests/web/test_app_factory_middleware.py b/tests/web/test_app_factory_middleware.py
index db5d2f29f6..c1f2bd4c01 100644
--- a/tests/web/test_app_factory_middleware.py
+++ b/tests/web/test_app_factory_middleware.py
@@ -1,16 +1,16 @@
"""
-Tests for app_factory middleware components: _is_private_ip, DiskSpoolingRequest,
-SecureCookieMiddleware, and ServerHeaderMiddleware.
+Tests for web-layer middleware: SecureCookieMiddleware, ServerHeaderMiddleware,
+DiskSpoolingRequest, and the is_private_ip helper they depend on.
"""
import ipaddress
from flask import Flask, Request
-from local_deep_research.web.app_factory import (
+from local_deep_research.security.network_utils import is_private_ip
+from local_deep_research.security.web_middleware import (
SecureCookieMiddleware,
ServerHeaderMiddleware,
- _is_private_ip,
)
@@ -42,40 +42,40 @@ def _make_simple_app(**config_overrides):
# ===================================================================
-# 1. Tests for _is_private_ip (module-level, directly importable)
+# 1. Tests for the is_private_ip helper used by SecureCookieMiddleware
# ===================================================================
class TestIsPrivateIp:
- """Unit tests for the module-level _is_private_ip helper."""
+ """Unit tests for security.network_utils.is_private_ip."""
def test_loopback_ipv4(self):
- assert _is_private_ip("127.0.0.1") is True
+ assert is_private_ip("127.0.0.1") is True
def test_loopback_ipv6(self):
- assert _is_private_ip("::1") is True
+ assert is_private_ip("::1") is True
def test_class_a_private(self):
- assert _is_private_ip("10.0.0.1") is True
+ assert is_private_ip("10.0.0.1") is True
def test_class_b_private(self):
- assert _is_private_ip("172.16.0.1") is True
+ assert is_private_ip("172.16.0.1") is True
def test_class_c_private(self):
- assert _is_private_ip("192.168.1.1") is True
+ assert is_private_ip("192.168.1.1") is True
def test_public_google_dns(self):
- assert _is_private_ip("8.8.8.8") is False
+ assert is_private_ip("8.8.8.8") is False
def test_public_cloudflare_dns(self):
- assert _is_private_ip("1.1.1.1") is False
+ assert is_private_ip("1.1.1.1") is False
def test_public_documentation_range(self):
"""203.0.113.0/24 (TEST-NET-3) is documentation/reserved, not routable.
@@ -83,31 +83,31 @@ class TestIsPrivateIp:
# This is actually considered private by Python's ipaddress module
# because it is reserved. Verify against the real implementation.
- result = _is_private_ip("203.0.113.1")
+ result = is_private_ip("203.0.113.1")
ip = ipaddress.ip_address("203.0.113.1")
assert result == (ip.is_private or ip.is_loopback)
def test_invalid_string(self):
- assert _is_private_ip("not-an-ip") is False
+ assert is_private_ip("not-an-ip") is False
def test_empty_string(self):
- assert _is_private_ip("") is False
+ assert is_private_ip("") is False
def test_invalid_octet_values(self):
- assert _is_private_ip("256.256.256.256") is False
+ assert is_private_ip("256.256.256.256") is False
def test_ipv6_private(self):
# fc00::/7 is unique local address (private)
- assert _is_private_ip("fc00::1") is True
+ assert is_private_ip("fc00::1") is True
def test_ipv6_public(self):
# 2001:4860:4860::8888 is Google Public DNS IPv6
- assert _is_private_ip("2001:4860:4860::8888") is False
+ assert is_private_ip("2001:4860:4860::8888") is False
# ===================================================================
diff --git a/tests/web/test_error_handler_behavior.py b/tests/web/test_error_handler_behavior.py
index 91cc93d08a..021c88ae2b 100644
--- a/tests/web/test_error_handler_behavior.py
+++ b/tests/web/test_error_handler_behavior.py
@@ -8,7 +8,7 @@ Existing tests cover registration and 404 content; these test:
- WebAPIException handler JSON conversion
- CSRF handler IP-based messaging (private/public/proxied/HTTPS)
- NewsAPIException handler JSON conversion
-- _is_private_ip edge cases (IPv4-mapped IPv6, link-local, multicast)
+- is_private_ip edge cases (IPv4-mapped IPv6, link-local, multicast)
"""
import pytest
@@ -267,26 +267,22 @@ class TestWebAPIExceptionHandler:
class TestIsPrivateIpEdgeCases:
- """Edge cases for _is_private_ip not covered by existing tests."""
+ """Edge cases for is_private_ip not covered by existing tests."""
def test_ipv4_mapped_ipv6_private(self):
"""IPv4-mapped IPv6 address with private IPv4 is treated as private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- assert _is_private_ip("::ffff:192.168.1.1") is True
+ assert is_private_ip("::ffff:192.168.1.1") is True
def test_link_local_address(self):
"""Link-local addresses (169.254.x.x) are private."""
- from local_deep_research.web.app_factory import _is_private_ip
+ from local_deep_research.security.network_utils import is_private_ip
- # 169.254.x.x is link-local, treated as private by ipaddress module
- assert _is_private_ip("169.254.1.1") is True
+ assert is_private_ip("169.254.1.1") is True
def test_multicast_address(self):
- """Multicast addresses (224.x.x.x) are not private/loopback."""
- from local_deep_research.web.app_factory import _is_private_ip
- import ipaddress
+ """Multicast addresses (224.x.x.x) are not private."""
+ from local_deep_research.security.network_utils import is_private_ip
- ip = ipaddress.ip_address("224.0.0.1")
- expected = ip.is_private or ip.is_loopback
- assert _is_private_ip("224.0.0.1") is expected
+ assert is_private_ip("224.0.0.1") is False