Skip to content

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

37.1 KB
Raw Blame
"""Integration tests for the settings-save egress validators.

These drive the REAL cross-field policy validators in
``security/egress/validators.py`` exactly as the settings write routes invoke
them (``web/routes/settings_routes.py``: ``save_all_settings`` /
``save_settings`` / ``api_update_setting``):

- ``validate_allowed_local_hostnames``: a PUBLIC hostname may not be smuggled
  into ``llm.allowed_local_hostnames`` (the host classifier would then trust
  external hosts as "local"); private / loopback hosts are accepted.

Each guarded property is asserted with an allow+deny pair so the test fails if
the rule were reverted. Direct-validator tests use realistic
``form_data`` / ``all_db_settings`` inputs; route-level tests drive the real
``api_update_setting`` PUT endpoint with only the settings/DB backend mocked,
proving the validation error is surfaced (not silently dropped).

All host classification uses literal IPs (8.8.8.8 public, 10.0.0.1 / 127.0.0.1
private), which the real classifier resolves OFFLINE via getaddrinfo on a
literal — no network round-trip, fully deterministic.
"""

from unittest.mock import MagicMock, patch

import pytest

from local_deep_research.security.egress import validators
from local_deep_research.security.egress.validators import (
    validate_allowed_local_hostnames,
    validate_engine_instance_urls,
)

HOSTS_KEY = "llm.allowed_local_hostnames"
SEARXNG_URL_KEY = "search.engine.web.searxng.default_params.instance_url"
GATE_ENV = "LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLS"
ALLOWLIST_ENV = "LDR_SEARCH_PRIVATE_ENGINE_URL_ALLOWLIST"


# ---------------------------------------------------------------------------
# Removed validator regression guard
# ---------------------------------------------------------------------------


def test_validate_strict_meta_combo_is_gone():
    """The meta-picker engines were removed, so the STRICT+meta-picker
    save-time validator must no longer exist (stray meta names are denied at
    runtime by ``evaluate_engine`` as ``engine_unknown`` instead)."""
    assert not hasattr(validators, "validate_strict_meta_combo")


# ---------------------------------------------------------------------------
# validate_allowed_local_hostnames  (no PUBLIC host in the local allowlist)
# ---------------------------------------------------------------------------


def test_public_host_in_local_allowlist_is_rejected():
    """A public IP would let the policy treat an external host as local."""
    err = validate_allowed_local_hostnames({HOSTS_KEY: ["8.8.8.8"]}, {})
    assert err is not None
    assert err["key"] == HOSTS_KEY
    assert "8.8.8.8" in err["error"]


def test_private_host_in_local_allowlist_is_accepted():
    """Allow side: an RFC1918 private address is a legitimate local host."""
    assert (
        validate_allowed_local_hostnames({HOSTS_KEY: ["10.0.0.1"]}, {}) is None
    )


def test_loopback_host_in_local_allowlist_is_accepted():
    """Loopback is local and must be accepted."""
    assert (
        validate_allowed_local_hostnames({HOSTS_KEY: ["127.0.0.1"]}, {}) is None
    )


def test_mixed_list_rejects_only_the_public_entries():
    """A list mixing private + public is rejected, naming only the public host."""
    err = validate_allowed_local_hostnames(
        {HOSTS_KEY: ["10.0.0.1", "8.8.8.8"]}, {}
    )
    assert err is not None
    assert "8.8.8.8" in err["error"]
    assert "10.0.0.1" not in err["error"]


def test_unresolvable_host_is_accepted_fail_open():
    """A name that does not resolve (DNS down / split-horizon) is accepted so a
    flaky-network user can still save; runtime classification still gates it.
    Resolution is stubbed to None to keep this deterministic and offline."""
    with patch.object(validators, "_resolve_with_timeout", return_value=None):
        assert (
            validate_allowed_local_hostnames(
                {HOSTS_KEY: ["intranet.corp.example"]}, {}
            )
            is None
        )


