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.

10.9 KB
Raw Blame
"""Exercise stored provider URLs and response-bearing fetches without egress.

The settings API, encrypted settings store, provider factory, SDK, fetch tool,
ContentFetcher, and HTML downloader are real. Only DNS and the final HTTP
transports are replaced; socket connections fail the test, including attempts
whose exceptions application code catches.
"""

import ipaddress
import socket
from types import SimpleNamespace

import httpx
import pytest
import requests
from openai import DefaultHttpxClient

from local_deep_research.content_fetcher import ContentFetcher
from local_deep_research.database.session_context import get_user_db_session
from local_deep_research.llm.providers import openai_base
from local_deep_research.llm.providers.implementations.custom_openai_endpoint import (
    CustomOpenAIEndpointProvider,
)
from local_deep_research.security import dns_pinning
from local_deep_research.security.egress.policy import (
    EgressContext,
    EgressScope,
)
from local_deep_research.settings import SettingsManager


ENDPOINT_SETTING = "llm.openai_endpoint.url"
FIXTURE_TEXT = "Local research service content is available."
# Always-blocked metadata literals: refused by every guard, the stored
# provider endpoint included.
METADATA_ADDRESSES = [
    "169.254.169.254",
    "192.0.0.192",
    "168.63.129.16",
    "fd00:ec2::23",
    "fd20:ce::254",
    "169.254.42.42",
    "fe80::a9fe:a9fe",
]
# Other link-local addresses: refused by the content-fetch guards, but
# deliberately still accepted as a provider endpoint (rootless Podman maps
# host.containers.internal to 169.254.1.2).
LINK_LOCAL_ADDRESSES = [
    "169.254.10.5",
    "169.254.169.253",
    "fe80::1",
]


@pytest.fixture(autouse=True)
def synthetic_network(monkeypatch):
    answers = {
        "localhost": ["127.0.0.1"],
        "backend-fixture.invalid": ["10.0.0.5"],
    }
    connections = []

    def resolve(host, port=None, *args, **kwargs):
        addresses = answers.get(host, [host])
        records = []
        for address in addresses:
            try:
                ip = ipaddress.ip_address(address)
            except ValueError as exc:
                raise socket.gaierror("No synthetic DNS answer") from exc
            family = socket.AF_INET6 if ip.version == 6 else socket.AF_INET
            records.append(
                (family, socket.SOCK_STREAM, 6, "", (str(ip), port or 80))
            )
        return records

    def refuse_connect(sock, address):
        connections.append(address)
        raise AssertionError(
            "A metadata regression test attempted a socket connection"
        )

    monkeypatch.setattr(socket, "getaddrinfo", resolve)
    # The downloader pins DNS through the resolver captured at module import.
    monkeypatch.setattr(dns_pinning, "_real_getaddrinfo", resolve)
    monkeypatch.setattr(socket.socket, "connect", refuse_connect)
    monkeypatch.setattr(socket.socket, "connect_ex", refuse_connect)
    yield answers
    assert connections == [], "All HTTP traffic must stay in fixture transports"


def _url(host):
    authority = f"[{host}]" if ":" in host else host
    return f"http://{authority}/v1"


@pytest.fixture
def sdk_transport(monkeypatch):
    requests_seen = []
    constructors = []
    real_constructor = openai_base.ChatOpenAI
    # OpenAI 2 uses httpx; the locked OpenAI 3 client uses httpx2.
    if issubclass(DefaultHttpxClient, httpx.Client):
        transport_module = httpx
    else:
        import httpx2

        transport_module = httpx2

    def respond(request):
        requests_seen.append(request)
        return transport_module.Response(
            200,
            json={
                "id": "chatcmpl-metadata-guard-fixture",
                "object": "chat.completion",
                "created": 0,
                "model": "fixture-model",
                "choices": [
                    {
                        "index": 0,
                        "message": {
                            "role": "assistant",
                            "content": FIXTURE_TEXT,
                        },
                        "finish_reason": "stop",
                    }
                ],
            },
        )

    # Preserve the real provider-owned clients and their redirect policy;
    # replace only the final network transport, not constructor arguments.
    monkeypatch.setattr(
        transport_module.HTTPTransport,
        "handle_request",
        lambda transport, request: respond(request),
    )
    models = []

    def construct(**kwargs):
        constructors.append(kwargs["base_url"])
        model = real_constructor(**kwargs)
        models.append(model)
        return model

    monkeypatch.setattr(openai_base, "ChatOpenAI", construct)
    try:
        yield SimpleNamespace(requests=requests_seen, constructors=constructors)
    finally:
        from local_deep_research.utilities.llm_utils import _close_base_llm

        for model in models:
            _close_base_llm(model)


def _save_and_read_snapshot(client, endpoint):
    response = client.put(
        f"/settings/api/{ENDPOINT_SETTING}", json={"value": endpoint}
    )
    assert response.status_code == 200, response.text
    username = client.get("/auth/check").json()["username"]
    with get_user_db_session(username) as session:
        snapshot = SettingsManager(session).get_settings_snapshot()
    assert snapshot[ENDPOINT_SETTING] == endpoint
    snapshot["llm.openai_endpoint.api_key"] = "metadata-guard-fixture-key"
    snapshot["llm.streaming"] = False
    return snapshot


