~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
"""
Comprehensive tests for notification-related modules.
Covers:
- NotificationURLValidator (SSRF prevention, scheme blocking, private IP detection)
- NotificationService (send logic, event sending, service testing, URL validation)
- NotificationManager (rate limiting, settings snapshot, event routing)
- RateLimiter (per-user limits, hourly/daily windows, cleanup)
- NotificationTemplate (Jinja2 rendering, custom templates, fallback)
- build_notification_url (URL building from settings)
- Queue helpers (send_queue_notification, send_queue_failed_notification)
- mask_sensitive_url (credential masking)
- Exception hierarchy
"""
import importlib.metadata
import ipaddress
import threading
import tomllib
from collections import deque
from datetime import datetime, timedelta, timezone
from pathlib import Path
from unittest.mock import Mock, patch
import pytest
from local_deep_research.notifications.exceptions import (
NotificationError,
RateLimitError,
SendError,
ServiceError,
)
from local_deep_research.notifications.manager import (
NotificationManager,
RateLimiter,
)
from local_deep_research.notifications.service import NotificationService
from local_deep_research.notifications.templates import (
EventType,
NotificationTemplate,
)
from local_deep_research.notifications.url_builder import build_notification_url
from local_deep_research.notifications.queue_helpers import (
send_queue_notification,
send_queue_failed_notification,
)
from local_deep_research.security.notification_validator import (
NotificationURLValidationError,
NotificationURLValidator,
)
from local_deep_research.security.url_builder import mask_sensitive_url
from local_deep_research.security.url_validator import (
URLValidationError,
URLValidator,
)
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
def _reset_shared_rate_limiter():
"""Reset the singleton rate limiter between tests to avoid cross-contamination."""
NotificationManager._shared_rate_limiter = None
yield
NotificationManager._shared_rate_limiter = None
@pytest.fixture(autouse=True)
def _enable_outbound_notifications(monkeypatch):
"""Module-level autouse: open the operator-level env gate so tests in
this file that exercise the inner notification logic don't bail at
NotificationManager.__init__ / NotificationService.send. Tests of the
gate itself (none in this file) should override with
monkeypatch.delenv. See SECURITY.md "Notification Webhook SSRF".
"""
monkeypatch.setenv("LDR_NOTIFICATIONS_ALLOW_OUTBOUND", "true")
@pytest.fixture()
def default_settings():
"""Settings snapshot that enables notifications with a valid URL."""
return {
"notifications.service_url": "discord://webhook_id/token",
"notifications.on_research_completed": True,
"notifications.on_research_failed": True,
"notifications.on_research_queued": True,
"notifications.rate_limit_per_hour": 10,
"notifications.rate_limit_per_day": 50,
"notifications.allow_private_ips": False,
}
@pytest.fixture()
def disabled_settings():
"""Settings snapshot with notifications disabled."""
return {
"notifications.service_url": "",
"notifications.on_research_completed": False,
"notifications.on_research_failed": False,
"notifications.rate_limit_per_hour": 10,
"notifications.rate_limit_per_day": 50,
}
# ===================================================================
# NotificationURLValidator
# ===================================================================
class TestNotificationURLValidator:
"""Tests for SSRF prevention and scheme validation."""
# -- Allowed schemes --------------------------------------------------
@pytest.mark.parametrize(
"url",
[
"discord://webhook_id/token",
"slack://token_a/token_b/token_c",
"mailto://user:[email protected]",
"https://hooks.example.com/webhook",
"http://hooks.example.com/webhook",
"tgram://123456789:Token_abc-123/987654321",
"gotify://gotify.example.com/token",
"pushover://user_key/token",
"ntfy://ntfy.sh/topic",
"ntfys://ntfy.sh/topic",
"json://hooks.example.com/endpoint",
"xml://hooks.example.com/endpoint",
"form://hooks.example.com/endpoint",
"matrix://user:[email protected]/room",
"mattermost://hooks.example.com/token",
"rocketchat://hooks.example.com/token",
"teams://token_a/token_b/token_c",
],
)
def test_allowed_schemes_pass(self, url):
is_valid, err = NotificationURLValidator.validate_service_url(url)
assert is_valid is True, f"Expected valid for {url}, got error: {err}"
assert err is None
# -- Blocked schemes ---------------------------------------------------
@pytest.mark.parametrize(
"url",
[
"file:///etc/passwd",
"ftp://evil.com/payload",
"ftps://evil.com/payload",
"data:text/html,<script>alert(1)</script>",
"javascript:alert(1)",
"vbscript:msgbox",
"about:blank",
"blob:http://evil.com/obj",
],
)
def test_blocked_schemes_rejected(self, url):
is_valid, err = NotificationURLValidator.validate_service_url(url)
assert is_valid is False
assert err is not None
# The error should mention 'protocol' or 'Blocked'
assert "protocol" in err.lower() or "blocked" in err.lower()
# -- Unknown scheme ----------------------------------------------------
def test_unknown_scheme_rejected(self):
is_valid, err = NotificationURLValidator.validate_service_url(
"gopher://evil.com"
)
assert is_valid is False
assert "unsupported" in err.lower() or "protocol" in err.lower()
# -- Empty / invalid inputs --------------------------------------------
@pytest.mark.parametrize("url", ["", None, 123, " "])
def test_empty_or_invalid_input(self, url):
is_valid, err = NotificationURLValidator.validate_service_url(url)
assert is_valid is False
def test_url_without_scheme(self):
is_valid, err = NotificationURLValidator.validate_service_url(
"example.com/webhook"
)
assert is_valid is False
# -- Private IP blocking -----------------------------------------------
@pytest.mark.parametrize(
"url",
[
"http://localhost:5000/webhook",
"http://127.0.0.1:8080/hook",
"https://0.0.0.0/hook",
"http://[::1]/hook",
],
)
def test_private_ip_blocked_by_default(self, url):
is_valid, err = NotificationURLValidator.validate_service_url(url)
assert is_valid is False
assert "private" in err.lower() or "blocked" in err.lower()
@pytest.mark.parametrize(
"url",
[
"http://localhost:5000/webhook",
"http://127.0.0.1:8080/hook",
],
)
def test_private_ip_allowed_when_flag_set(self, url):
is_valid, err = NotificationURLValidator.validate_service_url(
url, allow_private_ips=True
)
assert is_valid is True
# -- Private IP detection helper ----------------------------------------
@pytest.mark.parametrize(
"hostname,expected",
[
("localhost", True),
("127.0.0.1", True),
("::1", True),
("0.0.0.0", True),
("::", True),
("10.0.0.1", True),
("172.16.0.1", True),
("192.168.1.1", True),
("8.8.8.8", False),
("hooks.slack.com", False),
],
)
def test_is_private_ip(self, hostname, expected):
assert NotificationURLValidator._is_private_ip(hostname) is expected
# -- validate_multiple_urls ---------------------------------------------
def test_validate_multiple_urls_all_valid(self):
urls = "discord://id/token, slack://a/b/c"
is_valid, err = NotificationURLValidator.validate_multiple_urls(urls)
assert is_valid is True
assert err is None
def test_validate_multiple_urls_one_invalid(self):
urls = "discord://id/token, file:///etc/passwd"
is_valid, err = NotificationURLValidator.validate_multiple_urls(urls)
assert is_valid is False
assert err is not None
def test_validate_multiple_urls_empty(self):
is_valid, err = NotificationURLValidator.validate_multiple_urls("")
assert is_valid is False
def test_validate_multiple_urls_only_whitespace(self):
is_valid, err = NotificationURLValidator.validate_multiple_urls(" , ")
assert is_valid is False
# -- validate_service_url_strict ----------------------------------------
def test_strict_validation_raises_on_invalid(self):
with pytest.raises(NotificationURLValidationError):
NotificationURLValidator.validate_service_url_strict(
"file:///etc/passwd"
)
def test_strict_validation_returns_true_on_valid(self):
assert (
NotificationURLValidator.validate_service_url_strict(
"discord://id/token"
)
is True
)
# ===================================================================
# Apprise plugin compatibility, destination, and DNS contract
# ===================================================================
class TestPluginSchemeDNSContract:
"""Pin Apprise 1.12 compatibility, destinations, and DNS screening.
Destination behaviour is URL-mode-dependent. Discord and Slack use fixed
service endpoints after LDR rejects their secondary ``template`` resource.
ntfy cloud and Matrix t2bot modes are also fixed-endpoint modes, while ntfy
private, Matrix server/webhook, Signal, Gotify, and generic plugins send to
the authority host. LDR attempts one metadata-screening DNS lookup for
every non-literal plugin authority, including opaque tokens; successful
answers are screened, while DNS failure or timeout is allowed.
"""
# Reviewed floor, not an exact pin: pyproject declares
# ``apprise>=1.12.0,<2`` and the lock resolves at or above it. The
# BEHAVIOURAL contract is enforced separately (and more strongly) by
# ``test_query_key_parser_matches_apprise``, which diffs LDR's canonical
# query keys against the INSTALLED ``apprise.utils.parse.parse_qsd`` —
# so a future Apprise that changes those semantics fails CI regardless
# of what the version string says.
MIN_APPRISE_VERSION = "1.12.0"
MATRIX_TOKEN = "a" * 64
DNS_FIXTURES = (
(
"signal://signal-api.example.com:8739/+15551234567/+15557654321",
"signal-api.example.com",
),
(
"ntfy://ntfy.example.com/topic?mode=private",
"ntfy.example.com",
),
(
"matrix://user:[email protected]/%23room?mode=matrix",
"matrix.example.com",
),
)
def test_apprise_security_contract_matches_metadata_lock_and_runtime(self):
lock_path = Path(__file__).resolve().parents[3] / "pdm.lock"
project_path = lock_path.with_name("pyproject.toml")
with lock_path.open("rb") as lock_file:
lock_data = tomllib.load(lock_file)
with project_path.open("rb") as project_file:
project_data = tomllib.load(project_file)
locked_versions = [
package["version"]
for package in lock_data["package"]
if package["name"] == "apprise"
]
declared_requirements = [
dependency
for dependency in project_data["project"]["dependencies"]
if dependency.lower().startswith("apprise")
]
assert declared_requirements == [
f"apprise>={self.MIN_APPRISE_VERSION},<2"
], (
"pyproject.toml must declare the reviewed Apprise floor so the "
"mirrored query-key parser cannot be resolved against an older, "
"unreviewed Apprise"
)
# The floor is the contract, enforced on all three legs: the
# published dependency (pyproject.toml), the resolved lockfile
# (pdm.lock), and the installed runtime. It is a floor rather than an
# exact pin because the dependency-update bot legitimately moves the
# lock forward and CI installs into a container whose resolver/base
# layer may surface a forward-compatible build; a hard equality would
# fail the suite for drift that is not a contract regression. A
# downgrade below the reviewed floor still fails loudly.
def _release(version_string):
parts = []
for token in version_string.split("."):
digits = ""
for char in token:
if char.isdigit():
digits += char
else:
break
parts.append(int(digits) if digits else 0)
return tuple(parts)
assert locked_versions and all(
_release(version) >= _release(self.MIN_APPRISE_VERSION)
for version in locked_versions
), (
f"Locked apprise {locked_versions} is older than the reviewed "
f"floor {self.MIN_APPRISE_VERSION}"
)
runtime_version = importlib.metadata.version("apprise")
assert _release(runtime_version) >= _release(
self.MIN_APPRISE_VERSION
), (
"Installed apprise "
f"{runtime_version} is older than the reviewed floor "
f"{self.MIN_APPRISE_VERSION}"
)
@pytest.mark.parametrize(
("url", "attachment_type"),
[
pytest.param(
"discord://123456789012345678/token"
"?template=file%3A%2F%2F%2Fetc%2Fpasswd",
"AttachFile",
id="discord-file-template",
),
pytest.param(
"slack://T00000000/B00000000/token"
"?template=http%3A%2F%2F169.254.169.254%2Fmetadata",
"AttachHTTP",
id="slack-http-template",
),
],
)
@pytest.mark.filterwarnings(
"ignore:'imghdr' is deprecated.*:DeprecationWarning"
)
def test_unsafe_template_is_a_real_apprise_secondary_resource(
self, url, attachment_type
):
"""Keep the denylist tied to the locked dependency's behavior."""
from apprise import Apprise
apprise_instance = Apprise()
assert apprise_instance.add(url) is True
assert type(apprise_instance[0].template[0]).__name__ == attachment_type
is_valid, error = NotificationURLValidator.validate_service_url(url)
assert is_valid is False
assert error == "Blocked unsafe notification parameter: template"
@pytest.mark.filterwarnings(
"ignore:'imghdr' is deprecated.*:DeprecationWarning"
)
def test_apprise_protocol_prefix_compatibility(self):
"""Dependency bumps must trigger an explicit allowlist/doc review."""
from apprise import Apprise
details = Apprise().details()
protocols = {
protocol
for schema in details["schemas"]
for field in ("protocols", "secure_protocols")
for protocol in (schema[field] or ())
}
functional_overlap = {
"discord",
"slack",
"gotify",
"ntfy",
"ntfys",
"signal",
"matrix",
"json",
"xml",
"form",
"mailto",
}
ldr_only_names = {
"telegram",
"pushover",
"teams",
"mattermost",
"rocketchat",
}
apprise_names = {
"tgram",
"pover",
"workflow",
"workflows",
"mmost",
"mmosts",
"rocket",
"rockets",
}
assert functional_overlap <= protocols
assert ldr_only_names.isdisjoint(protocols)
assert apprise_names <= protocols
assert "msteams" not in protocols
@pytest.mark.parametrize(
("url", "mode", "hostname", "post_target", "destination"),
[
pytest.param(
"ntfy://topic",
"cloud",
"topic",
"apprise.plugins.ntfy.requests.post",
"https://ntfy.sh",
id="ntfy-cloud-fixed-endpoint",
),
pytest.param(
"ntfy://ntfy.example.com/topic?mode=private",
"private",
"ntfy.example.com",
"apprise.plugins.ntfy.requests.post",
"http://ntfy.example.com",
id="ntfy-private-authority-host",
),
pytest.param(
"matrix://" + MATRIX_TOKEN,
"t2bot",
MATRIX_TOKEN,
"apprise.plugins.matrix.base.requests.post",
"https://webhooks.t2bot.io/api/v1/matrix/hook/" + MATRIX_TOKEN,
id="matrix-t2bot-fixed-endpoint",
),
pytest.param(
"matrix://user:[email protected]/%23room?mode=matrix",
"matrix",
"matrix.example.com",
"apprise.plugins.matrix.base.requests.post",
"http://matrix.example.com/api/v1/matrix/hook/token",
id="matrix-webhook-authority-host",
),
],
)
def test_mode_selects_actual_destination_and_redirects_stay_disabled(
self, url, mode, hostname, post_target, destination
):
apprise_instance = NotificationService._new_apprise()
assert apprise_instance.asset.http_redirects is False
assert apprise_instance.add(url) is True
plugin = apprise_instance[0]
assert plugin.mode == mode
assert plugin.host == hostname
plugin.throttle = lambda *args, **kwargs: None
response = Mock(status_code=200, content=b"{}")
with patch(post_target, return_value=response) as post:
assert plugin.notify(body="body", title="title") is True
assert post.call_args.args[0] == destination
assert post.call_args.kwargs["allow_redirects"] is False
@pytest.mark.parametrize(
"url", ["ntfy://topic", "matrix://" + MATRIX_TOKEN]
)
def test_vendor_modes_do_not_resolve_token_authority(self, url):
with patch.object(
NotificationURLValidator, "_resolve_hostname_ips"
) as resolver:
assert NotificationURLValidator.validate_service_url_with_hint(
url
) == (
True,
None,
False,
)
resolver.assert_not_called()
@pytest.mark.parametrize(("fixture", "hostname"), DNS_FIXTURES)
@pytest.mark.parametrize(
("resolved_ip", "expect_valid"),
[
pytest.param(
"93.184.216.34",
True,
id="public-resolves-valid",
),
pytest.param(
"169.254.169.254",
False,
id="metadata-resolves-blocked",
),
],
)
def test_plugin_dns_single_validation_time_resolution(
self, fixture, hostname, resolved_ip, expect_valid
):
"""A successful plugin-authority lookup is performed exactly once."""
from apprise import Apprise
assert Apprise().add(fixture) is True
resolver_calls = []
def fake_resolve(name):
resolver_calls.append(name)
return [ipaddress.ip_address(resolved_ip)]
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
staticmethod(fake_resolve),
):
is_valid, error_msg, hint = (
NotificationURLValidator.validate_service_url_with_hint(
fixture, allow_private_ips=False
)
)
assert resolver_calls == [hostname]
assert is_valid is expect_valid
assert hint is False
assert error_msg == (
None
if expect_valid
# Message wording comes from the link-local guard added on main
# (the plugin-scheme partition blocks the whole link-local range,
# not just the metadata literals).
else f"Blocked cloud-metadata / link-local IP address: {hostname}"
)
@pytest.mark.parametrize(("fixture", "hostname"), DNS_FIXTURES)
def test_plugin_dns_failure_is_attempted_once_and_fails_open(
self, fixture, hostname
):
"""Pin the documented residual risk for plugin authorities."""
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=None,
) as resolver:
result = NotificationURLValidator.validate_service_url_with_hint(
fixture, allow_private_ips=False
)
assert result == (True, None, False)
resolver.assert_called_once_with(hostname)
# ===================================================================
# NotificationService
# ===================================================================
class TestNotificationService:
"""Tests for the low-level notification service wrapping Apprise."""
def test_init_defaults(self):
svc = NotificationService(outbound_allowed=True)
assert svc.allow_private_ips is False
def test_init_allow_private_ips(self):
svc = NotificationService(allow_private_ips=True, outbound_allowed=True)
assert svc.allow_private_ips is True
# -- _validate_url (static) -------------------------------------------
def test_validate_url_rejects_empty(self):
with pytest.raises(ServiceError, match="non-empty"):
NotificationService._validate_url("")
def test_validate_url_rejects_none(self):
with pytest.raises(ServiceError, match="non-empty"):
NotificationService._validate_url(None)
def test_validate_url_rejects_no_scheme(self):
with pytest.raises(ServiceError, match="Invalid URL"):
NotificationService._validate_url("example.com/webhook")
def test_validate_url_accepts_valid(self):
# Should not raise
NotificationService._validate_url("discord://id/token")
# -- _partition_urls (static) -----------------------------------------
def test_partition_urls_preserves_comma_inside_one_url(self):
# A multi-target Telegram URL keeps its ?to=id1,id2 query intact:
# the boundary split only separates at comma/whitespace followed
# by a scheme, matching the validator's partition.
strict, lenient = NotificationService._partition_urls(
"tgram://123456789:AAexample_token?to=111,222"
)
assert strict == []
assert lenient == ["tgram://123456789:AAexample_token?to=111,222"]
def test_partition_urls_splits_comma_separated_urls(self):
strict, lenient = NotificationService._partition_urls(
"tgram://123456789:AAexample_token/1,tgram://123456789:AAexample_token/2"
)
assert strict == []
assert lenient == [
"tgram://123456789:AAexample_token/1",
"tgram://123456789:AAexample_token/2",
]
def test_partition_urls_splits_whitespace_separated_urls(self):
strict, lenient = NotificationService._partition_urls(
"discord://id/token tgram://123456789:AAexample_token/987"
)
assert strict == []
assert lenient == [
"discord://id/token",
"tgram://123456789:AAexample_token/987",
]
def test_partition_urls_classifies_http_as_strict(self):
strict, lenient = NotificationService._partition_urls(
"https://webhook.example.com/a,http://webhook.example.com/b"
)
assert strict == [
"https://webhook.example.com/a",
"http://webhook.example.com/b",
]
assert lenient == []
# -- get_service_type --------------------------------------------------
def test_get_service_type_known(self):
svc = NotificationService(outbound_allowed=True)
assert svc.get_service_type("mailto://[email protected]") == "email"
assert svc.get_service_type("discord://id/token") == "discord"
assert svc.get_service_type("slack://a/b/c") == "slack"
assert svc.get_service_type("tgram://bot_token/chat_id") == "telegram"
assert svc.get_service_type("smtp://mail.example.com") == "smtp"
assert svc.get_service_type("smtps://mail.example.com") == "smtp"
def test_get_service_type_unknown(self):
svc = NotificationService(outbound_allowed=True)
assert svc.get_service_type("https://hooks.example.com") == "unknown"
# -- send (mocked Apprise) ---------------------------------------------
@patch("local_deep_research.notifications.service.NotificationURLValidator")
@patch("local_deep_research.notifications.service.apprise.Apprise")
def test_send_with_service_urls_success(self, MockApprise, MockValidator):
MockValidator.validate_multiple_urls.return_value = (True, None)
mock_instance = MockApprise.return_value
mock_instance.add.return_value = True
mock_instance.notify.return_value = True
svc = NotificationService(outbound_allowed=True)
result = svc.send(
title="Test",
body="Body",
service_urls="discord://id/token",
)
assert result is True
mock_instance.notify.assert_called_once()
@patch("local_deep_research.notifications.service.NotificationURLValidator")
@patch("local_deep_research.notifications.service.apprise.Apprise")
def test_send_with_invalid_url_raises_service_error(
self, MockApprise, MockValidator
):
MockValidator.validate_multiple_urls.return_value = (
False,
"bad url",
)
svc = NotificationService(outbound_allowed=True)
with pytest.raises(ServiceError):
svc.send(
title="Test",
body="Body",
service_urls="file:///etc/passwd",
)
@patch("local_deep_research.notifications.service.NotificationURLValidator")
@patch("local_deep_research.notifications.service.apprise.Apprise")
def test_send_apprise_add_failure_returns_false(
self, MockApprise, MockValidator
):
MockValidator.validate_multiple_urls.return_value = (True, None)
mock_instance = MockApprise.return_value
mock_instance.add.return_value = False
svc = NotificationService(outbound_allowed=True)
# When add() returns False the original apprise instance is used,
# but the temp one is used here so it returns False immediately.
result = svc.send(
title="Test", body="Body", service_urls="discord://id/token"
)
assert result is False
def test_send_no_urls_no_configured_services_returns_false(self):
svc = NotificationService(outbound_allowed=True)
result = svc.send(title="Test", body="Body")
assert result is False
# -- send_event --------------------------------------------------------
@patch.object(NotificationService, "send", return_value=True)
def test_send_event_uses_template(self, mock_send):
svc = NotificationService(outbound_allowed=True)
result = svc.send_event(
event_type=EventType.RESEARCH_COMPLETED,
context={"query": "test query", "research_id": "abc123"},
service_urls="discord://id/token",
)
assert result is True
mock_send.assert_called_once()
call_kwargs = mock_send.call_args
# The title and body should come from template formatting
assert call_kwargs[1]["service_urls"] == "discord://id/token"
# -- test_service (mocked Apprise) ------------------------------------
@patch("local_deep_research.notifications.service.NotificationURLValidator")
@patch("local_deep_research.notifications.service.apprise.Apprise")
def test_test_service_success(self, MockApprise, MockValidator):
MockValidator.validate_service_url_with_hint.return_value = (
True,
None,
False,
)
mock_instance = MockApprise.return_value
mock_instance.add.return_value = True
mock_instance.notify.return_value = True
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("discord://id/token")
assert result["success"] is True
@patch("local_deep_research.notifications.service.NotificationURLValidator")
def test_test_service_invalid_url(self, MockValidator):
MockValidator.validate_service_url_with_hint.return_value = (
False,
"blocked",
False,
)
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("file:///etc/passwd")
assert result["success"] is False
assert "error" in result
@patch("local_deep_research.notifications.service.NotificationURLValidator")
def test_test_service_invalid_url_surfaces_validator_reason(
self, MockValidator
):
# Validator's specific reason (e.g. "Blocked unsafe protocol: file")
# must reach the user so they can fix it instead of seeing a
# generic "Invalid notification service URL." Without this, an
# IPv6-only operator hitting the NAT64 block has no signal at
# all that there's a server-side opt-in to flip.
MockValidator.validate_service_url_with_hint.return_value = (
False,
"Blocked unsafe protocol: file",
False,
)
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("file:///etc/passwd")
assert result["success"] is False
assert "Blocked unsafe protocol: file" in result["error"]
# ------------------------------------------------------------------
# IP rejection matrix — single source of truth for which IPs trigger
# which user-visible behavior. Add new IP categories here rather
# than scattering fixtures across multiple tests. End-to-end against
# the REAL NotificationURLValidator (no mock) so validator wording
# drift fails here too — see NotificationURLValidator.validate_service_url
# docstring for the contract.
# ------------------------------------------------------------------
@pytest.mark.parametrize(
"url,expect_hint",
[
# --- Always-blocked: admin hint MUST be suppressed ---
# (none of these are unblockable via LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS
# or LDR_SECURITY_ALLOW_NAT64, so naming those env vars
# would mislead the user.)
# Cloud-metadata IPv4 (AWS/Azure/OCI/DO IMDS, ECS, Tencent, Alibaba)
pytest.param(
"http://169.254.169.254/latest/meta-data/", False, id="aws-imds"
),
pytest.param("http://169.254.170.2/", False, id="aws-ecs-v3"),
pytest.param(
"http://169.254.170.23/", False, id="aws-eks-pod-identity"
),
pytest.param("http://169.254.0.23/", False, id="tencent-metadata"),
pytest.param(
"http://100.100.100.200/", False, id="alibaba-metadata"
),
# NAT64-wrapped metadata
pytest.param(
"http://[64:ff9b::a9fe:a9fe]/",
False,
id="nat64-rfc6052-wrap-of-imds",
),
pytest.param(
"http://[64:ff9b:1:a9fe:a9:fe00::]/",
False,
id="nat64-rfc8215-wrap-of-imds",
),
# IPv6 transition prefixes (non-NAT64, always blocked)
pytest.param(
"http://[2002:7f00:1::]/",
False,
id="6to4-wrap-of-loopback",
),
pytest.param("http://[2001::]/", False, id="teredo-range"),
pytest.param("http://[100::]/", False, id="discard-prefix"),
pytest.param(
"http://[::ffff:169.254.169.254]/",
False,
id="ipv4-mapped-ipv6-of-imds",
),
pytest.param(
"http://[::169.254.169.254]/",
False,
id="ipv4-compat-ipv6-of-imds",
),
# NAT64-wrapped metadata beyond AWS IMDS — every metadata IP
# in ALWAYS_BLOCKED_METADATA_IPS is supposed to be caught
# through NAT64. Pin Alibaba (100.100.100.200) so a
# regression in is_nat64_wrapped_metadata_ip for non-IMDS
# metadata IPs cannot slip through.
pytest.param(
"http://[64:ff9b::6464:64c8]/",
False,
id="nat64-rfc6052-wrap-of-alibaba-metadata",
),
# Link-local stays blocked for every notification URL, even
# with the private-IP opt-in, so the hint must not offer it.
pytest.param("http://[fe80::1]/", False, id="link-local-fe80"),
pytest.param("http://169.254.10.5/", False, id="link-local-ipv4"),
# Plugin-scheme metadata (different validator prefix)
pytest.param(
"signal://169.254.169.254:8080/path",
False,
id="plugin-scheme-signal-to-imds",
),
# Legacy IPv4 forms are structurally rejected and cannot be unblocked.
pytest.param("http://0177.0.0.1/", False, id="octal-loopback"),
pytest.param("http://2130706433/", False, id="decimal-loopback"),
pytest.param("http://0x7f000001/", False, id="hex-loopback"),
# --- Recoverable: admin hint MUST appear ---
# (LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true would actually
# unblock these, so the hint is actionable.)
pytest.param("http://127.0.0.1/", True, id="ipv4-loopback"),
pytest.param("http://10.0.0.1/", True, id="rfc1918-10"),
pytest.param("http://172.16.0.1/", True, id="rfc1918-172-16"),
pytest.param("http://192.168.1.1/", True, id="rfc1918-192-168"),
pytest.param("http://100.64.0.1/", True, id="cgnat-100-64"),
pytest.param("http://[::1]/", True, id="ipv6-loopback"),
pytest.param("http://[fc00::1]/", True, id="ula-fc00"),
pytest.param("http://localhost/", True, id="localhost-dns"),
# NAT64-wrapped NON-metadata IPv4 — recoverable ONLY via
# LDR_SECURITY_ALLOW_NAT64=true (the private-IPs flag cannot
# unblock the NAT64 prefixes). 64:ff9b::5db8:d822 and the
# RFC8215 64:ff9b:1:: variant both wrap 93.184.216.34, a public
# IPv4. Guards against the NAT64 hint silently going dead — the
# exact IPv6-only/NAT64 deployment the hint exists to help.
pytest.param(
"http://[64:ff9b::5db8:d822]/",
True,
id="nat64-rfc6052-wrap-of-public",
),
pytest.param(
"http://[64:ff9b:1:5db8:d8:2200::]/",
True,
id="nat64-rfc8215-wrap-of-public",
),
# IPv4-mapped IPv6 of recoverable IPv4 — the validator's
# ipv4_mapped unwrap path must classify these as recoverable,
# not always-blocked (only IPv4-mapped of metadata is
# always-blocked).
pytest.param(
"http://[::ffff:127.0.0.1]/",
True,
id="ipv4-mapped-ipv6-of-loopback",
),
pytest.param(
"http://[::ffff:10.0.0.1]/",
True,
id="ipv4-mapped-ipv6-of-rfc1918",
),
],
)
def test_test_service_ip_rejection_matrix(self, url, expect_hint):
"""End-to-end against the REAL validator: pin the user-visible
behavior for every IP category. If ``expect_hint`` is True, the
URL targets a recoverable destination that
LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true (private IPs) or
LDR_SECURITY_ALLOW_NAT64=true (NAT64-wrapped non-metadata IPv4)
would unblock, so the admin hint MUST appear. If False, the URL
targets an
always-blocked category (cloud-metadata, 6to4, Teredo, discard,
IPv4-mapped IPv6 of metadata, NAT64-wrapped metadata,
plugin-scheme metadata) and the hint MUST be suppressed — the
env var cannot help.
Single source of truth: add new IP categories to this matrix
rather than scattering fixtures across multiple tests. See
NotificationURLValidator.validate_service_url docstring.
"""
svc = NotificationService(outbound_allowed=True)
result = svc.test_service(url)
assert result["success"] is False, f"Expected block for {url}"
assert result["error"], f"Empty error for {url}"
if expect_hint:
assert "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS" in result["error"], (
f"Expected admin hint for {url}, got: {result['error']!r}"
)
assert "LDR_SECURITY_ALLOW_NAT64" in result["error"], (
f"Expected NAT64 hint for {url}, got: {result['error']!r}"
)
else:
assert (
"LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS" not in result["error"]
), f"Hint should be suppressed for {url}, got: {result['error']!r}"
assert "LDR_SECURITY_ALLOW_NAT64" not in result["error"], (
f"NAT64 hint should be suppressed for {url}, "
f"got: {result['error']!r}"
)
# ------------------------------------------------------------------
# validate_service_url_with_hint — direct unit tests on the hint
# decision (third tuple element).
#
# The matrix above exercises this end-to-end via test_service for
# http(s) URLs. Plugin-scheme URLs reach test_service via a
# different validator prefix ("Blocked cloud-metadata /
# link-local IP address:") and the prefix guard inside
# validate_service_url_with_hint short-circuits before the hint
# decision is reached — meaning the plugin-scheme rows in the
# matrix pass via the prefix-guard fall-through, not via the hint
# decision. These direct unit tests pin the hint decision so the
# prefix guard cannot mask a regression in the hint logic itself.
# ------------------------------------------------------------------
@pytest.mark.parametrize(
"url,expected",
[
# Recoverable: env var WOULD unblock → True
("http://127.0.0.1/", True),
("http://10.0.0.1/", True),
("http://192.168.1.1/", True),
("http://100.64.0.1/", True),
("http://[::1]/", True),
("http://[fc00::1]/", True),
("http://localhost/", True),
# NAT64-wrapped NON-metadata IPv4 — hint is True ONLY via
# the NAT64 carve-out probe, not the private-IPs probe.
("http://[64:ff9b::5db8:d822]/", True),
("http://[64:ff9b:1:5db8:d8:2200::]/", True),
# Always-blocked: env var CANNOT unblock → False
("http://169.254.169.254/", False),
("http://169.254.170.2/", False),
("http://100.100.100.200/", False),
("http://[64:ff9b::a9fe:a9fe]/", False),
("http://[64:ff9b::6464:64c8]/", False),
("http://[2002:7f00:1::]/", False),
("http://[2001::]/", False),
("http://[100::]/", False),
("http://[::169.254.169.254]/", False),
("http://[::ffff:169.254.169.254]/", False),
# Link-local: the opt-in never reopens it.
("http://[fe80::1]/", False),
("http://169.254.10.5/", False),
# Plugin-scheme metadata — never reaches the hint branch via
# test_service (prefix guard short-circuits earlier) but pin
# the decision directly in case a future caller uses it.
("signal://169.254.169.254/", False),
],
)
def test_validate_service_url_with_hint_contract(self, url, expected):
"""Pin validate_service_url_with_hint's hint decision so the
prefix-guard fall-through cannot mask a regression in the
hint logic itself."""
_is_valid, _error_msg, hint = (
NotificationURLValidator.validate_service_url_with_hint(url)
)
assert hint is expected, f"Expected hint={expected} for {url}"
# ------------------------------------------------------------------
# validate_service_url_with_hint — single-pass DNS, branch coverage
# ------------------------------------------------------------------
def test_with_hint_resolves_dns_exactly_once_for_hostname(self):
"""The single-pass DNS claim: _resolve_hostname_ips must be
called exactly once for a hostname URL, not per-probe. The
rejection AND the hint must both fire — otherwise call_count==1
is vacuous (the hint path was skipped, not shared)."""
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=[ipaddress.ip_address("10.0.0.1")],
) as mock_resolve:
is_valid, error_msg, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://private.example.com/"
)
)
assert is_valid is False, (
"URL must be rejected; otherwise the hint path is never "
"reached and call_count==1 is meaningless"
)
assert hint is True, "Hint must fire for RFC1918 10.0.0.1"
assert mock_resolve.call_count == 1, (
f"Expected exactly 1 DNS resolution, got {mock_resolve.call_count}"
)
@pytest.mark.parametrize(
"allow_private_ips",
[False, True],
ids=["allow_private_ips-False", "allow_private_ips-True"],
)
def test_with_hint_mixed_private_and_nat64_combined_hint(
self, monkeypatch, allow_private_ips
):
"""A DNS resolution returning BOTH an RFC1918 private IPv4
(10.0.0.1) AND a NAT64-wrapped public IPv6
(64:ff9b::5db8:d822) must still surface the admin hint.
Neither single escape hatch alone unblocks the mixed list —
LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true leaves the NAT64 IP
blocked, and LDR_SECURITY_ALLOW_NAT64=true leaves the
RFC1918 IP blocked — but setting BOTH together would.
_compute_hint must evaluate the combined elevated policy
against the shared resolved_ips. Also pins: DNS is queried
exactly once for the hostname, and the URL is rejected at
the default level for both allow_private_ips values."""
monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "false")
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=[
ipaddress.ip_address("10.0.0.1"),
ipaddress.ip_address("64:ff9b::5db8:d822"),
],
) as mock_resolve:
is_valid, _error_msg, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://mixed.example.com/",
allow_private_ips=allow_private_ips,
)
)
assert is_valid is False, (
"URL must be rejected; otherwise the hint path is never reached"
)
assert hint is True, (
"Hint must fire for mixed private+NAT64 list — the "
"combined elevated policy (both env vars) would unblock "
"both IPs"
)
mock_resolve.assert_called_once_with("mixed.example.com")
def test_with_hint_allow_private_ips_private_ip_no_hint(self):
"""With allow_private_ips=True, an RFC1918 private IP is
allowed and the hint is False — the operator already opted in,
so no private-IP escape hatch is left to suggest."""
is_valid, error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://192.168.1.1/hook", allow_private_ips=True
)
)
assert is_valid is True
assert error is None
assert hint is False
def test_with_hint_allow_private_ips_metadata_blocks_no_hint(self):
"""With allow_private_ips=True, cloud-metadata IPs are still
blocked (always-blocked category) and the hint is False —
no operator escape hatch exists for metadata."""
is_valid, error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://169.254.169.254/", allow_private_ips=True
)
)
assert is_valid is False
assert hint is False
def test_with_hint_allow_private_ips_nat64_hint_fires(self):
"""With allow_private_ips=True, NAT64-wrapped non-metadata IPs
are still blocked (NAT64 prefixes sit outside private ranges)
and the hint fires to suggest LDR_SECURITY_ALLOW_NAT64."""
is_valid, error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://[64:ff9b::5db8:d822]/", allow_private_ips=True
)
)
assert is_valid is False, (
"NAT64-wrapped URL must be blocked even with allow_private_ips"
)
assert hint is True, (
"Hint must fire for NAT64-wrapped URL even with "
"allow_private_ips=True"
)
def test_with_hint_allow_private_ips_whitespace_only_skips_dns(self):
"""Preserves the allow_private_ips=True protocol-error contract
for whitespace-only input: returns the protocol-missing error
and skips DNS — there is no hostname to resolve, so
_resolve_hostname_ips must never be called."""
with patch.object(
NotificationURLValidator, "_resolve_hostname_ips"
) as mock_resolve:
result = NotificationURLValidator.validate_service_url_with_hint(
" ", allow_private_ips=True
)
assert result == (
False,
"Service URL must have a protocol (e.g., https://)",
False,
)
mock_resolve.assert_not_called()
def test_with_hint_valid_url_returns_no_hint(self):
"""A valid URL returns (True, None, False)."""
is_valid, error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://8.8.8.8/"
)
)
assert (is_valid, error, hint) == (True, None, False)
def test_with_hint_dns_failure_attempted_exactly_once(self):
"""When DNS fails, the failure is authoritative — no retry
inside validate_service_url or the hint probes. The URL is
allowed (fail-open) and _resolve_hostname_ips is called
exactly once. This is the sentinel design: an empty list
distinguishes 'DNS attempted and failed' from 'not supplied'."""
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=None,
) as mock_resolve:
is_valid, error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://flaky.example.com/"
)
)
assert mock_resolve.call_count == 1, (
f"Expected exactly 1 DNS resolution on failure, got "
f"{mock_resolve.call_count}"
)
assert is_valid is True, (
"DNS failure must fail-open (allow), not retry-and-reject"
)
assert error is None
assert hint is False
def test_with_hint_leading_whitespace_preserves_hint(self):
"""Leading whitespace must not suppress the hint — the URL
is stripped before host extraction."""
is_valid, error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
" http://10.0.0.1/ "
)
)
assert is_valid is False
assert hint is True
def test_with_hint_rfc_illegal_url_skips_dns(self):
"""URLs with RFC-illegal characters (backslash, control bytes)
must NOT trigger DNS pre-resolution — they are deterministically
rejected by validate_service_url without network activity."""
with patch.object(
NotificationURLValidator, "_resolve_hostname_ips"
) as mock_resolve:
is_valid, _error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://evil.com\\@127.0.0.1/"
)
)
assert is_valid is False
assert hint is False
mock_resolve.assert_not_called()
@pytest.mark.parametrize(
"url",
[
"http://example.com:99999/",
"http://[::1",
"http://",
],
ids=["invalid-port", "malformed-ipv6", "empty-host"],
)
def test_with_hint_malformed_url_skips_dns(self, url):
"""Malformed HTTP(S) URLs that parse_url rejects must NOT trigger
DNS pre-resolution. _extract_host returns None on
LocationParseError, so hostname is empty and DNS is skipped."""
with patch.object(
NotificationURLValidator, "_resolve_hostname_ips"
) as mock_resolve:
NotificationURLValidator.validate_service_url_with_hint(url)
mock_resolve.assert_not_called()
def test_with_hint_credential_url_ip_literal_skips_dns(self):
"""Credential-bearing HTTP(S) URLs with IP-literal hosts must
NOT trigger DNS — the IP is checked directly. The URL is
rejected (private IP) without any network activity."""
with patch.object(
NotificationURLValidator, "_resolve_hostname_ips"
) as mock_resolve:
is_valid, _error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://user:[email protected]/"
)
)
assert is_valid is False
assert hint is True
mock_resolve.assert_not_called()
def test_with_hint_credential_url_hostname_needs_dns(self):
"""Credential-bearing HTTP(S) URLs with hostname hosts DO
require DNS — the URL is syntactically valid (RFC 3986 allows
userinfo) and the IP check cannot complete without resolving
the hostname. DNS here is correct, not a bug."""
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=[ipaddress.ip_address("10.0.0.1")],
) as mock_resolve:
is_valid, _error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://user:[email protected]/"
)
)
assert is_valid is False
assert hint is True
assert mock_resolve.call_count == 1
def test_with_hint_allow_private_ips_nat64_hostname_single_dns(
self, monkeypatch
):
"""hostname + allow_private_ips=True + NAT64 rejection must
resolve DNS exactly once. The unified two-phase flow shares
the resolution across rejection and hint probes. The env is
pinned to NAT64-disabled so the rejection + hint are
deterministic regardless of any ambient
LDR_SECURITY_ALLOW_NAT64."""
monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "false")
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=[ipaddress.ip_address("64:ff9b::5db8:d822")],
) as mock_resolve:
is_valid, _error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://nat64.example.com/", allow_private_ips=True
)
)
assert mock_resolve.call_count == 1, (
f"Expected 1 DNS call, got {mock_resolve.call_count}"
)
assert is_valid is False, (
"NAT64-wrapped must block even with private IPs"
)
assert hint is True, "NAT64 hint must fire"
def test_validate_service_url_allow_nat64_true_unblocks_nat64(self):
"""allow_nat64=True forwarded through _is_private_ip must
unblock NAT64-wrapped non-metadata IPv4 that is otherwise
blocked."""
is_valid_default, _ = NotificationURLValidator.validate_service_url(
"http://[64:ff9b::5db8:d822]/"
)
assert is_valid_default is False, "NAT64 prefix must block by default"
is_valid_nat64, _ = NotificationURLValidator.validate_service_url(
"http://[64:ff9b::5db8:d822]/", allow_nat64=True
)
assert is_valid_nat64 is True, "allow_nat64=True must unblock NAT64"
def test_validate_service_url_allow_nat64_false_overrides_env(
self, monkeypatch
):
"""allow_nat64=False must override an enabled env setting,
blocking NAT64-wrapped destinations even when the env var
says to allow them."""
monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
is_valid, _ = NotificationURLValidator.validate_service_url(
"http://[64:ff9b::5db8:d822]/", allow_nat64=False
)
assert is_valid is False, (
"allow_nat64=False must override env and block NAT64"
)
def test_validate_service_url_positional_allow_nat64_compat(self):
"""The third positional argument must be allow_nat64 (not
_resolved_ips) to preserve backwards compatibility with
callers using positional args: validate_service_url(url, False, True)."""
is_valid, _ = NotificationURLValidator.validate_service_url(
"http://[64:ff9b::5db8:d822]/", False, True
)
assert is_valid is True, (
"Positional (url, False, True) must pass allow_nat64=True"
)
def test_validate_service_url_plugin_scheme_forwards_allow_nat64(
self, monkeypatch
):
"""Plugin-scheme IMDS guard must forward allow_nat64 so callers
can override the env setting for plugin URLs too."""
monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
is_valid, _ = NotificationURLValidator.validate_service_url(
"signal://[64:ff9b::5db8:d822]/", allow_nat64=False
)
assert is_valid is False, (
"Plugin-scheme must forward allow_nat64=False to block NAT64"
)
def test_with_hint_dual_stack_one_private_blocks(self):
"""A hostname resolving to BOTH a public and a private IP must
be BLOCKED — the loop in _host_blocks_at_level checks every
resolved IP. This is the real-world dual-stack case where a
short-circuit regression would create an SSRF bypass."""
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=[
ipaddress.ip_address("93.184.216.34"),
ipaddress.ip_address("10.0.0.1"),
],
) as mock_resolve:
is_valid, _error, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://dual-stack.example.com/"
)
)
assert mock_resolve.call_count == 1
assert is_valid is False, (
"Dual-stack with one private IP must be blocked"
)
assert hint is True
def test_with_hint_consistent_dns_failure_fails_open(self):
"""When DNS consistently fails (all resolutions return None),
the URL is ALLOWED (fail-open). This is the documented
historical behaviour. A future change to fail-closed must be
a deliberate decision, not a silent regression."""
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=None,
):
is_valid, error_msg, hint = (
NotificationURLValidator.validate_service_url_with_hint(
"http://unresolvable.example.com/"
)
)
assert is_valid is True, "Consistent DNS failure must fail-open (allow)"
assert error_msg is None
assert hint is False
@pytest.mark.parametrize("bad_input", [None, 123, "", " "])
def test_with_hint_non_string_returns_tuple_not_crash(self, bad_input):
"""validate_service_url_with_hint must return a (False, msg,
False) tuple for non-string / empty input, never raise."""
is_valid, error_msg, hint = (
NotificationURLValidator.validate_service_url_with_hint(bad_input)
)
assert is_valid is False
assert error_msg is not None
assert hint is False
@patch("local_deep_research.notifications.service.NotificationURLValidator")
@patch("local_deep_research.notifications.service.apprise.Apprise")
def test_test_service_add_failure(self, MockApprise, MockValidator):
MockValidator.validate_service_url_with_hint.return_value = (
True,
None,
False,
)
mock_instance = MockApprise.return_value
mock_instance.add.return_value = False
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("discord://id/token")
assert result["success"] is False
assert "Failed to add" in result["error"]
@patch("local_deep_research.notifications.service.NotificationURLValidator")
@patch("local_deep_research.notifications.service.apprise.Apprise")
def test_test_service_notify_failure(self, MockApprise, MockValidator):
MockValidator.validate_service_url_with_hint.return_value = (
True,
None,
False,
)
mock_instance = MockApprise.return_value
mock_instance.add.return_value = True
mock_instance.notify.return_value = False
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("discord://id/token")
assert result["success"] is False
assert "Failed to send" in result["error"]
@patch("local_deep_research.notifications.service.NotificationURLValidator")
def test_test_service_exception(self, MockValidator):
MockValidator.validate_service_url_with_hint.side_effect = RuntimeError(
"boom"
)
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("discord://id/token")
assert result["success"] is False
@patch("local_deep_research.notifications.service.NotificationURLValidator")
def test_test_service_empty_error_msg_uses_fallback(self, MockValidator):
# Defensive fallback: if the validator ever returned (False, "")
# (today it never does — every False branch sets a reason), the
# user still sees an actionable message rather than an empty
# string. Pins the `error_msg or "Invalid..."` guard.
MockValidator.validate_service_url_with_hint.return_value = (
False,
"",
False,
)
svc = NotificationService(outbound_allowed=True)
result = svc.test_service("https://example.com/hook")
assert result["success"] is False
assert result["error"] == "Invalid notification service URL."
def test_test_service_master_switch_off_short_circuits(self):
# When LDR_NOTIFICATIONS_ALLOW_OUTBOUND=False (the default),
# test_service must short-circuit BEFORE the URL is inspected by
# the validator. Pins the operator master-switch gate so a
# future refactor cannot accidentally route around it.
svc = NotificationService() # outbound_allowed defaults to False
result = svc.test_service("http://10.0.0.1/hook")
assert result["success"] is False
assert "LDR_NOTIFICATIONS_ALLOW_OUTBOUND" in result["error"]
# The URL itself was never inspected, so its details must not
# leak into the user-facing message:
assert "10.0.0.1" not in result["error"]
# -- SERVICE_PATTERNS --------------------------------------------------
def test_service_patterns_are_valid_regexes(self):
import re
for name, pattern in NotificationService.SERVICE_PATTERNS.items():
re.compile(pattern) # Should not raise
# ===================================================================
# RateLimiter
# ===================================================================
class TestRateLimiter:
"""Tests for the in-memory per-user rate limiter."""
def test_basic_allow(self):
rl = RateLimiter(max_per_hour=5, max_per_day=20)
assert rl.is_allowed("user1") is True
def test_hourly_limit_exceeded(self):
rl = RateLimiter(max_per_hour=3, max_per_day=100)
for _ in range(3):
assert rl.is_allowed("user1") is True
assert rl.is_allowed("user1") is False
def test_daily_limit_exceeded(self):
rl = RateLimiter(max_per_hour=100, max_per_day=3)
for _ in range(3):
assert rl.is_allowed("user1") is True
assert rl.is_allowed("user1") is False
def test_per_user_isolation(self):
rl = RateLimiter(max_per_hour=2, max_per_day=100)
# Exhaust user1's hourly limit
rl.is_allowed("user1")
rl.is_allowed("user1")
assert rl.is_allowed("user1") is False
# user2 should still be allowed
assert rl.is_allowed("user2") is True
def test_set_user_limits(self):
rl = RateLimiter(max_per_hour=10, max_per_day=50)
rl.set_user_limits("user1", max_per_hour=2, max_per_day=5)
limits = rl.get_user_limits("user1")
assert limits == (2, 5)
# User with custom limits
rl.is_allowed("user1")
rl.is_allowed("user1")
assert rl.is_allowed("user1") is False
# Default user still has 10/hour
for _ in range(10):
assert rl.is_allowed("default_user") is True
assert rl.is_allowed("default_user") is False
def test_get_user_limits_defaults(self):
rl = RateLimiter(max_per_hour=10, max_per_day=50)
assert rl.get_user_limits("unknown") == (10, 50)
def test_reset_single_user(self):
rl = RateLimiter(max_per_hour=2, max_per_day=100)
rl.is_allowed("user1")
rl.is_allowed("user1")
assert rl.is_allowed("user1") is False
rl.reset("user1")
assert rl.is_allowed("user1") is True
def test_reset_all_users(self):
rl = RateLimiter(max_per_hour=1, max_per_day=100)
rl.is_allowed("user1")
rl.is_allowed("user2")
assert rl.is_allowed("user1") is False
assert rl.is_allowed("user2") is False
rl.reset()
assert rl.is_allowed("user1") is True
assert rl.is_allowed("user2") is True
def test_old_entries_cleaned(self):
rl = RateLimiter(max_per_hour=2, max_per_day=100)
now = datetime.now(timezone.utc)
old = now - timedelta(hours=2)
# Manually inject old entries
rl._hourly_counts["user1"] = deque([old, old])
rl._daily_counts["user1"] = deque([old, old])
# After cleaning old entries, the user should be allowed again
assert rl.is_allowed("user1") is True
def test_cleanup_inactive_users(self):
rl = RateLimiter(
max_per_hour=10, max_per_day=50, cleanup_interval_hours=0
)
now = datetime.now(timezone.utc)
old = now - timedelta(days=8)
# Force a cleanup by setting last cleanup to long ago
rl._last_cleanup = now - timedelta(hours=25)
rl._hourly_counts["stale_user"] = deque([old])
rl._daily_counts["stale_user"] = deque([old])
# Trigger cleanup via is_allowed
rl.is_allowed("active_user")
assert "stale_user" not in rl._hourly_counts
assert "stale_user" not in rl._daily_counts
def test_thread_safety(self):
"""Multiple threads hitting the rate limiter concurrently."""
rl = RateLimiter(max_per_hour=100, max_per_day=1000)
results = []
errors = []
def hit():
try:
for _ in range(50):
rl.is_allowed("concurrent_user")
results.append(True)
except Exception as e:
errors.append(e)
threads = [threading.Thread(target=hit) for _ in range(4)]
for t in threads:
t.start()
for t in threads:
t.join(timeout=10)
assert len(errors) == 0
assert len(results) == 4
# ===================================================================
# NotificationManager
# ===================================================================
class TestNotificationManager:
"""Tests for the high-level notification manager."""
# Module-level autouse fixture _enable_outbound_notifications opens
# the operator-level env gate for all tests in this file.
def _make_manager(self, settings, user_id="test_user"):
return NotificationManager(settings_snapshot=settings, user_id=user_id)
# -- Initialization ---------------------------------------------------
def test_init_creates_shared_rate_limiter(self, default_settings):
mgr = self._make_manager(default_settings)
assert NotificationManager._shared_rate_limiter is not None
assert mgr._rate_limiter is NotificationManager._shared_rate_limiter
def test_init_reuses_shared_rate_limiter(self, default_settings):
mgr1 = self._make_manager(default_settings, "user_a")
mgr2 = self._make_manager(default_settings, "user_b")
assert mgr1._rate_limiter is mgr2._rate_limiter
def test_init_configures_per_user_limits(self, default_settings):
mgr = self._make_manager(default_settings, "user_a")
limits = mgr._rate_limiter.get_user_limits("user_a")
assert limits == (10, 50)
# -- _get_setting ------------------------------------------------------
def test_get_setting_returns_value(self, default_settings):
mgr = self._make_manager(default_settings)
assert mgr._get_setting("notifications.rate_limit_per_hour") == 10
def test_get_setting_returns_default(self, default_settings):
mgr = self._make_manager(default_settings)
assert (
mgr._get_setting("nonexistent.key", default="fallback")
== "fallback"
)
# -- _should_notify ----------------------------------------------------
def test_should_notify_enabled(self, default_settings):
mgr = self._make_manager(default_settings)
assert mgr._should_notify(EventType.RESEARCH_COMPLETED) is True
def test_should_notify_disabled(self, disabled_settings):
mgr = self._make_manager(disabled_settings)
assert mgr._should_notify(EventType.RESEARCH_COMPLETED) is False
def test_should_notify_missing_key(self, default_settings):
mgr = self._make_manager(default_settings)
# EventType.TEST is not in settings, should default to False
assert mgr._should_notify(EventType.TEST) is False
# -- send_notification -------------------------------------------------
@patch.object(NotificationService, "send_event", return_value=True)
def test_send_notification_success(self, mock_send_event, default_settings):
mgr = self._make_manager(default_settings)
result = mgr.send_notification(
EventType.RESEARCH_COMPLETED,
{"query": "test", "research_id": "123"},
)
assert result.sent is True
mock_send_event.assert_called_once()
def test_send_notification_disabled_returns_false(self, disabled_settings):
mgr = self._make_manager(disabled_settings)
result = mgr.send_notification(
EventType.RESEARCH_COMPLETED,
{"query": "test"},
)
assert result.sent is False
def test_send_notification_no_service_url_returns_false(self):
settings = {
"notifications.service_url": "",
"notifications.on_research_completed": True,
"notifications.rate_limit_per_hour": 10,
"notifications.rate_limit_per_day": 50,
}
mgr = self._make_manager(settings)
result = mgr.send_notification(
EventType.RESEARCH_COMPLETED,
{"query": "test"},
)
assert result.sent is False
def test_send_notification_rate_limited(self):
settings = {
"notifications.service_url": "discord://id/token",
"notifications.on_research_completed": True,
"notifications.rate_limit_per_hour": 1,
"notifications.rate_limit_per_day": 50,
}
mgr = self._make_manager(settings, "rate_test_user")
with patch.object(NotificationService, "send_event", return_value=True):
mgr.send_notification(
EventType.RESEARCH_COMPLETED,
{"query": "first"},
)
with pytest.raises(RateLimitError):
mgr.send_notification(
EventType.RESEARCH_COMPLETED,
{"query": "second"},
)
@patch.object(NotificationService, "send_event", return_value=True)
def test_send_notification_force_bypasses_rate_limit(self, mock_send):
settings = {
"notifications.service_url": "discord://id/token",
"notifications.on_research_completed": True,
"notifications.rate_limit_per_hour": 1,
"notifications.rate_limit_per_day": 50,
}
mgr = self._make_manager(settings, "force_user")
mgr.send_notification(EventType.RESEARCH_COMPLETED, {"query": "first"})
# Would normally be rate-limited, but force=True
result = mgr.send_notification(
EventType.RESEARCH_COMPLETED, {"query": "second"}, force=True
)
assert result.sent is True
@patch.object(NotificationService, "send_event", return_value=True)
def test_send_notification_force_bypasses_disabled(self, mock_send):
settings = {
"notifications.service_url": "discord://id/token",
"notifications.on_research_completed": False,
"notifications.rate_limit_per_hour": 10,
"notifications.rate_limit_per_day": 50,
}
mgr = self._make_manager(settings, "force_user2")
result = mgr.send_notification(
EventType.RESEARCH_COMPLETED, {"query": "forced"}, force=True
)
assert result.sent is True
@patch.object(
NotificationService, "send_event", side_effect=Exception("boom")
)
def test_send_notification_exception_returns_false(
self, mock_send, default_settings
):
mgr = self._make_manager(default_settings)
result = mgr.send_notification(
EventType.RESEARCH_COMPLETED,
{"query": "test"},
)
assert result.sent is False
# -- test_service via manager ------------------------------------------
@patch.object(
NotificationService, "test_service", return_value={"success": True}
)
def test_manager_test_service_delegates(self, mock_test, default_settings):
mgr = self._make_manager(default_settings)
result = mgr.test_service("discord://id/token")
assert result["success"] is True
mock_test.assert_called_once_with("discord://id/token")
# -- _log_notification -------------------------------------------------
def test_log_notification_with_query(self, default_settings):
mgr = self._make_manager(default_settings)
# Should not raise
mgr._log_notification(
EventType.RESEARCH_COMPLETED,
{"query": "test query"},
)
def test_log_notification_with_subscription(self, default_settings):
mgr = self._make_manager(default_settings)
mgr._log_notification(
EventType.SUBSCRIPTION_UPDATE,
{"subscription_name": "my sub"},
)
def test_log_notification_empty_context(self, default_settings):
mgr = self._make_manager(default_settings)
mgr._log_notification(EventType.TEST, {})
# ===================================================================
# NotificationTemplate
# ===================================================================
class TestNotificationTemplate:
"""Tests for Jinja2-based notification templates."""
def test_format_returns_title_and_body(self):
result = NotificationTemplate.format(
EventType.RESEARCH_COMPLETED,
{
"query": "quantum computing",
"research_id": "abc",
"summary": "results",
"url": "http://example.com",
},
)
assert "title" in result
assert "body" in result
assert isinstance(result["title"], str)
assert isinstance(result["body"], str)
def test_format_with_custom_template(self):
custom = {
"title": "Custom: {query}",
"body": "Research {research_id} is done.",
}
result = NotificationTemplate.format(
EventType.RESEARCH_COMPLETED,
{"query": "test", "research_id": "123"},
custom_template=custom,
)
assert result["title"] == "Custom: test"
assert result["body"] == "Research 123 is done."
def test_format_custom_template_missing_var(self):
custom = {
"title": "{missing_var}",
"body": "Body",
}
result = NotificationTemplate.format(
EventType.RESEARCH_COMPLETED,
{},
custom_template=custom,
)
assert (
"Missing variable" in result["body"]
or "error" in result["body"].lower()
)
def test_format_custom_template_sanitizes_context(self):
"""Ensure format string attacks are prevented."""
custom = {
"title": "{query}",
"body": "Body",
}
result = NotificationTemplate.format(
EventType.RESEARCH_COMPLETED,
{"query": "{__class__.__mro__}"},
custom_template=custom,
)
# The attack payload should be treated as a plain string
assert "__class__" in result["title"]
def test_fallback_template(self):
result = NotificationTemplate._get_fallback_template(
EventType.RESEARCH_COMPLETED,
{"query": "test"},
)
assert "title" in result
assert "body" in result
assert "Research Completed" in result["title"]
def test_event_type_values(self):
"""All EventType values are strings."""
for et in EventType:
assert isinstance(et.value, str)
def test_get_required_context_returns_list(self):
result = NotificationTemplate.get_required_context(
EventType.RESEARCH_COMPLETED
)
assert isinstance(result, list)
def test_format_unknown_event_type(self):
"""Event type without a template file should produce a generic message."""
# RATE_LIMIT_WARNING has no template file in TEMPLATE_FILES
result = NotificationTemplate.format(
EventType.RATE_LIMIT_WARNING,
{"detail": "too many requests"},
)
assert "title" in result
assert "body" in result
# ===================================================================
# build_notification_url
# ===================================================================
class TestBuildNotificationUrl:
"""Tests for notification callback URL building."""
def test_with_external_url(self):
snapshot = {"app.external_url": "https://myapp.example.com"}
url = build_notification_url(
"/research/123",
settings_snapshot=snapshot,
)
assert url == "https://myapp.example.com/research/123"
def test_with_host_and_port(self):
snapshot = {
"app.external_url": "",
"app.host": "0.0.0.0",
"app.port": 5000,
}
url = build_notification_url(
"/research/456",
settings_snapshot=snapshot,
)
assert url == "http://localhost:5000/research/456"
def test_fallback_url(self):
url = build_notification_url(
"/research/789",
settings_snapshot={},
fallback_base="http://localhost:5000",
)
assert url == "http://localhost:5000/research/789"
def test_validation_disabled(self):
url = build_notification_url(
"/research/abc",
settings_snapshot={},
validate=False,
)
assert "/research/abc" in url
def test_validation_catches_bad_url(self):
with pytest.raises(URLValidationError):
build_notification_url(
"/research/123",
settings_snapshot={"app.external_url": "ftp://bad.example.com"},
validate=True,
)
# ===================================================================
# Queue helpers
# ===================================================================
class TestQueueHelpers:
"""Tests for queue notification helper functions."""
@patch(
"local_deep_research.notifications.queue_helpers.NotificationManager"
)
def test_send_queue_notification_success(self, MockManager):
mock_instance = MockManager.return_value
mock_instance.send_notification.return_value = True
settings = {
"notifications.rate_limit_per_hour": 10,
"notifications.rate_limit_per_day": 50,
}
result = send_queue_notification(
username="alice",
research_id="r1",
query="test query",
settings_snapshot=settings,
position=3,
)
assert result is True
mock_instance.send_notification.assert_called_once()
@patch(
"local_deep_research.notifications.queue_helpers.NotificationManager"
)
def test_send_queue_notification_rate_limited(self, MockManager):
mock_instance = MockManager.return_value
mock_instance.send_notification.side_effect = RateLimitError("limited")
result = send_queue_notification(
username="alice",
research_id="r1",
query="test",
settings_snapshot={},
)
assert result is False
@patch(
"local_deep_research.notifications.queue_helpers.NotificationManager"
)
def test_send_queue_notification_exception(self, MockManager):
MockManager.side_effect = Exception("boom")
result = send_queue_notification(
username="alice",
research_id="r1",
query="test",
settings_snapshot={},
)
assert result is False
def test_send_queue_failed_no_snapshot(self):
result = send_queue_failed_notification(
username="alice",
research_id="r1",
query="test",
settings_snapshot=None,
)
assert result is False
@patch(
"local_deep_research.notifications.queue_helpers.NotificationManager"
)
def test_send_queue_failed_success(self, MockManager):
mock_instance = MockManager.return_value
mock_instance.send_notification.return_value = True
result = send_queue_failed_notification(
username="bob",
research_id="r2",
query="failed query",
error_message="timeout",
settings_snapshot={"notifications.rate_limit_per_hour": 10},
)
assert result is True
@patch(
"local_deep_research.notifications.queue_helpers.NotificationManager"
)
def test_send_queue_failed_rate_limited(self, MockManager):
mock_instance = MockManager.return_value
mock_instance.send_notification.side_effect = RateLimitError("limited")
result = send_queue_failed_notification(
username="bob",
research_id="r2",
query="test",
settings_snapshot={"x": 1},
)
assert result is False
# ===================================================================
# mask_sensitive_url
# ===================================================================
class TestMaskSensitiveUrl:
"""Tests for URL credential masking."""
def test_masks_password(self):
url = "https://user:[email protected]/path"
masked = mask_sensitive_url(url)
assert "secretpassword" not in masked
assert "***" in masked
def test_masks_long_tokens_in_path(self):
url = "discord://12345678901234567890123456/abcdefghijklmnopqrstuvwxyz"
masked = mask_sensitive_url(url)
# Long alphanumeric tokens should be masked
assert "***" in masked
def test_masks_query_string(self):
url = "https://hooks.example.com/webhook?token=secret123"
masked = mask_sensitive_url(url)
assert "secret123" not in masked
def test_preserves_scheme(self):
url = "https://example.com/path"
masked = mask_sensitive_url(url)
assert masked.startswith("https://")
def test_handles_invalid_url(self):
# Should not raise, returns something with ***
result = mask_sensitive_url("not a url at all")
assert isinstance(result, str)
def test_simple_url_no_secrets(self):
url = "https://example.com/short"
masked = mask_sensitive_url(url)
assert "example.com" in masked
# ===================================================================
# Exception hierarchy
# ===================================================================
class TestExceptionHierarchy:
"""Verify exception inheritance is correct."""
def test_service_error_is_notification_error(self):
assert issubclass(ServiceError, NotificationError)
def test_send_error_is_notification_error(self):
assert issubclass(SendError, NotificationError)
def test_rate_limit_error_is_notification_error(self):
assert issubclass(RateLimitError, NotificationError)
def test_notification_error_is_exception(self):
assert issubclass(NotificationError, Exception)
def test_notification_url_validation_error_is_value_error(self):
assert issubclass(NotificationURLValidationError, ValueError)
def test_url_validation_error_is_value_error(self):
assert issubclass(URLValidationError, ValueError)
def test_exceptions_carry_message(self):
e = SendError("test message")
assert str(e) == "test message"
# ===================================================================
# URLValidator (callback URL validation)
# ===================================================================
class TestURLValidatorHTTP:
"""Tests for validate_http_url used in notification callback URLs."""
def test_valid_https(self):
assert (
URLValidator.validate_http_url("https://example.com/path") is True
)
def test_valid_http(self):
assert URLValidator.validate_http_url("http://example.com/path") is True
def test_rejects_ftp(self):
with pytest.raises(URLValidationError):
URLValidator.validate_http_url("ftp://example.com")
def test_rejects_empty(self):
with pytest.raises(URLValidationError):
URLValidator.validate_http_url("")
def test_rejects_none(self):
with pytest.raises(URLValidationError):
URLValidator.validate_http_url(None)
def test_rejects_no_scheme(self):
with pytest.raises(URLValidationError):
URLValidator.validate_http_url("example.com/path")
def test_rejects_javascript(self):
with pytest.raises(URLValidationError):
URLValidator.validate_http_url("javascript:alert(1)")