def test_public_host_still_rejected_when_resolution_succeeds():
    """Deny counterpart to the fail-open test: when resolution returns an
    address, a public host is rejected (the stub must not blanket-accept)."""
    addrinfo = [(2, 1, 6, "", ("8.8.8.8", 0))]
    with patch.object(
        validators, "_resolve_with_timeout", return_value=addrinfo
    ):
        err = validate_allowed_local_hostnames(
            {HOSTS_KEY: ["resolves-public.example"]}, {}
        )
    assert err is not None
    assert "resolves-public.example" in err["error"]


def test_json_string_list_of_private_host_is_accepted():
    """The save pipeline may hand the JSON-typed value as a JSON string."""
    assert (
        validate_allowed_local_hostnames({HOSTS_KEY: '["10.0.0.1"]'}, {})
        is None
    )


def test_json_string_list_of_public_host_is_rejected():
    """Deny counterpart for the JSON-string decode path."""
    err = validate_allowed_local_hostnames({HOSTS_KEY: '["8.8.8.8"]'}, {})
    assert err is not None
    assert "8.8.8.8" in err["error"]


def test_malformed_json_string_is_rejected():
    """A non-JSON string for a JSON-typed setting is a hard validation error."""
    err = validate_allowed_local_hostnames({HOSTS_KEY: "not json"}, {})
    assert err is not None
    assert err["key"] == HOSTS_KEY


def test_non_list_value_is_rejected():
    """A scalar (non-list) value is rejected — must be a list of hostnames."""
    err = validate_allowed_local_hostnames({HOSTS_KEY: 5}, {})
    assert err is not None


def test_hosts_key_absent_returns_none():
    """The guard is inert when its key is not part of the save."""
    assert validate_allowed_local_hostnames({"other.key": "x"}, {}) is None


@pytest.mark.parametrize("all_db_settings", [{}, None])
def test_missing_form_data_returns_none(all_db_settings):
    """No form data means nothing to validate; the validator must not raise
    (it promises never to)."""
    assert validate_allowed_local_hostnames(None, all_db_settings) is None


# An entry list that fails validation in every way it can: a zone-scoped
# address, a percent-encoded name and a public address.
_STALE_ENTRIES = ["fd12::1%10", "gpu%2dbox.lan", "8.8.8.8"]


@pytest.mark.parametrize(
    "stored",
    [
        {"value": list(_STALE_ENTRIES)},
        MagicMock(value=list(_STALE_ENTRIES)),
        {"value": '["fd12::1%10", "gpu%2dbox.lan", "8.8.8.8"]'},
    ],
)
@pytest.mark.parametrize(
    "submitted",
    [list(_STALE_ENTRIES), '["fd12::1%10", "gpu%2dbox.lan", "8.8.8.8"]'],
)
def test_unchanged_list_is_not_revalidated(stored, submitted):
    """Validate-on-change, as for the engine URLs: the All-Settings tab
    resubmits every setting, so a stored list holding entries a stricter
    validator now refuses must not block an unrelated save. A list and its
    JSON text are the same value."""
    assert (
        validate_allowed_local_hostnames(
            {HOSTS_KEY: submitted}, {HOSTS_KEY: stored}
        )
        is None
    )


@pytest.mark.parametrize(
    "submitted",
    [
        _STALE_ENTRIES + ["10.0.0.1"],
        _STALE_ENTRIES[:-1],
        list(reversed(_STALE_ENTRIES)),
    ],
)
def test_changed_list_is_validated_in_full(submitted):
    """Deny counterpart: any change to the stored list (an added, removed
    or reordered entry) is validated in full, so the unchanged stale entries
    are reported too."""
    err = validate_allowed_local_hostnames(
        {HOSTS_KEY: submitted}, {HOSTS_KEY: {"value": list(_STALE_ENTRIES)}}
    )
    assert err is not None
    assert "not valid hostnames" in err["error"]


def test_list_without_stored_value_is_validated():
    """A key with no stored value counts as changed."""
    err = validate_allowed_local_hostnames(
        {HOSTS_KEY: list(_STALE_ENTRIES)}, {"other.key": {"value": "x"}}
    )
    assert err is not None


# ---------------------------------------------------------------------------
# validate_engine_instance_urls
# (a PUBLIC engine's user-editable URL may not point at a private host)
# ---------------------------------------------------------------------------