@pytest.mark.real_session_check
@pytest.mark.parametrize("address", METADATA_ADDRESSES)
def test_stored_endpoint_blocks_before_sdk_but_localhost_still_works(
    authenticated_client, sdk_transport, address
):
    snapshot = _save_and_read_snapshot(authenticated_client, _url(address))
    with pytest.raises(ValueError, match="failed SSRF validation"):
        CustomOpenAIEndpointProvider.create_llm(
            "fixture-model", settings_snapshot=snapshot
        )
    assert sdk_transport.constructors == []
    assert sdk_transport.requests == []

    # Exercise the same saved-setting path with a usable self-hosted backend.
    snapshot = _save_and_read_snapshot(authenticated_client, _url("localhost"))
    llm = CustomOpenAIEndpointProvider.create_llm(
        "fixture-model", settings_snapshot=snapshot
    )
    assert llm.invoke("Check the local service").content == FIXTURE_TEXT
    assert sdk_transport.constructors == [_url("localhost")]
    assert len(sdk_transport.requests) == 1
    assert str(sdk_transport.requests[0].url) == (
        "http://localhost/v1/chat/completions"
    )


@pytest.mark.real_session_check
@pytest.mark.parametrize("address", ["169.254.1.2"] + LINK_LOCAL_ADDRESSES)
def test_stored_link_local_endpoint_still_constructs(
    authenticated_client, sdk_transport, address
):
    # Not a metadata literal, so the provider guard must not refuse it: a
    # rootless Podman host backend lives at 169.254.1.2.
    snapshot = _save_and_read_snapshot(authenticated_client, _url(address))
    CustomOpenAIEndpointProvider.create_llm(
        "fixture-model", settings_snapshot=snapshot
    )
    assert len(sdk_transport.constructors) == 1
    assert address in sdk_transport.constructors[0]
    assert sdk_transport.requests == []


@pytest.fixture
def html_transport(monkeypatch):
    requests_seen = []
    paragraphs = "".join(
        f"<p>{FIXTURE_TEXT} This fixture describes a local document service "
        "that researchers use to read articles on their private network. "
        "The complete article should be returned through the fetch tool.</p>"
        for _ in range(8)
    )
    html = (
        "<html><head><title>Local research fixture</title></head>"
        f"<body><article>{paragraphs}</article></body></html>"
    )

    def send(adapter, request, **kwargs):
        requests_seen.append(request)
        response = requests.Response()
        response.status_code = 200
        response.url = request.url
        response.request = request
        response.headers["Content-Type"] = "text/html; charset=utf-8"
        response._content = html.encode()
        response.headers["Content-Length"] = str(len(response._content))
        return response

    monkeypatch.setattr(requests.adapters.HTTPAdapter, "send", send)
    return requests_seen


def _fetch(entry_point, url, local_hostnames=()):
    context = EgressContext(
        scope=EgressScope.PRIVATE_ONLY,
        primary_engine="test",
        require_local_llm=False,
        require_local_embeddings=False,
        local_hostnames=local_hostnames,
    )
    if entry_point == "content_fetcher":
        with ContentFetcher(egress_context=context) as fetcher:
            result = fetcher.fetch(url)
        return result["status"] == "success", result.get(
            "content", result.get("error")
        )

    from local_deep_research.advanced_search_system.tools.fetch import (
        build_fetch_tool,
    )
    from local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy import (
        SearchResultsCollector,
    )

    collector = SearchResultsCollector()
    tool = build_fetch_tool(
        "full",
        collector,
        egress_context=context,
        settings_snapshot={"web.enable_javascript_rendering": False},
        max_fetches=0,
    )
    output = tool.invoke({"url": url})
    return collector.find_by_url(url) is not None, output


@pytest.mark.parametrize("entry_point", ["content_fetcher", "agent_tool"])
@pytest.mark.parametrize("address", METADATA_ADDRESSES + LINK_LOCAL_ADDRESSES)
def test_metadata_never_reaches_fetch_transport(
    entry_point, address, html_transport
):
    success, output = _fetch(entry_point, _url(address))
    assert not success
    assert "blocked" in output.lower()
    assert FIXTURE_TEXT not in output
    assert html_transport == []


@pytest.mark.parametrize("entry_point", ["content_fetcher", "agent_tool"])
@pytest.mark.parametrize(
    "addresses",
    [
        ["169.254.10.5"],
        ["fe80::1"],
        ["192.0.0.192"],
        ["10.0.0.5", "192.0.0.192"],
    ],
)
def test_allowlisted_metadata_dns_never_reaches_fetch_transport(
    entry_point, addresses, synthetic_network, html_transport
):
    host = "metadata-fixture.invalid"
    synthetic_network[host] = addresses
    success, output = _fetch(entry_point, _url(host), local_hostnames=(host,))
    assert not success
    assert "blocked" in output.lower()
    assert FIXTURE_TEXT not in output
    assert html_transport == []


@pytest.mark.parametrize("entry_point", ["content_fetcher", "agent_tool"])
@pytest.mark.parametrize(
    "host",
    [
        "localhost",
        "10.0.0.5",
        "192.168.1.10",
        "fd12::1",
        "backend-fixture.invalid",
    ],
)
def test_private_content_reaches_fetch_output(
    entry_point, host, html_transport
):
    success, output = _fetch(entry_point, _url(host))
    assert success, output
    assert FIXTURE_TEXT in output
    assert html_transport
    assert all(request.url == _url(host) for request in html_transport)