~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
harden(notifications): pin resolved IPs and block private resolution for the Apprise send (#5575)
LearningCircuit34756532ae4d
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 08e67fcc9d..15bcbf2043 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -447,6 +447,18 @@ repos:description: "Block test modules that import nothing from local_deep_research(shadow tests). Opt out a legitimate no-import test with'# allow: no-sut-import — <reason>'. See CONTRIBUTING.md."+ - id: check-no-src-test-imports+ name: Forbid src.local_deep_research imports in tests+ entry: .pre-commit-hooks/check-no-src-test-imports.py+ language: script+ files: ^tests/.*\.py$+ # tests/hooks carry the alias as literal test data for the hook checks.+ exclude: ^tests/hooks/+ description: "Ban 'src.local_deep_research' imports and patch-target strings+ in tests. The 'src.' alias is a DISTINCT module object from the canonical+ 'local_deep_research'; importing a module under both loads two copies and+ breaks process-global singletons (the security.dns_pinning getaddrinfo+ shim the notification send fails closed on). Use 'local_deep_research'."- id: check-weak-testsname: Check for tautological / no-op testsentry: .pre-commit-hooks/check-weak-tests.pydiff --git a/.pre-commit-hooks/check-no-src-test-imports.py b/.pre-commit-hooks/check-no-src-test-imports.pynew file mode 100755index 0000000000..249dbf1d20--- /dev/null+++ b/.pre-commit-hooks/check-no-src-test-imports.py@@ -0,0 +1,159 @@+#!/usr/bin/env python3+"""Pre-commit hook: forbid ``src.local_deep_research`` references in tests.++The package is importable under two distinct names: the canonical+``local_deep_research`` (what the running app and every production module use)+and ``src.local_deep_research`` (resolvable only because the repo root is on+``sys.path`` during test collection). Python treats these as SEPARATE module+objects with separate globals — so importing the SAME module under both names+loads TWO copies of it.++For most modules that is merely wasteful, but for process-global singletons it+is a latent bug. ``security/dns_pinning`` installs a process-wide+``socket.getaddrinfo`` shim and the notification send path fails CLOSED unless+that shim is *this* module's object (strict identity). A single ``src.``+import anywhere in the suite loads a second ``dns_pinning``, whose shim+displaces the canonical one, so the notification-send guard reports "shim+missing" and refuses to send — a failure that surfaces only in the full/xdist+run where a ``src.`` importer lands in the same worker before the send tests.++The fix was to normalize every test import to the canonical package; this hook+keeps it that way. It flags, in ``tests/**/*.py``:++* ``import src.local_deep_research...`` / ``from src.local_deep_research... import ...``+* string literals that START with ``src.local_deep_research`` — i.e. mock+ ``patch(...)`` / ``patch.object(...)`` targets and ``module_path`` values,+ which import the ``src.`` module tree when the patch is entered exactly as a+ real import would.++Backtick-wrapped prose in comments/docstrings that merely NAMES the banned+alias is not flagged (AST ignores comments; a docstring value does not *start*+with the alias). ``tests/hooks/`` is exempt: those tests carry the alias as+literal test data for the hook checks themselves.+"""++import ast+import sys+from pathlib import Path++BANNED_PREFIX = "src.local_deep_research"++# Directories (as path components) whose test files legitimately carry the+# banned alias as test data for the pre-commit hooks themselves.+EXEMPT_DIR_COMPONENTS = ("hooks",)+++def _is_test_file(p: Path) -> bool:+ parts = p.parts+ if "tests" not in parts:+ return False+ # Everything under tests/hooks is exempt (hook test data).+ tests_idx = parts.index("tests")+ tail = parts[tests_idx + 1 :]+ return not any(c in tail for c in EXEMPT_DIR_COMPONENTS)+++def _banned(name) -> bool:+ return isinstance(name, str) and (+ name == BANNED_PREFIX or name.startswith(BANNED_PREFIX + ".")+ )+++class _Checker(ast.NodeVisitor):+ def __init__(self):+ self.errors = []++ def visit_Import(self, node):+ for alias in node.names:+ # import src.local_deep_research[...] OR import src (aliased)+ if _banned(alias.name) or alias.name == "src":+ self.errors.append(+ (node.lineno, f"import of banned alias '{alias.name}'")+ )+ self.generic_visit(node)++ def visit_ImportFrom(self, node):+ module = node.module or ""+ # from src.local_deep_research[...] import ...+ if _banned(module):+ self.errors.append(+ (node.lineno, f"import from banned alias '{module}'")+ )+ # from src import local_deep_research+ elif module == "src" and any(+ a.name == "local_deep_research" for a in node.names+ ):+ self.errors.append(+ (node.lineno, "import of 'local_deep_research' from 'src'")+ )+ self.generic_visit(node)++ def visit_Constant(self, node):+ # patch(...) targets / module_path values that START with the alias.+ if isinstance(node.value, str) and _banned(node.value):+ self.errors.append(+ (+ node.lineno,+ f"string references banned alias '{node.value}'",+ )+ )+ self.generic_visit(node)+++def check_file(filename: str) -> bool:+ p = Path(filename)+ if not _is_test_file(p):+ return True+ try:+ content = p.read_text(encoding="utf-8")+ except Exception as e: # pragma: no cover - unreadable file+ print(f"Error reading {filename}: {e}")+ return False+ try:+ tree = ast.parse(content, filename=filename)+ except SyntaxError:+ # Let ruff / the compiler report syntax errors.+ return True+ checker = _Checker()+ checker.visit(tree)+ if checker.errors:+ print(f"\n{filename}:")+ for lineno, msg in checker.errors:+ print(f" Line {lineno}: {msg}")+ return False+ return True+++def main() -> int:+ if len(sys.argv) < 2:+ print("Usage: check-no-src-test-imports.py <file1> <file2> ...")+ return 1+ has_errors = False+ for filename in sys.argv[1:]:+ if filename.endswith(".py") and not check_file(filename):+ has_errors = True+ if has_errors:+ print("\n" + "=" * 70)+ print("Banned 'src.local_deep_research' reference in tests!")+ print("=" * 70)+ print(+ "\nImport the package under its canonical name 'local_deep_research'"+ " instead\nof 'src.local_deep_research'. The two names are DISTINCT"+ " module objects;\nimporting a module under both loads two copies,"+ " which breaks process-\nglobal singletons (e.g. the"+ " security.dns_pinning getaddrinfo shim that\nthe notification send"+ " path fails closed on).\n"+ )+ print("Examples:")+ print(" BAD: from src.local_deep_research.chat.service import X")+ print(" GOOD: from local_deep_research.chat.service import X")+ print(+ ' BAD: patch("src.local_deep_research.config.llm_config.get_llm")'+ )+ print(' GOOD: patch("local_deep_research.config.llm_config.get_llm")')+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/SECURITY.md b/SECURITY.mdindex 0589b98695..99cacb19be 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -107,14 +107,21 @@ docker run --cap-add IPC_LOCK -e LDR_DB_CONFIG_CIPHER_MEMORY_SECURITY=ON ...### Notification Webhook SSRF-**Outbound notifications via Apprise are disabled by default.** To enable them, the operator must set `LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true` in the server environment. This is intentional: notifications carry a known residual SSRF risk that cannot be fully closed in code, and the env-only gate makes turning them on an explicit operator decision rather than something any logged-in user can flip via the settings API.+**Outbound notifications via Apprise are disabled by default.** To enable them, the operator must set `LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true` in the server environment. This gate is retained as defense-in-depth: the send-time DNS-rebinding window described below is now closed in code, but the env-only gate keeps turning outbound notifications on an explicit operator decision rather than something any logged-in user can flip via the settings API.-#### The residual risk+#### The rebinding window and how it is closed-LDR validates user-configured notification service URLs (`NotificationURLValidator`) before handing them to Apprise. Hostnames are resolved once at validation time and the resulting IPs are checked against private/internal ranges. There is a known **DNS rebinding TOCTOU window** between this check and the actual outbound request:+LDR validates user-configured notification service URLs (`NotificationURLValidator`) before handing them to Apprise. Hostnames are resolved once at validation time and the resulting IPs are checked against private/internal ranges. Apprise (and its underlying `requests`/`urllib3` stack) then resolves the hostname *again* when it sends — a classic **DNS-rebinding resolve-vs-connect TOCTOU**: an attacker controlling a domain could serve a public IP to the validator and a private/metadata IP to Apprise's send-time resolver, reaching internal services on the LDR server (e.g., `127.0.0.1:<internal-port>`) or cloud-metadata (`169.254.169.254`).-- **The window.** Apprise (and its underlying `requests`/`urllib3` stack) resolves the hostname *again* when it sends the notification. A DNS-rebinding attacker controlling a domain can serve a public IP to LDR's validator and a private IP to Apprise's send-time resolver — bypassing the private-IP check and reaching internal services on the LDR server (e.g., `127.0.0.1:<internal-port>`) or the local network. This is exploitable by any logged-in user, not just by the deployment operator.-- **Why it isn't closed in code.** Apprise exposes no Session/adapter/DNS hook. Closing the window would require monkey-patching `requests` inside Apprise's plugin namespace — fragile across Apprise versions, HTTPS-only, and doesn't handle redirects correctly. The blast radius outweighs the benefit.+This window is closed at the socket layer for the delivery path. The deliverable raw-webhook schemes are `json://`, `xml://`, and `form://` (Apprise rejects bare `http(s)://` notification URLs at `add()`, so those never actually deliver); other plugin schemes (`discord://`, `ntfy://`, `gotify://`, …) reach their own hardcoded or self-hosted endpoints.++- **Synchronous, in-thread delivery.** The notification service builds its Apprise instances with `AppriseAsset(async_mode=False)`, so every plugin's `notify()` runs in the sending thread rather than a `ThreadPoolExecutor` worker. This is what lets the thread-local guards below apply to Apprise's own resolution.+- **Redirect-following disabled → the redirect attack class is closed.** The Apprise instances are built with `AppriseAsset(http_redirects=False)`, and each parsed plugin additionally has its `redirects` flag re-forced to `False` after `add()` so a user-supplied `?redirect=yes` query parameter cannot override the default. A user-configured webhook therefore can no longer 30x-redirect the send to a private/loopback host **or** to an arbitrary public host for data exfiltration — the send is simply not redirected. Redirect-following is never needed for legitimate webhook delivery (endpoints answer 2xx directly). Most plugins honour the per-plugin flag (`allow_redirects=self.redirects`), including the raw-webhook `json`/`xml`/`form` schemes and `ntfy`/`gotify`; a few (e.g. `matrix://`) issue their HTTP calls without threading that flag through, so the per-plugin re-force does not reach them — for those the **block-private send window** below is the backstop that still refuses a redirect/rebind to a blocked address at the socket layer.+- **Pin the validated address → the original host's rebind is closed.** Each `notify()` is wrapped in `dns_pinning.pinned_notification_send` (see the general fetch path below), which **pins** every raw-webhook host in the batch to the address just validated. `requests`/`urllib3` cannot then connect to a rebind target: the address validated is the address connected to.+- **Block-private send window.** For the duration of the send a thread-local **block-private** mode also refuses any *unpinned* lookup (a plugin scheme's endpoint) that resolves to a private/loopback/link-local/cloud-metadata address, at the `getaddrinfo` layer before any socket is opened. The check runs on the very resolution the client is about to connect to, so there is no residual race. That send-time resolution is bounded by a timeout so a slow / hostile DNS authority cannot hang the sending thread — a timeout fails closed (refuses the send).+- **Per-scheme policy, matching the validator.** `http`/`https` block private + metadata unless the operator set `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true`; plugin and raw-webhook schemes (`json://`, `xml://`, `form://`, `discord://`, `ntfy://`, `gotify://`, …) allow private/LAN targets (self-hosted notifiers keep working) but **always** block cloud-metadata **and the entire link-local range** (IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`) regardless of any operator flag. The link-local block matters because cloud-provider metadata lives across the whole link-local range, not just the always-blocked literals (e.g. Scaleway serves instance metadata at `169.254.42.42`), and no legitimate self-hosted notifier lives on link-local. It is scoped to the plugin/raw-webhook partition: RFC1918, CGNAT, loopback, and non-link-local IPv6 ULA self-hosted notifiers are unaffected, and `http`/`https` still treats link-local as operator-recoverable via `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS`. It is threaded end-to-end (a `block_link_local` flag on `is_ip_blocked` / `pinned_notification_send` and the validator's plugin-scheme IMDS guard) rather than changing `is_ip_blocked`'s default, so the general fetch/LLM paths keep their existing link-local-under-`allow_private_ips` behaviour. TLS is unaffected: only name resolution is redirected, so SNI and certificate verification still use the original hostname.+- **Fail-closed invariants.** The send is refused (never sent unguarded) if the `getaddrinfo` shim is not the active resolver, or if the Apprise instance is not synchronous, or if a `tag` is supplied — any of which would let delivery fan out to worker threads the thread-local guards do not cover. A confirmed security block is **not retried**: the pin's connect-time rebind catch raises a non-retryable error directly, and a block-private window refusal (which Apprise swallows into a generic delivery failure) is recognised after the failed send via a thread-local marker and re-raised non-retryably — so a hostile / misconfigured destination fails fast in one attempt instead of being retried three times against a slow DNS authority. Invariant violations likewise fail fast.+- **Thread-scoped.** The pin and the block are thread-local, so they only affect the sending thread and can never wrongly block a legitimate private request running concurrently elsewhere.#### How to enable notifications@@ -127,7 +134,7 @@ By setting this, the operator acknowledges the residual risk above. To minimise- **Prefer plugin schemes over raw `http(s)://`.** Apprise plugin schemes (`discord://`, `slack://`, `ntfy://`, `ntfys://`, `gotify://`, `telegram://`, `mattermost://`, `rocketchat://`, `teams://`, `matrix://`, `mailto://`, etc.) hardcode their endpoints internally and have no user-controllable hostname — no SSRF surface. Use them whenever the target service supports them.- **Restrict egress** if private-network exposure is a concern: deploy LDR behind an egress-restricted network so that even a successful rebinding cannot reach internal services.-The general HTTP fetch path (`safe_requests`, used for RAG sources and web scraping) resolves the hostname and connects to that **same** validated address: `security.dns_pinning` pins the resolved IP for the outbound connection (re-resolving and re-validating at connect time, and re-pinning at every redirect hop) so `requests`/`urllib3` cannot connect to a different address than the one the guard checked. The request keeps the original hostname, so TLS SNI and certificate verification are unchanged — only name resolution is pinned. This does not apply to callers that hand a URL to an external client that re-resolves on its own (Apprise above; LLM SDKs — see "LLM Provider URL Validation"); for those, egress restriction remains the primary defense. It also does not apply when `requests` is configured to use a forward proxy (`HTTP(S)_PROXY` / `trust_env`): `urllib3` then resolves the *proxy* host rather than the target, so target-IP selection is delegated to the proxy and the pin is a safe no-op (the pre-connection `validate_url` check still runs).+The general HTTP fetch path (`safe_requests`, used for RAG sources and web scraping) resolves the hostname and connects to that **same** validated address: `security.dns_pinning` pins the resolved IP for the outbound connection (re-resolving and re-validating at connect time, and re-pinning at every redirect hop) so `requests`/`urllib3` cannot connect to a different address than the one the guard checked. The request keeps the original hostname, so TLS SNI and certificate verification are unchanged — only name resolution is pinned. The notification path above reuses this same shim (via `pinned_notification_send`, plus the block-private window for unpinned plugin-endpoint hosts) — but with redirect-following disabled outright rather than validated hop-by-hop, since a notification webhook has no legitimate need to follow redirects. It still does not apply to callers that hand a URL to an external client that re-resolves on its own with no in-thread `getaddrinfo` interception (LLM SDKs — see "LLM Provider URL Validation"); for those, egress restriction remains the primary defense. It also does not apply when `requests` is configured to use a forward proxy (`HTTP(S)_PROXY` / `trust_env`): `urllib3` then resolves the *proxy* host rather than the target, so target-IP selection is delegated to the proxy and the pin is a safe no-op (the pre-connection `validate_url` check still runs).### JS-Rendering Browser Redirect SSRF@@ -152,6 +159,10 @@ A reporter ([@Fushuling](https://github.com/Fushuling), [@RacerZ-fighting](httpsBoth `ssrf_validator.validate_url` and `NotificationURLValidator.validate_service_url` (HTTP/HTTPS branch) carry the fix. Future edits to the SSRF path should preserve `RFC_FORBIDDEN_URL_CHARS_RE` and the `urllib3.util.parse_url` host extraction — reverting either reintroduces the bypass.+**Multiple-`@` authority (notification path).** A related parser differential affects Apprise specifically: for an authority with more than one `@` (e.g. `json://[email protected]@decoy-public.example.com/path`), `urllib3.util.parse_url` — which the notification validator and the DNS pin use — reads the host after the *last* `@` (`decoy-public.example.com`, which validates and gets pinned), while Apprise's own `parse_url` reads `169.254.169.254` and connects there. Because Apprise re-parses and connects independently of the address the guard validated/pinned, `NotificationURLValidator` rejects any notification service URL whose authority (the `urlparse` netloc, so path/query `@`s do not count) contains more than one `@` — fail-closed, before the host is ever extracted. A single `@` (RFC 3986 userinfo, e.g. `mailto://user:pass@host`) is still accepted. This is on the notification path only; the general `safe_requests` path has no such differential because its validator and its HTTP client both use `urllib3`.++**Empty `//`-authority (notification path).** Another Apprise-specific parser differential: for a URL whose `scheme://` authority is empty but with content in the path (e.g. `json:///169.254.169.254/path`), `urllib3`/`requests` see *no host* — so the validator's per-scheme IP check would be skipped and the URL accepted — while Apprise falls back to treating the first path segment as the host and dials it (`169.254.169.254`). `NotificationURLValidator` rejects any notification service URL that carries the `//` authority marker but parses to an empty authority, before host extraction — fail-closed. This fires only when the `//` marker is present, so a scheme that legitimately has no `//` authority is untouched. It is defense-in-depth: the send-time block-private window backstops it (the in-path metadata host still resolves to a blocked address during the send), but rejecting it at validation stops the URL from ever being stored/attempted.+### Cloud Metadata Endpoint Block List`ssrf_validator.ALWAYS_BLOCKED_METADATA_IPS` is a frozenset of cloud-provider metadata IPs that are blocked under every flag combination, including `allow_localhost=True` and `allow_private_ips=True`. These IPs expose IAM / instance-role credentials and are never legitimate destinations for outbound HTTP. The current set is:@@ -163,10 +174,13 @@ Both `ssrf_validator.validate_url` and `NotificationURLValidator.validate_servic| `169.254.170.23` | AWS ECS task metadata v4 || `169.254.0.23` | Tencent Cloud || `100.100.100.200` | AlibabaCloud |+| `fd00:ec2::254` | AWS IMDS over IPv6 |++`fd00:ec2::254` is AWS's native IPv6 instance-metadata endpoint. It is a ULA (`fc00::/7`), **not** an IPv4-mapped or NAT64-wrapped form of `169.254.169.254`, so it is not covered by the IPv4 entries or the NAT64 embedded-IPv4 check above and must be listed explicitly — otherwise it stays reachable under `allow_private_ips=True`, which permits the whole `fc00::/7` range. Entries are matched by canonical string form (`is_ip_blocked` parses the candidate with `ipaddress.ip_address` first), so uppercase / zero-padded / expanded variants all normalise to the listed form before the membership test.-The block also catches IPv6-wrapped forms of these metadata IPs. When an IPv6 destination falls in a NAT64 prefix (`64:ff9b::/96` RFC 6052 well-known or `64:ff9b:1::/48` RFC 8215 local-use), the validator extracts the embedded IPv4 from the low 32 bits and matches it against this set — so `[64:ff9b::a9fe:a9fe]` cannot reach `169.254.169.254` even on a host with NAT64 routes configured. The check fires before any opt-in carve-out, so the operator switch described below cannot license IMDS exposure.+The block also catches IPv6-wrapped forms of the IPv4 metadata IPs. When an IPv6 destination falls in a NAT64 prefix (`64:ff9b::/96` RFC 6052 well-known or `64:ff9b:1::/48` RFC 8215 local-use), the validator extracts the embedded IPv4 from the low 32 bits and matches it against this set — so `[64:ff9b::a9fe:a9fe]` cannot reach `169.254.169.254` even on a host with NAT64 routes configured. The check fires before any opt-in carve-out, so the operator switch described below cannot license IMDS exposure.-Both `ssrf_validator.is_ip_blocked` and `NotificationURLValidator.validate_service_url` enforce this absolutely, including under `allow_private_ips=True`. The latter flag is an operator opt-in for self-hosted webhooks on internal networks (RFC1918, CGNAT, loopback, link-local, IPv6 ULA); it does NOT extend to metadata IPs or NAT64-wrapped metadata. Both validators delegate to the same `is_ip_blocked` helper to keep the absolute-block invariant in lockstep.+Both `ssrf_validator.is_ip_blocked` and `NotificationURLValidator.validate_service_url` enforce this absolutely, including under `allow_private_ips=True`. The latter flag is an operator opt-in for self-hosted webhooks on internal networks (RFC1918, CGNAT, loopback, link-local, IPv6 ULA); it does NOT extend to metadata IPs or NAT64-wrapped metadata. Both validators delegate to the same `is_ip_blocked` helper to keep the absolute-block invariant in lockstep. One scoped exception applies on top of this shared block: the **notification plugin/raw-webhook partition** additionally blocks the *entire* link-local range even under `allow_private_ips=True` (opt-in `block_link_local=True`), because cloud metadata is served across link-local beyond the always-blocked literals — see "Notification Webhook SSRF" above. This is scoped to that partition and does not change `is_ip_blocked`'s default (link-local remains allowed under `allow_private_ips=True` for the general fetch/LLM paths).Future contributors must not remove entries from this set. Adding a new cloud provider's metadata IP is encouraged when a new public-cloud target appears.diff --git a/changelog.d/+pin-notification-send-dns.security.md b/changelog.d/+pin-notification-send-dns.security.mdnew file mode 100644index 0000000000..11e84f3890--- /dev/null+++ b/changelog.d/+pin-notification-send-dns.security.md@@ -0,0 +1,40 @@+Hardened the outbound notification (Apprise) path against send-time DNS+rebinding. Notification service URLs were validated once at configuration+time, but Apprise re-resolves the hostname (and follows redirects) when it+actually sends, so a rebinding host could serve a public address to the+validator and a private/cloud-metadata address to the sender. The delivery+path now runs synchronously in-thread with HTTP redirect-following disabled+(closing redirect-to-internal and redirect-to-exfil outright, even against a+user-supplied `?redirect=yes`) and, for the duration of each send, pins every+raw-webhook host to the address just validated and refuses any unpinned lookup+that resolves to a private/loopback/link-local/cloud-metadata IP — blocking it+at the socket layer before a connection is made. Send-time DNS resolution is+bounded by a timeout (a slow/hostile resolver cannot hang the sending thread),+and the send fails closed if the pinning shim is not the active resolver or if+delivery would fan out to worker threads the thread-local guards do not cover.+Per-scheme policy matches the validator (http/https block private unless opted+in; plugin/self-hosted schemes allow LAN targets but always block+cloud-metadata), the original hostname is kept for TLS SNI and certificate+verification, and the pin/block are thread-local so concurrent requests are+unaffected. The `LDR_NOTIFICATIONS_ALLOW_OUTBOUND` gate remains as defense in+depth.++A follow-up review round closed further gaps: AWS's native IPv6 instance-metadata+endpoint (`fd00:ec2::254`, a ULA that the IPv4 metadata list and the NAT64+embedded-IPv4 check did not cover) is now always blocked, including under the+private-IP opt-in; notification service URLs whose authority contains more than+one `@` are rejected before the host is extracted (the validator/pin parser and+Apprise's own parser pick different hosts for such authorities); a confirmed+send-time SSRF block is now recognised and fails fast in a single attempt+instead of being retried; and the bounded send-time DNS lookup runs on a daemon+thread so a hung hostile resolver can never block graceful process shutdown.++A further round closed a residual and tightened defense in depth: the+notification plugin/raw-webhook partition now blocks the entire link-local range+(IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`) even under the private-IP opt-in —+cloud-provider metadata is served across link-local beyond the always-blocked+literals (e.g. Scaleway's `169.254.42.42`), while self-hosted RFC1918 / loopback /+non-link-local ULA notifiers keep working; and notification URLs with an empty+`//` authority but an in-path host (e.g. `json:///169.254.169.254/path`, where+the validator's parser sees no host but Apprise dials the path segment) are+rejected before host extraction.diff --git a/src/local_deep_research/notifications/service.py b/src/local_deep_research/notifications/service.pyindex 9113d1f2bc..99140c8ed2 100644--- a/src/local_deep_research/notifications/service.py+++ b/src/local_deep_research/notifications/service.py@@ -2,8 +2,10 @@Core notification service using Apprise."""+import contextlib+import functoolsimport re-from typing import Dict, List, Optional, Any+from typing import Dict, List, Optional, Any, Tuplefrom urllib.parse import urlparseimport apprise@@ -12,11 +14,12 @@ from tenacity import (retry,stop_after_attempt,wait_exponential,- retry_if_exception_type,+ retry_if_not_exception_type,)from .exceptions import ServiceError, SendErrorfrom .templates import EventType, NotificationTemplate+from ..security import dns_pinningfrom ..security.url_builder import mask_sensitive_urlfrom ..security.notification_validator import (NotificationURLValidator,@@ -65,14 +68,236 @@ class NotificationService:the operator opts in. See SECURITY.md "NotificationWebhook SSRF" for the rationale."""- self.apprise = apprise.Apprise()+ self.apprise = self._new_apprise()self.allow_private_ips = allow_private_ipsself.outbound_allowed = outbound_allowed+ @staticmethod+ def _new_apprise() -> apprise.Apprise:+ """Create an Apprise instance that delivers synchronously and does+ not follow HTTP redirects.++ ``async_mode=False`` forces Apprise to run every plugin's+ ``notify()`` in the calling thread instead of fanning out to a+ ``ThreadPoolExecutor``. This is required for the SSRF hardening in+ :meth:`_send_with_retry`: the DNS pin and the block-private window+ (``security.dns_pinning``) are thread-local, so they only apply to+ the resolution the sending thread performs. With the default async+ fan-out the plugins would resolve in worker threads that carry no+ pin/block and the guard would silently not apply (verified: the+ default asset resolves target hosts on worker threads).++ ``http_redirects=False`` disables 30x redirect-following for the+ raw-webhook plugins (``json``/``xml``/``form``, which pass+ ``allow_redirects=self.redirects`` to ``requests``). This closes the+ redirect attack class outright: a user-configured webhook can no+ longer 30x-redirect the send to a private/loopback host or to an+ arbitrary public host for data exfiltration. The pin ++ block-private window is then only responsible for the original+ validated host's own rebind, not for chasing redirect hops. It is a+ DEFAULT: a per-URL ``?redirect=yes`` can still override it, so+ :meth:`_disable_redirects` re-forces it off per-plugin after+ ``add()`` (see there).+ """+ return apprise.Apprise(+ asset=apprise.AppriseAsset(async_mode=False, http_redirects=False)+ )++ @staticmethod+ def _disable_redirects(apprise_instance: apprise.Apprise) -> None:+ """Force redirect-following OFF on every added plugin.++ ``_new_apprise`` sets the asset-level ``http_redirects=False``+ default, but Apprise lets a per-URL ``?redirect=yes`` query+ parameter override that default (``self.redirects =+ parse_bool(kwargs.get("redirect", asset.http_redirects))``). A+ low-privilege user could therefore re-enable redirect-following on+ their own webhook and reopen redirect-to-private / redirect-to-exfil.+ Setting ``redirects = False`` directly on each plugin AFTER it is+ parsed makes the closure airtight: the value is read at send time+ (``allow_redirects=self.redirects``), so this wins over any URL+ parameter. Redirect-following is never needed for legitimate+ webhook/plugin delivery (real endpoints answer 2xx directly), so+ this cannot break a genuine send.++ Not every plugin threads ``self.redirects`` into its HTTP call: the+ raw-webhook ``json``/``xml``/``form`` schemes and e.g. ``ntfy`` /+ ``gotify`` honour it, but a few (e.g. ``matrix://``) issue requests+ without it, so re-forcing the flag has no effect there. Those are+ backstopped by the block-private send window+ (``dns_pinning.pinned_notification_send``), which refuses a+ redirect/rebind to a blocked address at the ``getaddrinfo`` layer+ regardless of whether the plugin followed the redirect.+ """+ try:+ servers = list(apprise_instance)+ except TypeError as exc:+ # A mocked Apprise in unit tests is not iterable, so there is+ # nothing to harden (those tests never exercise a real redirect).+ # But if a REAL Apprise ever stops being iterable (upstream API+ # drift), silently returning here would leave the per-plugin+ # redirect-disable un-applied — fail-open. The asset-level+ # ``http_redirects=False`` default and the block-private window+ # still apply, but a per-URL ``?redirect=yes`` could re-enable+ # redirect-following. Log a warning (narrowed to TypeError) so+ # that drift is visible instead of silent.+ logger.warning(+ "Could not enumerate Apprise servers to force "+ "redirect-following off per plugin ({}); relying on the "+ "asset-level default and the block-private window",+ type(exc).__name__,+ )+ return+ for server in servers:+ server.redirects = False++ def _enforce_guarded_send_invariants(+ self, apprise_instance: apprise.Apprise, tag: Optional[str]+ ) -> None:+ """Enforce the fail-closed invariants for a DNS-guarded send.++ The pin + block-private window (``security.dns_pinning``) are+ thread-local and only cover IN-THREAD delivery. Refuse the send+ (fail closed) rather than silently sending unguarded unless:++ * ``async_mode`` is off — otherwise Apprise fans the plugins out to+ worker threads that carry neither the pin nor the block; and+ * ``tag`` is None — a multi-token tag likewise makes Apprise+ dispatch matching plugins across worker threads. No production+ caller passes a tag; this neutralizes a future one.++ Then force redirect-following off per plugin so a per-URL+ ``?redirect=yes`` cannot override the asset-level default.++ Raises:+ RuntimeError: if either invariant is violated (excluded from+ Tenacity retries so it fails fast).+ """+ if getattr(apprise_instance.asset, "async_mode", True) is True:+ raise RuntimeError(+ "Guarded notification send requires async_mode=False; "+ "refusing to send (the thread-local DNS pin/block would not "+ "apply to Apprise's worker-thread fan-out)."+ )+ if tag is not None:+ raise RuntimeError(+ "Guarded notification send does not support tag targeting; "+ "refusing to send (a tag can fan delivery out to worker "+ "threads that bypass the thread-local DNS pin/block)."+ )+ self._disable_redirects(apprise_instance)++ @staticmethod+ def _partition_urls(service_urls: str) -> Tuple[List[str], List[str]]:+ """Split an Apprise URL string into (http(s), everything-else).++ Splits on commas and whitespace — the separators Apprise's own+ ``add()`` accepts — so the partition matches what Apprise will+ actually dispatch. The two groups get different send-time SSRF+ policies (see :meth:`_dispatch`), mirroring the notification+ validator's per-scheme rules: ``http``/``https`` block private IPs+ unless the operator opted in, while plugin / raw-webhook schemes+ allow private (self-hosted LAN) but always block cloud-metadata.++ NOTE: the ``strict`` (``http``/``https``) partition is UNREACHABLE+ for delivery today — Apprise rejects bare ``http(s)://`` notification+ URLs at ``add()`` (verified: ``apprise.Apprise().add("http://x/")``+ is False), so a strict-partition ``add()`` in :meth:`_dispatch`+ returns False and nothing is sent. The stricter policy is retained+ as defense-in-depth for a hypothetical future where a raw ``http(s)``+ scheme becomes deliverable; deliverable webhooks use the raw-webhook+ schemes ``json``/``xml``/``form`` (in the ``lenient`` partition).+ """+ strict: List[str] = []+ lenient: List[str] = []+ for entry in service_urls.replace(",", " ").split():+ entry = entry.strip()+ if not entry:+ continue+ scheme = entry.split(":", 1)[0].lower() if ":" in entry else ""+ if scheme in ("http", "https"):+ strict.append(entry)+ else:+ lenient.append(entry)+ return strict, lenient++ def _guarded_notify(+ self,+ title: str,+ body: str,+ apprise_instance: apprise.Apprise,+ guard_factory=None,+ tag: Optional[str] = None,+ attach: Optional[List[str]] = None,+ ) -> bool:+ """Run a single Apprise ``notify()`` under the DNS-guard and the+ fail-closed invariants. Returns Apprise's raw boolean result.++ Single source of truth for the guarded send: both the retrying+ delivery path (:meth:`_send_with_retry`) and the admin+ "Send Test Notification" path (:meth:`test_service`) call this, so+ neither re-implements the invariant-enforcement / redirect-disable /+ guarded-``notify`` sequence that the SSRF hardening depends on.++ When ``guard_factory`` is provided, the fail-closed invariants are+ enforced (``async_mode`` off, no ``tag``, redirects forced off) and+ the send runs inside the pin + block-private window it returns. The+ per-thread SSRF-block marker is reset first so a block during THIS+ ``notify`` is attributable to it (see+ ``dns_pinning.consume_ssrf_block``). ``None`` sends without a guard.++ Args:+ title: Notification title+ body: Notification body text+ apprise_instance: Apprise instance to use for sending+ guard_factory: Optional zero-arg callable returning a context+ manager wrapped around the ``notify()`` call (the DNS pin ++ block-private window; see ``security.dns_pinning``).+ tag: Optional tag to target specific services+ attach: Optional list of file paths to attach++ Returns:+ True iff Apprise reported the notification delivered.+ """+ if guard_factory is not None:+ # Guarded (user-supplied URL) send: enforce the fail-closed+ # invariants the thread-local pin/block depend on and disable+ # redirects before dispatching, then clear any stale SSRF-block+ # marker so consume_ssrf_block reflects only this attempt.+ self._enforce_guarded_send_invariants(apprise_instance, tag)+ dns_pinning.reset_ssrf_block()++ guard = (+ guard_factory()+ if guard_factory is not None+ else contextlib.nullcontext()+ )++ # Send notification inside the guard so the pin + block-private+ # window (if any) governs Apprise's send-time DNS resolution.+ # ``notify`` is typed ``bool | None``; coerce to a definite bool+ # (None == nothing delivered == False).+ with guard:+ return bool(+ apprise_instance.notify(+ title=title,+ body=body,+ tag=tag,+ attach=attach,+ )+ )+@retry(stop=stop_after_attempt(3),wait=wait_exponential(multiplier=1, min=0.5, max=10),- retry=retry_if_exception_type((Exception,)),+ # Retry transient delivery failures (SendError, connection errors,+ # …) but NOT deliberate security refusals: a ValueError is a+ # connect-time SSRF block (the pin's rebind-to-private/metadata catch,+ # or the block-private window's send-time refusal surfaced below) and+ # a RuntimeError is a fail-closed invariant violation (shim not+ # installed, async_mode/tag guard). A confirmed-malicious or+ # misconfigured destination must fail fast, not be retried 3x.+ retry=retry_if_not_exception_type((ValueError, RuntimeError)),reraise=True,)def _send_with_retry(@@ -80,6 +305,7 @@ class NotificationService:title: str,body: str,apprise_instance: apprise.Apprise,+ guard_factory=None,tag: Optional[str] = None,attach: Optional[List[str]] = None,) -> bool:@@ -87,11 +313,15 @@ class NotificationService:Send a notification using the provided Apprise instance with retry logic.This method is decorated with Tenacity to handle retries automatically.+ A fresh guard context is created per attempt (via ``guard_factory``)+ so retries re-resolve and re-pin.Args:title: Notification titlebody: Notification body textapprise_instance: Apprise instance to use for sending+ guard_factory: Optional zero-arg callable returning the per-send+ DNS guard context (see :meth:`_guarded_notify`).tag: Optional tag to target specific servicesattach: Optional list of file paths to attach@@ -99,24 +329,45 @@ class NotificationService:True if notification was sent successfullyRaises:- SendError: If sending fails after all retry attempts+ SendError: If sending fails after all retry attempts (transient).+ ValueError: If a guarded send failed because the block-private+ window refused a send-time resolution as an SSRF target —+ a confirmed security block, raised non-retryably so it fails+ fast instead of being retried."""logger.debug(f"Sending notification: title='{title[:50]}...', tag={tag}")logger.debug(f"Body preview: {body[:200]}...")- # Send notification- notify_result = apprise_instance.notify(- title=title,- body=body,- tag=tag,- attach=attach,+ notify_result = self._guarded_notify(+ title, body, apprise_instance, guard_factory, tag, attach)if notify_result:logger.debug(f"Notification sent successfully: '{title[:50]}...'")return True++ # A guarded send that failed AND tripped the block-private window is a+ # confirmed SSRF block: the window raised socket.gaierror on a+ # send-time resolution to an internal/private/metadata IP, which+ # Apprise swallowed into a generic delivery failure. Fail fast — raise+ # a non-retryable ValueError (excluded from the retry predicate above)+ # instead of a retryable SendError, so a confirmed-malicious /+ # misconfigured destination is not retried 3x (~10s and 3x DNS to a+ # hostile authority). The pin path's own rebind catch already raises+ # ValueError before this point; this covers the UNPINNED block-window+ # path (plugin-scheme endpoints, unresolvable-at-pin-time hosts).+ if guard_factory is not None and dns_pinning.consume_ssrf_block():+ logger.warning(+ "Notification send blocked by the SSRF block-private window; "+ "failing fast (not retrying)"+ )+ raise ValueError(+ "Notification send refused: a send-time DNS resolution was "+ "blocked as internal/private/metadata (possible SSRF)"+ )+error_msg = "Failed to send notification to any service"logger.warning(error_msg)raise SendError(error_msg)@@ -184,29 +435,38 @@ class NotificationService:raise ServiceError(f"Invalid service URL: {error_msg}")try:- # If service_urls are provided, create a new Apprise instance+ # If service_urls are provided, partition them by scheme and+ # dispatch each group with its own SSRF send-time guard.if service_urls:- temp_apprise = apprise.Apprise()- result = temp_apprise.add(service_urls, tag=tag)-- if not result:+ strict_urls, lenient_urls = self._partition_urls(service_urls)+ if not strict_urls and not lenient_urls:logger.error(- f"Failed to add service URLs to Apprise: "+ f"No service URLs after parsing: "f"{mask_sensitive_url(service_urls)}")return False-- # Send notification with the temp instance (with retry)- return self._send_with_retry(- title, body, temp_apprise, tag, attach+ return self._dispatch(+ title, body, strict_urls, lenient_urls, tag, attach)- # Use the configured apprise instance+ # The pre-configured instance (self.apprise) is created empty in+ # __init__ and is never populated by this class — all delivery+ # goes through the guarded per-call service_urls path above.if len(self.apprise) == 0:logger.debug("No notification services configured in Apprise")return False- # Send notification (with retry)- return self._send_with_retry(title, body, self.apprise, tag, attach)+ # Defense-in-depth: if a future caller ever adds URLs directly to+ # self.apprise, refuse rather than deliver them here — this branch+ # has no DNS pin / block-private guard, so sending would silently+ # bypass the SSRF hardening the service_urls path enforces. Fail+ # closed. See SECURITY.md "Notification Webhook SSRF".+ logger.error(+ "Refusing to send via the pre-configured Apprise instance: "+ "it is populated but this path is unguarded. Pass "+ "service_urls to send() so the DNS pin / block-private guard "+ "applies."+ )+ return Falseexcept Exception as e:# Tenacity will retry, but if all retries fail, raise SendError@@ -215,6 +475,89 @@ class NotificationService:)raise SendError(f"Failed to send notification: {str(e)}")+ def _dispatch(+ self,+ title: str,+ body: str,+ strict_urls: List[str],+ lenient_urls: List[str],+ tag: Optional[str],+ attach: Optional[List[str]],+ ) -> bool:+ """Send each scheme-partition under its SSRF send-time guard.++ ``strict_urls`` (http/https): pin each host and block private ++ metadata resolution for the send (honoring the operator+ ``allow_private_ips`` opt-in) — closes rebinding and+ redirect-to-internal.++ ``lenient_urls`` (plugin / raw-webhook schemes): pin the raw-webhook+ hosts (json/xml/form) and block cloud-metadata AND the whole+ link-local range (``allow_private_ips=True`` + ``block_link_local=True``)+ — self-hosted LAN targets (RFC1918 / loopback / non-link-local ULA)+ keep working while a send-time rebind/redirect to a metadata or+ link-local IP is refused. This mirrors the notification validator's+ per-scheme policy exactly.++ Each non-empty partition is dispatched (and retried by Tenacity)+ under its own guard. A partition that adds no URLs returns False+ (matching the historical add-failure behavior); a partition that+ fails to deliver after all retries raises ``SendError`` (which the+ caller re-wraps), so overall success requires every partition to+ deliver.+ """+ partitions = []+ if strict_urls:+ partitions.append(+ (+ strict_urls,+ lambda: dns_pinning.pinned_notification_send(+ strict_urls,+ allow_localhost=False,+ allow_private_ips=self.allow_private_ips,+ ),+ )+ )+ if lenient_urls:+ partitions.append(+ (+ lenient_urls,+ lambda: dns_pinning.pinned_notification_send(+ lenient_urls,+ allow_localhost=False,+ allow_private_ips=True,+ # Plugin/raw-webhook schemes allow private LAN targets+ # but NOT link-local: cloud-provider metadata lives+ # there beyond the always-blocked literals (e.g.+ # some providers' IMDS) and no legitimate self-hosted+ # notifier does. Mirrors the validator's plugin-scheme+ # IMDS guard.+ block_link_local=True,+ ),+ )+ )++ any_ok = False+ for urls, guard_factory in partitions:+ temp_apprise = self._new_apprise()+ # apprise types ``add(servers=...)`` as an invariant ``list`` whose+ # element union includes ``str``; a ``list[str]`` is valid at+ # runtime but mypy rejects it on list invariance (upstream should+ # use ``Sequence``).+ if not temp_apprise.add(urls, tag=tag): # type: ignore[arg-type]+ logger.error(+ f"Failed to add service URLs to Apprise: "+ f"{mask_sensitive_url(' '.join(urls))}"+ )+ return False+ # _send_with_retry returns True or raises SendError after+ # Tenacity exhausts its retries; a raise propagates to send().+ self._send_with_retry(+ title, body, temp_apprise, guard_factory, tag, attach+ )+ any_ok = True+ return any_ok+def send_event(self,event_type: EventType,@@ -331,8 +674,9 @@ class NotificationService:"error": user_error,}- # Create temporary Apprise instance- temp_apprise = apprise.Apprise()+ # Create temporary Apprise instance (synchronous so the pin ++ # block-private window below applies in this thread).+ temp_apprise = self._new_apprise()add_result = temp_apprise.add(url)if not add_result:@@ -341,13 +685,40 @@ class NotificationService:"error": "Failed to add service URL",}- # Send test notification- result = temp_apprise.notify(- title="Test Notification",- body=(+ # Send the test through the SAME guarded dispatch core as the real+ # send path (:meth:`_guarded_notify`) — fail-closed invariants,+ # per-plugin redirect-disable, and the pin + block-private window+ # — instead of re-implementing it here. Single-shot (no Tenacity+ # retry) for fast test feedback. allow_private_ips mirrors the+ # validator's per-scheme policy: the operator flag for http/https,+ # True (metadata-only) for plugin / raw-webhook schemes. tag is+ # always None here.+ scheme = url.strip().split(":", 1)[0].lower() if ":" in url else ""+ is_plugin_scheme = scheme not in ("http", "https")+ allow_private = (+ self.allow_private_ips if not is_plugin_scheme else True+ )+ # Plugin/raw-webhook schemes run with allow_private_ips=True but+ # must still block the whole link-local range (metadata territory+ # beyond the always-blocked literals). Mirrors _dispatch's lenient+ # partition and the validator's plugin-scheme IMDS guard.+ guard_factory = functools.partial(+ dns_pinning.pinned_notification_send,+ [url.strip()],+ allow_localhost=False,+ allow_private_ips=allow_private,+ block_link_local=is_plugin_scheme,+ )++ result = self._guarded_notify(+ "Test Notification",+ ("This is a test notification from Local Deep Research. ""If you see this, your service is configured correctly!"),+ temp_apprise,+ guard_factory,+ tag=None,)if result:@@ -355,6 +726,33 @@ class NotificationService:"success": True,"message": "Test notification sent successfully",}++ # A guarded test send that failed AND tripped the block-private+ # window is a confirmed SSRF block: the window raised+ # socket.gaierror on a send-time resolution to an+ # internal/private/metadata IP, which Apprise swallowed into a+ # generic delivery failure. Surface the specific reason to the+ # admin instead of the generic message — mirrors the+ # consume_ssrf_block short-circuit in _send_with_retry. (The pin+ # path's own connect-time rebind catch raises ValueError before+ # this point and is reported via the except below; this covers the+ # UNPINNED block-window path — plugin-scheme endpoints and+ # unresolvable-at-pin-time hosts.)+ if dns_pinning.consume_ssrf_block():+ logger.warning(+ "Test notification blocked by the SSRF block-private "+ "window (send-time resolution to internal/private/"+ "metadata)"+ )+ return {+ "success": False,+ "error": (+ "Test notification refused: the destination resolved "+ "to an internal/private/metadata address at send time "+ "(possible SSRF). See SECURITY.md 'Notification "+ "Webhook SSRF'."+ ),+ }return {"success": False,"error": "Failed to send test notification",diff --git a/src/local_deep_research/security/dns_pinning.py b/src/local_deep_research/security/dns_pinning.pyindex 9094347518..13949bd16c 100644--- a/src/local_deep_research/security/dns_pinning.py+++ b/src/local_deep_research/security/dns_pinning.py@@ -36,6 +36,24 @@ Why a ``getaddrinfo`` shim rather than a custom ``HTTPAdapter``:``security/egress`` ``socket.connect`` audit hook, which also installs aprocess-wide, thread-local-gated interposition.+The outbound-notification path (Apprise) reuses the same shim through+:func:`pinned_notification_send`. Apprise fans out to arbitrary user URLs+via ``requests``/``urllib3`` and re-resolves at send time — the exact+resolve-vs-connect gap the shim closes — but it also follows redirects and+can be pointed at a *new*, unpinned host. So the notification window pins+every raw-webhook host in the batch AND activates a thread-local+"block-private" mode (:func:`block_private_resolution`): for its duration,+any UNPINNED lookup that resolves to a private/loopback/link-local/+cloud-metadata address is refused at the ``getaddrinfo`` layer (a+``socket.gaierror``), so a redirect-to-internal is blocked at the socket+layer before a connection is made. Public unpinned hosts resolve normally.+The block is thread-local, so it only affects the sending thread and can+never wrongly block a legitimate private request running concurrently in+another thread. It is activated only after Apprise is forced into+synchronous, in-thread delivery (``AppriseAsset(async_mode=False)``); with+the default async fan-out the send would run in worker threads that carry+no thread-local pin/block and the guard would silently not apply.+Import-order dependency: the pin only works while ``socket.getaddrinfo``is still THIS module's shim. If something replaces ``socket.getaddrinfo``wholesale AFTER this module is imported — e.g. ``gevent``/``eventlet``@@ -101,8 +119,61 @@ _real_getaddrinfo = _capture_real_getaddrinfo()# host (normalized) -> list of addrinfo 5-tuples that are safe to connect# to. Thread-local so concurrent fetches in different worker threads cannot# see one another's pins.+#+# The same thread-local also carries an optional ``block_private`` entry —+# a ``(allow_localhost, allow_private_ips, block_link_local)`` tuple set by+# :func:`block_private_resolution`. While present, every UNPINNED lookup on+# this thread is resolved and re-checked against the SSRF policy, and a+# result containing any blocked (private/loopback/link-local/metadata)+# address is refused. See :func:`_resolve_maybe_block`._thread_state = threading.local()+# Schemes whose URL host is a real, resolvable connection target that the+# client will connect to verbatim — so pinning the validated address is both+# possible and worthwhile. These are the raw-webhook Apprise schemes+# (``json``/``xml``/``form`` and their TLS variants) plus plain+# ``http``/``https``.+#+# Every OTHER reachable Apprise scheme is deliberately excluded from pinning,+# for one of two reasons — but both remaining kinds are still resolve-time+# block-checked by the block-private window (:func:`block_private_resolution`),+# so excluding them from pinning never leaves a cloud-metadata hole:+#+# * Token-host schemes (``discord://``, ``slack://``, ``tgram://`` …) put an+# opaque credential/token in ``parse_url``'s host field, not a hostname.+# Pinning would try to resolve that token as a name and break the send;+# these plugins POST to their own hardcoded public API endpoints anyway.+# * Self-hosted plugin schemes (``gotify://``, ``ntfy(s)://``, ``mattermost://``,+# ``matrix://``, ``rocketchat://``, ``teams://`` …) DO carry a real,+# resolvable host — the "opaque token" description does not apply to them.+# They are left unpinned because their per-plugin URL→endpoint mapping is+# plugin-specific (path/port rewriting) rather than a plain connect to the+# URL host, and because their partition intentionally allows private/LAN+# targets: the block-private window (metadata-only for this partition) is+# the right guarantee for them, and pinning would add complexity without+# changing the metadata outcome.+#+# This block-window guarantee holds only for schemes whose network I/O resolves+# through the shimmed ``socket.getaddrinfo`` — which every scheme reachable+# today does (they send via ``requests``/``urllib3`` or ``smtplib``, both of+# which call ``getaddrinfo``). Which schemes can reach this send path at all is+# gated upstream by ``NotificationURLValidator.ALLOWED_SCHEMES``; a scheme that+# connects via a primitive the shim cannot see (e.g. a raw ``socket.sendto``+# datagram, as Apprise's ``rsyslog://`` uses) would bypass BOTH the pin and the+# block window, so such a scheme must never be added to that allowlist.+_PINNABLE_SCHEMES = frozenset(+ {+ "http",+ "https",+ "json",+ "jsons",+ "xml",+ "xmls",+ "form",+ "forms",+ }+)+_installed = False@@ -125,6 +196,22 @@ def _normalize_host(host: Optional[str]) -> Optional[str]:return host or None+def _host_for_log(host) -> str:+ """Best-effort text form of a host for a log message.++ ``getaddrinfo`` accepts a ``bytes``/``bytearray`` host as well as a+ ``str``; decode one to text so the block-window warning reads cleanly.+ Decoding is for the log line only — the SSRF check runs on resolved IPs,+ never on the host string — so it must never raise: ``surrogateescape``+ round-trips any byte sequence. (The ``idna`` codec is deliberately NOT+ used here: it does not support an error handler and raises on non-hostname+ bytes.)+ """+ if isinstance(host, (bytes, bytearray)):+ return bytes(host).decode("utf-8", errors="surrogateescape")+ return str(host)++def _get_pins() -> dict:pins = getattr(_thread_state, "pins", None)if pins is None:@@ -133,6 +220,89 @@ def _get_pins() -> dict:return pins+def reset_ssrf_block() -> None:+ """Clear the per-thread "an SSRF block occurred" marker.++ Called before a guarded ``notify()`` so :func:`consume_ssrf_block`+ reflects only that attempt. See :func:`_resolve_maybe_block`.+ """+ _thread_state.ssrf_block_occurred = False+++def consume_ssrf_block() -> bool:+ """Return whether the block-private window refused a lookup on this+ thread since the last :func:`reset_ssrf_block`, and clear the marker.++ Apprise swallows the ``socket.gaierror`` the block raises inside its+ plugin, surfacing only a generic delivery failure. The sender+ (``notifications.service._send_with_retry``) consults this after a failed+ send to tell a confirmed security block apart from a transient error, so+ the block can fail fast instead of being retried 3x.+ """+ occurred = getattr(_thread_state, "ssrf_block_occurred", False)+ _thread_state.ssrf_block_occurred = False+ return bool(occurred)+++# Send-time DNS resolution is bounded so a slow / hostile DNS authority+# cannot hang the sending thread — which, on the notification path, is an+# HTTP request handler (test_service is reached straight from the "Send Test+# Notification" endpoint). Mirrors+# ``notification_validator._resolve_hostname_ips``.+_RESOLVE_TIMEOUT_SECONDS = 5+++def _getaddrinfo_bounded(host, port, family, type, proto, flags):+ """Call the genuine resolver with a bounded timeout; fail closed.++ Runs ``_real_getaddrinfo`` on a short-lived DAEMON thread (thread-safe+ timeout, no ``socket.setdefaulttimeout`` process-global mutation) so a+ hostile DNS authority that never answers cannot block the caller past+ ``_RESOLVE_TIMEOUT_SECONDS``. On timeout a ``socket.gaierror`` is raised+ — the lookup is REFUSED, never returned as a blank/partial answer a+ caller might treat as "resolved" — so the timeout can only ever fail+ closed. A resolution error raised by the resolver itself+ (``socket.gaierror`` / ``OSError``) propagates unchanged.++ The worker is a DAEMON thread deliberately: a ``getaddrinfo`` call that+ hangs in C cannot be cancelled, and a non-daemon worker (as a+ ``concurrent.futures`` pool thread is) would be joined by the interpreter+ at shutdown — letting an in-flight hostile lookup block graceful process+ exit / restart. A daemon worker is abandoned on timeout and never blocks+ interpreter exit.+ """+ result: dict = {}++ def _worker() -> None:+ try:+ result["value"] = _real_getaddrinfo(+ host, port, family, type, proto, flags+ )+ except BaseException as exc: # noqa: BLE001 - propagated to caller+ result["error"] = exc++ worker = threading.Thread(+ target=_worker,+ name="ldr-dns-pin-resolve",+ daemon=True,+ )+ worker.start()+ worker.join(_RESOLVE_TIMEOUT_SECONDS)+ if worker.is_alive():+ # Timed out. The daemon worker is abandoned (it dies with the+ # process) and the lookup is refused — fail closed.+ raise socket.gaierror(+ getattr(socket, "EAI_AGAIN", socket.EAI_FAIL),+ f"DNS resolution for {host!r} timed out after "+ f"{_RESOLVE_TIMEOUT_SECONDS}s during a pinned send (fail closed)",+ )+ if "error" in result:+ # Re-raise the resolver's own error unchanged (e.g. gaierror for+ # NXDOMAIN) so existing gaierror/OSError handling stays intact.+ raise result["error"]+ return result["value"]++def _pinned_getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):"""Process-wide ``socket.getaddrinfo`` replacement.@@ -184,7 +354,76 @@ def _pinned_getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):getattr(socket, "EAI_ADDRFAMILY", socket.EAI_FAIL),"No pinned address for the requested family/socktype",)- return _real_getaddrinfo(host, port, family, type, proto, flags)+ # Not pinned. Delegate to the real resolver, but if a block-private+ # window is active on this thread, refuse any answer that resolves to a+ # blocked address (redirect-to-internal / rebind-to-metadata guard).+ return _resolve_maybe_block(host, port, family, type, proto, flags)+++def _resolve_maybe_block(host, port, family, type, proto, flags):+ """Real resolution for an unpinned host, honoring the block window.++ When no block-private window is active this is a transparent+ pass-through to the genuine resolver — with NO added timeout/thread+ overhead, so ordinary process-wide DNS is completely unaffected by the+ shim. When a window IS active (set by :func:`block_private_resolution`,+ i.e. during a notification send), the resolution is (a) bounded by a+ timeout so a slow / hostile DNS authority cannot hang the sending thread+ (fail closed — a timeout refuses the lookup, it never returns a blank+ answer), and (b) the resolved addresses are checked against the SSRF+ policy and the lookup is refused with ``socket.gaierror`` if ANY of them+ is blocked — closing a redirect-to-internal or rebind-to-metadata that+ targets a host that was never pinned. The check runs on the SAME address+ list the caller will connect to (this IS the ``getaddrinfo`` the client+ uses), so there is no second resolution to race against.+ """+ block = getattr(_thread_state, "block_private", None)+ if block is None:+ # No window active: transparent, zero-overhead pass-through.+ return _real_getaddrinfo(host, port, family, type, proto, flags)+ # Window active — bound the resolution (send path) and fail closed on a+ # timeout by letting the gaierror propagate to the client.+ results = _getaddrinfo_bounded(host, port, family, type, proto, flags)+ # A ``None`` host is an AF_PASSIVE bind+ # (``getaddrinfo(None, port, ..., AI_PASSIVE)`` — a local listening-socket+ # setup, not an outbound name to rebind), so it carries no attacker-+ # controllable destination and is exempt from the block check. EVERY other+ # host is checked, INCLUDING a ``bytes``/``bytearray`` host: ``getaddrinfo``+ # accepts a bytes name and a bytes host (e.g. ``b"169.254.169.254"``)+ # resolves to metadata/link-local exactly as a ``str`` host would, so+ # returning it unchecked would be the one guard that fails OPEN. The check+ # itself runs on the resolved IPs regardless of the host type — only the+ # log line needs a text host, so a bytes host is decoded for display.+ if host is None:+ return results+ host_display = _host_for_log(host)+ allow_localhost, allow_private_ips, block_link_local = block+ for info in results:+ ip_str = str(info[4][0])+ if ssrf_validator.is_ip_blocked(+ ip_str,+ allow_localhost=allow_localhost,+ allow_private_ips=allow_private_ips,+ block_link_local=block_link_local,+ ):+ logger.warning(+ "Blocked send-time resolution of {} to internal/private/"+ "metadata IP {} during the pinned notification window "+ "(possible SSRF / redirect-to-internal)",+ host_display,+ ip_str,+ )+ # Mark the thread so the sender can tell this confirmed security+ # block apart from a transient failure once Apprise has swallowed+ # the gaierror below — a confirmed block must fail fast, not be+ # retried. Consumed by ``consume_ssrf_block``.+ _thread_state.ssrf_block_occurred = True+ raise socket.gaierror(+ getattr(socket, "EAI_FAIL", -1),+ "Blocked resolution to an internal/private/metadata IP "+ "during the pinned notification send window",+ )+ return results# Stamp our shim so a later capture (e.g. after ``importlib.reload``) can tell@@ -208,52 +447,94 @@ def install() -> None:global _installedif _installed:return- # A reload resets ``_installed`` to False, so also refuse to reinstall- # when our shim is already the active resolver. Combined with the capture- # guard above, this keeps a reload from ever chaining shim-onto-shim.- if not getattr(socket.getaddrinfo, _SHIM_MARKER, False):+ # Install our shim unless it is ALREADY EXACTLY this module's shim+ # (identity check, not just the marker). A reload resets ``_installed`` to+ # False and rebuilds ``_pinned_getaddrinfo`` as a fresh function object,+ # while ``socket.getaddrinfo`` still points at the PREVIOUS load's shim —+ # a stale, marker-stamped resolver whose thread-local reads live in the+ # old module. Reinstalling here keeps ``socket.getaddrinfo`` in lockstep+ # with the reloaded module so ``_shim_installed()`` — the invariant the+ # notification send fails closed on — holds after a reload, instead of+ # silently reporting the shim as missing forever.+ #+ # This cannot chain shim-onto-shim: ``_real_getaddrinfo`` is captured via+ # ``_capture_real_getaddrinfo``, which never returns a shim, so the newly+ # installed shim's pass-through calls the genuine resolver, not the old+ # shim.+ if socket.getaddrinfo is not _pinned_getaddrinfo:socket.getaddrinfo = _pinned_getaddrinfo_installed = True-def _extract_host(url: Optional[str]) -> Tuple[Optional[str], bool]:- """Return ``(normalized_host, is_ip_literal)`` for ``url``.+def _shim_installed() -> bool:+ """True iff THIS module's shim is still the active ``getaddrinfo``.++ The pin and block-private guarantees only hold while+ ``socket.getaddrinfo`` is exactly this module's ``_pinned_getaddrinfo``:+ the thread-local pin/block state lives here, so a wholesale replacement+ after import (``gevent``/``eventlet`` monkeypatch, another socket shim,+ or a stale post-reload shim) would consult different state and silently+ drop the guard. The check is strict identity — a *different* shim, even+ one stamped with our marker, does not satisfy it because it would read a+ different ``_thread_state``. Callers on the send path treat a False here+ as fail-closed rather than sending unguarded.+ """+ return socket.getaddrinfo is _pinned_getaddrinfo+++def _extract_scheme_host(+ url: Optional[str],+) -> Tuple[Optional[str], Optional[str], bool]:+ """Return ``(scheme, normalized_host, is_ip_literal)`` for ``url``.- ``host`` is ``None`` when the URL is empty or the parser rejects it.- Uses ``urllib3.util.parse_url`` — the same parser ``requests`` uses+ ``scheme`` is lower-cased (``None`` when absent). ``host`` is ``None``+ when the URL is empty or the parser rejects it. Uses+ ``urllib3.util.parse_url`` — the same parser ``requests`` usesinternally and the same one ``ssrf_validator.validate_url`` validatesagainst — so the host we pin is the host the client will resolve."""if not url:- return None, False+ return None, None, Falsetry:parsed = parse_url(url)except (LocationParseError, ValueError):- return None, False+ return None, None, False+ scheme = (parsed.scheme or "").lower() or Nonehost = _normalize_host(parsed.host)if host is None:- return None, False+ return scheme, None, Falsetry:ipaddress.ip_address(host)- return host, True # IP literal — no DNS to rebind+ return scheme, host, True # IP literal — no DNS to rebindexcept ValueError:- return host, False+ return scheme, host, False+++def _extract_host(url: Optional[str]) -> Tuple[Optional[str], bool]:+ """Return ``(normalized_host, is_ip_literal)`` for ``url``.++ Thin wrapper over :func:`_extract_scheme_host` for callers that don't+ need the scheme (e.g. :func:`pinned_request`).+ """+ _scheme, host, is_literal = _extract_scheme_host(url)+ return host, is_literaldef _resolve_and_validate(host: str,allow_localhost: bool,allow_private_ips: bool,+ block_link_local: bool = False,) -> List[tuple]:"""Resolve ``host`` once and validate every returned address.Uses the real resolver (never the shim, to avoid recursion and toignore any pin) and applies exactly the ``is_ip_blocked`` policy that``validate_url`` applies — honoring ``allow_localhost`` /- ``allow_private_ips`` while the ``ALWAYS_BLOCKED_METADATA_IPS`` set- keeps firing regardless. This is the connect-time re-validation that- the pin adds: an answer that changed since ``validate_url`` ran is- caught here.+ ``allow_private_ips`` (and ``block_link_local`` for the notification+ path) while the ``ALWAYS_BLOCKED_METADATA_IPS`` set keeps firing+ regardless. This is the connect-time re-validation that the pin adds: an+ answer that changed since ``validate_url`` ran is caught here.Returns the addrinfo list to pin (all entries validated safe).@@ -261,12 +542,14 @@ def _resolve_and_validate(ValueError: if any resolved address is blocked. SSRF-style messageso existing callers/tests catch it uniformly.requests.ConnectionError: if the host no longer resolves at pin- time — fail closed as an ordinary transport error so the- existing retry / ``RequestException`` handling stays intact.+ time, OR if resolution times out (a slow / hostile DNS authority+ cannot hang the send) — fail closed as an ordinary transport+ error so the existing retry / ``RequestException`` handling stays+ intact."""try:- addr_info = _real_getaddrinfo(- host, None, socket.AF_UNSPEC, socket.SOCK_STREAM+ addr_info = _getaddrinfo_bounded(+ host, None, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, 0)except socket.gaierror as exc:raise requests.ConnectionError(@@ -283,6 +566,7 @@ def _resolve_and_validate(ip_str,allow_localhost=allow_localhost,allow_private_ips=allow_private_ips,+ block_link_local=block_link_local,):logger.warning("Blocked connect-time address for host {}: resolves to "@@ -345,6 +629,175 @@ def pinned_request(pins.pop(host, None)+def block_private_resolution(+ allow_localhost: bool = False,+ allow_private_ips: bool = False,+ block_link_local: bool = False,+) -> Iterator[None]:+ """Refuse UNPINNED lookups that resolve to a blocked address.++ While this context is active on the calling thread, any host that is+ NOT covered by an active pin and resolves to a private / loopback /+ link-local / cloud-metadata address (per ``ssrf_validator.is_ip_blocked``+ with the supplied flags) is refused at the ``getaddrinfo`` layer with a+ ``socket.gaierror``. Pinned hosts are unaffected (they short-circuit to+ their validated addresses), and public unpinned hosts resolve normally.++ ``block_link_local`` (notification lenient partition): when True, the+ whole link-local range stays refused even under ``allow_private_ips=True``+ — closing metadata reachable in link-local beyond the always-blocked+ literals (e.g. Scaleway ``169.254.42.42``) without over-blocking RFC1918 /+ loopback / non-link-local ULA self-hosted notifiers.++ This closes redirect-to-internal / rebind-to-metadata for hosts that+ were never pinned (e.g. a webhook that 302-redirects to+ ``169.254.169.254`` or ``127.0.0.1``): the block runs on the very+ resolution the client is about to connect to, so there is no window to+ race.++ Thread-local: only the calling thread is affected, so a legitimate+ private request in another thread is never disturbed. Windows nest+ (inner replaces outer, restored on exit).+ """+ prev = getattr(_thread_state, "block_private", None)+ _thread_state.block_private = (+ allow_localhost,+ allow_private_ips,+ block_link_local,+ )+ try:+ yield+ finally:+ _thread_state.block_private = prev+++def pin_hosts(+ urls,+ allow_localhost: bool = False,+ allow_private_ips: bool = False,+ block_link_local: bool = False,+) -> Iterator[None]:+ """Pin the validated address of every pinnable host in ``urls``.++ For each URL whose scheme is in :data:`_PINNABLE_SCHEMES` and whose host+ is a real (non-literal) name, resolves once, validates every returned+ address against the SSRF policy, and pins those addresses for the+ duration of the context. IP literals, token-host plugin schemes, and+ unparseable URLs are skipped (nothing to rebind, or the host is not a+ resolvable name). A host that fails to resolve right now is also skipped+ rather than aborting the whole batch — it is left unpinned so the+ accompanying block-private window still governs its send-time lookup and+ Apprise fails only that one URL.++ ``block_link_local`` is forwarded to the connect-time validation so a+ raw-webhook host that resolves into link-local (metadata territory) is+ refused even under ``allow_private_ips=True`` (notification lenient+ partition).++ Raises:+ ValueError: if a pinnable host resolves to a blocked address (the+ batch is refused — fail closed).+ """+ pins = _get_pins()+ saved: List[Tuple[str, bool, Optional[list]]] = []+ pinned_now = set()+ try:+ for url in urls:+ scheme, host, is_literal = _extract_scheme_host(url)+ if scheme not in _PINNABLE_SCHEMES:+ continue+ if host is None or is_literal or host in pinned_now:+ continue+ try:+ entry = _resolve_and_validate(+ host,+ allow_localhost,+ allow_private_ips,+ block_link_local=block_link_local,+ )+ except requests.ConnectionError:+ logger.debug(+ "Skipping pin for currently-unresolvable host {}", host+ )+ continue+ saved.append((host, host in pins, pins.get(host)))+ pins[host] = entry+ pinned_now.add(host)+ yield+ finally:+ for host, had_previous, previous in reversed(saved):+ if had_previous:+ pins[host] = previous+ else:+ pins.pop(host, None)+++def pinned_notification_send(+ urls,+ allow_localhost: bool = False,+ allow_private_ips: bool = False,+ block_link_local: bool = False,+) -> Iterator[None]:+ """Guard a single in-thread Apprise ``notify()`` over ``urls``.++ Combines :func:`pin_hosts` (pin every raw-webhook host in the batch to+ its validated address) with :func:`block_private_resolution` (refuse any+ unpinned lookup — a redirect target or a token-scheme endpoint — that+ resolves to a blocked address). Both are thread-local, so the caller+ MUST run the ``notify()`` synchronously in this thread+ (``AppriseAsset(async_mode=False)``); an async fan-out would resolve in+ worker threads that carry neither the pin nor the block.++ ``allow_private_ips`` mirrors the notification validator's per-scheme+ policy: pass the operator flag for ``http``/``https`` batches (private+ blocked unless opted in) and ``True`` for the plugin/raw-webhook batch+ (private allowed, cloud-metadata still always blocked).++ ``block_link_local`` should be ``True`` for the plugin/raw-webhook batch+ (which runs with ``allow_private_ips=True``) so the whole link-local+ range stays blocked there — cloud-provider metadata lives in link-local+ beyond the always-blocked literals, and no legitimate self-hosted+ notifier does. It is forwarded to both the pin's connect-time validation+ and the block-private window.++ Raises:+ RuntimeError: if the ``getaddrinfo`` shim is not the active resolver+ (see :func:`_shim_installed`). The pin/block cannot be+ guaranteed in that state, so the send is REFUSED (fail closed)+ rather than proceeding unguarded.+ """+ # Fail closed if our shim is not installed: without it the pin registry+ # and the block-private window are never consulted, so proceeding would+ # send completely unguarded (silent fail-open). Refuse instead.+ if not _shim_installed():+ raise RuntimeError(+ "DNS pin shim is not the active socket.getaddrinfo; refusing the "+ "notification send (fail closed). The resolve-vs-connect pin and "+ "block-private window cannot be guaranteed — see "+ "security.dns_pinning."+ )+ with contextlib.ExitStack() as stack:+ stack.enter_context(+ pin_hosts(+ urls,+ allow_localhost,+ allow_private_ips,+ block_link_local=block_link_local,+ )+ )+ stack.enter_context(+ block_private_resolution(+ allow_localhost,+ allow_private_ips,+ block_link_local=block_link_local,+ )+ )+ yield++# Install on import: safe_requests imports this module, so the shim is in# place before any fetch. Transparent until a pin is active.install()diff --git a/src/local_deep_research/security/notification_validator.py b/src/local_deep_research/security/notification_validator.pyindex 743068810d..3e551b952f 100644--- a/src/local_deep_research/security/notification_validator.py+++ b/src/local_deep_research/security/notification_validator.py@@ -76,7 +76,10 @@ class NotificationURLValidator:@staticmethoddef _ip_matches_blocked_range(- ip, allow_private_ips: bool = False, allow_nat64: Optional[bool] = None+ ip,+ allow_private_ips: bool = False,+ allow_nat64: Optional[bool] = None,+ block_link_local: bool = False,) -> bool:"""Block-decision for a parsed IP, delegating to``ssrf_validator.is_ip_blocked`` so the two validators share a@@ -93,6 +96,11 @@ class NotificationURLValidator:above still fire. This closes the historical bypass where``allow_private_ips=True`` skipped the host check entirelyand let metadata IPs through the notification path.+ - block_link_local: when True, the whole link-local range+ (169.254.0.0/16, fe80::/10) stays blocked even under+ allow_private_ips=True. Used by the plugin-scheme IMDS guard so+ metadata reachable in link-local beyond the always-blocked+ literals cannot slip through the lenient partition."""from .ssrf_validator import is_ip_blocked@@ -100,6 +108,7 @@ class NotificationURLValidator:str(ip),allow_private_ips=allow_private_ips,allow_nat64=allow_nat64,+ block_link_local=block_link_local,)@staticmethod@@ -117,31 +126,43 @@ class NotificationURLValidator:"""# NOTE: best-effort, validation-time check. Apprise re-resolves# the hostname when it actually sends the request (via- # requests/urllib3), so an attacker controlling DNS can serve a- # public IP here and a private IP at send time — a classic DNS- # rebinding TOCTOU window. Apprise exposes no Session/adapter/- # DNS hook to close this in code without fragile monkey-patching- # of its plugin internals.+ # requests/urllib3), so a DNS-rebinding attacker could serve a+ # public IP here and a private/metadata IP at send time — the+ # classic resolve-vs-connect TOCTOU window.#- # RESIDUAL RISK (documented, not closed here): the ``safe_requests``- # fetch path now pins the validated address for the actual- # connection (``security.dns_pinning``). That pin is NOT reused for- # Apprise: a single ``notify()`` can fan out to multiple service- # URLs and Apprise's plugins re-resolve — and may follow redirects- # to further hosts — inside their own request stack, so a partial- # pin here would give false confidence rather than a guarantee.- # The env-only master switch below remains the boundary; pinning- # the full Apprise delivery path is a tracked follow-up.+ # SEND-TIME GUARD (this window is now closed in code for the+ # delivery path): ``notifications.service`` forces Apprise into+ # synchronous, in-thread delivery (``AppriseAsset(async_mode=False)``),+ # disables HTTP redirect-following for the send (asset-level+ # ``http_redirects=False`` re-forced per plugin, so a user-supplied+ # ``?redirect=yes`` cannot re-enable it), and wraps every ``notify()``+ # in ``dns_pinning.pinned_notification_send`` (see+ # ``security.dns_pinning``). Together, for the duration of the send,+ # that (a) closes the redirect attack class outright — a webhook can+ # no longer 30x-redirect the send to a private/loopback host or to an+ # arbitrary public host for data exfiltration, because the send is+ # simply not redirected; (b) pins every raw-webhook host in the batch+ # to the address validated here, so the ORIGINAL host's own DNS+ # rebind cannot steer the connection to a different address; and+ # (c) activates a thread-local block-private mode so any UNPINNED+ # lookup (a plugin scheme's endpoint) that resolves to a blocked+ # address is refused at the ``getaddrinfo`` layer — on a+ # timeout-bounded resolution — before a socket is opened. The block+ # runs on the very resolution the client connects to, so there is no+ # residual race. Per-scheme policy mirrors this validator: http/https+ # block private+metadata (unless the operator opts in), plugin /+ # raw-webhook schemes block only cloud-metadata (self-hosted LAN+ # targets keep working); cloud-metadata is ALWAYS blocked regardless+ # of scheme or operator flag. Because the pin/block are thread-local,+ # they never disturb a legitimate private request on another thread.#- # Because the window cannot be closed cleanly in code, the- # whole outbound-notification path is gated behind an env-only- # master switch (LDR_NOTIFICATIONS_ALLOW_OUTBOUND, default off);- # turning it on is the operator's explicit risk-acceptance. See- # SECURITY.md "Notification Webhook SSRF". Operators wanting to- # avoid the window entirely should prefer plugin schemes- # (discord://, slack://, ntfy://, ntfys://, gotify://,- # telegram://, mattermost://, etc.) that hardcode their- # endpoints instead of raw http(s):// webhooks.+ # DEFENSE IN DEPTH: the whole outbound-notification path is still+ # gated behind an env-only master switch+ # (LDR_NOTIFICATIONS_ALLOW_OUTBOUND, default off); enabling it is the+ # operator's explicit decision. See SECURITY.md "Notification Webhook+ # SSRF". Operators can further avoid raw webhooks by preferring+ # plugin schemes (discord://, slack://, ntfy://, ntfys://, gotify://,+ # telegram://, mattermost://, etc.) that hardcode their endpoints.## concurrent.futures for thread-safe timeout instead of# socket.setdefaulttimeout() which is process-global.@@ -176,6 +197,7 @@ class NotificationURLValidator:allow_private_ips: bool = False,allow_nat64: Optional[bool] = None,resolved_ips: Optional[List[ResolvedIP]] = None,+ block_link_local: bool = False,) -> bool:"""Decide whether ``hostname`` is blocked at the given``allow_private_ips`` / ``allow_nat64`` level, optionally reusing@@ -186,6 +208,9 @@ class NotificationURLValidator:DNS-rebinding TOCTOU windows between calls. If ``resolved_ips``is None and ``hostname`` is not an IP literal, DNS is resolvedvia ``_resolve_hostname_ips``.++ ``block_link_local`` forces the whole link-local range blocked even+ under ``allow_private_ips=True`` (plugin-scheme IMDS guard)."""# Localhost-string shortcuts only apply when the operator hasn't# opted into private-IP reachability. With allow_private_ips=True@@ -207,6 +232,7 @@ class NotificationURLValidator:ip,allow_private_ips=allow_private_ips,allow_nat64=allow_nat64,+ block_link_local=block_link_local,)except ValueError:pass@@ -224,6 +250,7 @@ class NotificationURLValidator:ip,allow_private_ips=allow_private_ips,allow_nat64=allow_nat64,+ block_link_local=block_link_local,):return Truereturn False@@ -259,6 +286,7 @@ class NotificationURLValidator:allow_private_ips: bool = False,allow_nat64: Optional[bool] = None,_resolved_ips: Optional[List[ResolvedIP]] = None,+ block_link_local: bool = False,) -> bool:"""Check if hostname resolves to a private IP address.@@ -273,6 +301,10 @@ class NotificationURLValidator:allow_nat64: Override for the ``security.allow_nat64`` carve-out.None (default) reads the env setting; an explicit boolanswers the hint probe.+ block_link_local: When True, the whole link-local range stays+ blocked even under allow_private_ips=True. Used by the+ plugin-scheme IMDS guard (metadata lives in link-local+ beyond the always-blocked literals).Returns:True if hostname is a private IP or localhost (subject to@@ -283,6 +315,7 @@ class NotificationURLValidator:allow_private_ips=allow_private_ips,allow_nat64=allow_nat64,resolved_ips=_resolved_ips,+ block_link_local=block_link_local,)@staticmethod@@ -423,6 +456,56 @@ class NotificationURLValidator:f"Allowed: {', '.join(NotificationURLValidator.ALLOWED_SCHEMES[:5])}...",)+ # Reject authorities with more than one "@" (fail closed). urllib3's+ # parse_url (which the SSRF host-check + the DNS pin validate against)+ # and Apprise's own parse_url disagree on which host a multi-"@"+ # authority denotes: for+ # ``json://[email protected]@decoy-public.example.com/path``+ # urllib3 sees ``decoy-public.example.com`` (validated/pinned) while+ # Apprise connects to ``169.254.169.254``. This is the same+ # parser-differential class as GHSA-g23j-2vwm-5c25; there is no+ # legitimate reason for a second "@" in a notification authority, so+ # reject it before the host is ever extracted. ``netloc`` is the+ # authority only (path/query/fragment excluded), so an "@" in a query+ # string is not counted. A single "@" (RFC 3986 userinfo, e.g.+ # ``mailto://user:pass@host``) is still allowed.+ if parsed.netloc.count("@") > 1:+ logger.warning(+ "Blocked notification URL: authority contains multiple '@' "+ "(parser-differential SSRF risk)"+ )+ return (+ False,+ "URL authority contains multiple '@' characters, "+ "which is not allowed",+ )++ # Reject a scheme://-form URL whose authority is EMPTY while content+ # (a host smuggled into the path) follows — another parser-differential+ # SSRF (defense-in-depth; the send-time block window backstops it).+ # urllib3/requests parse an empty ``//`` authority as "no host", so the+ # per-scheme IP checks below are skipped and the URL is accepted, but+ # Apprise falls back to treating the first path segment as the host and+ # dials it: ``json:///169.254.169.254/path`` reaches+ # ``169.254.169.254``. No legitimate notification URL has an empty+ # ``//`` authority, so reject it before host extraction. This fires+ # ONLY when the ``//`` authority marker is present — a scheme that+ # legitimately has no ``//`` authority (an RFC ``mailto:user@host``+ # form) never reaches here, so it is not broken.+ after_scheme = url[len(parsed.scheme) + 1 :]+ if after_scheme.startswith("//") and not parsed.netloc:+ remainder = after_scheme[2:] # everything past the '//'+ if remainder:+ logger.warning(+ "Blocked notification URL with empty authority but "+ "in-path host (parser-differential SSRF risk)"+ )+ return (+ False,+ "URL host (authority) is empty; a host in the path after "+ "'scheme:///' is not allowed",+ )+# Extract the host for any allowed scheme. We use urllib3 (the# parser ``requests`` uses internally) instead of urlparse —# urlparse is vulnerable to parser-differential bypasses like@@ -460,6 +543,26 @@ class NotificationURLValidator:return False, "URL host contains disallowed characters"hostname = NotificationURLValidator._normalize_host(hostname)+ # A populated ``//`` authority that urllib3 parses to an EMPTY host+ # (e.g. ``json://169.254.169.254:80@/`` — an IP smuggled into the+ # userinfo with nothing after the ``@``) is the sibling of the+ # multi-``@`` / empty-``//``-authority cases above: urllib3 returns no+ # host, so the per-scheme ``_is_private_ip`` checks below (guarded on+ # ``if hostname``) are skipped and the URL is accepted, yet the+ # authority still carries a target that another parser could dial. No+ # legitimate notification URL has a non-empty ``//`` authority with an+ # empty host, so reject it fail-closed before the scheme checks.+ if after_scheme.startswith("//") and parsed.netloc and not hostname:+ logger.warning(+ "Blocked notification URL: non-empty authority with empty host "+ "(parser-differential SSRF risk)"+ )+ return (+ False,+ "URL authority has no host; a host smuggled into the userinfo "+ "is not allowed",+ )+if scheme in ("http", "https"):if hostname and NotificationURLValidator._is_private_ip(hostname,@@ -478,8 +581,13 @@ class NotificationURLValidator:else:# Plugin-scheme IMDS guard. ``allow_private_ips=True`` leaves# ALWAYS_BLOCKED_METADATA_IPS and NAT64-wrapped metadata as- # the only active blocks in ``_is_private_ip`` — exactly the- # set we want to enforce regardless of operator flags.+ # active blocks in ``_is_private_ip``; ``block_link_local=True``+ # additionally keeps the whole link-local range blocked — cloud+ # metadata lives in link-local beyond the always-blocked literals+ # (e.g. Scaleway 169.254.42.42) and no legitimate self-hosted+ # notifier does. Exactly the set we want to enforce regardless of+ # operator flags (RFC1918 / loopback / non-link-local ULA still+ # allowed).## resolved_ips is intentionally NOT forwarded here: the# plugin-scheme guard must always perform its own resolution@@ -488,13 +596,15 @@ class NotificationURLValidator:hostname,allow_private_ips=True,allow_nat64=allow_nat64,+ block_link_local=True,):logger.warning(- f"Blocked cloud-metadata IP in notification URL: {hostname}"+ "Blocked cloud-metadata / link-local IP in notification "+ f"URL: {hostname}")return (False,- f"Blocked cloud-metadata IP address: {hostname}",+ f"Blocked cloud-metadata / link-local IP address: {hostname}",)# Passed all security checksdiff --git a/src/local_deep_research/security/ssrf_validator.py b/src/local_deep_research/security/ssrf_validator.pyindex 45adc76867..e4c00fc4e7 100644--- a/src/local_deep_research/security/ssrf_validator.py+++ b/src/local_deep_research/security/ssrf_validator.py@@ -20,6 +20,11 @@ from .ip_ranges import NAT64_PREFIXES# Cloud-provider metadata endpoints — always blocked, even with# allow_localhost=True or allow_private_ips=True. These IPs expose IAM /# instance-role credentials and are never legitimate destinations.+#+# Entries are matched by canonical string form: is_ip_blocked parses the+# candidate with ipaddress.ip_address first, so any textual variant+# (uppercase / zero-padded / expanded IPv6) is normalized to the canonical+# form below before the membership test.# nosec B104 - Hardcoded IPs are intentional for SSRF preventionALWAYS_BLOCKED_METADATA_IPS = frozenset({@@ -28,9 +33,29 @@ ALWAYS_BLOCKED_METADATA_IPS = frozenset("169.254.170.23", # AWS ECS task metadata v4"169.254.0.23", # Tencent Cloud"100.100.100.200", # AlibabaCloud+ # AWS native IPv6 IMDS endpoint. Documented by AWS as the IPv6+ # instance-metadata address ([fd00:ec2::254]). It is a ULA+ # (fc00::/7), NOT an IPv4-mapped / NAT64-wrapped form of+ # 169.254.169.254, so the IPv4 entries above and the NAT64+ # embedded-IPv4 check do not cover it — it must be listed+ # explicitly or it stays reachable under allow_private_ips=True+ # (which permits fc00::/7).+ "fd00:ec2::254", # AWS IMDS over IPv6})+# Link-local ranges. When ``block_link_local`` is set (notification path),+# these stay blocked even under ``allow_private_ips=True`` — cloud-provider+# metadata lives here beyond the always-blocked literals and no legitimate+# self-hosted notifier does. Kept as a distinct list (a subset of the private+# ranges) so the carve-out is explicit and testable. Module-level (built once+# at import) rather than rebuilt on every ``is_ip_blocked`` call.+# nosec B104 - Hardcoded ranges are intentional for SSRF prevention+LINK_LOCAL_RANGES = [+ ipaddress.ip_network("169.254.0.0/16"), # IPv4 link-local+ ipaddress.ip_network("fe80::/10"), # IPv6 link-local+]+# Allowed URL schemesALLOWED_SCHEMES = {"http", "https"}@@ -54,6 +79,30 @@ def is_nat64_wrapped_metadata_ip(ip: ipaddress._BaseAddress) -> bool:return False+def is_nat64_wrapped_link_local_ip(ip: ipaddress._BaseAddress) -> bool:+ """True iff ``ip`` is an IPv6 address inside a NAT64 prefix whose embedded+ IPv4 (low 32 bits) is IPv4 link-local (``169.254.0.0/16``).++ Mirrors ``is_nat64_wrapped_metadata_ip`` for the ``block_link_local``+ notification guard. The ``security.allow_nat64`` opt-in re-opens general+ IPv4 reachability via NAT64, but it must not re-open link-local — where+ cloud-provider metadata lives beyond the always-blocked literals (e.g.+ Scaleway's ``169.254.42.42``). Consulted only when ``block_link_local`` is+ set, so non-notification callers (which permit link-local under+ ``allow_private_ips``) keep the opt-in's reachability unchanged.+ """+ if not isinstance(ip, ipaddress.IPv6Address):+ return False+ for nat64_prefix in NAT64_PREFIXES:+ if ip in nat64_prefix:+ embedded_v4 = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)+ return any(+ isinstance(r, ipaddress.IPv4Network) and embedded_v4 in r+ for r in LINK_LOCAL_RANGES+ )+ return False++# RFC 3986 forbids these characters in URLs; their presence in a URL signals# a parser-differential attempt (GHSA-g23j-2vwm-5c25). \s covers space, \t,# \n, \r, \v, \f. Backslash is the load-bearing payload — Python's urlparse@@ -68,6 +117,7 @@ def is_ip_blocked(allow_localhost: bool = False,allow_private_ips: bool = False,allow_nat64: Optional[bool] = None,+ block_link_local: bool = False,) -> bool:"""Check if an IP address is in a blocked range.@@ -83,6 +133,19 @@ def is_ip_blocked(Note: cloud metadata endpoints in ``ALWAYS_BLOCKED_METADATA_IPS``(AWS / Azure / OCI / DigitalOcean / AlibabaCloud / Tencent / ECS)are ALWAYS blocked regardless of these flags.+ block_link_local: When True, the entire link-local range — IPv4+ ``169.254.0.0/16`` and IPv6 ``fe80::/10`` — is treated as blocked+ EVEN under ``allow_private_ips=True``. Used by the notification+ send path (see ``security.dns_pinning`` /+ ``notification_validator``): the lenient plugin/raw-webhook+ partition allows private LAN targets, but link-local is where+ cloud-provider metadata lives beyond the six always-blocked+ literals (e.g. Scaleway's ``169.254.42.42``) and is never a+ legitimate self-hosted notifier, so it stays blocked there. Has no+ effect unless ``allow_private_ips=True`` — without the opt-in+ link-local is already blocked. Default False preserves the+ behavior every non-notification caller relies on (RFC1918 /+ loopback / non-link-local ULA remain allowed under the flag).allow_nat64: Override for the ``security.allow_nat64`` carve-out.``None`` (default) reads the env setting — the behavior everyexisting caller relies on. An explicit ``bool`` answers a@@ -144,6 +207,16 @@ def is_ip_blocked(if is_nat64_wrapped_metadata_ip(ip):return True+ # For the notification send path (``block_link_local``), a NAT64-wrapped+ # link-local address must also stay blocked even under the allow_nat64+ # opt-in — otherwise the carve-out below `continue`s past the link-local+ # check for the IPv6-wrapped form of e.g. Scaleway's 169.254.42.42.+ # (When NAT64 is off the whole prefix is already blocked in the loop, so+ # this only changes the opt-in case; gated on block_link_local so+ # non-notification callers are unaffected.)+ if block_link_local and is_nat64_wrapped_link_local_ip(ip):+ return True+# Operator escape hatch for IPv6-only deployments using DNS64+NAT64.# Read lazily (not at import) so test monkeypatching works and so the# value is not cached across env mutations. Cloud-metadata IPs are@@ -173,6 +246,17 @@ def is_ip_blocked(if allow_private_ips:is_loopback = any(ip in lr for lr in LOOPBACK_RANGES)is_private = any(ip in pr for pr in PRIVATE_RANGES)+ # Notification path: link-local stays blocked even under+ # the private-IP opt-in (metadata lives here beyond the+ # always-blocked literals; no legitimate self-hosted+ # notifier does). Fires before the private/loopback skip so+ # it cannot be un-blocked by it. Metadata literals already+ # returned True above, so this only governs the rest of the+ # link-local range.+ if block_link_local and any(+ ip in llr for llr in LINK_LOCAL_RANGES+ ):+ return Trueif is_loopback or is_private:continue# If allow_localhost is True, skip blocking for loopback onlydiff --git a/tests/auth_tests/test_encrypted_db.py b/tests/auth_tests/test_encrypted_db.pyindex da780de0ff..655b63ebaf 100644--- a/tests/auth_tests/test_encrypted_db.py+++ b/tests/auth_tests/test_encrypted_db.py@@ -292,12 +292,12 @@ class TestConnectionVerification:def test_verify_connection_correct_password(self, db_manager, auth_user):"""Verify connection verification returns True with correct password."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_sqlcipher_pragmas,set_sqlcipher_key,verify_sqlcipher_connection,)- from src.local_deep_research.database.sqlcipher_compat import (+ from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)@@ -320,11 +320,11 @@ class TestConnectionVerification:def test_verify_connection_wrong_password(self, db_manager, auth_user):"""Verify accessing encrypted data with wrong password fails."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_sqlcipher_pragmas,set_sqlcipher_key,)- from src.local_deep_research.database.sqlcipher_compat import (+ from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)@@ -351,7 +351,7 @@ class TestConnectionVerification:def test_all_pragmas_applied_comprehensive(self, db_manager, auth_user):"""Comprehensive test verifying ALL SQLCipher pragmas are applied."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (get_sqlcipher_settings,)@@ -408,7 +408,7 @@ class TestConnectionVerification:def test_create_sqlcipher_connection_helper(self, db_manager, auth_user):"""Test the create_sqlcipher_connection helper function."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (create_sqlcipher_connection,)@@ -433,7 +433,7 @@ class TestConnectionVerification:self, db_manager, auth_user):"""Test create_sqlcipher_connection fails with wrong password."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (create_sqlcipher_connection,)diff --git a/tests/auth_tests/test_sqlcipher_backwards_compat.py b/tests/auth_tests/test_sqlcipher_backwards_compat.pyindex 4a62889ddd..514aed984d 100644--- a/tests/auth_tests/test_sqlcipher_backwards_compat.py+++ b/tests/auth_tests/test_sqlcipher_backwards_compat.py@@ -12,13 +12,13 @@ from pathlib import Pathimport pytest-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,apply_performance_pragmas,apply_sqlcipher_pragmas,set_sqlcipher_key,)-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)@@ -371,7 +371,7 @@ class TestOldToNewPragmaOrderMigration:OLD order: key -> cipher_page_size -> cipher_hmac_algorithm -> kdf_iterThis simulates how databases were created before this PR."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (get_sqlcipher_settings,set_sqlcipher_key,)@@ -583,7 +583,7 @@ class TestOldToNewPragmaOrderMigration:Verify password change (rekey) works on databases created withOLD pragma order when using NEW pragma order code."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (set_sqlcipher_rekey,)diff --git a/tests/auth_tests/test_sqlcipher_compatibility.py b/tests/auth_tests/test_sqlcipher_compatibility.pyindex a95dda4920..a45b99c3e9 100644--- a/tests/auth_tests/test_sqlcipher_compatibility.py+++ b/tests/auth_tests/test_sqlcipher_compatibility.py@@ -11,11 +11,11 @@ from pathlib import Pathimport pytest-from src.local_deep_research.database.encrypted_db import DatabaseManager-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.encrypted_db import DatabaseManager+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,apply_sqlcipher_pragmas,get_sqlcipher_settings,@@ -59,11 +59,11 @@ def auth_user(temp_data_dir, monkeypatch):"""Create a test user in auth database."""monkeypatch.setenv("LDR_DATA_DIR", str(temp_data_dir))- from src.local_deep_research.database.auth_db import (+ from local_deep_research.database.auth_db import (get_auth_db_session,init_auth_database,)- from src.local_deep_research.database.models.auth import User+ from local_deep_research.database.models.auth import Userinit_auth_database()auth_db = get_auth_db_session()diff --git a/tests/auth_tests/test_sqlcipher_key_derivation.py b/tests/auth_tests/test_sqlcipher_key_derivation.pyindex 3faf3021c9..243e807990 100644--- a/tests/auth_tests/test_sqlcipher_key_derivation.py+++ b/tests/auth_tests/test_sqlcipher_key_derivation.py@@ -11,14 +11,14 @@ from pathlib import Pathimport pytest-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (LEGACY_PBKDF2_SALT,_get_key_from_password,get_sqlcipher_settings,set_sqlcipher_key,set_sqlcipher_rekey,)-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)@@ -155,7 +155,7 @@ class TestKeyDerivationWithDatabase:def test_derived_key_opens_database(self, sqlcipher_module, temp_db_path):"""Verify derived key can create and open a database."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,)@@ -175,7 +175,7 @@ class TestKeyDerivationWithDatabase:conn.close()# Reopen with same password- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_sqlcipher_pragmas,)@@ -192,7 +192,7 @@ class TestKeyDerivationWithDatabase:def test_wrong_password_cannot_open(self, sqlcipher_module, temp_db_path):"""Verify wrong password cannot open database."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,)@@ -209,7 +209,7 @@ class TestKeyDerivationWithDatabase:conn.close()# Try to open with password2- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_sqlcipher_pragmas,)@@ -228,7 +228,7 @@ class TestKeyDerivationWithDatabase:def test_rekey_uses_same_derivation(self, sqlcipher_module, temp_db_path):"""Verify rekey produces key compatible with set_sqlcipher_key."""- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,)@@ -249,7 +249,7 @@ class TestKeyDerivationWithDatabase:conn.close()# Open with new password using set_sqlcipher_key- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_sqlcipher_pragmas,)diff --git a/tests/auth_tests/test_sqlcipher_performance.py b/tests/auth_tests/test_sqlcipher_performance.pyindex c73ca17297..6df23d92a8 100644--- a/tests/auth_tests/test_sqlcipher_performance.py+++ b/tests/auth_tests/test_sqlcipher_performance.py@@ -11,13 +11,13 @@ from pathlib import Pathimport pytest-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,apply_performance_pragmas,apply_sqlcipher_pragmas,set_sqlcipher_key,)-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)diff --git a/tests/auth_tests/test_sqlcipher_rekey.py b/tests/auth_tests/test_sqlcipher_rekey.pyindex b7cb776bba..02d6d61f13 100644--- a/tests/auth_tests/test_sqlcipher_rekey.py+++ b/tests/auth_tests/test_sqlcipher_rekey.py@@ -12,7 +12,7 @@ from unittest.mock import Mock, patchimport pytest-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (LEGACY_PBKDF2_SALT,apply_cipher_defaults_before_key,apply_sqlcipher_pragmas,@@ -21,7 +21,7 @@ from src.local_deep_research.database.sqlcipher_utils import (set_sqlcipher_rekey,_get_key_from_password,)-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)@@ -249,13 +249,13 @@ class TestRekeyWithSQLAlchemy:"""Verify rekey works through SQLAlchemy connection."""from sqlalchemy import create_engine, event, text- from src.local_deep_research.database.sqlcipher_utils import (+ from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,apply_sqlcipher_pragmas,set_sqlcipher_key,set_sqlcipher_rekey,)- from src.local_deep_research.database.sqlcipher_compat import (+ from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)@@ -322,7 +322,7 @@ class TestSetSqlcipherRekey:mock_conn.execute.side_effect = [TypeError("not sqlalchemy"), None]with patch(- "src.local_deep_research.database.sqlcipher_utils.get_key_from_password",+ "local_deep_research.database.sqlcipher_utils.get_key_from_password",return_value=b"\xab\xcd\xef",) as mock_get_key:set_sqlcipher_rekey(mock_conn, "new_password")@@ -334,7 +334,7 @@ class TestSetSqlcipherRekey:mock_conn.execute.side_effect = [TypeError("not sqlalchemy"), None]with patch(- "src.local_deep_research.database.sqlcipher_utils.get_key_from_password",+ "local_deep_research.database.sqlcipher_utils.get_key_from_password",return_value=b"\xab\xcd\xef",):set_sqlcipher_rekey(mock_conn, "test_password")@@ -352,7 +352,7 @@ class TestSetSqlcipherRekey:mock_conn = Mock()with patch(- "src.local_deep_research.database.sqlcipher_utils.get_key_from_password",+ "local_deep_research.database.sqlcipher_utils.get_key_from_password",return_value=b"\xab\xcd\xef",):set_sqlcipher_rekey(mock_conn, "new_password")diff --git a/tests/auth_tests/test_sqlcipher_settings.py b/tests/auth_tests/test_sqlcipher_settings.pyindex 6c9a8c5128..0f146cd0e7 100644--- a/tests/auth_tests/test_sqlcipher_settings.py+++ b/tests/auth_tests/test_sqlcipher_settings.py@@ -11,7 +11,7 @@ from pathlib import Pathimport pytest-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (DEFAULT_KDF_ITERATIONS,DEFAULT_PAGE_SIZE,DEFAULT_HMAC_ALGORITHM,@@ -21,7 +21,7 @@ from src.local_deep_research.database.sqlcipher_utils import (apply_performance_pragmas,set_sqlcipher_key,)-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)diff --git a/tests/auth_tests/test_sqlcipher_threads.py b/tests/auth_tests/test_sqlcipher_threads.pyindex 437325ed0a..8dce3faab8 100644--- a/tests/auth_tests/test_sqlcipher_threads.py+++ b/tests/auth_tests/test_sqlcipher_threads.py@@ -14,13 +14,13 @@ from pathlib import Pathimport pytest-from src.local_deep_research.database.sqlcipher_utils import (+from local_deep_research.database.sqlcipher_utils import (apply_cipher_defaults_before_key,apply_performance_pragmas,apply_sqlcipher_pragmas,set_sqlcipher_key,)-from src.local_deep_research.database.sqlcipher_compat import (+from local_deep_research.database.sqlcipher_compat import (get_sqlcipher_module,)diff --git a/tests/chat/conftest.py b/tests/chat/conftest.pyindex de2c2f905f..5d07f58980 100644--- a/tests/chat/conftest.py+++ b/tests/chat/conftest.py@@ -35,16 +35,16 @@ from local_deep_research.database.session_context import (get_user_db_session as _REAL_GET_USER_DB_SESSION,)-# ``chat.routes`` is importable as BOTH of these under the CI import layout-# (``src`` on PYTHONPATH + the repo root on sys.path); each resolves to a-# DISTINCT module object with its own ``ChatService`` attribute. The running-# app registers the non-``src`` blueprint, but the heal fixture rebinds every-# alias that is loaded so a poisoner targeting either object cannot bleed into-# a later chat test.-_CHAT_ROUTES_ALIASES = (- "local_deep_research.chat.routes",- "src.local_deep_research.chat.routes",-)+# ``chat.routes`` binds process-global names (``ChatService``,+# ``SettingsManager``, ``get_user_db_session``, ``_load_settings``) that a mock+# leaked by an earlier test can poison. Tests import it under exactly one+# canonical name: the ``src.local_deep_research`` alias is banned in tests (see+# ``.pre-commit-hooks/check-no-src-test-imports.py``) precisely because+# importing a module under both names loads two distinct copies and breaks+# process-global singletons -- so ``chat.routes`` now resolves to a single+# module object and the heal fixture only needs to rebind that one. Kept as a+# tuple so the heal loop stays uniform if another canonical alias is ever added.+_CHAT_ROUTES_ALIASES = ("local_deep_research.chat.routes",)def _capture_real_load_settings():@@ -111,16 +111,17 @@ def _restore_chat_routes_service():``send_message`` commits ``UserActiveResearch(..., settings_snapshot=...)``(#5549), turning an expected 200/429 into a generic 500.- Two subtleties this heals that a single-module rebind missed:+ A subtlety this heals that a naive re-read missed:- * **Module duplication.** ``chat.routes`` is loaded under two distinct- module objects (see ``_CHAT_ROUTES_ALIASES``), each with its own- attributes. Rebind whichever aliases are loaded.* **A poisoned source module.** Re-reading ``ChatService`` /``SettingsManager`` / ``get_user_db_session`` at heal time would re-bind a*leaked mock* if that module is the one poisoned. Rebind the genuineobjects captured at import time (``_REAL_CHAT_SERVICE`` et al.) instead.+ (``chat.routes`` resolves to a single canonical module object now -- the+ ``src.`` alias that used to create a second copy is banned in tests, see+ ``_CHAT_ROUTES_ALIASES`` -- so the heal rebinds that one object.)+Rebinding before AND after each test heals any leak inflicted by an earliertest (pre-yield) and prevents this test from leaking to the next(post-yield). Tests that establish their own ``with patch(...)`` inside the@@ -200,7 +201,7 @@ def mock_user_db_session():yield session_mockwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",side_effect=_mock_session,):yield session_mock@@ -209,7 +210,7 @@ def mock_user_db_session():@pytest.fixturedef chat_service(setup_database_for_all_tests):"""Provide ChatService with test database."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicereturn ChatService(username="test_user")diff --git a/tests/chat/test_chat_accumulated_context.py b/tests/chat/test_chat_accumulated_context.pyindex e95d2e8062..d8a11e84d0 100644--- a/tests/chat/test_chat_accumulated_context.py+++ b/tests/chat/test_chat_accumulated_context.py@@ -36,7 +36,7 @@ class TestAccumulatedContextStructure:def test_context_structure_from_manager(self):"""Test context structure created by ChatContextManager."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermessages = [{"role": "user", "content": "Test query", "message_type": "query"}@@ -59,7 +59,7 @@ class TestAccumulatedContextStructure:def test_context_limits_entities(self):"""Test that entities are limited to 20."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManager# Create more than 20 entitiesmany_entities = [f"entity{i}" for i in range(30)]@@ -72,7 +72,7 @@ class TestAccumulatedContextStructure:def test_context_limits_topics(self):"""Test that topics are limited to 10."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManager# Create more than 10 topicsmany_topics = [f"topic{i}" for i in range(15)]@@ -89,7 +89,7 @@ class TestContextMerging:def test_merge_entities_deduplicates(self):"""Test that merging entities removes duplicates."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManageraccumulated = {"key_entities": ["entity1", "entity2"]}manager = ChatContextManager("test-session", [], accumulated)@@ -107,7 +107,7 @@ class TestContextSummary:def test_summary_created_from_content(self):"""Test that summaries are created from content."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager("test-session", [], {})@@ -125,7 +125,7 @@ Third paragraph with more details."""def test_summary_skips_headers(self):"""Test that summary skips markdown headers."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager("test-session", [], {})@@ -144,7 +144,7 @@ More content here."""def test_summary_handles_short_paragraphs(self):"""Test that summary handles content with short paragraphs."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager("test-session", [], {})@@ -236,7 +236,7 @@ class TestEdgeCases:def test_empty_accumulated_context_handled(self):"""Test handling of None/empty accumulated context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager1 = ChatContextManager("test", [], None)manager2 = ChatContextManager("test", [], {})@@ -250,7 +250,7 @@ class TestEdgeCases:def test_special_characters_in_context(self):"""Test handling of special characters in context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManageraccumulated = {"key_entities": ["<script>", "O'Reilly", '"quotes"'],@@ -267,7 +267,7 @@ class TestEdgeCases:def test_unicode_in_context(self):"""Test handling of unicode in context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermessages = [{"role": "user", "content": "你好世界", "message_type": "query"},diff --git a/tests/chat/test_chat_add_progress_step.py b/tests/chat/test_chat_add_progress_step.pyindex 15740f36a6..8f0f4e697c 100644--- a/tests/chat/test_chat_add_progress_step.py+++ b/tests/chat/test_chat_add_progress_step.py@@ -23,8 +23,8 @@ import uuidimport pytest-from src.local_deep_research.chat.service import ChatService-from src.local_deep_research.database.models import (+from local_deep_research.chat.service import ChatService+from local_deep_research.database.models import (ChatProgressStep,ChatSession,ChatSessionStatus,@@ -71,7 +71,7 @@ def _patch_user_db(monkeypatch, SessionLocal):db.close()monkeypatch.setattr(- "src.local_deep_research.chat.service.get_user_db_session", _ctx+ "local_deep_research.chat.service.get_user_db_session", _ctx)diff --git a/tests/chat/test_chat_archive_atomic_guard.py b/tests/chat/test_chat_archive_atomic_guard.pyindex b7fd636530..d3812264cf 100644--- a/tests/chat/test_chat_archive_atomic_guard.py+++ b/tests/chat/test_chat_archive_atomic_guard.py@@ -24,8 +24,8 @@ import uuidimport pytest-from src.local_deep_research.chat.service import ChatService-from src.local_deep_research.database.models import (+from local_deep_research.chat.service import ChatService+from local_deep_research.database.models import (ChatMessage,ChatSession,ChatSessionStatus,diff --git a/tests/chat/test_chat_archive_blocked_in_progress.py b/tests/chat/test_chat_archive_blocked_in_progress.pyindex 1c31cbbf69..fff1630b49 100644--- a/tests/chat/test_chat_archive_blocked_in_progress.py+++ b/tests/chat/test_chat_archive_blocked_in_progress.py@@ -22,12 +22,12 @@ from unittest.mock import patchimport pytest-from src.local_deep_research.chat.service import (+from local_deep_research.chat.service import (ArchiveBlockedError,ChatService,)-from src.local_deep_research.constants import ResearchStatus-from src.local_deep_research.database.models import (+from local_deep_research.constants import ResearchStatus+from local_deep_research.database.models import (ChatSession,ChatSessionStatus,ResearchHistory,@@ -69,7 +69,7 @@ def _run_archive(SessionLocal, service, session_id):yield dbwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",side_effect=lambda *_args, **_kwargs: _managed_test_session(),):return service.archive_session(session_id)diff --git a/tests/chat/test_chat_attempt_delete_retry.py b/tests/chat/test_chat_attempt_delete_retry.pyindex 75b7f32154..add7aa511b 100644--- a/tests/chat/test_chat_attempt_delete_retry.py+++ b/tests/chat/test_chat_attempt_delete_retry.py@@ -28,13 +28,13 @@ from unittest.mock import patchimport pytest-from src.local_deep_research.chat.service import (+from local_deep_research.chat.service import (AttemptInProgress,AttemptNotFound,ChatService,)-from src.local_deep_research.constants import ResearchStatus-from src.local_deep_research.database.models import (+from local_deep_research.constants import ResearchStatus+from local_deep_research.database.models import (ChatMessage,ChatProgressStep,ChatRole,@@ -64,7 +64,7 @@ def _service_db(SessionLocal):yield dbwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",side_effect=lambda *_args, **_kwargs: _managed_test_session(),):yield@@ -386,11 +386,11 @@ class TestDeleteAttemptService:flagged = []with (patch(- "src.local_deep_research.chat.service.set_termination_flag",+ "local_deep_research.chat.service.set_termination_flag",side_effect=lambda rid: flagged.append(rid),),patch(- "src.local_deep_research.chat.service.is_research_thread_alive",+ "local_deep_research.chat.service.is_research_thread_alive",return_value=True,),_service_db(SessionLocal),@@ -431,7 +431,7 @@ class TestDeleteAttemptService:# is_research_thread_alive returns False → sweep reclaims.with (patch(- "src.local_deep_research.chat.service.is_research_thread_alive",+ "local_deep_research.chat.service.is_research_thread_alive",return_value=False,),_service_db(SessionLocal),diff --git a/tests/chat/test_chat_boundaries.py b/tests/chat/test_chat_boundaries.pyindex 10c33b2d03..26efc2d6b2 100644--- a/tests/chat/test_chat_boundaries.py+++ b/tests/chat/test_chat_boundaries.py@@ -13,7 +13,7 @@ class TestMessageBoundaries:def test_message_with_empty_content_accepted(self):"""Test that empty message content is accepted."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_session_obj = MagicMock()mock_session_obj.id = "test-session"@@ -35,7 +35,7 @@ class TestMessageBoundaries:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")@@ -54,7 +54,7 @@ class TestMessageBoundaries:"""chat_messages.content is NOT NULL.add_message must reject content=None at the application layer."""import pytest- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceservice = ChatService(username="testuser")with pytest.raises(ValueError, match="content is required"):@@ -72,7 +72,7 @@ class TestContextBoundaries:def test_accumulated_context_entities_limited_to_50(self):"""Test that key_entities are limited to 50 items."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_session_obj = MagicMock()mock_session_obj.id = "test-session"@@ -91,7 +91,7 @@ class TestContextBoundaries:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")@@ -107,7 +107,7 @@ class TestContextBoundaries:def test_accumulated_context_topics_limited_to_20(self):"""Test that topics are limited to 20 items."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_session_obj = MagicMock()mock_session_obj.id = "test-session"@@ -126,7 +126,7 @@ class TestContextBoundaries:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")@@ -142,7 +142,7 @@ class TestContextBoundaries:def test_accumulated_summary_truncated_to_8000_chars(self):"""Test that summary is truncated to 8000 characters."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_session_obj = MagicMock()mock_session_obj.id = "test-session"@@ -161,7 +161,7 @@ class TestContextBoundaries:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")@@ -181,7 +181,7 @@ class TestSessionBoundaries:def test_session_title_at_max_100_chars(self):"""Test that title from query is limited to 100 chars + ellipsis."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceadded_sessions = []@@ -197,7 +197,7 @@ class TestSessionBoundaries:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")@@ -216,7 +216,7 @@ class TestSessionBoundaries:def test_session_title_exactly_100_chars_no_ellipsis(self):"""Test that 100-char query doesn't get ellipsis."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceadded_sessions = []@@ -232,7 +232,7 @@ class TestSessionBoundaries:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")@@ -251,7 +251,7 @@ class TestContextManagerBoundaries:def test_findings_limited_to_5(self):"""Test that findings are limited to MAX_FINDINGS_TO_INCLUDE (5)."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManager# Create 10 assistant messages with research_idmessages = [@@ -280,7 +280,7 @@ class TestContextManagerBoundaries:def test_create_summary_truncates_long_paragraphs_to_300(self):"""Test that _create_summary truncates paragraphs to 300 chars."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagerlong_paragraph = "Z" * 500@@ -302,7 +302,7 @@ class TestEdgeCases:def test_entity_deduplication(self):"""Test that duplicate entities are deduplicated."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_session_obj = MagicMock()mock_session_obj.id = "test-session"@@ -321,7 +321,7 @@ class TestEdgeCases:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="testuser")diff --git a/tests/chat/test_chat_concurrency.py b/tests/chat/test_chat_concurrency.pyindex dfd1621e61..d0b0a972ab 100644--- a/tests/chat/test_chat_concurrency.py+++ b/tests/chat/test_chat_concurrency.py@@ -19,7 +19,7 @@ class TestChatConcurrency:def test_concurrent_session_creation_unique_ids(self):"""Test that concurrent session creation generates unique IDs."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecreated_ids = []lock = threading.Lock()@@ -43,7 +43,7 @@ class TestChatConcurrency:# Apply patch at test level (outside threads) to avoid race conditions# during patch application/removal across threadswith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):# Create sessions concurrently@@ -65,7 +65,7 @@ class TestChatConcurrency:def test_multiple_sessions_same_user_isolated(self):"""Test that multiple sessions for the same user are independent."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicesessions_created = []lock = threading.Lock()@@ -106,7 +106,7 @@ class TestChatConcurrency:# Patch at module level before spawning threadswith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):# Create multiple sessions concurrently@@ -125,7 +125,7 @@ class TestChatConcurrency:def test_concurrent_reads_during_write_consistent(self):"""Test that reads during writes return consistent data."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatService# Shared state for the mockmock_sessions = {}@@ -192,7 +192,7 @@ class TestChatConcurrency:# Apply patch at test level (outside threads) to avoid race conditionswith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):# Now do concurrent reads@@ -208,7 +208,7 @@ class TestChatConcurrency:def test_rapid_message_sends_no_data_loss(self):"""Test that rapidly sending messages doesn't lose any messages."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemessages_added = []lock = threading.Lock()@@ -243,7 +243,7 @@ class TestChatConcurrency:# Patch at module level before spawning threadswith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):# Send many messages rapidly@@ -266,7 +266,7 @@ class TestChatConcurrency:def test_concurrent_context_updates_preserve_data(self):"""Test that concurrent context updates don't lose entities."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatService# The implementation uses with_for_update() for row-level locking# to ensure atomic read-modify-write operations@@ -320,7 +320,7 @@ class TestChatConcurrency:# Apply patch at test level (outside threads) to avoid race conditionswith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):with ThreadPoolExecutor(max_workers=num_updates) as executor:@@ -341,7 +341,7 @@ class TestChatConcurrency:def test_thread_local_services_independent(self):"""Test that ChatService instances in different threads are independent."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceservice_ids = []lock = threading.Lock()@@ -385,7 +385,7 @@ class TestAddMessageSequenceRace:from datetime import datetime, UTCfrom sqlalchemy import create_enginefrom sqlalchemy.orm import sessionmaker- from src.local_deep_research.database.models import (+ from local_deep_research.database.models import (Base,ChatSession,)@@ -425,8 +425,8 @@ class TestAddMessageSequenceRace:constraint fires."""from contextlib import contextmanager- from src.local_deep_research.chat.service import ChatService- from src.local_deep_research.database.models import ChatMessage+ from local_deep_research.chat.service import ChatService+ from local_deep_research.database.models import ChatMessageengine, Session, session_id = self._setup_real_db(tmp_path)@@ -455,7 +455,7 @@ class TestAddMessageSequenceRace:return Nonewith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",real_get_user_db_session,):with ThreadPoolExecutor(max_workers=num_messages) as executor:diff --git a/tests/chat/test_chat_context_advanced.py b/tests/chat/test_chat_context_advanced.pyindex 01a7795aa5..051ae01659 100644--- a/tests/chat/test_chat_context_advanced.py+++ b/tests/chat/test_chat_context_advanced.py@@ -4,7 +4,7 @@ Advanced tests for ChatContextManager.Tests context window limits, summarization, and context building."""-from src.local_deep_research.chat.context import ChatContextManager+from local_deep_research.chat.context import ChatContextManagerclass TestContextBuilding:diff --git a/tests/chat/test_chat_context_manager.py b/tests/chat/test_chat_context_manager.pyindex df693d6450..28a776ef53 100644--- a/tests/chat/test_chat_context_manager.py+++ b/tests/chat/test_chat_context_manager.py@@ -8,7 +8,7 @@ class TestChatContextManagerBuildResearchContext:self, sample_messages, sample_accumulated_context):"""Test that build_research_context returns all required keys."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -36,7 +36,7 @@ class TestChatContextManagerBuildResearchContext:self, sample_accumulated_context):"""Test that is_multi_turn is False when no previous messages."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -51,7 +51,7 @@ class TestChatContextManagerBuildResearchContext:self, sample_messages, sample_accumulated_context):"""Test that is_multi_turn is True when previous messages exist."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -66,7 +66,7 @@ class TestChatContextManagerBuildResearchContext:self, sample_messages, sample_accumulated_context):"""Test that turn_count is included in the context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -81,7 +81,7 @@ class TestChatContextManagerBuildResearchContext:self, sample_messages, sample_accumulated_context):"""Test that session_id is included in the context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="test-session-abc",@@ -100,7 +100,7 @@ class TestChatContextManagerExtraction:self, sample_messages, sample_accumulated_context):"""Test that only assistant messages with research_id are extracted."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -124,7 +124,7 @@ class TestChatContextManagerExtraction:self, many_messages, sample_accumulated_context):"""Test that findings are limited to 5 most recent."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -148,7 +148,7 @@ class TestChatContextManagerCreateSummary:def test_create_summary_finds_first_paragraph(self):"""Test that _create_summary finds the first substantial paragraph."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagercontent = """# Heading@@ -170,7 +170,7 @@ This is the second paragraph."""def test_create_summary_skips_headers(self):"""Test that _create_summary skips markdown headers when substantial content follows."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManager# Content with a substantial paragraph (>50 chars) after headerscontent = """# Main Heading@@ -193,7 +193,7 @@ This is the actual content paragraph with more than fifty characters of meaningfdef test_create_summary_truncates_long_content(self):"""Test that _create_summary truncates long paragraphs to 300 chars."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagerlong_paragraph = "X" * 500@@ -214,7 +214,7 @@ class TestChatContextManagerExtractContextUpdates:def test_extract_context_updates_returns_required_keys(self):"""Test that extract_context_updates returns all required keys."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -238,7 +238,7 @@ class TestChatContextManagerKeyEntitiesAndTopics:self, sample_messages, sample_accumulated_context):"""Test that key entities are retrieved from accumulated context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -256,7 +256,7 @@ class TestChatContextManagerKeyEntitiesAndTopics:self, sample_messages, sample_accumulated_context):"""Test that topics are retrieved from accumulated context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="session-123",@@ -291,14 +291,14 @@ class TestBuildResearchContextFocusedSummary:def test_focused_summary_used_as_past_findings(self, mocker):"""With a query + snapshot, past_findings is the focused LLM summary."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagerfake_llm = mocker.Mock()fake_llm.invoke.return_value = mocker.Mock(content="Prior work, focused on cost.")get_llm = mocker.patch(- "src.local_deep_research.config.llm_config.get_llm",+ "local_deep_research.config.llm_config.get_llm",return_value=fake_llm,)@@ -323,11 +323,9 @@ class TestBuildResearchContextFocusedSummary:def test_no_current_query_uses_raw_findings(self, mocker):"""A no-arg call (no focus question) makes no LLM call."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManager- get_llm = mocker.patch(- "src.local_deep_research.config.llm_config.get_llm"- )+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")manager = ChatContextManager(session_id="s1",messages=self._conversation(),@@ -359,7 +357,7 @@ class TestFollowupContextModes:]def _manager(self, mode):- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagerreturn ChatContextManager(session_id="s1",@@ -369,9 +367,7 @@ class TestFollowupContextModes:)def test_raw_mode_uses_recent_findings_no_llm(self, mocker):- get_llm = mocker.patch(- "src.local_deep_research.config.llm_config.get_llm"- )+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")result = self._manager("raw").build_research_context(current_query="cost?")@@ -380,9 +376,7 @@ class TestFollowupContextModes:assert "qubits" in result["past_findings"].lower()def test_full_mode_sends_whole_transcript_no_llm(self, mocker):- get_llm = mocker.patch(- "src.local_deep_research.config.llm_config.get_llm"- )+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")result = self._manager("full").build_research_context(current_query="cost?")@@ -393,9 +387,7 @@ class TestFollowupContextModes:assert "What is quantum computing?" in pastdef test_none_mode_sends_no_prior_findings_no_llm(self, mocker):- get_llm = mocker.patch(- "src.local_deep_research.config.llm_config.get_llm"- )+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")result = self._manager("none").build_research_context(current_query="cost?")@@ -407,7 +399,7 @@ class TestFollowupContextModes:fake_llm = mocker.Mock()fake_llm.invoke.return_value = mocker.Mock(content="Focused summary.")mocker.patch(- "src.local_deep_research.config.llm_config.get_llm",+ "local_deep_research.config.llm_config.get_llm",return_value=fake_llm,)result = self._manager("summary").build_research_context(@@ -421,7 +413,7 @@ class TestFollowupContextModes:"""A get_llm() failure (e.g. misconfigured provider) degrades thesummary to empty rather than crashing the follow-up request."""mocker.patch(- "src.local_deep_research.config.llm_config.get_llm",+ "local_deep_research.config.llm_config.get_llm",side_effect=RuntimeError("no provider configured"),)result = self._manager("summary").build_research_context(diff --git a/tests/chat/test_chat_delete_terminates_research.py b/tests/chat/test_chat_delete_terminates_research.pyindex d2d687b35f..ff22a43bd4 100644--- a/tests/chat/test_chat_delete_terminates_research.py+++ b/tests/chat/test_chat_delete_terminates_research.py@@ -27,9 +27,9 @@ import uuidfrom contextlib import contextmanagerfrom unittest.mock import patch-from src.local_deep_research.chat.service import ChatService-from src.local_deep_research.constants import ResearchStatus-from src.local_deep_research.database.models import (+from local_deep_research.chat.service import ChatService+from local_deep_research.constants import ResearchStatus+from local_deep_research.database.models import (ChatSession,ChatSessionStatus,ResearchHistory,@@ -72,7 +72,7 @@ def _patched_service_db(SessionLocal):yield dbwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",side_effect=lambda *_args, **_kwargs: _managed_test_session(),):yield@@ -104,7 +104,7 @@ def test_delete_session_flags_in_progress_research_for_termination(# delete_session once the import has captured the reference.with (patch(- "src.local_deep_research.chat.service.set_termination_flag",+ "local_deep_research.chat.service.set_termination_flag",side_effect=_capture,),_patched_service_db(SessionLocal),@@ -136,7 +136,7 @@ def test_delete_session_skips_completed_research(setup_database_for_all_tests):with (patch(- "src.local_deep_research.chat.service.set_termination_flag",+ "local_deep_research.chat.service.set_termination_flag",side_effect=lambda rid: flagged.append(rid),),_patched_service_db(SessionLocal),@@ -160,7 +160,7 @@ def test_delete_session_returns_false_for_missing_session(flagged = []with (patch(- "src.local_deep_research.chat.service.set_termination_flag",+ "local_deep_research.chat.service.set_termination_flag",side_effect=lambda rid: flagged.append(rid),),_patched_service_db(SessionLocal),diff --git a/tests/chat/test_chat_followup_context_logging.py b/tests/chat/test_chat_followup_context_logging.pyindex 530630a6b2..0edccbe8c0 100644--- a/tests/chat/test_chat_followup_context_logging.py+++ b/tests/chat/test_chat_followup_context_logging.py@@ -4,9 +4,9 @@ The summary path is otherwise silent (no token-counter entry), so a follow-uplooked like an unexplained pause. One info line per follow-up records what ran."""-from src.local_deep_research.chat.context import ChatContextManager+from local_deep_research.chat.context import ChatContextManager-_LOGGER = "src.local_deep_research.chat.context.logger"+_LOGGER = "local_deep_research.chat.context.logger"def _conversation():diff --git a/tests/chat/test_chat_fuzz.py b/tests/chat/test_chat_fuzz.pyindex 1b2f88574d..a3fee66a08 100644--- a/tests/chat/test_chat_fuzz.py+++ b/tests/chat/test_chat_fuzz.py@@ -88,7 +88,7 @@ class TestChatContextManagerFuzz:self, messages, accumulated):"""Test that build_research_context never crashes on arbitrary input."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagertry:manager = ChatContextManager(@@ -112,7 +112,7 @@ class TestChatContextManagerFuzz:@settings(max_examples=50, suppress_health_check=[HealthCheck.too_slow])def test_accumulated_context_handles_arbitrary_data(self, accumulated):"""Test that accumulated context with arbitrary data is handled."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagertry:manager = ChatContextManager(@@ -138,7 +138,7 @@ class TestChatContextManagerFuzz:@settings(max_examples=50, suppress_health_check=[HealthCheck.too_slow])def test_create_summary_handles_arbitrary_content(self, content):"""Test that summary creation handles arbitrary content."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagertry:manager = ChatContextManager("test-session", [], {})@@ -156,7 +156,7 @@ class TestChatContextManagerFuzz:@settings(max_examples=30, suppress_health_check=[HealthCheck.too_slow])def test_extract_context_updates_handles_arbitrary_input(self, content):"""Test that context update extraction handles arbitrary input."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagertry:manager = ChatContextManager("test-session", [], {})@@ -186,7 +186,7 @@ class TestChatServiceFuzz:@settings(max_examples=50, suppress_health_check=[HealthCheck.too_slow])def test_title_generation_handles_any_string(self, query):"""Test that title generation handles any input string."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicetry:service = ChatService(username="test_user")@@ -208,7 +208,7 @@ class TestChatServiceFuzz:@settings(max_examples=30, suppress_health_check=[HealthCheck.too_slow])def test_add_message_handles_unicode(self, content, role, message_type):"""Test that add_message handles various Unicode content."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatService# Skip empty content for valid messagesassume(len(content.strip()) > 0)@@ -226,7 +226,7 @@ class TestChatServiceFuzz:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):try:@@ -422,7 +422,7 @@ class TestPromptContextFuzz:@settings(max_examples=20, suppress_health_check=[HealthCheck.too_slow])def test_findings_extraction_handles_many_messages(self, messages):"""Test that findings extraction handles many messages."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagertry:manager = ChatContextManager("test-session", messages, {})@@ -445,7 +445,7 @@ class TestEdgeCases:def test_empty_messages_list(self):"""Test handling of empty messages list."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager("test-session", [], {})context = manager.build_research_context()@@ -455,7 +455,7 @@ class TestEdgeCases:def test_none_messages_list(self):"""Test handling of None messages."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager("test-session", None, {})context = manager.build_research_context()@@ -464,7 +464,7 @@ class TestEdgeCases:def test_none_accumulated_context(self):"""Test handling of None accumulated context."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager("test-session", [], None)entities = manager._get_key_entities()@@ -475,7 +475,7 @@ class TestEdgeCases:def test_very_long_content_truncation(self):"""Test that very long content is properly truncated."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManager# Create message with very long contentlong_content = "A" * 10000@@ -497,7 +497,7 @@ class TestEdgeCases:def test_special_characters_in_entities(self):"""Test handling of special characters in entities."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManageraccumulated = {"key_entities": [diff --git a/tests/chat/test_chat_research_history_integration.py b/tests/chat/test_chat_research_history_integration.pyindex f9b1304c02..832eab90db 100644--- a/tests/chat/test_chat_research_history_integration.py+++ b/tests/chat/test_chat_research_history_integration.py@@ -18,7 +18,7 @@ class TestResearchHistoryLinking:def test_message_stores_research_id(self):"""Test that message with research correctly stores research_id."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_session = MagicMock()captured_message = None@@ -43,7 +43,7 @@ class TestResearchHistoryLinking:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="test_user")@@ -62,7 +62,7 @@ class TestResearchHistoryLinking:def test_message_with_research_id_increments_message_count(self):"""Test that session message count is incremented when research_id is set."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicefrom tests.chat.conftest import setup_query_mock_with_sessionmock_session = MagicMock()@@ -79,7 +79,7 @@ class TestResearchHistoryLinking:yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",mock_get_user_db_session,):service = ChatService(username="test_user")diff --git a/tests/chat/test_chat_research_integration.py b/tests/chat/test_chat_research_integration.pyindex 7224f01f33..b098ba1ea9 100644--- a/tests/chat/test_chat_research_integration.py+++ b/tests/chat/test_chat_research_integration.py@@ -9,7 +9,7 @@ class TestResearchIntegration:def test_research_context_built_from_conversation_history(self):"""Test that research context reflects the conversation turns."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermessages = [{@@ -56,7 +56,7 @@ class TestResearchIntegration:def test_context_includes_previous_research_findings(self):"""Test that context includes findings from previous research."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermessages = [{@@ -90,7 +90,7 @@ class TestResearchIntegration:def test_multi_turn_flag_correct_for_first_message(self):"""Test that is_multi_turn is False for first message."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="test-session",@@ -105,7 +105,7 @@ class TestResearchIntegration:def test_multi_turn_flag_correct_for_followup(self):"""Test that is_multi_turn is True for follow-up messages."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermessages = [{@@ -140,7 +140,7 @@ class TestContextExtraction:def test_extract_context_updates_from_new_research(self):"""Test extracting context updates from new research content."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermanager = ChatContextManager(session_id="test-session",diff --git a/tests/chat/test_chat_route_helpers.py b/tests/chat/test_chat_route_helpers.pyindex c8f9df00a0..37fa25172f 100644--- a/tests/chat/test_chat_route_helpers.py+++ b/tests/chat/test_chat_route_helpers.py@@ -13,14 +13,14 @@ class TestParseIntParam:def test_parse_int_param_valid_value(self):"""Test parsing a valid integer string."""- from src.local_deep_research.chat.routes import _parse_int_param+ from local_deep_research.chat.routes import _parse_int_paramresult = _parse_int_param("42", default=10)assert result == 42def test_parse_int_param_default_on_invalid(self):"""Test that invalid values return the default."""- from src.local_deep_research.chat.routes import _parse_int_param+ from local_deep_research.chat.routes import _parse_int_param# Non-numeric stringresult = _parse_int_param("abc", default=10)@@ -32,7 +32,7 @@ class TestParseIntParam:def test_parse_int_param_respects_min_val(self):"""Test that values below min_val are clamped."""- from src.local_deep_research.chat.routes import _parse_int_param+ from local_deep_research.chat.routes import _parse_int_param# Value below minimumresult = _parse_int_param("-5", default=10, min_val=0)@@ -44,7 +44,7 @@ class TestParseIntParam:def test_parse_int_param_respects_max_val(self):"""Test that values above max_val are clamped."""- from src.local_deep_research.chat.routes import _parse_int_param+ from local_deep_research.chat.routes import _parse_int_param# Value above maximumresult = _parse_int_param("200", default=10, min_val=0, max_val=100)@@ -56,14 +56,14 @@ class TestParseIntParam:def test_parse_int_param_handles_none(self):"""Test that None values return the default."""- from src.local_deep_research.chat.routes import _parse_int_param+ from local_deep_research.chat.routes import _parse_int_paramresult = _parse_int_param(None, default=25)assert result == 25def test_parse_int_param_handles_float_string(self):"""Test that float strings fall back to default."""- from src.local_deep_research.chat.routes import _parse_int_param+ from local_deep_research.chat.routes import _parse_int_paramresult = _parse_int_param("3.14", default=10)assert result == 10diff --git a/tests/chat/test_chat_send_message_reclaim.py b/tests/chat/test_chat_send_message_reclaim.pyindex 4bd0314aa4..7e1013a24b 100644--- a/tests/chat/test_chat_send_message_reclaim.py+++ b/tests/chat/test_chat_send_message_reclaim.py@@ -29,14 +29,14 @@ import uuidfrom datetime import datetime, timedelta, UTCfrom unittest.mock import patch-from src.local_deep_research.constants import ResearchStatus-from src.local_deep_research.database.models import (+from local_deep_research.constants import ResearchStatus+from local_deep_research.database.models import (ChatSession,ChatSessionStatus,ResearchHistory,UserActiveResearch,)-from src.local_deep_research.web.routes.globals import (+from local_deep_research.web.routes.globals import (is_research_thread_alive,reclaim_stale_user_active_research,)@@ -177,7 +177,7 @@ def test_reclaim_skips_live_thread(setup_database_for_all_tests):)with patch(- "src.local_deep_research.web.routes.globals.is_research_thread_alive",+ "local_deep_research.web.routes.globals.is_research_thread_alive",return_value=True,):with SessionLocal() as db:diff --git a/tests/chat/test_chat_service.py b/tests/chat/test_chat_service.pyindex 77a7654194..3b9ec8eeaa 100644--- a/tests/chat/test_chat_service.py+++ b/tests/chat/test_chat_service.py@@ -14,7 +14,7 @@ class TestChatServiceSessionCreation:def test_create_session_returns_uuid(self, mock_user_db_session):"""Test that create_session returns a valid UUID."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -31,7 +31,7 @@ class TestChatServiceSessionCreation:def test_create_session_with_initial_query(self, mock_user_db_session):"""Test creating a session with an initial query."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -46,7 +46,7 @@ class TestChatServiceSessionCreation:def test_create_session_with_custom_title(self, mock_user_db_session):"""Test creating a session with a custom title."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -63,7 +63,7 @@ class TestChatServiceSessionCreation:self, mock_user_db_session, long_query_text):"""Test that title is generated from query and truncated to 100 chars + '...'."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -90,7 +90,7 @@ class TestChatServiceSessionCreation:self, mock_user_db_session):"""Test that title is generated in format 'Chat YYYY-MM-DD HH:MM' when no query."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -110,7 +110,7 @@ class TestChatServiceSessionCreation:self, mock_user_db_session):"""Test that accumulated_context is initialized with proper structure."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -137,7 +137,7 @@ class TestChatServiceAddMessage:self, mock_user_db_session, mock_chat_session):"""Test that add_message returns a valid UUID."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatService# Set up query mock to return session (handles with_for_update)setup_query_mock_with_session(mock_user_db_session, mock_chat_session)@@ -162,7 +162,7 @@ class TestChatServiceAddMessage:self, mock_user_db_session, mock_chat_session):"""Test that sequence number increments with each message."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_chat_session.message_count = 5setup_query_mock_with_session(mock_user_db_session, mock_chat_session)@@ -186,7 +186,7 @@ class TestChatServiceAddMessage:self, mock_user_db_session, mock_chat_session):"""Test that session message_count is updated."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_chat_session.message_count = 5setup_query_mock_with_session(mock_user_db_session, mock_chat_session)@@ -206,7 +206,7 @@ class TestChatServiceAddMessage:def test_add_message_raises_for_invalid_session(self, mock_user_db_session):"""Test that add_message raises ValueError for non-existent session."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatService# Set up query mock to return None (session not found)setup_query_mock_with_session(mock_user_db_session, None)@@ -231,7 +231,7 @@ class TestChatServiceContextAccumulation:self, mock_user_db_session, mock_chat_session):"""Test that new entities are added to accumulated context."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_chat_session.accumulated_context = {"key_entities": ["entity1"],@@ -266,7 +266,7 @@ class TestChatServiceContextAccumulation:self, mock_user_db_session, mock_chat_session):"""Test that entities are limited to 50."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_chat_session.accumulated_context = {"key_entities": [],@@ -291,7 +291,7 @@ class TestChatServiceContextAccumulation:self, mock_user_db_session, mock_chat_session):"""Test that topics are limited to 20."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_chat_session.accumulated_context = {"key_entities": [],@@ -316,7 +316,7 @@ class TestChatServiceContextAccumulation:self, mock_user_db_session, mock_chat_session):"""Test that summary is truncated to 8000 characters."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_chat_session.accumulated_context = {"key_entities": [],@@ -345,7 +345,7 @@ class TestChatServiceGetSession:self, mock_user_db_session, mock_chat_session):"""Test that get_session returns the correct session as a dict."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicequery_mock = MagicMock()query_mock.filter_by.return_value.first.return_value = mock_chat_session@@ -364,7 +364,7 @@ class TestChatServiceGetSession:):"""Test that get_session raises ChatSessionNotFound for missing rows."""import pytest- from src.local_deep_research.chat.service import (+ from local_deep_research.chat.service import (ChatService,ChatSessionNotFound,)@@ -387,7 +387,7 @@ class TestChatServiceGetSessionMessages:):"""get_session_messages does TWO queries (ChatMessage+ ChatProgressStep). Helper sets up the side_effect to dispatch."""- from src.local_deep_research.database.models import (+ from local_deep_research.database.models import (ChatMessage,ChatProgressStep,)@@ -412,7 +412,7 @@ class TestChatServiceGetSessionMessages:self, mock_user_db_session, sample_messages):"""Test that get_session_messages returns messages in order."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_messages = []for msg in sample_messages:@@ -432,7 +432,7 @@ class TestChatServiceGetSessionMessages:self, mock_user_db_session):"""Test that get_session_messages returns empty list when no messages."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceself._setup_query_side_effect(mock_user_db_session, [], [])@@ -445,7 +445,7 @@ class TestChatServiceGetSessionMessages:self, mock_user_db_session, sample_messages):"""Test that get_session_messages respects limit and offset."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_messages = []for msg in sample_messages[:2]:@@ -472,8 +472,8 @@ class TestChatServiceGetSessionMessages:milestones. The merged stream must surface step entries withthat exact discriminator value."""- from src.local_deep_research.chat.service import ChatService- from src.local_deep_research.database.models import (+ from local_deep_research.chat.service import ChatService+ from local_deep_research.database.models import (ChatMessage,ChatProgressStep,)@@ -565,7 +565,7 @@ class TestChatServiceTitleGeneration:generation out of the POST /api/chat/sessions path so the HTTPresponse isn't blocked on a model round-trip."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.add = MagicMock()mock_user_db_session.commit = MagicMock()@@ -573,7 +573,7 @@ class TestChatServiceTitleGeneration:settings_snapshot = {"chat.llm_title_generation": {"value": True}}with patch(- "src.local_deep_research.config.llm_config.get_llm"+ "local_deep_research.config.llm_config.get_llm") as mock_get_llm:service = ChatService(username="testuser")service.create_session(@@ -587,7 +587,7 @@ class TestChatServiceTitleGeneration:self, mock_user_db_session, mock_chat_session):"""regenerate_title_with_llm writes the LLM-returned title to the session."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatService# Title must equal the non-LLM fallback so the idempotency check# at the top of regenerate_title_with_llm doesn't short-circuit.@@ -605,11 +605,11 @@ class TestChatServiceTitleGeneration:with (patch(- "src.local_deep_research.config.llm_config.get_llm",+ "local_deep_research.config.llm_config.get_llm",return_value=fake_llm,),patch(- "src.local_deep_research.config.thread_settings.get_setting_from_snapshot",+ "local_deep_research.config.thread_settings.get_setting_from_snapshot",return_value=True,),):@@ -636,7 +636,7 @@ class TestChatServiceTitleGeneration:second log entry in aggregators (log injection). The storedtitle must have all CR/LF flattened to spaces."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicequery = "Does quantum entanglement violate locality?"mock_chat_session.title = query # equals fallback → not skipped@@ -654,11 +654,11 @@ class TestChatServiceTitleGeneration:with (patch(- "src.local_deep_research.config.llm_config.get_llm",+ "local_deep_research.config.llm_config.get_llm",return_value=fake_llm,),patch(- "src.local_deep_research.config.thread_settings.get_setting_from_snapshot",+ "local_deep_research.config.thread_settings.get_setting_from_snapshot",return_value=True,),):@@ -685,7 +685,7 @@ class TestChatServiceTitleGeneration:"""If the title no longer matches the non-LLM fallback (because theuser manually edited it, or a sibling tab's LLM-gen already ran),skip the LLM call to avoid burning credits to overwrite their work."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicequery = "Does quantum entanglement violate locality?"mock_chat_session.title = "My Custom Title" # user-edited@@ -696,11 +696,11 @@ class TestChatServiceTitleGeneration:with (patch(- "src.local_deep_research.config.llm_config.get_llm",+ "local_deep_research.config.llm_config.get_llm",return_value=fake_llm,),patch(- "src.local_deep_research.config.thread_settings.get_setting_from_snapshot",+ "local_deep_research.config.thread_settings.get_setting_from_snapshot",return_value=True,),):@@ -722,7 +722,7 @@ class TestChatServiceTitleGeneration:self, mock_user_db_session):"""Empty query → None (no LLM call, no DB write)."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceservice = ChatService(username="testuser")assert (@@ -753,7 +753,7 @@ class TestChatMessageEnumValidation:from datetime import datetime as _dt, UTC as _utcfrom sqlalchemy import create_enginefrom sqlalchemy.orm import sessionmaker- from src.local_deep_research.database.models import (+ from local_deep_research.database.models import (Base,ChatSession,)@@ -786,7 +786,7 @@ class TestChatMessageEnumValidation:def test_add_message_rejects_invalid_role(self, tmp_path):"""Unknown role → ValueError (which routes map to HTTP 400)."""from contextlib import contextmanager- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceengine, Session, session_id = self._setup_real_db(tmp_path)@@ -797,7 +797,7 @@ class TestChatMessageEnumValidation:service = ChatService(username="testuser")with patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",real_get_user_db_session,):with pytest.raises(ValueError, match="Invalid role"):@@ -812,7 +812,7 @@ class TestChatMessageEnumValidation:def test_add_message_rejects_invalid_message_type(self, tmp_path):"""Unknown message_type → ValueError."""from contextlib import contextmanager- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceengine, Session, session_id = self._setup_real_db(tmp_path)@@ -823,7 +823,7 @@ class TestChatMessageEnumValidation:service = ChatService(username="testuser")with patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",real_get_user_db_session,):with pytest.raises(ValueError, match="Invalid message_type"):@@ -838,8 +838,8 @@ class TestChatMessageEnumValidation:def test_add_message_accepts_string_values(self, tmp_path):"""Valid string values are coerced to enum members transparently."""from contextlib import contextmanager- from src.local_deep_research.chat.service import ChatService- from src.local_deep_research.database.models import (+ from local_deep_research.chat.service import ChatService+ from local_deep_research.database.models import (ChatMessage,ChatMessageType,ChatRole,@@ -854,7 +854,7 @@ class TestChatMessageEnumValidation:service = ChatService(username="testuser")with patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",real_get_user_db_session,):service.add_message(@@ -887,7 +887,7 @@ class TestChatServiceGetInProgressResearchId:def test_returns_none_when_no_in_progress_research(self, mock_user_db_session):- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.query.return_value.filter.return_value.first.return_value = None@@ -897,7 +897,7 @@ class TestChatServiceGetInProgressResearchId:def test_returns_id_when_in_progress_research_exists(self, mock_user_db_session):- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.query.return_value.filter.return_value.first.return_value = ("research-abc-123",@@ -919,7 +919,7 @@ class TestChatServiceGetInProgressResearchId:import pytestfrom sqlalchemy.exc import OperationalError- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicemock_user_db_session.query.side_effect = OperationalError("stmt", {}, Exception("boom")@@ -935,9 +935,9 @@ class TestChatServiceGetInProgressResearchId:"""Locks the query shape against accidental regressions — thepartial-unique-index lookup depends on the predicate matchingthe index's WHERE clause exactly."""- from src.local_deep_research.chat.service import ChatService- from src.local_deep_research.constants import ResearchStatus- from src.local_deep_research.database.models import ResearchHistory+ from local_deep_research.chat.service import ChatService+ from local_deep_research.constants import ResearchStatus+ from local_deep_research.database.models import ResearchHistoryquery_mock = MagicMock()query_mock.filter.return_value.first.return_value = Nonediff --git a/tests/chat/test_chat_settings_integration.py b/tests/chat/test_chat_settings_integration.pyindex 96c191121e..9c52fd8932 100644--- a/tests/chat/test_chat_settings_integration.py+++ b/tests/chat/test_chat_settings_integration.py@@ -21,7 +21,7 @@ class TestLoadSettingsHelper:so a UI setting change just before the chat send takes effect onthe very next research run (matches the behaviour of``research_routes.start_research``)."""- from src.local_deep_research.chat import routes as chat_routes+ from local_deep_research.chat import routes as chat_routeswith (patch.object(chat_routes, "get_user_db_session") as mock_get_db,@@ -52,7 +52,7 @@ class TestLoadSettingsHelper:backs the snapshot semantics relied on by the research pipeline,where the snapshot is supposed to survive global setting changesthat happen during the research run."""- from src.local_deep_research.chat import routes as chat_routes+ from local_deep_research.chat import routes as chat_routessnapshots: list[dict] = [{"llm.model": {"value": "first"}},diff --git a/tests/chat/test_chat_socket_events.py b/tests/chat/test_chat_socket_events.pyindex 266f3cb23a..6bcd79dfe1 100644--- a/tests/chat/test_chat_socket_events.py+++ b/tests/chat/test_chat_socket_events.py@@ -12,7 +12,7 @@ from unittest.mock import MagicMock, patchimport pytest-from src.local_deep_research.web.services.socket_service import SocketIOService+from local_deep_research.web.services.socket_service import SocketIOService@pytest.fixture(autouse=True)@@ -35,18 +35,18 @@ class TestSocketIOHandlers:def test_on_connect_logs_client_sid(self, app):"""Test that client connection is logged with SID."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)with patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class:mock_socketio = MagicMock()mock_socketio_class.return_value = mock_socketiowith patch(- "src.local_deep_research.web.services.socket_service.logger"+ "local_deep_research.web.services.socket_service.logger") as mock_logger:service = SocketIOService(app=app)@@ -75,7 +75,7 @@ class TestSocketIOHandlers:def test_on_disconnect_cleans_up_subscriptions(self):"""Test that client disconnection cleans up subscriptions."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -83,7 +83,7 @@ class TestSocketIOHandlers:mock_app.config = {"SECRET_KEY": "test-secret"}with patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class:mock_socketio = MagicMock()mock_socketio_class.return_value = mock_socketio@@ -113,7 +113,7 @@ class TestSocketIOHandlers:def test_on_subscribe_adds_to_subscription_set(self):"""Test that subscribe event adds client to subscription set."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -122,17 +122,17 @@ class TestSocketIOHandlers:with (patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class,patch(- "src.local_deep_research.web.services.socket_service.session",+ "local_deep_research.web.services.socket_service.session",{"username": "alice", "session_id": "sess-alice"},),patch.object(SocketIOService, "_user_owns_research", return_value=True),patch(- "src.local_deep_research.web.auth.session_manager."+ "local_deep_research.web.auth.session_manager.""session_manager.validate_session",return_value="alice",),@@ -157,7 +157,7 @@ class TestSocketIOHandlers:def test_on_subscribe_sends_current_status_if_available(self):"""Test that subscribe sends current status when research is active."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -166,17 +166,17 @@ class TestSocketIOHandlers:with (patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class,patch(- "src.local_deep_research.web.services.socket_service.session",+ "local_deep_research.web.services.socket_service.session",{"username": "alice", "session_id": "sess-alice"},),patch.object(SocketIOService, "_user_owns_research", return_value=True),patch(- "src.local_deep_research.web.auth.session_manager."+ "local_deep_research.web.auth.session_manager.""session_manager.validate_session",return_value="alice",),@@ -185,7 +185,7 @@ class TestSocketIOHandlers:mock_socketio_class.return_value = mock_socketiowith patch(- "src.local_deep_research.web.services.socket_service.get_active_research_snapshot"+ "local_deep_research.web.services.socket_service.get_active_research_snapshot") as mock_snapshot:mock_snapshot.return_value = {"progress": 50,@@ -207,7 +207,7 @@ class TestSocketIOHandlers:def test_emit_to_subscribers_broadcasts_to_room(self):"""Test that emit_to_subscribers broadcasts to all subscribers."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -215,7 +215,7 @@ class TestSocketIOHandlers:mock_app.config = {"SECRET_KEY": "test-secret"}with patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class:mock_socketio = MagicMock()mock_socketio_class.return_value = mock_socketio@@ -243,7 +243,7 @@ class TestSocketIOHandlers:def test_emit_socket_event_handles_exceptions(self):"""Test that emit_socket_event handles exceptions gracefully."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -251,7 +251,7 @@ class TestSocketIOHandlers:mock_app.config = {"SECRET_KEY": "test-secret"}with patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class:mock_socketio = MagicMock()mock_socketio.emit.side_effect = Exception("Network error")@@ -266,7 +266,7 @@ class TestSocketIOHandlers:def test_concurrent_subscribe_unsubscribe_thread_safety(self):"""Test that concurrent subscribe/unsubscribe operations are thread-safe."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -275,17 +275,17 @@ class TestSocketIOHandlers:with (patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class,patch(- "src.local_deep_research.web.services.socket_service.session",+ "local_deep_research.web.services.socket_service.session",{"username": "alice", "session_id": "sess-alice"},),patch.object(SocketIOService, "_user_owns_research", return_value=True),patch(- "src.local_deep_research.web.auth.session_manager."+ "local_deep_research.web.auth.session_manager.""session_manager.validate_session",return_value="alice",),@@ -336,7 +336,7 @@ class TestSocketIOHandlers:def test_subscription_cleanup_on_error(self):"""Test that subscriptions are cleaned up even if emit fails."""- from src.local_deep_research.web.services.socket_service import (+ from local_deep_research.web.services.socket_service import (SocketIOService,)@@ -345,17 +345,17 @@ class TestSocketIOHandlers:with (patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class,patch(- "src.local_deep_research.web.services.socket_service.session",+ "local_deep_research.web.services.socket_service.session",{"username": "alice", "session_id": "sess-alice"},),patch.object(SocketIOService, "_user_owns_research", return_value=True),patch(- "src.local_deep_research.web.auth.session_manager."+ "local_deep_research.web.auth.session_manager.""session_manager.validate_session",return_value="alice",),@@ -383,7 +383,7 @@ class TestSocketIOHandlers:# Now disconnect - should clean up even with errorswith patch(- "src.local_deep_research.web.services.socket_service.logger"+ "local_deep_research.web.services.socket_service.logger"):service._SocketIOService__handle_disconnect(mock_request, "close"diff --git a/tests/chat/test_chat_user_isolation.py b/tests/chat/test_chat_user_isolation.pyindex e1a3403583..0ee1e92b77 100644--- a/tests/chat/test_chat_user_isolation.py+++ b/tests/chat/test_chat_user_isolation.py@@ -20,7 +20,7 @@ from unittest.mock import MagicMock, patchimport pytestfrom sqlalchemy.exc import SQLAlchemyError-from src.local_deep_research.chat.service import ChatSessionNotFound+from local_deep_research.chat.service import ChatSessionNotFound# Exceptions every isolation test must tolerate: the MagicMock query# chains don't match the real SQLAlchemy shape used by some methods, so@@ -50,7 +50,7 @@ def username_capturing_db():yield mock_sessionwith patch(- "src.local_deep_research.chat.service.get_user_db_session",+ "local_deep_research.chat.service.get_user_db_session",_fake_get_user_db_session,):yield captured, mock_session@@ -63,7 +63,7 @@ class TestUserIsolation:self, username_capturing_db):"""get_session queries the correct user's database."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, mock_session = username_capturing_dbmock_session.query.return_value.filter_by.return_value.first.return_value = None@@ -78,7 +78,7 @@ class TestUserIsolation:self, username_capturing_db):"""get_session_messages queries the correct user's database."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, _ = username_capturing_db@@ -92,7 +92,7 @@ class TestUserIsolation:self, username_capturing_db):"""list_sessions queries the correct user's database."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, _ = username_capturing_db@@ -106,7 +106,7 @@ class TestUserIsolation:self, username_capturing_db):"""update_accumulated_context queries the correct user's database."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, mock_session = username_capturing_dbmock_session.query.return_value.filter_by.return_value.with_for_update.return_value.first.return_value = None@@ -121,7 +121,7 @@ class TestUserIsolation:self, username_capturing_db):"""delete_session queries the correct user's database."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, mock_session = username_capturing_dbmock_session.query.return_value.filter_by.return_value.first.return_value = None@@ -139,7 +139,7 @@ class TestCrossUserAccess:self, username_capturing_db):"""Different ChatService instances use their own usernames."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, _ = username_capturing_db@@ -158,7 +158,7 @@ class TestCrossUserAccess:self, username_capturing_db):"""All CRUD operations consistently use the service username."""- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServicecaptured, mock_session = username_capturing_dbmock_session.query.return_value.filter_by.return_value.first.return_value = Nonediff --git a/tests/chat/test_chat_xss_prevention.py b/tests/chat/test_chat_xss_prevention.pyindex a878d47450..8306293425 100644--- a/tests/chat/test_chat_xss_prevention.py+++ b/tests/chat/test_chat_xss_prevention.py@@ -229,7 +229,7 @@ class TestContextManagerXSS:def test_xss_in_messages_handled_in_context(self):"""Test that XSS in messages doesn't affect context building."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManagermessages = [{@@ -259,7 +259,7 @@ class TestContextManagerXSS:def test_xss_in_accumulated_context(self):"""Test that XSS in accumulated context is handled safely."""- from src.local_deep_research.chat.context import ChatContextManager+ from local_deep_research.chat.context import ChatContextManageraccumulated = {"key_entities": [diff --git a/tests/database/test_chat_models.py b/tests/database/test_chat_models.pyindex a69de41964..a22b2b46dd 100644--- a/tests/database/test_chat_models.py+++ b/tests/database/test_chat_models.py@@ -10,7 +10,7 @@ class TestChatSessionModel:def test_chat_session_table_exists(self, setup_database_for_all_tests):"""Test that the chat_sessions table exists in the database."""- from src.local_deep_research.database.models import Base+ from local_deep_research.database.models import Base# Get all table names from metadatatable_names = set(Base.metadata.tables.keys())@@ -24,7 +24,7 @@ class TestChatSessionModel:self, setup_database_for_all_tests):"""Test that ChatSession has all required columns."""- from src.local_deep_research.database.models.chat import ChatSession+ from local_deep_research.database.models.chat import ChatSessionrequired_columns = {"id",@@ -47,7 +47,7 @@ class TestChatSessionModel:):"""Test that accumulated_context JSON field serializes correctly."""from datetime import datetime, UTC- from src.local_deep_research.database.models.chat import ChatSession+ from local_deep_research.database.models.chat import ChatSessionSessionLocal = setup_database_for_all_testssession = SessionLocal()@@ -85,7 +85,7 @@ class TestChatSessionModel:):"""Test that default status is 'active'."""from datetime import datetime, UTC- from src.local_deep_research.database.models.chat import ChatSession+ from local_deep_research.database.models.chat import ChatSessionSessionLocal = setup_database_for_all_testssession = SessionLocal()@@ -116,7 +116,7 @@ class TestChatMessageModel:def test_chat_message_table_exists(self, setup_database_for_all_tests):"""Test that the chat_messages table exists in the database."""- from src.local_deep_research.database.models import Base+ from local_deep_research.database.models import Basetable_names = set(Base.metadata.tables.keys())@@ -129,7 +129,7 @@ class TestChatMessageModel:self, setup_database_for_all_tests):"""Test that ChatMessage has all required columns."""- from src.local_deep_research.database.models.chat import ChatMessage+ from local_deep_research.database.models.chat import ChatMessagerequired_columns = {"id",@@ -153,7 +153,7 @@ class TestChatMessageModel:self, setup_database_for_all_tests):"""Test that ChatMessage has foreign key relationship to ChatSession."""- from src.local_deep_research.database.models.chat import ChatMessage+ from local_deep_research.database.models.chat import ChatMessage# Check foreign keysforeign_keys = [@@ -169,7 +169,7 @@ class TestChatMessageModel:):"""Test that research_id column is nullable."""from datetime import datetime, UTC- from src.local_deep_research.database.models.chat import (+ from local_deep_research.database.models.chat import (ChatMessage,ChatSession,)@@ -224,7 +224,7 @@ class TestChatModelCascade:):"""Test that deleting a session also deletes its messages."""from datetime import datetime, UTC- from src.local_deep_research.database.models.chat import (+ from local_deep_research.database.models.chat import (ChatSession,ChatMessage,)@@ -286,7 +286,7 @@ class TestChatModelCascade:):"""Test that messages are properly ordered by sequence number."""from datetime import datetime, UTC- from src.local_deep_research.database.models.chat import (+ from local_deep_research.database.models.chat import (ChatSession,ChatMessage,)@@ -343,7 +343,7 @@ class TestChatSessionStatus:def test_session_can_be_archived(self, setup_database_for_all_tests):"""Test that a session status can be changed to 'archived'."""from datetime import datetime, UTC- from src.local_deep_research.database.models.chat import ChatSession+ from local_deep_research.database.models.chat import ChatSessionSessionLocal = setup_database_for_all_testssession = SessionLocal()@@ -389,7 +389,7 @@ class TestChatMessageContentNotNull:import pytestfrom datetime import datetime, UTCfrom sqlalchemy.exc import IntegrityError- from src.local_deep_research.database.models.chat import (+ from local_deep_research.database.models.chat import (ChatMessage,ChatSession,)@@ -426,7 +426,7 @@ class TestChatMessageContentNotNull:"""ChatService.add_message validates content!=None before any DBwrite, raising ValueError so the route layer can surface a 400."""import pytest- from src.local_deep_research.chat.service import ChatService+ from local_deep_research.chat.service import ChatServiceservice = ChatService(username="not-real-for-validator-test")with pytest.raises(ValueError, match="content is required"):@@ -451,7 +451,7 @@ class TestChatMessageContentNotNull:@pytest.fixturedef fk_enforced_engine(tmp_path):"""Fresh-install SQLite engine with FK enforcement on for every connection."""- from src.local_deep_research.database.models import Base+ from local_deep_research.database.models import Basedb_path = tmp_path / "fk_test.db"engine = create_engine(f"sqlite:///{db_path}")diff --git a/tests/news/test_document_scheduler_settings.py b/tests/news/test_document_scheduler_settings.pyindex 0a02f49229..c9c050372e 100644--- a/tests/news/test_document_scheduler_settings.py+++ b/tests/news/test_document_scheduler_settings.py@@ -8,7 +8,7 @@ from dataclasses import FrozenInstanceErrorimport pytest-from src.local_deep_research.scheduler.background import (+from local_deep_research.scheduler.background import (DocumentSchedulerSettings,)diff --git a/tests/notifications/test_notification_webhook_dns_pin.py b/tests/notifications/test_notification_webhook_dns_pin.pynew file mode 100644index 0000000000..7da278edc6--- /dev/null+++ b/tests/notifications/test_notification_webhook_dns_pin.py@@ -0,0 +1,1302 @@+"""SSRF hardening for the notification (Apprise) delivery path.++These tests prove that the DNS pin + block-private send window+(``security.dns_pinning`` + ``notifications.service``) close the+resolve-vs-connect / DNS-rebinding TOCTOU that Apprise's own send-time+re-resolution would otherwise reopen:++* the ``getaddrinfo`` shim actually intercepts *Apprise's* resolution+ (Apprise is forced synchronous/in-thread so the thread-local guard+ applies) — an end-to-end ``json://`` webhook is delivered, rebound, and+ redirected through the real Apprise + ``requests`` stack;+* a host that validated public but rebinds to a private/metadata IP is+ refused before any connection;+* a webhook that redirects to an internal IP is refused at the socket+ layer during the window;+* plugin schemes with a token "host" (``discord://``) are never resolved+ as a hostname (not broken by pinning); and+* TLS SNI + certificate verification still use the original hostname while+ the socket connects to the pinned IP.+"""++import contextlib+import datetime+import ipaddress+import socket+import ssl+import threading+import time+from http.server import BaseHTTPRequestHandler, HTTPServer+from unittest.mock import patch++import apprise+import pytest+import requests+from cryptography import x509+from cryptography.hazmat.primitives import hashes, serialization+from cryptography.hazmat.primitives.asymmetric import rsa+from cryptography.x509.oid import NameOID++from local_deep_research.notifications.exceptions import SendError, ServiceError+from local_deep_research.notifications.service import NotificationService+from local_deep_research.security import dns_pinning+++# --------------------------------------------------------------------------+# Test doubles+# --------------------------------------------------------------------------+class _Resolver:+ """Drive ``dns_pinning._real_getaddrinfo`` with scripted answers.++ ``answers`` maps host -> list of successive answers (each a list of IP+ strings). Each lookup consumes the next answer; the final answer sticks+ for every later call, so a two-element list simulates a rebind that then+ stays put (validation sees answer #1, the pin/send sees answer #2).+ """++ def __init__(self, answers):+ self._answers = {+ h.lower().rstrip("."): list(v) for h, v in answers.items()+ }+ self.calls = []++ def __call__(self, host, port, family=0, type=0, proto=0, flags=0):+ self.calls.append((host, port))+ norm = (host or "").lower().rstrip(".")+ # A numeric IP literal resolves to ITSELF — exactly what the real+ # getaddrinfo does. Without this, a redirect/rebind whose target is a+ # bare IP literal (e.g. 169.254.169.254) would raise "no answer" here+ # BEFORE any block check could run, making such a test pass for the+ # wrong reason (vacuously green even if the block were deleted).+ try:+ ipaddress.ip_address(norm)+ is_literal = True+ except ValueError:+ is_literal = False+ if is_literal:+ ips = [norm]+ else:+ seq = self._answers.get(norm)+ if not seq:+ raise socket.gaierror(+ socket.EAI_NONAME, f"no answer for {host}"+ )+ ips = seq[0] if len(seq) == 1 else seq.pop(0)+ results = []+ for ip in ips:+ fam = socket.AF_INET6 if ":" in ip else socket.AF_INET+ sockaddr = (+ (ip, port or 0, 0, 0)+ if fam == socket.AF_INET6+ else (ip, port or 0)+ )+ results.append(+ (fam, socket.SOCK_STREAM, socket.IPPROTO_TCP, "", sockaddr)+ )+ return results+++class _RecordingHandler(BaseHTTPRequestHandler):+ """200 OK that records every request path it served."""++ hits = None # set on the subclass+ redirect_to = None # optional Location target++ def _handle(self):+ type(self).hits.append(self.path)+ if type(self).redirect_to:+ self.send_response(302)+ self.send_header("Location", type(self).redirect_to)+ self.end_headers()+ return+ body = b"OK"+ self.send_response(200)+ self.send_header("Content-Length", str(len(body)))+ self.end_headers()+ self.wfile.write(body)++ def do_GET(self):+ self._handle()++ def do_POST(self):+ length = int(self.headers.get("Content-Length", 0) or 0)+ if length:+ self.rfile.read(length)+ self._handle()++ def log_message(self, *args):+ pass+++def _start_server(redirect_to=None, tls_cert=None):+ """Start a loopback HTTP(S) server; return (server, port, hits)."""+ hits = []+ handler = type(+ "BoundHandler",+ (_RecordingHandler,),+ {"hits": hits, "redirect_to": redirect_to},+ )+ server = HTTPServer(("127.0.0.1", 0), handler)+ if tls_cert is not None:+ cert_file, key_file = tls_cert+ ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)+ ctx.load_cert_chain(certfile=cert_file, keyfile=key_file)+ server.socket = ctx.wrap_socket(server.socket, server_side=True)+ threading.Thread(target=server.serve_forever, daemon=True).start()+ return server, server.server_address[1], hits+++def _make_self_signed_cert(hostname, tmp_path):+ """Mint a self-signed cert (SAN=DNS:hostname); return (cert, key) paths."""+ key = rsa.generate_private_key(public_exponent=65537, key_size=2048)+ name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, hostname)])+ now = datetime.datetime.now(datetime.timezone.utc)+ cert = (+ x509.CertificateBuilder()+ .subject_name(name)+ .issuer_name(name)+ .public_key(key.public_key())+ .serial_number(x509.random_serial_number())+ .not_valid_before(now - datetime.timedelta(minutes=5))+ .not_valid_after(now + datetime.timedelta(days=1))+ .add_extension(+ x509.SubjectAlternativeName([x509.DNSName(hostname)]),+ critical=False,+ )+ .add_extension(+ x509.BasicConstraints(ca=True, path_length=None), critical=True+ )+ .sign(key, hashes.SHA256())+ )+ cert_file = tmp_path / "cert.pem"+ key_file = tmp_path / "key.pem"+ cert_file.write_bytes(cert.public_bytes(serialization.Encoding.PEM))+ key_file.write_bytes(+ key.private_bytes(+ encoding=serialization.Encoding.PEM,+ format=serialization.PrivateFormat.TraditionalOpenSSL,+ encryption_algorithm=serialization.NoEncryption(),+ )+ )+ return str(cert_file), str(key_file)+++def _connect_spy():+ """Record every ``socket.connect`` target address for the duration."""+ targets = []+ real_connect = socket.socket.connect++ def spy(self, address):+ targets.append(address)+ return real_connect(self, address)++ with patch.object(socket.socket, "connect", spy):+ yield targets+++def _service():+ return NotificationService(allow_private_ips=False, outbound_allowed=True)+++# ==========================================================================+# dns_pinning primitives: block_private_resolution+# ==========================================================================+def test_block_private_refuses_metadata_at_socket_layer():+ """An unpinned lookup that resolves to cloud-metadata is refused with a+ gaierror while the block-private window is active (even with+ allow_private_ips=True, metadata is always blocked)."""+ resolver = _Resolver({"redir.example": [["169.254.169.254"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(allow_private_ips=True):+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("redir.example", 80)+ # Outside the window the same lookup resolves normally.+ assert socket.getaddrinfo("redir.example", 80)[0][4][0] == (+ "169.254.169.254"+ )+++def test_block_private_refuses_rfc1918_when_not_opted_in():+ resolver = _Resolver({"redir.example": [["10.1.2.3"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(allow_private_ips=False):+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("redir.example", 80)+++def test_block_private_allows_rfc1918_when_opted_in_but_still_blocks_metadata():+ resolver = _Resolver(+ {"lan.example": [["10.1.2.3"]], "imds.example": [["169.254.169.254"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(allow_private_ips=True):+ # Private allowed under the opt-in...+ assert socket.getaddrinfo("lan.example", 80)[0][4][0] == "10.1.2.3"+ # ...but metadata is still refused.+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("imds.example", 80)+++def test_block_private_passes_public_through():+ resolver = _Resolver({"ok.example": [["93.184.216.34"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(allow_private_ips=False):+ assert (+ socket.getaddrinfo("ok.example", 80)[0][4][0] == "93.184.216.34"+ )+++def test_block_private_is_thread_scoped():+ """The window on one thread must not affect another thread's lookup."""+ resolver = _Resolver({"lan.example": [["10.1.2.3"]]})+ other_result = {}++ def worker():+ # No window active on this thread -> resolves normally.+ other_result["ip"] = socket.getaddrinfo("lan.example", 80)[0][4][0]++ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(allow_private_ips=False):+ t = threading.Thread(target=worker)+ t.start()+ t.join()+ assert other_result["ip"] == "10.1.2.3"+++# ==========================================================================+# dns_pinning primitives: pin_hosts+# ==========================================================================+def test_pin_hosts_pins_only_pinnable_schemes():+ """json:// (raw webhook) is resolved+pinned; discord:// (token host) is+ left untouched — pinning must never try to resolve an opaque token."""+ resolver = _Resolver({"hook.example": [["93.184.216.34"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.pin_hosts(+ ["json://hook.example/x", "discord://webhook_id/token"],+ allow_private_ips=True,+ ):+ # hook.example is pinned; a lookup returns the pinned address+ # without consulting the resolver again.+ calls_before = len(resolver.calls)+ got = socket.getaddrinfo("hook.example", 443)+ assert got[0][4][0] == "93.184.216.34"+ assert len(resolver.calls) == calls_before # served from pin+ # discord's token was never resolved.+ assert not any(h == "webhook_id" for h, _ in resolver.calls)+++def test_pin_hosts_rejects_rebind_to_metadata():+ """A pinnable host that validates public but resolves to metadata at pin+ time is refused (fail closed) before the window is active."""+ resolver = _Resolver({"hook.example": [["169.254.169.254"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with pytest.raises(ValueError, match="SSRF"):+ with dns_pinning.pin_hosts(+ ["json://hook.example/x"], allow_private_ips=True+ ):+ pass+++def test_pin_hosts_skips_unresolvable_host_without_aborting():+ """A host that doesn't resolve right now is skipped (left unpinned), not+ fatal — so a sibling URL in the same batch is unaffected."""+ resolver = _Resolver({"good.example": [["93.184.216.34"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.pin_hosts(+ ["json://dead.example/x", "json://good.example/y"],+ allow_private_ips=True,+ ):+ assert (+ socket.getaddrinfo("good.example", 443)[0][4][0]+ == "93.184.216.34"+ )+++# ==========================================================================+# End-to-end through the real Apprise + requests stack (proves the shim+# intercepts Apprise's own resolution)+# ==========================================================================+def test_public_json_webhook_delivers_through_apprise():+ """A legitimate raw webhook is delivered end-to-end: Apprise resolves the+ host through the shim, connects to the pinned address, and the loopback+ server receives the POST."""+ server, port, hits = _start_server()+ resolver = _Resolver({"good.example": [["127.0.0.1"]]})+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ result = _service().send(+ title="t",+ body="b",+ service_urls=f"json://good.example:{port}/notify",+ )+ assert result is True+ assert hits, "loopback webhook server never received the request"+ finally:+ server.shutdown()+++def test_rebind_to_metadata_blocked_through_apprise():+ """Validation sees a public IP; the pin's connect-time re-validation+ catches the rebind to cloud-metadata and refuses the send before any+ connection is made."""+ resolver = _Resolver(+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://rebind.example/notify",+ )+ assert not any(addr[0] == "169.254.169.254" for addr in targets), (+ f"connected to metadata IP: {targets}"+ )+++def test_multi_url_batch_guards_every_host():+ """A single notify() fans out to several raw-webhook URLs. EVERY host in+ the batch is pinned/checked: one host that rebinds to metadata refuses+ the whole batch (fail closed) and no connection to the metadata IP is+ made — proving the guard is not applied to just the first URL."""+ server, port, _hits = _start_server()+ resolver = _Resolver(+ {+ "a.example": [["127.0.0.1"]],+ "b.example": [["93.184.216.34"], ["169.254.169.254"]],+ }+ )+ urls = f"json://a.example:{port}/x,json://b.example/y"+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(title="t", body="b", service_urls=urls)+ try:+ assert not any(addr[0] == "169.254.169.254" for addr in targets)+ finally:+ server.shutdown()+++def test_redirect_to_metadata_blocked_at_socket_layer():+ """A public webhook host that 302-redirects to a cloud-metadata IP:+ defense-in-depth. Redirect-following is disabled for the send+ (``http_redirects=False`` + per-plugin re-force), so Apprise does NOT+ follow the 302 at all — the initial request to the (pinned) public host+ happens, the send fails on the unfollowed 302, and no connection to the+ metadata IP is ever made. Even if the redirect WERE followed, the+ block-private window would refuse the ``169.254.169.254`` resolution at+ the getaddrinfo layer (the mock resolver now resolves that literal to+ itself, so that block genuinely fires — see+ ``test_block_private_refuses_metadata_at_socket_layer`` for the isolated+ teeth). Two independent layers; this asserts the end-to-end outcome."""+ server, port, hits = _start_server(+ redirect_to="http://169.254.169.254/latest/meta-data/"+ )+ resolver = _Resolver({"public.example": [["127.0.0.1"]]})+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls=f"json://public.example:{port}/hook",+ )+ assert hits, "initial request to the public host never happened"+ assert not any(addr[0] == "169.254.169.254" for addr in targets), (+ f"connected to metadata IP: {targets}"+ )+ finally:+ server.shutdown()+++def test_redirect_following_disabled_by_default():+ """Fix B, isolated from the block-private backstop: a webhook that+ 302-redirects to a target the send window does NOT independently block+ (``redir-target.example`` -> loopback, which the lenient plugin policy+ allows) is still never followed, because redirect-following is disabled+ for the send. So ONLY the redirect-disable stops the second hop — this+ gives fix B clean teeth (deleting the redirect-disable makes the target+ server receive the request and this test fail). Also closes+ redirect-to-arbitrary-public exfil, of which the loopback target is a+ stand-in."""+ target_server, target_port, target_hits = _start_server()+ hook_server, hook_port, hook_hits = _start_server(+ redirect_to=f"http://redir-target.example:{target_port}/pwn"+ )+ resolver = _Resolver(+ {+ "public.example": [["127.0.0.1"]],+ "redir-target.example": [["127.0.0.1"]],+ }+ )+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls=f"json://public.example:{hook_port}/hook",+ )+ assert hook_hits, "initial request to the webhook host never happened"+ assert not target_hits, (+ "redirect was FOLLOWED to the target server "+ f"(hits={target_hits}) — redirect-following was not disabled"+ )+ assert not any(addr[1] == target_port for addr in targets), (+ f"connected to the redirect target port {target_port}: {targets}"+ )+ finally:+ hook_server.shutdown()+ target_server.shutdown()+++def test_redirect_param_yes_cannot_reenable_redirects():+ """Airtight redirect-disable: a user-supplied ``?redirect=yes`` on the+ webhook URL would, via Apprise's per-URL override, normally re-enable+ redirect-following even when the asset default is off. The per-plugin+ re-force (``NotificationService._disable_redirects``) neutralizes it, so+ the redirect is STILL not followed. The redirect target is again a+ loopback stand-in that the block-private window does not itself block, so+ this isolates the re-force (deleting it makes the redirect follow through+ to the target server and this test fail)."""+ target_server, target_port, target_hits = _start_server()+ hook_server, hook_port, hook_hits = _start_server(+ redirect_to=f"http://redir-target.example:{target_port}/pwn"+ )+ resolver = _Resolver(+ {+ "public.example": [["127.0.0.1"]],+ "redir-target.example": [["127.0.0.1"]],+ }+ )+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls=(+ f"json://public.example:{hook_port}"+ "/hook?redirect=yes"+ ),+ )+ assert hook_hits, "initial request to the webhook host never happened"+ assert not target_hits, (+ "?redirect=yes re-enabled redirect-following "+ f"(target hits={target_hits}) — the per-plugin re-force failed"+ )+ assert not any(addr[1] == target_port for addr in targets), (+ f"connected to the redirect target port {target_port}: {targets}"+ )+ finally:+ hook_server.shutdown()+ target_server.shutdown()+++def test_redirect_to_loopback_blocked_for_http_scheme_default_policy():+ """The strict (http/https) policy blocks a redirect to loopback even+ though the plugin policy would allow it. Exercised at the primitive level+ because Apprise does not accept raw http(s):// notification URLs."""+ resolver = _Resolver({"redir.example": [["127.0.0.1"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.pinned_notification_send(+ ["http://public.example/hook"], allow_private_ips=False+ ):+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("redir.example", 80)+++def test_discord_plugin_scheme_not_pinned_and_unaffected():+ """A discord:// URL (hardcoded public endpoint, opaque token host) is a+ plugin scheme, not a raw webhook: pinning must not try to resolve its+ token as a hostname, and the send still reaches Apprise's discord plugin+ with the guard in place."""+ # Empty resolver: any hostname lookup (e.g. the validator's fail-open+ # probe of the token) returns gaierror rather than hitting the network.+ resolver = _Resolver({})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with patch(+ "apprise.plugins.discord.NotifyDiscord.send", return_value=True+ ) as mock_send:+ result = _service().send(+ title="t",+ body="b",+ service_urls="discord://123456789/abcdefg",+ )+ # Delivered (guard did not break the plugin) and the plugin actually ran.+ assert result is True+ assert mock_send.called+++# ==========================================================================+# Fail-closed hardening invariants+# ==========================================================================+def test_pinned_notification_send_fails_closed_when_shim_missing():+ """If ``socket.getaddrinfo`` is no longer our shim (e.g. a late+ gevent/eventlet monkeypatch), the thread-local pin/block would silently+ not apply. pinned_notification_send must REFUSE the send (fail closed)+ rather than proceed unguarded. Teeth: drop the ``_shim_installed`` guard+ and this raises nothing."""+ saved = socket.getaddrinfo+ resolver = _Resolver({}) # empty: any real lookup would gaierror+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ # Displace our shim with a plain non-shim resolver.+ socket.getaddrinfo = resolver+ assert not dns_pinning._shim_installed()+ with pytest.raises(RuntimeError, match="shim"):+ with dns_pinning.pinned_notification_send(+ ["json://x.example/y"], allow_private_ips=True+ ):+ pass+ finally:+ socket.getaddrinfo = saved+ # Shim restored for the rest of the suite.+ assert dns_pinning._shim_installed()+++def _fixed_resolver(ip):+ """A resolver that answers EVERY host (str or bytes) with ``ip``."""++ def resolver(host, port, family=0, type=0, proto=0, flags=0):+ return [+ (+ socket.AF_INET,+ socket.SOCK_STREAM,+ socket.IPPROTO_TCP,+ "",+ (ip, port or 0),+ )+ ]++ return resolver+++def test_block_window_refuses_bytes_host_resolving_to_metadata():+ """``getaddrinfo`` accepts a ``bytes`` host, so an attacker/plugin can+ hand the shim ``b"..."`` that resolves to cloud metadata. Under an active+ block-private window a bytes host must be block-checked and REFUSED on the+ resolved IP exactly like a ``str`` host — not returned unchecked (the one+ guard that used to fail OPEN).++ Teeth: restore the old ``if not isinstance(host, str): return results``+ early-return in ``_resolve_maybe_block`` and the bytes host resolves to+ the metadata IP and is returned unchecked — no gaierror — so this test+ fails.+ """+ dns_pinning.reset_ssrf_block()+ with patch.object(+ dns_pinning, "_real_getaddrinfo", _fixed_resolver("169.254.169.254")+ ):+ with dns_pinning.block_private_resolution(+ allow_private_ips=True, block_link_local=True+ ):+ with pytest.raises(socket.gaierror):+ dns_pinning._pinned_getaddrinfo(b"metadata.example", 80)+ # A CONFIRMED security block (not a transient error) so the sender fails+ # fast instead of retrying.+ assert dns_pinning.consume_ssrf_block()+++def test_block_window_allows_bytes_host_resolving_to_public_ip():+ """The bytes-host fix fails CLOSED without over-blocking: a bytes host+ that resolves to a public address is still returned (the block check runs+ on the resolved IP, which is not blocked), so a legitimate bytes host is+ never refused just for being bytes."""+ dns_pinning.reset_ssrf_block()+ with patch.object(+ dns_pinning, "_real_getaddrinfo", _fixed_resolver("93.184.216.34")+ ):+ with dns_pinning.block_private_resolution(+ allow_private_ips=True, block_link_local=True+ ):+ got = dns_pinning._pinned_getaddrinfo(b"public.example", 443)+ assert got[0][4][0] == "93.184.216.34"+ assert not dns_pinning.consume_ssrf_block()+++def test_block_window_exempts_none_host_passive_bind():+ """A ``None`` host is an AF_PASSIVE bind+ (``getaddrinfo(None, port, ..., AI_PASSIVE)``) — a local listening-socket+ setup, not a rebindable outbound name — so it is exempt from the block+ check even while a window is active (it must not raise)."""+ dns_pinning.reset_ssrf_block()+ with patch.object(+ dns_pinning, "_real_getaddrinfo", _fixed_resolver("169.254.169.254")+ ):+ with dns_pinning.block_private_resolution(+ allow_private_ips=True, block_link_local=True+ ):+ # No raise even though the resolver answers with a metadata IP:+ # a None (passive-bind) host is not an outbound destination.+ got = dns_pinning._pinned_getaddrinfo(+ None,+ 8080,+ socket.AF_INET,+ socket.SOCK_STREAM,+ 0,+ socket.AI_PASSIVE,+ )+ assert got # returned unchecked+ assert not dns_pinning.consume_ssrf_block()+++def test_send_time_resolution_timeout_fails_closed(monkeypatch):+ """A slow/hostile DNS authority must not hang the sending thread: the+ block-window resolution is bounded and fails closed (gaierror) well+ before the resolver would have returned. Teeth: remove the timeout+ wrapping and this call blocks for the full sleep instead."""+ monkeypatch.setattr(dns_pinning, "_RESOLVE_TIMEOUT_SECONDS", 0.2)++ def slow(host, *a, **k):+ # Intentional "hang" the 0.2s bound must interrupt; the test itself+ # returns in ~0.2s (the sleep only lingers in the abandoned worker).+ time.sleep(1.5) # allow: unmarked-sleep+ return [+ (+ socket.AF_INET,+ socket.SOCK_STREAM,+ socket.IPPROTO_TCP,+ "",+ ("93.184.216.34", 0),+ )+ ]++ with patch.object(dns_pinning, "_real_getaddrinfo", slow):+ with dns_pinning.block_private_resolution(allow_private_ips=True):+ start = time.monotonic()+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("slow.example", 80)+ elapsed = time.monotonic() - start+ assert elapsed < 1.0, (+ f"resolution was not bounded (took {elapsed:.2f}s; timeout was 0.2s)"+ )+++def test_guarded_send_refuses_async_mode_and_tag():+ """The guarded-send invariants fail closed: async_mode must be off and+ tag must be None, or the thread-local pin/block would be bypassed by+ Apprise's worker-thread fan-out. Teeth: drop the checks in+ ``_enforce_guarded_send_invariants`` and neither raises."""+ svc = _service()+ # Correct config: synchronous, no tag -> accepted.+ good = svc._new_apprise()+ svc._enforce_guarded_send_invariants(good, None)+ # async_mode=True -> refused.+ bad_async = apprise.Apprise(asset=apprise.AppriseAsset(async_mode=True))+ with pytest.raises(RuntimeError, match="async_mode"):+ svc._enforce_guarded_send_invariants(bad_async, None)+ # tag present -> refused.+ with pytest.raises(RuntimeError, match="tag"):+ svc._enforce_guarded_send_invariants(good, "urgent")+++def test_ssrf_block_is_not_retried():+ """A confirmed SSRF block (pin's connect-time rebind-to-metadata) must+ fail fast, not be retried 3x by Tenacity. The rebind host resolves+ public at validation (call #1) and metadata at the guarded pin (call+ #2), which raises the SSRF ValueError; with that excluded from retries+ the guarded pin runs exactly ONCE. Teeth: restore+ ``retry_if_exception_type((Exception,))`` and the pin is retried, so+ rebind.example is resolved 4 times (1 validation + 3 pin attempts)."""+ resolver = _Resolver(+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://rebind.example/notify",+ )+ rebind_calls = [+ c+ for c in resolver.calls+ if (c[0] or "").lower().rstrip(".") == "rebind.example"+ ]+ assert len(rebind_calls) == 2, (+ f"expected 1 validation + 1 (non-retried) pin resolution, got "+ f"{len(rebind_calls)}: {rebind_calls}"+ )+++# ==========================================================================+# TLS: SNI + cert verification use the hostname, not the pinned IP+# ==========================================================================+def test_tls_sni_and_cert_use_hostname_while_connecting_to_pinned_ip(+ tmp_path,+):+ """With the host pinned to the loopback server, an HTTPS request to the+ hostname still completes certificate verification against that+ hostname's cert. If the pin had leaked the IP into SNI / cert+ validation, verification would fail — so success proves only name+ resolution is redirected.++ Teeth: the hostname resolves to a NON-loopback, unreachable TEST-NET-3+ address (203.0.113.9) by DEFAULT; ONLY the pin redirects the connection+ to 127.0.0.1 where the cert is actually served. The pinned address is+ injected directly (what ``pin_hosts`` installs after validating) so it+ is independent of the resolver's default answer — that independence is+ what gives the test teeth: drop the pin and the request targets+ 203.0.113.9 and never reaches the loopback server, so the assertions+ fail. The ``_connect_spy`` below pins that down: the socket connects to+ 127.0.0.1 (the pin), never to 203.0.113.9 (the default resolution)."""+ hostname = "pinned-tls.example"+ cert_file, key_file = _make_self_signed_cert(hostname, tmp_path)+ server, port, _hits = _start_server(tls_cert=(cert_file, key_file))+ # Default resolution is a non-loopback, unreachable address.+ resolver = _Resolver({hostname: [["203.0.113.9"]]})+ # The pin points at the loopback server. Port 0 is rewritten to the+ # lookup's port by the shim (matching how _resolve_and_validate pins).+ loopback_pin = [+ (+ socket.AF_INET,+ socket.SOCK_STREAM,+ socket.IPPROTO_TCP,+ "",+ ("127.0.0.1", 0),+ )+ ]+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ pins = dns_pinning._get_pins()+ pins[hostname] = loopback_pin+ try:+ with _connect_spy() as targets:+ resp = requests.get(+ f"https://{hostname}:{port}/",+ verify=cert_file,+ timeout=5,+ )+ finally:+ pins.pop(hostname, None)+ assert resp.status_code == 200+ # Connected to the PINNED loopback IP, never the default non-loopback+ # resolution — proving the pin (not the resolver) chose the address.+ assert any(addr[0] == "127.0.0.1" for addr in targets), targets+ assert not any(addr[0] == "203.0.113.9" for addr in targets), targets+ finally:+ server.shutdown()+++# ==========================================================================+# P1.3: a block-window block fails fast (not retried 3x)+# ==========================================================================+def test_block_window_block_is_not_retried():+ """A confirmed SSRF block from the BLOCK-PRIVATE WINDOW (an UNPINNED+ plugin-scheme host that rebinds to metadata at send time) must fail fast,+ not be retried 3x by Tenacity. ntfy:// is a plugin scheme (not pinned),+ so the pin's own connect-time ValueError does not apply — the block is a+ socket.gaierror that Apprise swallows into a generic failure. The service+ consults ``dns_pinning.consume_ssrf_block()`` after the failed send and+ re-raises it non-retryably. The rebind host resolves public at validation+ (call #1) and metadata at the send-time window resolution (call #2), so+ with the block excluded from retries the host is resolved exactly TWICE.+ Teeth: drop the ``consume_ssrf_block`` short-circuit in ``_send_with_retry``+ and the send is retried, resolving the host 4 times (1 validation + 3+ send attempts)."""+ resolver = _Resolver(+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="ntfy://rebind.example/mytopic",+ )+ rebind_calls = [+ c+ for c in resolver.calls+ if (c[0] or "").lower().rstrip(".") == "rebind.example"+ ]+ assert len(rebind_calls) == 2, (+ f"expected 1 validation + 1 (non-retried) send resolution, got "+ f"{len(rebind_calls)}: {rebind_calls}"+ )+ assert not any(addr[0] == "169.254.169.254" for addr in targets), targets+++# ==========================================================================+# P0.1: AWS IPv6 IMDS (fd00:ec2::254) blocked through the pin/block path+# ==========================================================================+def test_ipv6_imds_rejected_by_pin_at_connect_time():+ """A pinnable raw-webhook host that resolves to AWS's IPv6 IMDS+ (fd00:ec2::254) at pin time is refused (fail closed) even under+ allow_private_ips=True — which permits the fc00::/7 ULA range the address+ sits in. The cloud-metadata block is absolute."""+ resolver = _Resolver({"hook.example": [["fd00:ec2::254"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with pytest.raises(ValueError, match="SSRF"):+ with dns_pinning.pin_hosts(+ ["json://hook.example/x"], allow_private_ips=True+ ):+ pass+++def test_ipv6_imds_refused_by_block_window():+ """An UNPINNED lookup that resolves to AWS's IPv6 IMDS is refused at the+ getaddrinfo layer while the block-private window is active, even with+ allow_private_ips=True."""+ resolver = _Resolver({"redir.example": [["fd00:ec2::254"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(allow_private_ips=True):+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("redir.example", 80)+++# ==========================================================================+# P2.10: additional coverage+# ==========================================================================+def test_send_with_tag_is_refused_end_to_end():+ """send(..., tag=...) is refused end-to-end: a tag can fan delivery out+ to worker threads that bypass the thread-local pin/block, so the+ guarded-send invariant rejects it (RuntimeError, wrapped as SendError)+ before any connection — no socket is opened to the target."""+ resolver = _Resolver({"good.example": [["93.184.216.34"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://good.example/notify",+ tag="a,b",+ )+ assert not any(addr[0] == "93.184.216.34" for addr in targets), targets+++def test_rfc1918_host_pinned_and_allowed_by_notification_guard():+ """A raw-webhook (json) host that resolves to an RFC1918 address is+ PINNED (not blocked) by the lenient notification guard — self-hosted LAN+ webhooks keep working. The pinned lookup returns the validated RFC1918+ address without re-resolving."""+ resolver = _Resolver({"lan.example": [["10.11.12.13"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.pinned_notification_send(+ ["json://lan.example/hook"], allow_private_ips=True+ ):+ got = socket.getaddrinfo("lan.example", 443)+ assert got[0][4][0] == "10.11.12.13"+++def test_selfhosted_private_plugin_delivers_end_to_end():+ """A self-hosted plugin notifier (ntfy / gotify) on a private host+ delivers end-to-end: the lenient partition allows private/LAN targets+ (cloud-metadata still always blocked). The loopback server stands in for+ the private endpoint; the guard pins/permits it and the plugin POSTs+ successfully through the real Apprise + requests stack."""+ server, port, hits = _start_server()+ resolver = _Resolver({"lan.example": [["127.0.0.1"]]})+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)+ try:+ for url in (+ f"ntfy://lan.example:{port}/topic",+ f"gotify://lan.example:{port}/atoken",+ ):+ hits.clear()+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ result = svc.send(title="t", body="b", service_urls=url)+ assert result is True, url+ assert hits, f"self-hosted plugin never received the POST: {url}"+ finally:+ server.shutdown()+++def test_non_json_plugin_redirect_not_followed():+ """redirect-disable applies to a NON-json plugin too (ntfy honors the+ per-plugin ``redirects`` flag). An ntfy endpoint that 302-redirects to+ another host is NOT followed: the target server is never hit and the send+ fails on the unfollowed 302. The redirect target is a loopback stand-in+ the lenient block-window does NOT itself block, so ONLY the+ redirect-disable stops the second hop (teeth)."""+ target_server, target_port, target_hits = _start_server()+ hook_server, hook_port, hook_hits = _start_server(+ redirect_to=f"http://redir-target.example:{target_port}/pwn"+ )+ resolver = _Resolver(+ {+ "ntfyhost.example": [["127.0.0.1"]],+ "redir-target.example": [["127.0.0.1"]],+ }+ )+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with pytest.raises(SendError):+ svc.send(+ title="t",+ body="b",+ service_urls=f"ntfy://ntfyhost.example:{hook_port}/topic",+ )+ assert hook_hits, "initial request to the ntfy host never happened"+ assert not target_hits, (+ f"ntfy redirect was FOLLOWED to the target (hits={target_hits}) "+ "— redirect-disable did not apply to the plugin"+ )+ finally:+ hook_server.shutdown()+ target_server.shutdown()+++# ==========================================================================+# test_service (admin "Send Test Notification") is guarded like send()+# ==========================================================================+def test_test_service_rebind_to_metadata_blocked_through_apprise():+ """The admin "Send Test Notification" path (``test_service``) runs through+ the SAME guarded core (:meth:`NotificationService._guarded_notify`) as the+ real send, so a plugin-scheme host that validates public but rebinds to+ cloud-metadata at send time is refused: the block-private window raises a+ gaierror on the send-time resolution (Apprise swallows it), NO connection+ to the metadata IP is made, and ``test_service`` reports failure. The+ consume_ssrf_block cosmetic then surfaces the SPECIFIC SSRF-block reason to+ the admin instead of the generic "Failed to send" message.++ Teeth: pass ``guard_factory=None`` to ``_guarded_notify`` in+ ``test_service`` (drop the pin/block window) and Apprise resolves+ ``rebind.example`` to ``169.254.169.254`` and connects to it — the connect+ spy sees the metadata IP and this test fails. Dropping only the+ consume_ssrf_block branch makes the error revert to the generic message+ and the reason assertion fails."""+ resolver = _Resolver(+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ result = _service().test_service("ntfy://rebind.example/mytopic")+ assert result["success"] is False+ assert not any(addr[0] == "169.254.169.254" for addr in targets), (+ f"connected to metadata IP: {targets}"+ )+ # Cosmetic: the specific SSRF-block reason is surfaced (consume_ssrf_block),+ # not the generic delivery-failure message.+ assert "SSRF" in result["error"], (+ f"expected the specific SSRF-block reason, got: {result['error']!r}"+ )+++def test_test_service_selfhosted_loopback_delivers():+ """Counterpart to the block test: ``test_service`` against a self-hosted+ loopback plugin endpoint still delivers end-to-end through the real+ Apprise + requests stack (the lenient partition permits private/loopback;+ only metadata / link-local are refused)."""+ server, port, hits = _start_server()+ resolver = _Resolver({"lan.example": [["127.0.0.1"]]})+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ result = svc.test_service(f"ntfy://lan.example:{port}/topic")+ assert result["success"] is True, result+ assert hits, "self-hosted loopback endpoint never received the POST"+ finally:+ server.shutdown()+++# ==========================================================================+# IPv6 IMDS (fd00:ec2::254) refused end-to-end through send() (sockaddr path)+# ==========================================================================+def test_ipv6_imds_rebind_refused_through_send():+ """End-to-end IPv6 sockaddr path: a raw-webhook (json) host that validates+ to a public IPv6 but rebinds to AWS's IPv6 IMDS (``fd00:ec2::254``) at the+ guarded pin is refused before any connection — the IPv6 analogue of+ ``test_rebind_to_metadata_blocked_through_apprise``. The pin's connect-time+ re-validation catches the rebind (the cloud-metadata block is absolute even+ under allow_private_ips=True, which permits the fc00::/7 ULA the address+ sits in) and raises the SSRF ValueError, wrapped as SendError.++ Teeth: drop the ``is_ip_blocked`` check in+ ``dns_pinning._resolve_and_validate`` (or remove ``fd00:ec2::254`` from+ ``ALWAYS_BLOCKED_METADATA_IPS``) and the send connects to the IPv6 IMDS —+ the connect spy sees it and this test fails."""+ resolver = _Resolver(+ {+ "rebind6.example": [+ ["2606:2800:220:1:248:1893:25c8:1946"], # public IPv6+ ["fd00:ec2::254"], # AWS IPv6 IMDS+ ]+ }+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://rebind6.example/notify",+ )+ assert not any(str(addr[0]) == "fd00:ec2::254" for addr in targets), (+ f"connected to IPv6 IMDS: {targets}"+ )+++# ==========================================================================+# Fix 1: link-local blocked for the lenient notification partition even under+# allow_private_ips=True (metadata beyond the always-blocked literals), while+# RFC1918 self-hosted notifiers keep working.+# ==========================================================================+def test_link_local_refused_by_notification_block_window():+ """An UNPINNED lookup that resolves into the link-local range (Scaleway's+ metadata ``169.254.42.42`` is the canonical example — NOT one of the six+ always-blocked literals) is refused by the notification block-private+ window when ``block_link_local=True``, even though allow_private_ips=True+ permits RFC1918. Teeth: drop ``block_link_local`` and this lookup+ resolves normally (link-local is otherwise allowed under the private-IP+ opt-in)."""+ resolver = _Resolver({"scaleway.example": [["169.254.42.42"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(+ allow_private_ips=True, block_link_local=True+ ):+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("scaleway.example", 80)+++def test_ipv6_link_local_refused_by_notification_block_window():+ """IPv6 link-local (fe80::/10) is likewise refused under+ ``block_link_local=True`` even with allow_private_ips=True."""+ resolver = _Resolver({"ll6.example": [["fe80::1"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(+ allow_private_ips=True, block_link_local=True+ ):+ with pytest.raises(socket.gaierror):+ socket.getaddrinfo("ll6.example", 80)+++def test_rfc1918_still_allowed_under_block_link_local():+ """``block_link_local=True`` must NOT over-block: RFC1918 / loopback /+ non-link-local ULA self-hosted notifiers still resolve under the lenient+ partition. Only link-local is refused."""+ resolver = _Resolver(+ {+ "lan.example": [["10.11.12.13"]],+ "lan2.example": [["192.168.1.5"]],+ "loop.example": [["127.0.0.1"]],+ "ula.example": [["fd00::1"]],+ }+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with dns_pinning.block_private_resolution(+ allow_private_ips=True, block_link_local=True+ ):+ assert (+ socket.getaddrinfo("lan.example", 80)[0][4][0] == "10.11.12.13"+ )+ assert (+ socket.getaddrinfo("lan2.example", 80)[0][4][0] == "192.168.1.5"+ )+ assert (+ socket.getaddrinfo("loop.example", 80)[0][4][0] == "127.0.0.1"+ )+ assert socket.getaddrinfo("ula.example", 80)[0][4][0] == "fd00::1"+++def test_link_local_scaleway_pin_rejects_rebind():+ """A pinnable raw-webhook host that rebinds INTO link-local at pin time is+ refused (fail closed) under ``block_link_local=True`` — the connect-time+ re-validation catches metadata that lives in link-local beyond the+ always-blocked literals."""+ resolver = _Resolver({"hook.example": [["169.254.42.42"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with pytest.raises(ValueError, match="SSRF"):+ with dns_pinning.pin_hosts(+ ["json://hook.example/x"],+ allow_private_ips=True,+ block_link_local=True,+ ):+ pass+++def test_scaleway_link_local_refused_end_to_end_through_send():+ """End-to-end: ``send()`` refuses a json:// webhook whose IP-literal host+ is a link-local metadata address (Scaleway ``169.254.42.42``). The+ validator's plugin-scheme IMDS guard rejects it pre-send, so ``send``+ raises ServiceError and no connection is made to the link-local IP."""+ resolver = _Resolver({})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(ServiceError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://169.254.42.42/notify",+ )+ assert not any(addr[0] == "169.254.42.42" for addr in targets), targets+++def test_rfc1918_json_webhook_still_delivers_end_to_end():+ """The link-local block does not regress self-hosted delivery: a json://+ webhook on an RFC1918 host still delivers end-to-end through the lenient+ partition (loopback stands in for the private endpoint)."""+ server, port, hits = _start_server()+ resolver = _Resolver({"lan.example": [["127.0.0.1"]]})+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)+ try:+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ result = svc.send(+ title="t",+ body="b",+ service_urls=f"json://lan.example:{port}/notify",+ )+ assert result is True+ assert hits, "RFC1918 self-hosted webhook never received the POST"+ finally:+ server.shutdown()+++# ==========================================================================+# WIRING locks: block_link_local=True is threaded through the two+# notification send call sites themselves (service.py's ``_dispatch``+# lenient partition and ``test_service``'s guard factory) — not just+# present somewhere in the shared ``is_ip_blocked`` / validator machinery.+#+# Every test above that exercises link-local either drives the primitives+# directly (``dns_pinning.block_private_resolution`` /+# ``dns_pinning.pin_hosts``) or uses an IP-LITERAL URL+# (``test_scaleway_link_local_refused_end_to_end_through_send``), which the+# validator's plugin-scheme IMDS guard rejects PRE-SEND — ``_dispatch`` /+# ``pinned_notification_send`` is never reached. So none of them would+# notice if ``block_link_local=True`` were dropped at either call site while+# the shared validator/``is_ip_blocked`` stayed intact.+#+# These tests use a HOSTNAME that validates PUBLIC (the validator's own+# resolution, call #1 of the scripted resolver) but rebinds to a link-local+# address that is NOT one of the six always-blocked metadata literals (call+# #2, at the guarded send call site itself) — Scaleway's ``169.254.42.42``+# / a bare IPv6 ``fe80::`` address, both ordinary link-local space that+# ``allow_private_ips=True`` would otherwise ADMIT. So a refusal here can+# only come from the ``block_link_local=True`` threaded through the+# call site under test, giving each test real teeth against that one wire.+# ==========================================================================+def test_link_local_rebind_refused_by_dispatch_lenient_partition():+ """WIRING lock for ``_dispatch``'s lenient-partition+ ``block_link_local=True`` (``notifications/service.py`` ~line 535).++ ``ll-rebind.example`` validates PUBLIC at ``send()``'s pre-send+ validation (resolver call #1) but rebinds to Scaleway's link-local+ metadata address ``169.254.42.42`` at ``_dispatch``'s ``pin_hosts``+ resolution (call #2, "pin time" — json:// is a pinnable scheme).+ ``169.254.42.42`` is ordinary link-local space, allowed under+ ``allow_private_ips=True`` (the lenient partition's policy); it is+ refused ONLY because ``_dispatch`` also passes+ ``block_link_local=True`` into that same ``pinned_notification_send``+ call. ``send()`` must refuse it and no connection may reach the+ link-local IP.++ Teeth: change ``block_link_local=True`` to ``False`` at _dispatch's+ lenient ``pinned_notification_send`` call (service.py ~line 535,+ leaving ``is_ip_blocked`` / the validator untouched) and this test+ fails — the rebind pins successfully and the connect spy sees+ 169.254.42.42.+ """+ resolver = _Resolver(+ {"ll-rebind.example": [["93.184.216.34"], ["169.254.42.42"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://ll-rebind.example/notify",+ )+ assert not any(addr[0] == "169.254.42.42" for addr in targets), (+ f"connected to link-local IP: {targets}"+ )+++def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():+ """IPv6 analogue of the test above: ``ll-rebind6.example`` validates+ public IPv6 (resolver call #1) but rebinds to a bare IPv6 link-local+ address ``fe80::1`` (fe80::/10, not an always-blocked literal) at+ ``_dispatch``'s pin resolution (call #2). Same wiring lock —+ refused only by ``_dispatch``'s ``block_link_local=True``."""+ resolver = _Resolver(+ {+ "ll-rebind6.example": [+ ["2606:2800:220:1:248:1893:25c8:1946"], # public IPv6+ ["fe80::1"], # IPv6 link-local+ ]+ }+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SendError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://ll-rebind6.example/notify",+ )+ assert not any(str(addr[0]) == "fe80::1" for addr in targets), (+ f"connected to IPv6 link-local IP: {targets}"+ )+++def test_test_service_link_local_rebind_refused_by_guard_factory():+ """WIRING lock for ``test_service``'s guard-factory+ ``block_link_local=is_plugin_scheme`` (``notifications/service.py``+ ~line 710).++ ``ntfy://`` is a plugin scheme (not in ``_PINNABLE_SCHEMES``), so+ ``pin_hosts`` never resolves/pins it; the send-time lookup instead runs+ under the block-private WINDOW (``block_private_resolution``), which+ consults the SAME ``block_link_local`` flag ``test_service`` threads+ into its guard factory. The host validates public at ``test_service``'s+ pre-send validation (resolver call #1) and rebinds to Scaleway's+ link-local ``169.254.42.42`` at send time (call #2) — refused only+ because ``block_link_local=True`` is threaded through THIS call site,+ not because the address is otherwise blocked (it is ordinary link-local+ space, allowed under ``allow_private_ips=True``, which plugin schemes+ always run with).++ Teeth: change ``block_link_local=is_plugin_scheme`` to+ ``block_link_local=False`` in test_service's guard_factory (service.py+ ~line 710) and this test fails — the block window admits the+ link-local resolution, Apprise connects, and the connect spy sees+ 169.254.42.42.+ """+ resolver = _Resolver(+ {"ll-rebind-ts.example": [["93.184.216.34"], ["169.254.42.42"]]}+ )+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ result = _service().test_service(+ "ntfy://ll-rebind-ts.example/mytopic"+ )+ assert result["success"] is False+ assert not any(addr[0] == "169.254.42.42" for addr in targets), (+ f"connected to link-local IP: {targets}"+ )+ # Cosmetic corroboration that the block-private WINDOW (not some other+ # failure) is what fired.+ assert "SSRF" in result["error"], (+ f"expected the specific SSRF-block reason, got: {result['error']!r}"+ )+++# ==========================================================================+# Fix 2: empty-authority notification URLs (host smuggled into the path) are+# rejected at the validator before send.+# ==========================================================================+def test_empty_authority_metadata_in_path_rejected_before_send():+ """``json:///169.254.169.254/path`` has an empty ``//`` authority:+ urllib3/requests see no host (so the validator's IP check would be+ skipped) but Apprise dials the in-path host ``169.254.169.254``. The+ empty-authority guard rejects it at validation, so ``send`` raises+ ServiceError and no connection to the metadata IP is made."""+ resolver = _Resolver({})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(ServiceError):+ _service().send(+ title="t",+ body="b",+ service_urls="json:///169.254.169.254/path",+ )+ assert not any(addr[0] == "169.254.169.254" for addr in targets), targetsdiff --git a/tests/search_engines/test_base_helpers.py b/tests/search_engines/test_base_helpers.pyindex bb0b3c5edc..14bb79d1a8 100644--- a/tests/search_engines/test_base_helpers.py+++ b/tests/search_engines/test_base_helpers.py@@ -14,10 +14,10 @@ from unittest.mock import Mock, patchimport pytest-from src.local_deep_research.web_search_engines.search_engine_base import (+from local_deep_research.web_search_engines.search_engine_base import (BaseSearchEngine,)-from src.local_deep_research.web_search_engines.rate_limiting import (+from local_deep_research.web_search_engines.rate_limiting import (RateLimitError,)diff --git a/tests/security/test_notification_validator.py b/tests/security/test_notification_validator.pyindex 66ac7161ed..d2cdf208e9 100644--- a/tests/security/test_notification_validator.py+++ b/tests/security/test_notification_validator.py@@ -390,6 +390,47 @@ class TestParserDifferentialBypass:assert is_valid is Trueassert error is None+ def test_multi_at_authority_rejected(self):+ """A second '@' in the authority is a parser-differential SSRF:+ urllib3 (the validator/pin parser) reads the host after the LAST+ '@' (``decoy-public.example.com``) while Apprise's own parser reads+ ``169.254.169.254`` and connects there. Reject any authority with+ more than one '@' before the host is ever extracted (fail closed)."""+ is_valid, error = NotificationURLValidator.validate_service_url(+ "json://[email protected]@decoy-public.example.com/path",+ allow_private_ips=True,+ )+ assert is_valid is False+ assert error is not None+ assert "@" in error++ def test_multi_at_authority_rejected_http_scheme(self):+ is_valid, _ = NotificationURLValidator.validate_service_url(+ "http://a@[email protected]/x"+ )+ assert is_valid is False++ def test_single_at_userinfo_still_allowed(self):+ """A single '@' (RFC 3986 userinfo) is legitimate and must not be+ collateral damage of the multi-'@' rejection."""+ for url in (+ "json://[email protected]/path",+ "json://user:[email protected]/path",+ "mailto://user:[email protected]",+ ):+ is_valid, error = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is True, (url, error)++ def test_at_in_query_not_counted(self):+ """The multi-'@' check counts only the authority (urlparse netloc),+ so an '@' in the query string is not a rejection cause."""+ is_valid, error = NotificationURLValidator.validate_service_url(+ "json://hook.example.com/path?to=a@b@c", allow_private_ips=True+ )+ assert is_valid is True, error+def test_apprise_signal_url_accepted(self):"""signal:// (Apprise's Signal-API-REST transport) is allowed.@@ -552,6 +593,170 @@ class TestCloudMetadataBlockedForPluginSchemes:assert "cloud-metadata" in error.lower()+class TestLinkLocalBlockedForPluginSchemes:+ """Plugin-scheme link-local guard (metadata beyond the always-blocked+ literals).++ The lenient plugin/raw-webhook partition runs with+ ``allow_private_ips=True`` so self-hosted LAN notifiers work. But+ cloud-provider metadata lives across the WHOLE link-local range+ (169.254.0.0/16, fe80::/10), not just the six always-blocked literals+ (e.g. Scaleway's 169.254.42.42). ``validate_service_url`` must reject+ any link-local plugin-scheme target while still allowing RFC1918 /+ loopback / non-link-local ULA.+ """++ # Link-local metadata / auto-config addresses that are NOT in+ # ALWAYS_BLOCKED_METADATA_IPS — these were reachable before the fix.+ LINK_LOCAL_IPS = (+ "169.254.42.42", # Scaleway metadata (verified reachable pre-fix)+ "169.254.1.1",+ "169.254.255.254",+ )+ PLUGIN_SCHEMES = ("json", "xml", "form", "signal", "gotify", "ntfy")++ @pytest.mark.parametrize("ip", LINK_LOCAL_IPS)+ @pytest.mark.parametrize("scheme", PLUGIN_SCHEMES)+ def test_ipv4_link_local_blocked_even_with_allow_private_ips(+ self, scheme, ip+ ):+ url = f"{scheme}://{ip}/path"+ is_valid, error = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is False, f"{url} should be blocked"+ assert "link-local" in error.lower()++ def test_ipv6_link_local_blocked(self):+ is_valid, error = NotificationURLValidator.validate_service_url(+ "json://[fe80::1]/path", allow_private_ips=True+ )+ assert is_valid is False+ assert "link-local" in error.lower()++ def test_rfc1918_still_allowed(self):+ for url in (+ "json://10.11.12.13/hook",+ "json://172.16.5.5/hook",+ "json://192.168.50.20/hook",+ ):+ is_valid, error = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is True, f"{url} should be allowed, got: {error}"++ def test_loopback_and_ula_still_allowed(self):+ for url in ("json://127.0.0.1/hook", "json://[fd00::1]/hook"):+ is_valid, error = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is True, f"{url} should be allowed, got: {error}"++ def test_http_scheme_link_local_still_operator_recoverable(self):+ """The link-local block is scoped to the PLUGIN partition. Under+ http/https the operator opt-in still permits link-local (it is+ unreachable for delivery today and the hint contract treats it as+ recoverable) — so the scoped fix must NOT change that."""+ is_valid, _error = NotificationURLValidator.validate_service_url(+ "http://169.254.1.1/x", allow_private_ips=True+ )+ assert is_valid is True+++class TestEmptyAuthorityRejected:+ """Empty-authority parser-differential SSRF (host smuggled into path).++ ``json:///169.254.169.254/path`` has an empty ``//`` authority:+ urllib3/requests see no host (the IP check is skipped) while Apprise+ dials the first path segment as the host. ``validate_service_url``+ rejects any empty-authority ``scheme://`` URL before host extraction,+ without breaking legitimate URLs.+ """++ @pytest.mark.parametrize(+ "url",+ [+ "json:///169.254.169.254/path",+ "xml:///10.0.0.1/x",+ "form:///metadata",+ "https:///example.com/webhook",+ "json:///path-only",+ ],+ )+ def test_empty_authority_rejected(self, url):+ is_valid, error = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is False, f"{url} should be rejected"+ assert "empty" in error.lower()++ @pytest.mark.parametrize(+ "url",+ [+ "json://host.example/path",+ "json://169.254.169.254.example/path", # host, not empty authority+ "mailto://user:[email protected]",+ "ntfy://host.example/topic",+ "discord://webhook_id/token",+ "slack://TestApp@TokenA/TokenB/TokenC",+ "https://example.com/webhook",+ "signal://192.168.50.20:8739/+15551234567/+15557654321",+ ],+ )+ def test_legit_urls_with_authority_still_pass(self, url):+ is_valid, error = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is True, f"{url} should pass, got: {error}"+++class TestEmptyHostAuthorityRejected:+ """Non-empty ``//`` authority that urllib3 parses to an EMPTY host.++ ``json://169.254.169.254:80@/`` smuggles an IP into the userinfo with+ nothing after the trailing ``@``: urllib3 returns no host, so the+ per-scheme private-IP check (guarded on ``if hostname``) is skipped and the+ URL would be accepted, yet the authority still carries a target another+ parser could dial. Sibling of the multi-``@`` / empty-``//``-authority+ guards — rejected fail-closed before the scheme checks.+ """++ def test_ip_in_userinfo_empty_host_rejected(self):+ is_valid, error = NotificationURLValidator.validate_service_url(+ "json://169.254.169.254:80@/", allow_private_ips=True+ )+ assert is_valid is False+ assert "host" in error.lower()++ @pytest.mark.parametrize(+ "url",+ [+ "json://169.254.169.254:80@/",+ "json://169.254.169.254@",+ "xml://10.0.0.5:443@/x",+ ],+ )+ def test_empty_host_variants_rejected(self, url):+ is_valid, _ = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert is_valid is False, f"{url} should be rejected"+++class TestAllowedSchemesRawSocketRegression:+ """``ALLOWED_SCHEMES`` gates which Apprise schemes reach the guarded send+ path. A scheme whose plugin does network I/O via a primitive the DNS-pin+ shim cannot see — a raw ``socket.sendto`` datagram (``rsyslog://``) or+ similar — would bypass BOTH the address pin and the block-private window.+ Lock such schemes out of the allowlist so one can't be added later without+ matching pin/block coverage.+ """++ @pytest.mark.parametrize("scheme", ["rsyslog", "aprs", "syslog", "xmpp"])+ def test_raw_socket_scheme_not_allowed(self, scheme):+ assert scheme not in NotificationURLValidator.ALLOWED_SCHEMES++class TestValidateServiceUrlStrict:"""Tests for validate_service_url_strict static method."""diff --git a/tests/security/test_ssrf_validator.py b/tests/security/test_ssrf_validator.pyindex e4b9725008..b02cf841b4 100644--- a/tests/security/test_ssrf_validator.py+++ b/tests/security/test_ssrf_validator.py@@ -126,7 +126,7 @@ class TestIsIpBlocked:def test_cgnat_blocked_by_default(self):"""CGNAT addresses (100.64.x.x) should be blocked by default."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -136,7 +136,7 @@ class TestIsIpBlocked:def test_cgnat_allowed_with_allow_private_ips(self):"""CGNAT addresses (100.64.x.x) should be allowed with allow_private_ips=True."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -147,7 +147,7 @@ class TestIsIpBlocked:def test_link_local_allowed_with_allow_private_ips(self):"""Link-local addresses (169.254.x.x) should be allowed with allow_private_ips=True."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -159,7 +159,7 @@ class TestIsIpBlocked:def test_ipv6_ula_blocked_by_default(self):"""IPv6 Unique Local Addresses (fc00::/7) should be blocked by default."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -168,7 +168,7 @@ class TestIsIpBlocked:def test_ipv6_ula_allowed_with_allow_private_ips(self):"""IPv6 ULA (fc00::/7) should be allowed with allow_private_ips=True."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -177,7 +177,7 @@ class TestIsIpBlocked:def test_ipv6_link_local_blocked_by_default(self):"""IPv6 link-local addresses (fe80::/10) should be blocked by default."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -186,7 +186,7 @@ class TestIsIpBlocked:def test_ipv6_link_local_allowed_with_allow_private_ips(self):"""IPv6 link-local (fe80::/10) should be allowed with allow_private_ips=True."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -384,7 +384,7 @@ class TestContainerNetworking:def test_podman_host_containers_internal(self):"""Podman's host.containers.internal (resolves to CGNAT) should work with allow_private_ips."""- from src.local_deep_research.security.ssrf_validator import validate_url+ from local_deep_research.security.ssrf_validator import validate_urlwith patch("socket.getaddrinfo") as mock_getaddrinfo:# Podman rootless containers typically resolve host.containers.internal to 100.64.x.x@@ -399,7 +399,7 @@ class TestContainerNetworking:def test_ollama_in_podman(self):"""Ollama running on host accessible via Podman's CGNAT should work."""- from src.local_deep_research.security.ssrf_validator import validate_url+ from local_deep_research.security.ssrf_validator import validate_urlwith patch("socket.getaddrinfo") as mock_getaddrinfo:# Ollama on host via Podman CGNAT@@ -416,7 +416,7 @@ class TestContainerNetworking:def test_searxng_in_podman(self):"""SearXNG running on host accessible via Podman's CGNAT should work."""- from src.local_deep_research.security.ssrf_validator import validate_url+ from local_deep_research.security.ssrf_validator import validate_urlwith patch("socket.getaddrinfo") as mock_getaddrinfo:# SearXNG on host via Podman CGNAT@@ -431,7 +431,7 @@ class TestContainerNetworking:def test_cgnat_url_blocked_by_default(self):"""CGNAT URLs should be blocked by default (without allow_private_ips)."""- from src.local_deep_research.security.ssrf_validator import validate_url+ from local_deep_research.security.ssrf_validator import validate_url# Direct CGNAT IPassert validate_url("http://100.64.0.1:8080") is False@@ -444,7 +444,7 @@ class TestContainerNetworking:def test_docker_bridge_network(self):"""Docker bridge network IPs should work with allow_private_ips."""- from src.local_deep_research.security.ssrf_validator import validate_url+ from local_deep_research.security.ssrf_validator import validate_url# Docker typically uses 172.17.x.x for bridge networkassert (@@ -472,91 +472,91 @@ class TestParserDifferentialBypass:def test_advisory_canonical_payload(self):"""The exact PoC from the advisory must be rejected."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1:6666\\@1.1.1.1") is Falsedef test_backslash_no_port(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\\@1.1.1.1") is Falsedef test_double_backslash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\\\\@1.1.1.1") is Falsedef test_slash_then_backslash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1/\\@1.1.1.1") is Falsedef test_tab_at_seam(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\[email protected]") is Falsedef test_carriage_return_at_seam(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\[email protected]") is Falsedef test_newline_at_seam(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\[email protected]") is Falsedef test_space_at_seam(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1 @1.1.1.1") is Falsedef test_ipv6_loopback_with_backslash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://[::1]\\@1.1.1.1") is Falsedef test_ipv4_mapped_ipv6_with_backslash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://[::ffff:127.0.0.1]\\@1.1.1.1") is Falsedef test_backslash_with_trailing_port(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\\@1.1.1.1:80") is Falsedef test_trailing_dot_loopback_with_backslash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1.\\@1.1.1.1") is Falsedef test_null_byte_in_userinfo(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -564,7 +564,7 @@ class TestParserDifferentialBypass:def test_idn_unicode_host_rejected(self):"""IDN/Unicode hosts are rejected by urllib3 / ASCII guard."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -575,7 +575,7 @@ class TestParserDifferentialBypass:def test_octal_ip_resolves_to_loopback(self):"""Octal IP form '0177.0.0.1' resolves to 127.0.0.1 via getaddrinfo."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -587,7 +587,7 @@ class TestParserDifferentialBypass:def test_decimal_int_ip_resolves_to_loopback(self):"""Decimal-int IP form '2130706433' resolves to 127.0.0.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -605,35 +605,35 @@ class TestParserDifferentialBypass:Layer 1 doesn't match ``%5C`` (it's three printable ASCII chars);Layer 2 is the load-bearing defence on the SafeSession.send path."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1:6666/%[email protected]") is Falsedef test_backslash_deep_in_path(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://example.com/path\\@1.1.1.1") is Falsedef test_backslash_in_userinfo_password(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://user:pass\\@127.0.0.1/") is Falsedef test_backslash_with_port_on_trailing_host(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1\\@evil.com:8080") is Falsedef test_interior_whitespace_at_seam(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -644,7 +644,7 @@ class TestParserDifferentialBypass:connections to ``[::]:port`` to a service bound on ``[::1]:port``,so it must be blocked alongside ``0.0.0.0`` (the IPv4 equivalent,already covered via 0.0.0.0/8 in BLOCKED_IP_RANGES)."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -654,7 +654,7 @@ class TestParserDifferentialBypass:"""Equivalent representation ``0::`` — must normalise to ``::``before the IP-range check or this bypasses the literal-stringallow-list in notification_validator."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -662,7 +662,7 @@ class TestParserDifferentialBypass:def test_ipv6_unspecified_full_form_blocked(self):"""Equivalent representation ``0:0:0:0:0:0:0:0``."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -680,7 +680,7 @@ class TestDnsResolvedBypass:"""def test_hostname_resolving_to_loopback_blocked(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -691,7 +691,7 @@ class TestDnsResolvedBypass:assert validate_url("http://attacker.example.com/") is Falsedef test_hostname_resolving_to_rfc1918_blocked(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -702,7 +702,7 @@ class TestDnsResolvedBypass:assert validate_url("http://attacker.example.com/") is Falsedef test_hostname_resolving_to_link_local_blocked(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -714,7 +714,7 @@ class TestDnsResolvedBypass:def test_hostname_resolving_to_aws_metadata_blocked(self):"""Hardcoded AWS metadata block fires even with allow_private_ips."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -735,7 +735,7 @@ class TestDnsResolvedBypass:DNS returning a public IP first then a private IP must still block.Round-robin / multi-A-record DNS could otherwise be a bypass."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -750,7 +750,7 @@ class TestDnsResolvedBypass:def test_dns_resolution_failure_fails_closed(self):"""``getaddrinfo`` raising ``gaierror`` must return False (not allow)."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -759,7 +759,7 @@ class TestDnsResolvedBypass:def test_ipv6_dns_resolution_to_loopback_blocked(self):"""Hostname resolving to IPv6 ``::1`` must be blocked."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -774,7 +774,7 @@ class TestDnsResolvedBypass:Hostname resolving to ``::ffff:127.0.0.1`` (IPv4-mapped IPv6) mustbe blocked — exercises the IPv4-mapped unwrap in is_ip_blocked."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -794,7 +794,7 @@ class TestAlternateIpFormsBlocked:def test_octal_loopback_blocked(self):"""``0177.0.0.1`` → ``127.0.0.1`` via getaddrinfo on Linux."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -805,7 +805,7 @@ class TestAlternateIpFormsBlocked:assert validate_url("http://0177.0.0.1/") is Falsedef test_decimal_int_loopback_blocked(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -817,7 +817,7 @@ class TestAlternateIpFormsBlocked:def test_short_ipv4_form_loopback_blocked(self):"""``127.1`` (short form) → ``127.0.0.1`` via getaddrinfo on Linux."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -829,7 +829,7 @@ class TestAlternateIpFormsBlocked:def test_ipv4_mapped_ipv6_loopback_literal_blocked(self):"""``[::ffff:127.0.0.1]`` is an IPv4-mapped IPv6 of loopback."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -837,7 +837,7 @@ class TestAlternateIpFormsBlocked:def test_ipv4_mapped_ipv6_rfc1918_literal_blocked(self):"""``[::ffff:10.0.0.1]`` — IPv4-mapped IPv6 of RFC1918."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -845,7 +845,7 @@ class TestAlternateIpFormsBlocked:def test_ipv4_mapped_ipv6_aws_metadata_literal_blocked(self):"""``[::ffff:169.254.169.254]`` — AWS metadata via mapped IPv6."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -860,28 +860,28 @@ class TestAllowFlagMatrix:"""def test_loopback_default_blocked(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1/") is Falsedef test_loopback_with_allow_localhost(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1/", allow_localhost=True) is Truedef test_loopback_with_allow_private_ips(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://127.0.0.1/", allow_private_ips=True) is Truedef test_ipv6_loopback_with_allow_localhost(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -895,7 +895,7 @@ class TestAllowFlagMatrix:``allow_localhost`` is therefore conservatively scoped to``::1`` and ``127.0.0.0/8`` and does NOT permit ``::``."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -903,14 +903,14 @@ class TestAllowFlagMatrix:def test_ipv6_unspecified_blocked_even_with_allow_private_ips(self):"""Same reasoning: ``::`` is not in any allowed-range carve-out."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://[::]/", allow_private_ips=True) is Falsedef test_aws_metadata_blocked_under_allow_localhost(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -924,7 +924,7 @@ class TestAllowFlagMatrix:Codebase comments call this out as ALWAYS blocked. Locks in thatthe most permissive flag still doesn't reach AWS metadata."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -937,6 +937,26 @@ class TestAllowFlagMatrix:class TestAlwaysBlockedMetadataIPs:"""Cloud-metadata IPs blocked under every flag combination."""+ def test_aws_ipv6_imds_blocked_under_all_flags(self):+ """AWS's native IPv6 IMDS endpoint (fd00:ec2::254) is a ULA+ (fc00::/7), NOT an IPv4-mapped / NAT64-wrapped form of+ 169.254.169.254, so it is not covered by the IPv4 entries or the+ NAT64 embedded-IPv4 check and must be listed explicitly. It must be+ blocked under every flag combination — most importantly+ allow_private_ips=True, which otherwise permits the whole fc00::/7+ ULA range. Any textual variant normalizes to the canonical form+ before the membership test."""+ from local_deep_research.security.ssrf_validator import is_ip_blocked++ for variant in (+ "fd00:ec2::254",+ "FD00:EC2::254",+ "fd00:ec2:0:0:0:0:0:254",+ ):+ assert is_ip_blocked(variant) is True+ assert is_ip_blocked(variant, allow_localhost=True) is True+ assert is_ip_blocked(variant, allow_private_ips=True) is True+def test_metadata_ip_blocked_under_all_flags(self):"""Every IP in the always-blocked set must be blocked under allallow-flag combinations."""@@ -1070,42 +1090,42 @@ class TestSchemeRejection:"""Non-http(s) schemes must be rejected outright (not just the host check)."""def test_file_scheme_rejected(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("file:///etc/passwd") is Falsedef test_ftp_scheme_rejected(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("ftp://example.com/") is Falsedef test_gopher_scheme_rejected(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("gopher://example.com/") is Falsedef test_dict_scheme_rejected(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("dict://example.com:11211/stat") is Falsedef test_no_scheme_rejected(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("127.0.0.1") is Falsedef test_scheme_relative_url_rejected(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1113,7 +1133,7 @@ class TestSchemeRejection:def test_uppercase_https_scheme_accepted(self):"""Schemes are case-insensitive per RFC 3986."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1168,7 +1188,7 @@ class TestNeverRaises:],)def test_pathological_input_returns_bool(self, weird_input):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1186,7 +1206,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_6to4_wrapped_loopback_blocked(self):"""``[2002:7f00:1::]`` — 6to4 wrap of 127.0.0.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1194,7 +1214,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_6to4_wrapped_rfc1918_blocked(self):"""``[2002:c0a8:101::]`` — 6to4 wrap of 192.168.1.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1202,7 +1222,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_nat64_wrapped_loopback_blocked(self):"""``[64:ff9b::7f00:1]`` — NAT64 wrap of 127.0.0.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1210,7 +1230,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_teredo_prefix_blocked(self):"""Teredo (2001::/32) tunnels IPv6-over-UDP/IPv4."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1218,7 +1238,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_ipv6_discard_prefix_blocked(self):"""RFC 6666 discard prefix (100::/64) is reserved for sinkholes."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1229,7 +1249,7 @@ class TestIPv6TransitionPrefixesBlocked:Cloud metadata is the highest-value SSRF target; the 2002::/16block is what catches this case (the IMDS hardcoded literalcheck is on the IPv4 form only)."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1237,7 +1257,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_nat64_wraps_aws_metadata_blocked(self):"""[64:ff9b::a9fe:a9fe] — NAT64 wrap of 169.254.169.254 (AWS IMDS)."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1245,7 +1265,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_6to4_wraps_rfc1918_class_a_blocked(self):"""[2002:0a00:1::] — 6to4 wrap of 10.0.0.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1253,7 +1273,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_6to4_wraps_rfc1918_class_b_blocked(self):"""[2002:ac10:1::] — 6to4 wrap of 172.16.0.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1261,7 +1281,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_nat64_wraps_rfc1918_class_a_blocked(self):"""[64:ff9b::a00:1] — NAT64 wrap of 10.0.0.1."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1273,7 +1293,7 @@ class TestIPv6TransitionPrefixesBlocked:the local-use prefix, [64:ff9b:1::a9fe:a9fe] reaches AWS IMDSidentically to the WKP form. Missing this prefix earned aHackerOne bounty against the Ruby ssrf_filter library."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1281,7 +1301,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_nat64_local_use_wraps_aws_metadata_blocked(self):"""[64:ff9b:1::a9fe:a9fe] — local-use NAT64 wrap of 169.254.169.254."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1292,7 +1312,7 @@ class TestIPv6TransitionPrefixesBlocked:(DEPRECATED 2006). On hosts with ::/96 routes this reaches IMDSidentically to the IPv4-mapped and NAT64-wrapped forms. Samedefense-in-depth class as the transition prefixes."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1300,7 +1320,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_ipv4_compatible_imds_hex_form_blocked(self):"""Same address, hex form: [::a9fe:a9fe]."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1308,7 +1328,7 @@ class TestIPv6TransitionPrefixesBlocked:def test_ipv4_compatible_rfc1918_blocked(self):"""[::192.168.1.1] — IPv4-Compatible wrap of RFC1918."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1331,42 +1351,42 @@ class TestIPv6TransitionPrefixesAllowFlagMatrix:"""def test_6to4_blocked_under_allow_localhost(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)assert is_ip_blocked("2002:7f00:1::", allow_localhost=True) is Truedef test_6to4_blocked_under_allow_private_ips(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)assert is_ip_blocked("2002:c0a8:101::", allow_private_ips=True) is Truedef test_nat64_blocked_under_allow_localhost(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)assert is_ip_blocked("64:ff9b::7f00:1", allow_localhost=True) is Truedef test_nat64_blocked_under_allow_private_ips(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)assert is_ip_blocked("64:ff9b::a00:1", allow_private_ips=True) is Truedef test_teredo_blocked_under_allow_private_ips(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)assert is_ip_blocked("2001::1", allow_private_ips=True) is Truedef test_discard_blocked_under_allow_private_ips(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -1375,7 +1395,7 @@ class TestIPv6TransitionPrefixesAllowFlagMatrix:def test_6to4_aws_metadata_blocked_under_allow_private_ips(self):"""High-value: even with the most permissive flag, the 6to4 wrapof AWS IMDS must remain blocked."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1386,7 +1406,7 @@ class TestIPv6TransitionPrefixesAllowFlagMatrix:def test_nat64_aws_metadata_blocked_under_allow_private_ips(self):"""Same locking-in for NAT64 wrap of IMDS."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1404,7 +1424,7 @@ class TestIPv6TransitionPrefixesAntiCollision:def test_google_dns_v6_passes(self):"""2001:4860:4860::8888 — Google Public DNS. Second hextet 0x4860is outside the 2001::/32 Teredo block."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1413,7 +1433,7 @@ class TestIPv6TransitionPrefixesAntiCollision:def test_cloudflare_dns_v6_passes(self):"""2606:4700:4700::1111 — Cloudflare Public DNS, far from anytransition prefix."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1422,7 +1442,7 @@ class TestIPv6TransitionPrefixesAntiCollision:def test_root_server_v6_passes(self):"""2001:500::/30 root-server allocation — second hextet 0x0500is outside Teredo."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1430,7 +1450,7 @@ class TestIPv6TransitionPrefixesAntiCollision:def test_he_tunnelbroker_v6_passes(self):"""2001:470::/32 Hurricane Electric — second hextet 0x0470."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1438,7 +1458,7 @@ class TestIPv6TransitionPrefixesAntiCollision:def test_neighbor_above_6to4_passes(self):"""2003::/16 sits adjacent to 2002::/16 but is not in it."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1447,7 +1467,7 @@ class TestIPv6TransitionPrefixesAntiCollision:def test_discard_prefix_neighbor_passes(self):"""100:1::/16 sits outside the 100::/64 discard prefix(second hextet 0x0001)."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1468,7 +1488,7 @@ class TestNat64EnvOptOut:"""def test_nat64_wkp_blocked_when_env_unset(self, monkeypatch):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1476,7 +1496,7 @@ class TestNat64EnvOptOut:assert validate_url("http://[64:ff9b::a00:1]/") is Falsedef test_nat64_wkp_allowed_when_env_true(self, monkeypatch):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1486,7 +1506,7 @@ class TestNat64EnvOptOut:assert validate_url("http://[64:ff9b::808:808]/") is Truedef test_nat64_local_use_allowed_when_env_true(self, monkeypatch):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1496,7 +1516,7 @@ class TestNat64EnvOptOut:def test_env_does_not_unblock_6to4(self, monkeypatch):"""6to4 has no live legitimate use; the operator switch mustnot extend to it."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1504,7 +1524,7 @@ class TestNat64EnvOptOut:assert validate_url("http://[2002:c0a8:101::]/") is Falsedef test_env_does_not_unblock_teredo(self, monkeypatch):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1512,7 +1532,7 @@ class TestNat64EnvOptOut:assert validate_url("http://[2001::1]/") is Falsedef test_env_does_not_unblock_discard(self, monkeypatch):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1523,19 +1543,90 @@ class TestNat64EnvOptOut:"""The IPv4-form metadata literal is in ALWAYS_BLOCKED_METADATA_IPSand is checked BEFORE the prefix loop. The NAT64 carve-outcannot reach it."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")assert validate_url("http://169.254.169.254/") is False+ def test_env_does_not_unblock_link_local_for_notification_path(self):+ """NAT64 opt-in must not reopen link-local metadata for the+ notification send path. ``64:ff9b::a9fe:2a2a`` is the NAT64 wrap of+ Scaleway's ``169.254.42.42`` (link-local metadata); with+ ``block_link_local=True`` it stays blocked even under the carve-out,+ matching how the direct v4 form is blocked."""+ from local_deep_research.security.ssrf_validator import is_ip_blocked++ # NAT64 well-known prefix wrap of the link-local metadata address.+ assert (+ is_ip_blocked(+ "64:ff9b::a9fe:2a2a",+ allow_private_ips=True,+ block_link_local=True,+ allow_nat64=True,+ )+ is True+ )+ # RFC 8215 local-use NAT64 prefix wrap of the same address.+ assert (+ is_ip_blocked(+ "64:ff9b:1::a9fe:2a2a",+ allow_private_ips=True,+ block_link_local=True,+ allow_nat64=True,+ )+ is True+ )+ # Control: the direct v4 link-local form is blocked on this path.+ assert (+ is_ip_blocked(+ "169.254.42.42",+ allow_private_ips=True,+ block_link_local=True,+ allow_nat64=True,+ )+ is True+ )++ def test_env_still_allows_link_local_wrap_for_default_callers(self):+ """The link-local NAT64 block is gated on ``block_link_local`` (the+ notification path). Default callers permit link-local under+ ``allow_private_ips``, so a NAT64-wrapped link-local stays reachable+ for them under the opt-in — behavior unchanged."""+ from local_deep_research.security.ssrf_validator import is_ip_blocked++ assert (+ is_ip_blocked(+ "64:ff9b::a9fe:2a2a",+ allow_private_ips=True,+ allow_nat64=True,+ )+ is False+ )++ def test_link_local_block_does_not_overblock_public_wrap(self):+ """The link-local carve-out must not over-block: a NAT64-wrapped+ *public* IPv4 (Google DNS ``8.8.8.8``) is still reachable under the+ opt-in even with ``block_link_local=True`` — only link-local closes."""+ from local_deep_research.security.ssrf_validator import is_ip_blocked++ assert (+ is_ip_blocked(+ "64:ff9b::808:808",+ allow_private_ips=True,+ block_link_local=True,+ allow_nat64=True,+ )+ is False+ )+def test_env_does_not_unblock_imds_via_nat64_wkp_wrap(self, monkeypatch):"""The IMDS embedded-IPv4 check fires before the NAT64 carve-out:even with operator opt-in, [64:ff9b::a9fe:a9fe] (NAT64 WKP wrapof 169.254.169.254) stays blocked. ALWAYS_BLOCKED_METADATA_IPSis absolute by design."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1546,7 +1637,7 @@ class TestNat64EnvOptOut:self, monkeypatch):"""Same lock-in for the RFC 8215 local-use prefix wrap."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1558,7 +1649,7 @@ class TestNat64EnvOptOut:):"""169.254.170.2 (AWS ECS task metadata v3) is also in thealways-blocked set; NAT64 wrap stays blocked under opt-in."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1568,7 +1659,7 @@ class TestNat64EnvOptOut:def test_env_falsy_values_keep_blocked(self, monkeypatch):"""'false', '0', and unset must all keep the block in place."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1581,7 +1672,7 @@ class TestNat64EnvOptOut:def test_env_true_does_not_bypass_loopback_in_block_list(self, monkeypatch):"""Sanity: opting into NAT64 must not accidentally unblocknon-NAT64 entries that share a prefix family."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -1593,7 +1684,7 @@ class TestNat64EnvOptOut:"""The carve-out's ``continue`` lives in the same loop that walksULA (fc00::/7) and link-local (fe80::/10). Pin that opting intoNAT64 does not accidentally unblock these adjacent IPv6 ranges."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -1602,7 +1693,7 @@ class TestNat64EnvOptOut:assert is_ip_blocked("fd12:3456:789a::1") is Truedef test_env_true_does_not_unblock_ipv6_link_local(self, monkeypatch):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_ip_blocked,)@@ -1622,7 +1713,7 @@ class TestIsNat64WrappedMetadataIp:that point the address is no longer IPv6 and the NAT64 checkdoes not apply."""import ipaddress- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_nat64_wrapped_metadata_ip,)@@ -1636,7 +1727,7 @@ class TestIsNat64WrappedMetadataIp:def test_returns_false_for_non_nat64_ipv6(self):"""Public IPv6 (Google DNS) is not in any NAT64 prefix."""import ipaddress- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_nat64_wrapped_metadata_ip,)@@ -1652,7 +1743,7 @@ class TestIsNat64WrappedMetadataIp:prefix but the embedded IPv4 is not metadata — helper returnsFalse so the broader carve-out logic can apply."""import ipaddress- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_nat64_wrapped_metadata_ip,)@@ -1665,7 +1756,7 @@ class TestIsNat64WrappedMetadataIp:def test_returns_true_for_imds_via_wkp(self):import ipaddress- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_nat64_wrapped_metadata_ip,)@@ -1678,7 +1769,7 @@ class TestIsNat64WrappedMetadataIp:def test_returns_true_for_imds_via_local_use(self):import ipaddress- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (is_nat64_wrapped_metadata_ip,)@@ -1694,49 +1785,49 @@ class TestValidateUrlEdgeCases:"""Robustness: validate_url must never raise, only return bool."""def test_empty_string_returns_false(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("") is Falsedef test_whitespace_only_returns_false(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url(" ") is Falsedef test_tab_newline_only_returns_false(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("\t\n") is Falsedef test_none_returns_false(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url(None) is Falsedef test_int_returns_false(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url(123) is Falsedef test_malformed_ipv6_no_crash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)assert validate_url("http://[::") is Falsedef test_extremely_long_url_no_crash(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1760,7 +1851,7 @@ class TestLegitimateUrlsStillPass:)def test_simple_http_url(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1768,7 +1859,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://example.com/") is Truedef test_explicit_port(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1776,7 +1867,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://example.com:8080/") is Truedef test_userinfo_is_rfc_legal(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1784,7 +1875,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://user:[email protected]/") is Truedef test_userinfo_with_port(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1792,7 +1883,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://user:[email protected]:8080/") is Truedef test_trailing_dot_hostname(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1800,7 +1891,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://example.com./") is Truedef test_path_query_fragment(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1808,7 +1899,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://example.com/path?q=1#frag") is Truedef test_plus_in_query_string(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1817,7 +1908,7 @@ class TestLegitimateUrlsStillPass:def test_encoded_backslash_in_path_is_rfc_legal(self):"""%5C in a PATH (not a host bypass) is RFC-legal and must pass."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1825,7 +1916,7 @@ class TestLegitimateUrlsStillPass:assert validate_url("http://example.com/path%5Cfile") is Truedef test_encoded_space_in_path(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1837,7 +1928,7 @@ class TestLegitimateUrlsStillPass:def test_uppercase_hostname_case_folded(self):"""Locks in case-folding parity between urlparse and urllib3."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1846,7 +1937,7 @@ class TestLegitimateUrlsStillPass:def test_ipv6_public(self):"""IPv6 hosts unwrap from brackets and check correctly."""- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1886,7 +1977,7 @@ class TestUnspecifiedIPv4Blocked:],)def test_unspecified_ipv4_literal_blocked(self, url):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1911,7 +2002,7 @@ class TestDnsResolutionNonGaierror:[PermissionError("eperm"), OSError("eio"), RuntimeError("boom")],)def test_non_gaierror_during_dns_fails_closed(self, exc, loguru_caplog):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1941,7 +2032,7 @@ class TestRfcForbiddenControlChars:["\x01", "\x1f", "\x7f"],)def test_control_byte_in_url_rejected(self, ctrl_char):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1963,7 +2054,7 @@ class TestAlternateIpHexForm:"""def test_hex_dword_loopback_resolves_and_blocks(self):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -1993,7 +2084,7 @@ class TestPortEdgeCases:],)def test_port_edge_case_blocked(self, url):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -2016,7 +2107,7 @@ class TestMultipleAtSignsContract:def test_double_at_resolves_to_last_segment(self):from urllib3.util import parse_url- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -2046,7 +2137,7 @@ class TestUserinfoContainsIpShape:def test_userinfo_ip_shape_is_not_a_bypass(self):from urllib3.util import parse_url- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)@@ -2082,7 +2173,7 @@ class TestIpv6ZoneIdBlocked:],)def test_ipv6_zone_id_link_local_blocked(self, url):- from src.local_deep_research.security.ssrf_validator import (+ from local_deep_research.security.ssrf_validator import (validate_url,)diff --git a/tests/security/test_ssrf_validator_high_value.py b/tests/security/test_ssrf_validator_high_value.pyindex 9d3fafb2bb..09a3a637d0 100644--- a/tests/security/test_ssrf_validator_high_value.py+++ b/tests/security/test_ssrf_validator_high_value.py@@ -85,6 +85,54 @@ class TestIsIpBlockedSpecialRanges:def test_loopback_also_allowed_with_private_flag(self):assert is_ip_blocked("127.0.0.1", allow_private_ips=True) is False+ def test_link_local_blocked_with_block_link_local_flag(self):+ """block_link_local=True (notification path) keeps the whole+ link-local range blocked even under allow_private_ips=True —+ metadata lives there beyond the always-blocked literals (e.g.+ Scaleway 169.254.42.42)."""+ assert (+ is_ip_blocked(+ "169.254.42.42",+ allow_private_ips=True,+ block_link_local=True,+ )+ is True+ )+ assert (+ is_ip_blocked(+ "169.254.1.1", allow_private_ips=True, block_link_local=True+ )+ is True+ )+ assert (+ is_ip_blocked(+ "fe80::1", allow_private_ips=True, block_link_local=True+ )+ is True+ )++ def test_block_link_local_does_not_overblock_rfc1918_loopback_ula(self):+ """block_link_local must NOT block RFC1918 / CGNAT / loopback /+ non-link-local ULA — self-hosted notifiers keep working."""+ for ip in (+ "10.11.12.13",+ "172.16.5.5",+ "192.168.50.20",+ "100.64.0.1",+ "127.0.0.1",+ "fd00::1",+ ):+ assert (+ is_ip_blocked(ip, allow_private_ips=True, block_link_local=True)+ is False+ ), ip++ def test_block_link_local_noop_without_private_flag(self):+ """Without allow_private_ips, link-local is already blocked; the+ flag changes nothing there (and public stays allowed)."""+ assert is_ip_blocked("169.254.1.1", block_link_local=True) is True+ assert is_ip_blocked("93.184.216.34", block_link_local=True) is False+class TestIsIpBlockedCloudMetadata:"""Cloud-provider metadata endpoints always blocked under all flags."""@@ -291,5 +339,6 @@ class TestConstants:"169.254.170.23","169.254.0.23","100.100.100.200",+ "fd00:ec2::254",})diff --git a/tests/vector_stores/test_facade_load.py b/tests/vector_stores/test_facade_load.pyindex d4defc3275..576c724412 100644--- a/tests/vector_stores/test_facade_load.py+++ b/tests/vector_stores/test_facade_load.py@@ -10,8 +10,8 @@ import threadingimport numpy as np-from src.local_deep_research.vector_stores import get_vector_store_class-from src.local_deep_research.vector_stores.facade import VectorIndex+from local_deep_research.vector_stores import get_vector_store_class+from local_deep_research.vector_stores.facade import VectorIndexdef _noop(_p):diff --git a/tests/vector_stores/test_faiss_store.py b/tests/vector_stores/test_faiss_store.pyindex 98bb0a58a0..8fd3f4ff50 100644--- a/tests/vector_stores/test_faiss_store.py+++ b/tests/vector_stores/test_faiss_store.py@@ -12,7 +12,7 @@ import faissimport numpy as npimport pytest-from src.local_deep_research.vector_stores.implementations.faiss_store import (+from local_deep_research.vector_stores.implementations.faiss_store import (FaissVectorStore,)@@ -332,7 +332,7 @@ class TestPersistLoad:raise RuntimeError("simulated write_index failure")monkeypatch.setattr(- "src.local_deep_research.vector_stores.implementations."+ "local_deep_research.vector_stores.implementations.""faiss_store.write_index",_boom,)diff --git a/tests/vector_stores/test_legacy_cleanup_no_plaintext.py b/tests/vector_stores/test_legacy_cleanup_no_plaintext.pyindex d40ceea81a..fe757d6de1 100644--- a/tests/vector_stores/test_legacy_cleanup_no_plaintext.py+++ b/tests/vector_stores/test_legacy_cleanup_no_plaintext.py@@ -17,7 +17,7 @@ import pytestfrom langchain_community.vectorstores import FAISSfrom langchain_core.embeddings import Embeddings-from src.local_deep_research.vector_stores.legacy_cleanup import (+from local_deep_research.vector_stores.legacy_cleanup import (migrate_legacy_docstores,_rag_cache_root,)@@ -291,7 +291,7 @@ def test_extract_map_sweeps_stale_tmp_but_spares_fresh_concurrent_tmp(import timefrom pathlib import Path- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (_STALE_TMP_AGE_SECONDS,_write_sidecar_atomic,)@@ -400,10 +400,10 @@ def test_non_string_idmap_value_is_rejected_without_str_coercion(cache_root):def test_full_migration_round_trip_no_reembed(cache_root):"""old LangChain FAISS -> extract sidecar -> re-key to IndexIDMap2 by int id,without re-embedding; search returns the int ids; orphans dropped."""- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)- from src.local_deep_research.vector_stores import get_vector_store_class+ from local_deep_research.vector_stores import get_vector_store_classuserdir = cache_root / "u"uuids = [uuid.uuid4().hex for _ in range(4)]@@ -455,7 +455,7 @@ def test_rekey_already_migrated_tolerates_concurrently_deleted_sidecar(report success — NOT raise FileNotFoundError, which makes the callerdestructively quarantine a perfectly healthy, just-rekeyed index."""- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)@@ -494,8 +494,8 @@ def test_rekey_fresh_build_tolerates_concurrent_migration(cache_root, mocker):import faissimport numpy as np- import src.local_deep_research.vector_stores.legacy_cleanup as lc- from src.local_deep_research.vector_stores.legacy_cleanup import (+ import local_deep_research.vector_stores.legacy_cleanup as lc+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)@@ -537,7 +537,7 @@ def test_rekey_on_plain_indexidmap_raises_not_aborts(cache_root):import faissimport numpy as np- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)@@ -569,7 +569,7 @@ def test_rekey_on_plain_indexidmap_raises_not_aborts(cache_root):def test_rekey_rejects_duplicate_ids_from_sidecar(cache_root):"""Two legacy positions resolving to the SAME DocumentChunk.id must berefused (would bake an id-collision the set()-based read-back can't see)."""- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)@@ -601,10 +601,10 @@ def test_rekey_on_already_migrated_index_does_not_crash(cache_root):silently reconstructs wrong vectors) — it must detect the new format,drop the stale sidecar, and leave the index intact."""- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)- from src.local_deep_research.vector_stores import get_vector_store_class+ from local_deep_research.vector_stores import get_vector_store_classuserdir = cache_root / "u"uuids = [uuid.uuid4().hex for _ in range(3)]@@ -664,7 +664,7 @@ def test_rekey_rejects_already_migrated_with_mismatched_ids(cache_root):import faissimport numpy as np- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)@@ -704,7 +704,7 @@ def test_rekey_rejects_foreign_faiss_class_without_segfault(cache_root):import faissimport numpy as np- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)@@ -742,7 +742,7 @@ def test_rekey_rejects_already_migrated_with_duplicate_ids(cache_root):import faissimport numpy as np- from src.local_deep_research.vector_stores.legacy_cleanup import (+ from local_deep_research.vector_stores.legacy_cleanup import (rekey_index_file,)diff --git a/tests/web/services/conftest.py b/tests/web/services/conftest.pyindex 18931a4a8a..4a5630f8b5 100644--- a/tests/web/services/conftest.py+++ b/tests/web/services/conftest.py@@ -33,22 +33,16 @@ def _allow_socket_subscribe(monkeypatch):Scope: function. The patches are torn down at test exit."""# Lazy import — keep this conftest cheap for tests that never touch- # the socket service at all. Some tests in this dir import via- # ``local_deep_research...`` while others use ``src.local_deep_research...``;- # Python may cache them as separate module identities, so resolve- # whichever is importable and patch its session binding.- try:- from local_deep_research.web.services.socket_service import (- SocketIOService,- )-- module_path = "local_deep_research.web.services.socket_service"- except ImportError:- from src.local_deep_research.web.services.socket_service import (- SocketIOService,- )-- module_path = "src.local_deep_research.web.services.socket_service"+ # the socket service at all. Import via the canonical+ # ``local_deep_research`` package (the module instance the running app+ # binds its routes to); the ``src.local_deep_research`` alias is banned in+ # tests (it is a distinct module identity — see the check-no-src-test-imports+ # pre-commit hook) so there is only one binding to patch.+ from local_deep_research.web.services.socket_service import (+ SocketIOService,+ )++ module_path = "local_deep_research.web.services.socket_service"# __handle_subscribe / __handle_unsubscribe now also re-validate the# socket's session id against the SessionManager (defense-in-depth), sodiff --git a/tests/web/services/test_chat_step_decision.py b/tests/web/services/test_chat_step_decision.pyindex 39ce8e169c..dbc1792de0 100644--- a/tests/web/services/test_chat_step_decision.py+++ b/tests/web/services/test_chat_step_decision.py@@ -14,7 +14,7 @@ The tests below pin down the contract per scenario.import pytest-from src.local_deep_research.web.services.research_service import (+from local_deep_research.web.services.research_service import (_chat_step_decision,_compose_chat_step_content,_STEP_PHASES,diff --git a/tests/web/test_socket_subscribe_ownership.py b/tests/web/test_socket_subscribe_ownership.pyindex c535778d75..dab2cfbc99 100644--- a/tests/web/test_socket_subscribe_ownership.py+++ b/tests/web/test_socket_subscribe_ownership.py@@ -12,7 +12,7 @@ not need to stand up a Flask app or the singleton wrapper.from unittest.mock import patch, MagicMock-from src.local_deep_research.web.services.socket_service import SocketIOService+from local_deep_research.web.services.socket_service import SocketIOServicedef _patched_session(row):@@ -32,7 +32,7 @@ def _patched_session(row):def test_owns_research_true_when_row_exists():with patch(- "src.local_deep_research.database.session_context.get_user_db_session",+ "local_deep_research.database.session_context.get_user_db_session",return_value=_patched_session(("abc",)),):assert SocketIOService._user_owns_research("alice", "abc") is True@@ -41,7 +41,7 @@ def test_owns_research_true_when_row_exists():def test_owns_research_false_when_row_missing():"""Cross-user disclosure regression: bob must not see alice's research."""with patch(- "src.local_deep_research.database.session_context.get_user_db_session",+ "local_deep_research.database.session_context.get_user_db_session",return_value=_patched_session(None),):assert (@@ -57,7 +57,7 @@ def test_owns_research_denies_on_exception():raise RuntimeError("DB unavailable")with patch(- "src.local_deep_research.database.session_context.get_user_db_session",+ "local_deep_research.database.session_context.get_user_db_session",raising,):assert SocketIOService._user_owns_research("alice", "anything") is False@@ -89,7 +89,7 @@ def test_owns_benchmark_run_true_for_integer_id():(ResearchHistory) misses; second (BenchmarkRun) hits."""with patch(- "src.local_deep_research.database.session_context.get_user_db_session",+ "local_deep_research.database.session_context.get_user_db_session",return_value=_patched_session_seq([None, (5,)]),):assert SocketIOService._user_owns_research("alice", "5") is True@@ -99,7 +99,7 @@ def test_owns_benchmark_run_false_when_not_owned():"""An integer id matching no ResearchHistory and no BenchmarkRun rowin the user's own DB is rejected (no cross-user widening)."""with patch(- "src.local_deep_research.database.session_context.get_user_db_session",+ "local_deep_research.database.session_context.get_user_db_session",return_value=_patched_session_seq([None, None]),):assert SocketIOService._user_owns_research("bob", "5") is False@@ -122,16 +122,16 @@ def test_unsubscribe_rejected_when_user_does_not_own_research():with (patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class,patch(- "src.local_deep_research.web.services.socket_service.session",+ "local_deep_research.web.services.socket_service.session",{"username": "alice", "session_id": "sess-alice"},),# Session is valid (defense-in-depth check passes) so this test# exercises the ownership rejection specifically.patch(- "src.local_deep_research.web.auth.session_manager."+ "local_deep_research.web.auth.session_manager.""session_manager.validate_session",return_value="alice",),@@ -178,14 +178,14 @@ def test_unsubscribe_allowed_when_user_owns_research():with (patch(- "src.local_deep_research.web.services.socket_service.SocketIO"+ "local_deep_research.web.services.socket_service.SocketIO") as mock_socketio_class,patch(- "src.local_deep_research.web.services.socket_service.session",+ "local_deep_research.web.services.socket_service.session",{"username": "alice", "session_id": "sess-alice"},),patch(- "src.local_deep_research.web.auth.session_manager."+ "local_deep_research.web.auth.session_manager.""session_manager.validate_session",return_value="alice",),diff --git a/tests/web_services/conftest.py b/tests/web_services/conftest.pyindex 2ca3e0386f..552d76ba06 100644--- a/tests/web_services/conftest.py+++ b/tests/web_services/conftest.py@@ -14,24 +14,17 @@ def _allow_socket_subscribe():``session.get("username")`` lookup in ``__handle_subscribe`` raises``RuntimeError: Working outside of request context``.- Tests in this directory import via ``local_deep_research.web...``- (no ``src.`` prefix). Patch BOTH paths because Python may treat the- two import paths as distinct module identities depending on how the- package is installed.+ Tests in this directory import via the canonical+ ``local_deep_research.web...`` package (no ``src.`` prefix). The+ ``src.local_deep_research`` alias is banned in tests (it is a distinct+ module identity — see the check-no-src-test-imports pre-commit hook), so+ there is a single binding to patch."""- # Resolve the module from whichever path is importable.- try:- from local_deep_research.web.services.socket_service import (- SocketIOService,- )-- module_path = "local_deep_research.web.services.socket_service"- except ImportError:- from src.local_deep_research.web.services.socket_service import (- SocketIOService,- )-- module_path = "src.local_deep_research.web.services.socket_service"+ from local_deep_research.web.services.socket_service import (+ SocketIOService,+ )++ module_path = "local_deep_research.web.services.socket_service"# __handle_subscribe / __handle_unsubscribe now also re-validate the# socket's session id against the SessionManager (defense-in-depth), so