def test_searxng_private_instance_url_is_rejected():
    """RFC1918 instance_url is an internal-probe target and is refused."""
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://10.0.0.1:8080"}, {}
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY
    assert GATE_ENV in err["error"]


def test_searxng_loopback_instance_url_is_rejected():
    """Loopback instance_url is refused under the default posture."""
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://127.0.0.1:8080"}, {}
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


def test_searxng_link_local_instance_url_is_rejected():
    """Link-local (169.254.0.0/16, non-metadata) instance_url is refused."""
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://169.254.10.20"}, {}
    )
    assert err is not None


def test_searxng_metadata_instance_url_is_rejected():
    """A cloud-metadata IP is refused (and flagged as always-blocked)."""
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://169.254.169.254"}, {}
    )
    assert err is not None
    assert "metadata" in err["error"].lower()


def test_searxng_public_instance_url_is_accepted():
    """Allow side: a public instance_url is a legitimate SearXNG target."""
    assert (
        validate_engine_instance_urls({SEARXNG_URL_KEY: "http://8.8.8.8"}, {})
        is None
    )


def test_searxng_non_http_scheme_is_rejected():
    """A non-http(s) scheme is never a valid engine URL."""
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "file:///etc/passwd"}, {}
    )
    assert err is not None
    assert "http" in err["error"].lower()


def test_searxng_hostname_resolving_private_is_rejected():
    """A hostname that resolves to a private address is refused."""
    addrinfo = [(2, 1, 6, "", ("10.0.0.5", 0))]
    with patch.object(
        validators, "_resolve_with_timeout", return_value=addrinfo
    ):
        err = validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://searx.internal.example"}, {}
        )
    assert err is not None


def test_searxng_unresolvable_host_is_accepted_fail_open():
    """A name that does not resolve is accepted (fail-open on DNS hiccups);
    runtime allow_private_ips derivation still gates the actual fetch."""
    with patch.object(validators, "_resolve_with_timeout", return_value=None):
        assert (
            validate_engine_instance_urls(
                {SEARXNG_URL_KEY: "http://searx.public.example"}, {}
            )
            is None
        )


def test_searxng_key_absent_returns_none():
    """The guard is inert when no guarded engine-URL key is part of the save."""
    assert validate_engine_instance_urls({"other.key": "x"}, {}) is None


def test_operator_gate_allows_private_instance_url(monkeypatch):
    """With the operator opt-in set, a private instance_url is accepted
    (the legitimate LAN self-host case)."""
    monkeypatch.setenv(GATE_ENV, "true")
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://10.0.0.1:8080"}, {}
        )
        is None
    )


def test_operator_gate_still_rejects_metadata(monkeypatch):
    """Deny counterpart: the opt-in relaxes private IPs but NOT the
    always-blocked cloud-metadata set."""
    monkeypatch.setenv(GATE_ENV, "true")
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://169.254.169.254"}, {}
    )
    assert err is not None
    assert "metadata" in err["error"].lower()


def test_operator_gate_still_rejects_non_http_scheme(monkeypatch):
    """The opt-in never licenses a non-http(s) scheme."""
    monkeypatch.setenv(GATE_ENV, "true")
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "gopher://10.0.0.1"}, {}
    )
    assert err is not None


# ---------------------------------------------------------------------------
# search.private_engine_url_allowlist
# (env-only per-origin alternative to the blanket operator gate)
# ---------------------------------------------------------------------------

# Hermetic DNS: hostname URLs in these tests resolve to loopback via this
# patch, so rejection can never silently flip to the unresolvable-host
# fail-open in a resolver-less sandbox.
LOOPBACK_ADDRINFO = [(2, 1, 6, "", ("127.0.0.1", 0))]


