~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
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.pynew file mode 100644index 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.pyindex 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 ipaddressimport osfrom pathlib import Pathfrom importlib import resources as importlib_resources@@ -22,107 +21,15 @@ from ..utilities.log_utils import InterceptHandlerfrom ..security import SecurityHeaders, get_security_defaultfrom ..security.rate_limiter import limiterfrom ..security.file_upload_validator import FileUploadValidator+from ..security.web_middleware import (+ SecureCookieMiddleware,+ ServerHeaderMiddleware,+)# Removed DB_PATH import - using per-user databases nowfrom .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.pyindex 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 Flaskclass 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 Truedef 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 Truedef 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 Truedef 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 Truedef 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 Truedef 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 Falsedef 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 Falseclass 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.pyindex 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 ipaddressfrom 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 Truedef test_loopback_ipv6(self):- assert _is_private_ip("::1") is True+ assert is_private_ip("::1") is Truedef test_class_a_private(self):- assert _is_private_ip("10.0.0.1") is True+ assert is_private_ip("10.0.0.1") is Truedef test_class_b_private(self):- assert _is_private_ip("172.16.0.1") is True+ assert is_private_ip("172.16.0.1") is Truedef test_class_c_private(self):- assert _is_private_ip("192.168.1.1") is True+ assert is_private_ip("192.168.1.1") is Truedef test_public_google_dns(self):- assert _is_private_ip("8.8.8.8") is False+ assert is_private_ip("8.8.8.8") is Falsedef test_public_cloudflare_dns(self):- assert _is_private_ip("1.1.1.1") is False+ assert is_private_ip("1.1.1.1") is Falsedef 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 Falsedef test_empty_string(self):- assert _is_private_ip("") is False+ assert is_private_ip("") is Falsedef test_invalid_octet_values(self):- assert _is_private_ip("256.256.256.256") is False+ assert is_private_ip("256.256.256.256") is Falsedef 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 Truedef 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.pyindex 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 Truedef 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 Truedef 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