def test_allowlisted_private_instance_url_is_accepted(monkeypatch):
    """A private URL whose exact origin is operator-allowlisted is accepted
    without the blanket opt-in."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://localhost:8080")
    loopback = [(2, 1, 6, "", ("127.0.0.1", 0))]
    with patch.object(
        validators, "_resolve_with_timeout", return_value=loopback
    ):
        assert (
            validate_engine_instance_urls(
                {SEARXNG_URL_KEY: "http://localhost:8080"}, {}
            )
            is None
        )


def test_allowlist_is_exact_origin(monkeypatch):
    """Matching is exact scheme+host+port: a different port or host does not
    match, and the rejection names the allowlist variable as a remedy."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://localhost:8080")
    for url in (
        "http://localhost:9090",
        "http://127.0.0.1:8080",  # different host TEXT, even if same machine
        "https://localhost:8080",  # different scheme
        "http://10.0.0.1:8080",
    ):
        with patch.object(
            validators, "_resolve_with_timeout", return_value=LOOPBACK_ADDRINFO
        ):
            err = validate_engine_instance_urls({SEARXNG_URL_KEY: url}, {})
        assert err is not None, f"expected {url} to be rejected"
        assert ALLOWLIST_ENV in err["error"]


def test_allowlist_cosmetic_variants_match(monkeypatch):
    """Purely cosmetic URL variation of a listed origin still matches: host
    case, a trailing dot, a trailing slash / path, and an explicit default
    port."""
    monkeypatch.setenv(
        ALLOWLIST_ENV, "http://localhost:8080, https://searx.lan"
    )
    # Every hostname resolves private, so acceptance can ONLY come from the
    # allowlist match — never from the unresolvable-host fail-open.
    loopback = [(2, 1, 6, "", ("127.0.0.1", 0))]
    for url in (
        "HTTP://LOCALHOST:8080",
        "http://localhost.:8080",
        "http://localhost:8080/",
        "http://localhost:8080/searxng",
        "https://searx.lan:443",
    ):
        with patch.object(
            validators, "_resolve_with_timeout", return_value=loopback
        ):
            assert (
                validate_engine_instance_urls({SEARXNG_URL_KEY: url}, {})
                is None
            ), f"expected {url} to match the allowlist"


def test_allowlist_ipv6_literal_is_canonicalized(monkeypatch):
    """IPv6 textual variants of the same address compare equal."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://[0:0:0:0:0:0:0:1]:8080")
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://[::1]:8080"}, {}
        )
        is None
    )


def test_allowlist_never_licenses_metadata(monkeypatch):
    """Listing a cloud-metadata origin grants nothing — the always-blocked
    set is checked before the private exemption the allowlist provides."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://169.254.169.254:80")
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://169.254.169.254"}, {}
    )
    assert err is not None
    assert "metadata" in err["error"].lower()


def test_allowlist_never_licenses_non_http_scheme(monkeypatch):
    """Non-http(s) entries are unparseable as origins and grant nothing."""
    monkeypatch.setenv(ALLOWLIST_ENV, "gopher://10.0.0.1:70")
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "gopher://10.0.0.1:70"}, {}
    )
    assert err is not None


def test_allowlist_malformed_entries_are_ignored(monkeypatch):
    """Junk entries neither grant access nor break parsing of valid ones."""
    monkeypatch.setenv(
        ALLOWLIST_ENV, "not a url,,http://[broken:8080,http://localhost:8080"
    )
    with patch.object(
        validators, "_resolve_with_timeout", return_value=LOOPBACK_ADDRINFO
    ):
        # Hermetic DNS: acceptance must come from the surviving allowlist
        # entry, never from the unresolvable-host fail-open.
        assert (
            validate_engine_instance_urls(
                {SEARXNG_URL_KEY: "http://localhost:8080"}, {}
            )
            is None
        )
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://10.0.0.1:8080"}, {}
    )
    assert err is not None


def test_allowlist_parser_differential_url_never_matches_or_saves(monkeypatch):
    """A backslash URL that urlsplit and urllib3 read as DIFFERENT hosts
    (GHSA-g23j-2vwm-5c25 shape) must neither match the allowlist nor pass
    the save validator — the RFC-forbidden-chars guard closes the parser
    differential on both layers."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://localhost:8080")
    hostile = "http://evil.internal\\@localhost:8080"
    assert validators.engine_url_in_private_allowlist(hostile) is False
    err = validate_engine_instance_urls({SEARXNG_URL_KEY: hostile}, {})
    assert err is not None


def test_allowlist_schemeless_entry_grants_nothing(monkeypatch):
    """The most likely operator mistake — omitting the scheme — must not
    grant access (urlsplit reads 'localhost:8080' as scheme 'localhost')."""
    monkeypatch.setenv(ALLOWLIST_ENV, "localhost:8080")
    with patch.object(
        validators, "_resolve_with_timeout", return_value=LOOPBACK_ADDRINFO
    ):
        err = validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://localhost:8080"}, {}
        )
    assert err is not None


def test_allowlist_whitespace_only_env_grants_nothing(monkeypatch):
    monkeypatch.setenv(ALLOWLIST_ENV, "  , ,  ")
    with patch.object(
        validators, "_resolve_with_timeout", return_value=LOOPBACK_ADDRINFO
    ):
        err = validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://localhost:8080"}, {}
        )
    assert err is not None


def test_allowlist_ipv4_mapped_ipv6_is_a_distinct_origin(monkeypatch):
    """Listed 127.0.0.1 must not match the IPv4-mapped IPv6 form and vice
    versa — canonicalization is address-preserving, never widening."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://127.0.0.1:8080")
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://[::ffff:127.0.0.1]:8080"}, {}
    )
    assert err is not None

    monkeypatch.setenv(ALLOWLIST_ENV, "http://[::ffff:127.0.0.1]:8080")
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://127.0.0.1:8080"}, {}
    )
    assert err is not None


def test_allowlist_ipv6_zone_id_is_part_of_the_origin(monkeypatch):
    """A link-local zone ID distinguishes origins: same zone matches, a
    different zone does not."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://[fe80::1%eth0]:8080")
    assert (
        validators.engine_url_in_private_allowlist("http://[fe80::1%eth0]:8080")
        is True
    )
    assert (
        validators.engine_url_in_private_allowlist("http://[fe80::1%eth1]:8080")
        is False
    )


def test_allowlist_percent_encoded_host_never_matches_or_saves(monkeypatch):
    """The host is deliberately NOT percent-decoded for allowlist matching
    (urllib3 doesn't decode either), so an encoded 'localhost' neither
    matches the listing nor slips past the save validator (whose own
    classification path decodes and resolves it to loopback)."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://localhost:8080")
    encoded = "http://%6c%6f%63%61%6c%68%6f%73%74:8080"
    assert validators.engine_url_in_private_allowlist(encoded) is False
    with patch.object(
        validators, "_resolve_with_timeout", return_value=LOOPBACK_ADDRINFO
    ):
        err = validate_engine_instance_urls({SEARXNG_URL_KEY: encoded}, {})
    assert err is not None


def test_allowlist_trailing_dot_after_port_fails_closed(monkeypatch):
    """`:8080.` is not a parseable port — the origin is None, so the URL
    neither matches the listing nor saves (host still resolves loopback)."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://localhost:8080")
    with patch.object(
        validators, "_resolve_with_timeout", return_value=LOOPBACK_ADDRINFO
    ):
        err = validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://localhost:8080."}, {}
        )
    assert err is not None


def test_allowlisted_hostname_matches_textually(monkeypatch):
    """The allowlist matches the origin TEXT the operator listed — a listed
    internal hostname is accepted even though it resolves to a private
    address (that resolution is exactly what the operator approved)."""
    monkeypatch.setenv(ALLOWLIST_ENV, "http://searx.internal.example:8080")
    addrinfo = [(2, 1, 6, "", ("10.0.0.5", 0))]
    with patch.object(
        validators, "_resolve_with_timeout", return_value=addrinfo
    ):
        assert (
            validate_engine_instance_urls(
                {SEARXNG_URL_KEY: "http://searx.internal.example:8080"}, {}
            )
            is None
        )


def test_engine_url_guard_runs_via_first_error():
    """The new validator is wired into the shared entry point used by every
    settings-save route."""
    err = validators.first_egress_validation_error(
        {SEARXNG_URL_KEY: "http://127.0.0.1:8080"}, {}
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


# ---------------------------------------------------------------------------
# Route-level wiring: api_update_setting PUT surfaces the validator errors
# ---------------------------------------------------------------------------


def _make_setting(key, value, ui_element="text"):
    s = MagicMock()
    s.key = key
    s.value = value
    s.ui_element = ui_element
    s.editable = True
    return s


# ---------------------------------------------------------------------------
# validate_engine_instance_urls — validate-on-change
#
# Regression: the shipped default ``instance_url`` is a loopback URL that the
# "All Settings" tab resubmits untouched with every save. Validating an
# UNCHANGED value 400'd otherwise-unrelated saves. Only a genuine change (or a
# brand-new key with no stored value) is validated; the runtime
# allow_private_ips=False backstop still gates the actual fetch.
# ---------------------------------------------------------------------------

DEFAULT_SEARXNG_URL = "http://localhost:8080"


def test_unchanged_default_loopback_instance_url_is_accepted():
    """Regression repro: a full-form save carrying the shipped loopback
    ``instance_url`` default untouched, plus unrelated keys, is accepted when
    the same value is already stored — both directly and via the shared entry
    point every save route calls."""
    form_data = {
        "llm.temperature": 0.7,
        "search.iterations": 2,
        SEARXNG_URL_KEY: DEFAULT_SEARXNG_URL,
    }
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    assert validate_engine_instance_urls(form_data, all_db_settings) is None
    assert (
        validators.first_egress_validation_error(form_data, all_db_settings)
        is None
    )


def test_unchanged_default_loopback_accepted_with_dict_shaped_stored_value():
    """Robustness: the stored entry may be a ``{"value": ...}`` dict rather than
    an ORM row; an unchanged value is still recognized and accepted."""
    all_db_settings = {SEARXNG_URL_KEY: {"value": DEFAULT_SEARXNG_URL}}
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: DEFAULT_SEARXNG_URL}, all_db_settings
        )
        is None
    )


def test_changing_instance_url_to_private_is_rejected():
    """Deny counterpart: changing the stored (public) URL to a private one is a
    genuine change and is validated -> rejected."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, "http://8.8.8.8"),
    }
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://10.0.0.1:8080"}, all_db_settings
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


def test_changing_stored_loopback_to_different_private_is_rejected():
    """Even when the stored value is itself loopback, changing it to a
    different private address is a real change and must be validated."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://10.0.0.1:8080"}, all_db_settings
    )
    assert err is not None
    assert GATE_ENV in err["error"]


def test_changing_instance_url_to_public_is_accepted():
    """Allow counterpart: changing the stored URL to a public one is fine."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://8.8.8.8"}, all_db_settings
        )
        is None
    )


def test_new_instance_url_key_with_no_stored_value_is_validated():
    """A key with no stored entry counts as changed -> validated, so a private
    value is still rejected (no stored value to compare against)."""
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://10.0.0.1:8080"}, {}
        )
        is not None
    )
    # Also when other settings exist but not this one.
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://127.0.0.1:8080"},
            {"other.key": _make_setting("other.key", "x")},
        )
        is not None
    )


def test_unchanged_private_instance_url_under_operator_gate_is_accepted(
    monkeypatch,
):
    """Under the operator opt-in an unchanged private value is fine — the
    skip-on-unchanged path and the opt-in both leave it accepted."""
    monkeypatch.setenv(GATE_ENV, "true")
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: DEFAULT_SEARXNG_URL}, all_db_settings
        )
        is None
    )


# ---------------------------------------------------------------------------
# validate_engine_instance_urls — cosmetic-variant "unchanged" comparison
#
# The All-Settings tab resubmits the stored value verbatim, but a user who
# merely reformats it (different case, an added/removed trailing slash)
# without changing the actual destination should not have that cosmetic
# resubmit treated as a genuine change. ``_engine_url_is_unchanged`` now
# also compares scheme/host case-insensitively and ignores a trailing slash
# on the path. This must only ever widen "unchanged" — a real change to a
# different host/port/path still has to be validated (and rejected when
# private).
# ---------------------------------------------------------------------------


def test_unchanged_instance_url_different_scheme_and_host_case_is_accepted():
    """A cosmetic resubmit with a different scheme/host CASE of the exact
    same stored url is recognized as unchanged -> no SSRF validation -> no
    400."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "HTTP://LOCALHOST:8080"}, all_db_settings
        )
        is None
    )


def test_unchanged_instance_url_trailing_slash_is_accepted():
    """A cosmetic resubmit adding a bare trailing slash to the stored url is
    recognized as unchanged."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://localhost:8080/"}, all_db_settings
        )
        is None
    )


def test_instance_url_with_added_path_is_a_genuine_change():
    """Deny counterpart: appending an actual path segment (not just a bare
    trailing slash) is a real change and must still be validated ->
    rejected, since the stored/submitted host is private."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://localhost:8080/foo"}, all_db_settings
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


def test_cosmetic_variant_of_a_different_private_host_is_still_rejected():
    """Security-preservation: normalizing case/trailing-slash must never fold
    a genuinely DIFFERENT host onto the stored one. A different private host
    (still cosmetically upper-cased) is a real change and is rejected."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "HTTP://192.168.1.5:8080/"}, all_db_settings
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


def test_genuine_public_change_still_accepted():
    """A real change to a different, public host is still a change (goes
    through validation) and is accepted since it's public."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, DEFAULT_SEARXNG_URL),
    }
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "HTTP://EXAMPLE.COM:8080/"}, all_db_settings
        )
        is None
    )


def test_unparseable_stored_or_submitted_value_falls_back_to_exact_match():
    """If cosmetic-normalization parsing fails on either side (e.g. a
    non-numeric port), the comparison falls back to the exact
    ``str.strip()`` match rather than raising or silently treating it as
    unchanged."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, "http://localhost:abc"),
    }
    # Different value than stored, and unparseable -> falls back to exact
    # string compare, which does not match -> a genuine change -> validated.
    # ``urlsplit`` itself does not raise on a non-numeric port (that only
    # happens when ``.port`` is accessed, which the SSRF check never does),
    # so the submitted value parses fine as far as ``_engine_url_ssrf_error``
    # is concerned: its hostname is "localhost", which resolves to loopback
    # and is refused as a private/loopback address — not because
    # "http://localhost:xyz" fails to parse as a URL.
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://localhost:xyz"}, all_db_settings
    )
    assert err is not None
    # Identical unparseable strings still match on the exact-string
    # fallback, so they are correctly recognized as unchanged.
    assert (
        validate_engine_instance_urls(
            {SEARXNG_URL_KEY: "http://localhost:abc"}, all_db_settings
        )
        is None
    )


# ---------------------------------------------------------------------------
# Decimal / hex loopback literals — confirm save-time rejection when
# submitted as a genuine change. These numeric forms are not recognized by
# ``ipaddress.ip_address`` as literal IPs, so ``_engine_url_ssrf_error``
# routes them through hostname resolution (``_resolve_with_timeout`` ->
# ``socket.getaddrinfo``) instead of the literal-IP branch. The C library
# resolves bare-integer / 0x-hex notation to 127.0.0.1 purely locally (no
# network I/O — verified offline against the real resolver), so these are
# still caught and rejected, independent of anything in the cosmetic
# "unchanged" normalization above.
# ---------------------------------------------------------------------------


def test_decimal_loopback_literal_instance_url_is_rejected_as_a_change():
    """``2130706433`` is the decimal encoding of 127.0.0.1. Submitted as a
    change from the stored public url, it must resolve and be rejected."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, "http://8.8.8.8"),
    }
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://2130706433:8080"}, all_db_settings
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


def test_hex_loopback_literal_instance_url_is_rejected_as_a_change():
    """``0x7f000001`` is the hex encoding of 127.0.0.1. Submitted as a
    change from the stored public url, it must resolve and be rejected."""
    all_db_settings = {
        SEARXNG_URL_KEY: _make_setting(SEARXNG_URL_KEY, "http://8.8.8.8"),
    }
    err = validate_engine_instance_urls(
        {SEARXNG_URL_KEY: "http://0x7f000001:8080"}, all_db_settings
    )
    assert err is not None
    assert err["key"] == SEARXNG_URL_KEY


# ---------------------------------------------------------------------------
# Registry contract — a future public engine must not be able to silently
# skip the save-time SSRF guard.
#
# ``_public_engine_url_settings()`` only guards an engine's URL when its
# registry class exposes BOTH ``is_public is True`` and a non-empty *string*
# ``url_setting``; it is seeded with the SearXNG key as a hardcoded fallback,
# but otherwise derives the guarded set by walking ``ENGINE_REGISTRY`` and
# reading those two class attributes (see ``validators.py``). If a future
# public engine declares a non-string or empty-string ``url_setting``, it
# would silently fall outside the guard (a genuinely absent/``None``
# ``url_setting`` has no configurable URL and is intentionally out of
# scope). These tests pin the contract so that regression is caught.
# ---------------------------------------------------------------------------


def test_public_registry_engines_with_a_url_setting_are_all_guarded():
    """Walk the REAL engine registry: every class that is ``is_public is
    True`` and declares a non-``None`` ``url_setting`` must (a) declare it
    as a non-empty string, and (b) have that key present in
    ``_public_engine_url_settings()``. This is the exact contract
    ``_public_engine_url_settings()`` relies on to auto-discover public
    engines -- if a future engine declares a non-string or empty-string
    ``url_setting``, this test fails instead of the engine silently
    shipping without the SSRF guard. A public engine whose ``url_setting``
    is genuinely absent/``None`` has no configurable URL (no SSRF surface)
    and is intentionally skipped.

    Investigated registry structure: ``ENGINE_REGISTRY``
    (``web_search_engines/engine_registry.py``) maps every engine name to
    its module/class; ``_get_engine_class`` lazily imports each. As of this
    writing, ``elasticsearch`` and ``paperless`` also declare a
    ``url_setting`` but are LOCAL-nature engines (``is_local = True``,
    ``is_public`` unset) and are correctly excluded from this guard --
    only ``searxng`` combines ``is_public = True`` with a ``url_setting``.
    """
    from local_deep_research.security.egress.policy import _get_engine_class
    from local_deep_research.security.egress.validators import (
        _public_engine_url_settings,
    )
    from local_deep_research.web_search_engines.engine_registry import (
        ENGINE_REGISTRY,
    )

    guarded = _public_engine_url_settings()
    public_engines_with_url_setting = []
    for name in ENGINE_REGISTRY:
        cls = _get_engine_class(name)
        if cls is None:
            # Not expected to happen for any registry entry in a working
            # checkout, but importability isn't this test's concern.
            continue
        if getattr(cls, "is_public", None) is not True:
            continue
        url_setting = getattr(cls, "url_setting", None)
        if url_setting is None:
            # Genuinely absent url_setting -> no configurable URL -> no
            # SSRF surface for this engine. Intentionally out of scope.
            continue
        assert isinstance(url_setting, str) and url_setting, (
            f"{name}.url_setting must be a non-empty string to be picked "
            "up by _public_engine_url_settings() -- a non-string or "
            "empty-string value silently opts this public engine out of "
            "the save-time SSRF guard"
        )
        assert url_setting in guarded, (
            f"{name} is is_public=True with url_setting={url_setting!r} "
            "but that key is not covered by _public_engine_url_settings() "
            "-- a future public engine's configurable URL must be "
            "reachable through that function or it silently skips the "
            "save-time SSRF guard"
        )
        public_engines_with_url_setting.append(name)

    # Known case today. Fail loudly (rather than vacuously passing) if
    # registry wiring ever changes so this loop stops covering anything.
    assert "searxng" in public_engines_with_url_setting


def test_searxng_is_public_url_setting_contract_matches_guard():
    """Minimum-viable version of the contract above, independent of
    registry enumeration: SearXNG itself is ``is_public = True``, declares
    a non-empty string ``url_setting``, and that key is in the guarded
    set consumed by ``validate_engine_instance_urls``."""
    from local_deep_research.security.egress.validators import (
        _public_engine_url_settings,
    )
    from local_deep_research.web_search_engines.engines.search_engine_searxng import (
        SearXNGSearchEngine,
    )

    assert SearXNGSearchEngine.is_public is True
    assert isinstance(SearXNGSearchEngine.url_setting, str)
    assert SearXNGSearchEngine.url_setting
    assert SearXNGSearchEngine.url_setting in _public_engine_url_settings()
    assert SearXNGSearchEngine.url_setting == SEARXNG_URL_KEY


if __name__ == "__main__":  # pragma: no cover
    raise SystemExit(pytest.main([__file__, "-q"]))